It works, but accessing it from mainland China can sometimes be unstable. Some projects use workers.dev directly as their entry point, making latency and availability a matter of luck.

Here is a common workaround: instead of using the default workers.dev, use your own domain, CNAME it to a Cloudflare optimized domain, and finally catch the requests using Workers routing.

Simply put:

用户 -> 你的域名 -> 优选域名对应的 Cloudflare 节点 -> Workers 路由 -> 你的 Worker

This isn't magic acceleration, nor does it guarantee the fastest speeds forever. It just changes the entry point to a more suitable Cloudflare node.

When to Use This

This guide is best suited for the following situations:

• You already have a functioning Worker.
• The default workers.dev entry point is unstable in your network.
• You have your own domain, and it is already hosted on Cloudflare.
• You want to specify an optimized entry point yourself, rather than using Cloudflare's automatically generated binding method.

If you just want to bind a regular domain to your Worker without messing with optimized domains, using Custom Domains directly is much simpler.

Conclusion First

This guide uses Workers Routes, not Custom Domains.

The reason is simple:

• Custom Domains will cause Cloudflare to automatically create DNS records.
• However, here we need to manually CNAME the domain to an optimized domain.
• Therefore, a Workers Route like domain/* is much more suitable.

If you are just deploying a Worker normally without setting up an optimized domain, using Custom Domains is easier.

If you want to specify your own optimized entry point, using routes is more appropriate.

Prerequisites

You will need the following:

In our examples, we assume:

Worker 名称：my-worker
你的域名：wk.example.com
优选域名：cloudflare.example.net

Replace these with your own when following along.

Final Result

Once finished, you will access your own domain:

https://wk.example.com

The request will first go to the Cloudflare node corresponding to your optimized domain, and then be handed over to the target Worker by the Workers Route. Normal visits, API paths, and static resource paths should all be caught by the same Worker.

Step 1: Verify the Worker is Functioning Normally

Don't rush to change your DNS just yet.

Open the default Worker address:

https://my-worker.<你的 workers.dev 子域>.workers.dev

Proceed only if it returns content normally.

If the default address doesn't even load, fix the Worker first. Otherwise, adding DNS and routing later will only make things more confusing.

You can also test it via command line:

curl -I https://my-worker.<你的 workers.dev 子域>.workers.dev

As long as you get a normal HTTP status code, you're good.

Step 2: Add DNS Records

Go to the Cloudflare dashboard and select your domain example.com.

Add a DNS record:

The key here is to select DNS only (the gray cloud) for the proxy status.

Do not enable the proxy.

If you enable the proxy, Cloudflare will process it using its standard proxy logic, and the entry point may not be the optimized domain you want. Many people make a mistake here.

After adding it, your domain should be:

wk.example.com

Step 3: Add Workers Route

Go to the Cloudflare dashboard:

Workers 和 Pages -> 你的 Worker -> 设置 -> 域和路由

Add a route:

wk.example.com/*

Then select your project for the Worker, such as my-worker.

The /* here cannot be omitted.

If you don't add it, the route will only match the root path, and many APIs, static resources, and sub-paths will just break.

Step 4: Test Access

Open in your browser:

https://wk.example.com

Test via command line:

curl -I https://wk.example.com

If your Worker has API paths, test those too:

curl -I https://wk.example.com/api

Don't just test the homepage. Many projects load fine on the homepage, but API paths aren't caught by the route, which you only discover later.

How to Verify It's Working

First, check the DNS:

nslookup wk.example.com

Or:

dig wk.example.com

Normally, you should see it eventually pointing to the optimized domain you set.

Then test HTTPS:

curl -I https://wk.example.com

If it returns the response from your Worker, it means the route is also working.

Frequently Asked Questions

1. Returning a 404 Error

This is most likely because the route is not configured correctly.

Check:

wk.example.com/*

Verify the domain name, the asterisk, and the slash.

2. DNS Resolves, but Worker Doesn't Respond

DNS only brings the request to the Cloudflare node.

Whether the Worker executes depends on the Workers Route. Go to "Domains & Routes" to check if the route is bound to the correct Worker.

3. HTTPS Certificate Error

Wait a little while first.

If it still doesn't work, check if the domain is properly hosted in Cloudflare and if the DNS records are typed correctly.

Also, don't randomly use domains that don't belong to you. That's not how certificates and routing work.

4. Optimized Domain Suddenly Slows Down

This is normal.

"Optimization" is not an absolute truth; it just tested well at the moment. Networks change, and nodes change too.

There are only two solutions:

• Switch to a different optimized domain.
• Run speed tests yourself regularly.

5. Is the Free Quota Enough?

It is generally enough for regular personal projects.

The Cloudflare Workers free plan has daily request limits and CPU time limits. Lightweight APIs, redirect pages, and small tools usually have no issues.

But if you are using it for high-traffic downloads or reverse proxying a bunch of things, don't expect to free-ride indefinitely. You'll hit the limits sooner or later.

Choosing Between Routes and Custom Domains

Keep it simple:

I'm using routing here not because it's more advanced, but simply because it fits the "optimized domain" approach.

A Complete Example

Assuming:

Worker：my-worker
域名：example.com
入口：wk.example.com
优选域名：cloudflare.example.net

DNS:

CNAME  wk  cloudflare.example.net  仅 DNS 解析

Workers Route:

wk.example.com/*

Access:

https://wk.example.com

If it returns the Worker content, you're done.

Final Thoughts

This solution is suitable when you already have a Worker project but the default entry point access is unstable.

Don't overhype it. An optimized domain just changes the entry point; it won't make a poorly built project fast, nor will it fix code issues within the Worker itself.

Make sure the Worker works normally first, then change the DNS, and then bind the route. Following this order prevents things from getting messy.

References

• Cloudflare Workers Routing
• Cloudflare Workers Custom Domains
• Cloudflare Workers Limits

What's really troublesome are the trivial tasks that follow: adding a phone, deleting an old device, generating a QR code, modifying configurations, reloading the service, and checking if peers have handshaked.

Manually editing wg0.conf is doable, but it gets annoying if you do it often. Moreover, if you accidentally mistype a private key, public key, or AllowedIPs, you have to go back and troubleshoot all over again.

So I wrote wg-manager.sh. The goal is simple: wrap up common WireGuard operations so you don't have to type them from scratch every time.

Applicable Scenarios

This script is suitable for a small WireGuard environment on a personal VPS:

• Want to quickly add or remove clients.
• Want to generate a QR code directly in the terminal to scan with a phone.
• Don't want to manually edit wg0.conf every time.
• Want to use a menu to check the status, reload the configuration, and export client files.

If you already have a complex environment with policy routing, multiple network interfaces, and multiple exits, this script might not be suitable for taking over directly.

Prerequisites

It's written by default for common server environments like Debian / Ubuntu. Before using it, you need at least:

• A Linux server with root privileges.
• A system that can normally install WireGuard-related packages.
• A firewall or cloud provider security group that allows the UDP port used by WireGuard.
• To roughly know the network segment you want to assign to your clients.

Final Result

In the end, you can just run:

sudo ./wg-manager.sh

Then use the menu to add/remove clients, view QR codes, check service status, and reload the configuration. You don't have to repeatedly look up commands for common operations.

What This Script Does

wg-manager is a Bash script mainly used to manage WireGuard servers and clients.

Currently, it can do the following:

• Install the WireGuard server.
• Create the first client.
• Add / remove clients.
• Automatically allocate client IPs.
• Generate client configuration files.
• Display a QR code in the terminal for direct scanning with a phone.
• Support global mode and simple split tunneling mode.
• Check service status and peer information.
• Rebuild configurations and reload.
• Uninstall configurations managed by the script.

It's suitable for a Debian / Ubuntu cloud server.

It is not suitable for scenarios that already have a complex WireGuard production environment, lots of policy routing, and highly specific split tunneling rules. This script isn't meant to take over complex networks; it's mainly to streamline the most common workflows for everyday users.

Why Write a Menu Mode

Usually, scripts like this start out using command-line arguments:

sudo ./wg-manager.sh add-client iphone
sudo ./wg-manager.sh qr iphone
sudo ./wg-manager.sh status

It works, but you have to memorize the commands.

When doing manual operations on a day-to-day basis, I'd rather just see a menu:

sudo ./wg-manager.sh

And then choose:

1) Install WireGuard
2) Add a client
3) Delete a client
4) List clients
5) View client configuration
6) Show client QR code
7) Check service status
8) Reload configuration
9) Uninstall

This way, you don't have to check the README every time.

There is also a detail: when starting in menu mode, it will first check if you are root.

If you didn't use sudo, it exits immediately. You don't want someone filling out a bunch of prompts only to be told at the end that they lack permissions. That kind of experience is a bit absurd.

Getting the Script

If the repository is already public, you can clone it directly:

git clone https://github.com/Kaurisss/wg-manager.git
cd wg-manager
chmod +x wg-manager.sh

Or you can just download the single file:

curl -fsSL -o wg-manager.sh https://raw.githubusercontent.com/Kaurisss/wg-manager/main/wg-manager.sh
chmod +x wg-manager.sh

It is recommended to run the script on a server. Don't force it to run locally on Windows; this thing is intended for Linux servers anyway.

Using the Menu Mode

The simplest way:

sudo ./wg-manager.sh

For the first time, choose to install WireGuard.

The script will ask you to fill in these details:

• WireGuard interface name, default wg0
• UDP port, default 51820
• IPv4 subnet, default 10.66.66.0/24
• Whether to enable IPv6
• Client DNS
• Name of the first client
• Client mode: Global / Split tunneling

For most of them, you can just press Enter to use the default values.

After installation, it will generate the server configuration and conveniently generate the first client configuration as well.

If qrencode is installed, it can also display a QR code right in the terminal. You can just scan and import it with the WireGuard mobile client, which is quite handy.

Command-Line Mode

The menu is great for manual clicking.

But for writing documentation, automation, and copying commands, subcommands still need to be preserved.

Install and create the first client:

sudo ./wg-manager.sh install --client-name phone

Enable IPv6:

sudo ./wg-manager.sh install --enable-ipv6 --client-name phone

Custom port and subnet:

sudo ./wg-manager.sh install \
  --port 51820 \
  --ipv4-net 10.66.66.0/24 \
  --enable-ipv6 \
  --ipv6-net fd66:66:66::/64 \
  --client-name laptop

Add a client:

sudo ./wg-manager.sh add-client iphone

Show QR code:

sudo ./wg-manager.sh qr iphone

Check status:

sudo ./wg-manager.sh status

List clients:

./wg-manager.sh list-clients

Reload configuration:

sudo ./wg-manager.sh reload

Uninstall:

sudo ./wg-manager.sh uninstall --yes

Global Mode and Split Tunneling Mode

The script offers two client modes.

Global Mode

Global mode means all client traffic goes through WireGuard:

AllowedIPs = 0.0.0.0/0,::/0

Suitable for:

• Connecting back to the server when you're out with your phone.
• Wanting all traffic to pass through this VPS.
• Not wanting to bother with split tunneling rules.

Split Tunneling Mode

Split tunneling mode means only designated subnets go through WireGuard.

For example, routing only intranet addresses:

sudo ./wg-manager.sh add-client office \
  --mode split \
  --allowed-ips 10.0.0.0/8,172.16.0.0/12,192.168.0.0/16

Note that this only uses AllowedIPs for simple split tunneling.

It is not intelligent routing; it won't automatically recognize games, websites, or domains. If you want highly specific rules, you'll have to use a more complex solution.

Where Are the Generated Files Stored?

By default, they are all in /etc/wireguard/:

/etc/wireguard/
├── wg0.conf
├── clients/
│   ├── phone.conf
│   └── iphone.conf
├── peers/
│   └── iphone/
│       ├── private.key
│       ├── public.key
│       ├── psk.key
│       └── meta
├── backup/
└── .wg-manager/
    ├── server.env
    ├── server_private.key
    └── server_public.key

This contains private keys, PSKs, and client configurations.

Do not push these to GitHub.

In a public repository, you should only put the script, README, and example configurations. Uploading real configuration files is basically digging a hole for yourself.

Security Groups and Firewalls

The script attempts to handle UFW and firewalld, automatically allowing WireGuard's UDP port.

But cloud servers also have security groups.

This script cannot manage the cloud provider's console.

If you can't connect, check these first:

• Has the cloud server's security group allowed UDP 51820?
• Is the local firewall blocking it?
• Did you mistype the endpoint in the client?
• Has the server's public IP changed?
• Is there any handshake in sudo ./wg-manager.sh status?

Don't immediately blame the script if you can't connect.

With networking, it's often not that the configuration wasn't generated; it's that the traffic simply didn't come in.

Troubleshooting Order

I generally follow this order:

1. Is the Service Up?

sudo ./wg-manager.sh status

Or:

sudo systemctl status wg-quick@wg0

2. Is the Client Configuration Generated?

ls -l /etc/wireguard/clients/

3. Can the QR Code Be Scanned?

sudo ./wg-manager.sh qr iphone

4. Have the Peers Handshaked?

sudo wg

Having a latest handshake is the only way to prove the client has actually connected.

If there's no handshake, continue checking the port, security group, endpoint, and public/private keys.

Known Limitations

This script is not a silver bullet.

Current limitations include roughly:

• Only supports Debian / Ubuntu.
• IPv4 subnets are only handled as /24.
• IPv6 subnets are only handled as /64.
• Uses iptables / ip6tables for NAT by default.
• Does not take over existing complex WireGuard environments.
• Split tunneling is just simple AllowedIPs; no intelligent rules.

These limitations aren't bugs; they are a deliberate control of scope.

For scripts like this, the worst thing is trying to cover everything from the start, and ending up with a mess that no one dares to run.

Final Words

wg-manager isn't meant to replace the official WireGuard tools.

It merely wraps the few things I frequently do into a script: installing, adding clients, deleting clients, scanning QR codes, checking status, and reloading configurations.

Every time I can avoid manually editing wg0.conf is one less chance to write the configuration incorrectly.

Getting it to run stably first, and then slowly adding features later. That direction feels a lot more human.

Initially, I just wanted a lightweight theme instead of those flashy template sites. Later, I came across the OpenCode terminal style, which looked pretty good—black and white, monospace fonts, and a relatively clean structure, so I decided to use it for now.

Why I use this theme

Mainly for a few reasons:

• The pages are clean and don't distract from the article content.
• Monospace fonts make reading code comfortable.
• The black and white style is timeless and doesn't easily cause aesthetic fatigue.
• The structure is simple, making future modifications relatively easy.

Some themes look dazzling at first glance, but when you actually write articles, they become a mess: too many cards, chaotic colors, and a bunch of animations. They look less like blogs and more like landing pages for selling courses.

This one, at least, isn't that abstract.

Current state

Currently, the blog mainly hosts these contents:

• Logs of tinkering with networks and servers.
• Linux, scripts, and command cheat sheets.
• Notes on tool deployment and troubleshooting pitfalls.
• Later, I might post about AI coding, websites, and automation.

The writing doesn't have to be too formal; as long as it's understandable and reproducible, that's fine.

Code block effect

Command blocks look roughly like this:

npm install
npm run build

Regular code blocks:

function log(message) {
  console.log(`[stdout] ${message}`)
}

log('hello opencode')

Potential future tweaks

The theme is usable, but it's not like I won't touch it at all.

I'll probably tweak these things:

1. Make the homepage article list a bit more compact.
2. Adjust Chinese typography details.
3. Ensure category and tag pages aren't too empty.
4. Rewrite the code block copy button if it doesn't work well.
5. Continue fixing things that look off on mobile.

Get it running first, then slowly tweak it.

Conclusion

Right now, this site just serves as my personal technical notes.

Writing articles isn't about pretending to be professional; it's mostly to prevent forgetting how to configure things next time. If I can document the pitfalls, the effort wasn't wasted.

There are too many Linux commands to memorize them all. It's enough to remember the common ones and be able to look up the rest quickly when needed.

Table of Contents

1. Quick Reference Table
2. Files and Directories
3. Viewing Files
4. Text Processing
5. Finding Files
6. Permissions and Users
7. Processes and Services
8. Networking
9. Package Management
10. Disks and Mounting
11. Compression and Archiving
12. Logs and Troubleshooting
13. Shell Miscellany
14. Common One-Liners

Quick Reference Table

Files and Directories

ls

View directories:

ls
ls -l
ls -la
ls -lh

Common parameters:

• -l: Detailed list
• -a: Show hidden files
• -h: Human-readable file sizes, e.g., 1.2G

cd and pwd

pwd
cd /var/www
cd ~
cd -

cd - takes you back to the previous directory, which is quite useful.

cp

cp a.txt b.txt
cp -r src/ backup/
cp -a src/ backup/

-a attempts to preserve permissions, timestamps, and other information, making it more reliable than -r when backing up directories.

mv

mv old.txt new.txt
mv file.txt /tmp/

Can be used for both moving and renaming.

rm

rm file.txt
rm -r folder/
rm -rf folder/

Be careful not to slip up with rm -rf. Especially when using variables, echo the path first, otherwise you will regret it if you delete the wrong thing.

mkdir

mkdir logs
mkdir -p app/data/cache

-p automatically creates intermediate directories.

Viewing Files

cat

cat file.txt

View small files directly. Don't use it for large files as it will flood your screen.

less

less app.log

Common operations:

• /keyword: Search
• n: Next result
• q: Quit

head and tail

head -n 20 app.log
tail -n 50 app.log
tail -f app.log

Generally use tail -f for viewing logs.

nl

nl file.txt

Displays files with line numbers. Useful when troubleshooting configurations.

Text Processing

grep

grep "ERROR" app.log
grep -n "ERROR" app.log
grep -R "listen" /etc/nginx
grep -i "error" app.log

Common parameters:

• -n: Show line numbers
• -R: Search directories recursively
• -i: Ignore case

If rg (ripgrep) is available on the system, I usually prefer it as it's much faster:

rg "ERROR"
rg "listen" /etc/nginx

sed

sed -n '1,20p' file.txt
sed 's/old/new/g' file.txt

Often used for replacing text or just viewing specific lines.

awk

awk '{print $1}' access.log
awk '{print $1, $9}' access.log

Processes text by columns. Frequently used for log analysis.

cut

cut -d':' -f1 /etc/passwd
cut -d',' -f1,3 data.csv

Use this for simple column splitting; no need to write complex scripts right away.

sort and uniq

sort file.txt
sort -n numbers.txt
sort file.txt | uniq
sort file.txt | uniq -c

Very handy for counting duplicates.

wc

wc -l file.txt
wc -c file.txt

Counts lines and bytes.

Finding Files

find

find . -name "*.log"
find /var/log -type f -mtime -7
find . -type f -size +100M

A few common conditions:

• -name: By name
• -type f: Find files only
• -type d: Find directories only
• -mtime -7: Modified within 7 days
• -size +100M: Larger than 100M

which

which nginx
which python

Shows exactly where a command is coming from.

locate

locate nginx.conf

Fast, but relies on an index. Newly created files might not be found.

Permissions and Users

chmod

chmod 644 file.txt
chmod 755 script.sh
chmod +x script.sh

Common permissions:

• 644: Regular files
• 755: Executable scripts or directories
• 600: Sensitive files like private keys

chown

sudo chown user:group file.txt
sudo chown -R www-data:www-data /var/www/app

You often need to check this when website directory permissions are incorrect.

User-related

whoami
id
passwd
sudo useradd name
sudo usermod -aG sudo name

Processes and Services

Viewing Processes

ps aux
ps aux | grep nginx
top
htop

Use htop if you have it; it looks nicer.

Killing Processes

kill 1234
kill -9 1234
pkill -f nginx

kill -9 is a forceful kill, not a universal fix button. Try a normal kill first, and use it only if that fails.

systemd Services

sudo systemctl status nginx
sudo systemctl start nginx
sudo systemctl restart nginx
sudo systemctl enable nginx

View service logs:

journalctl -u nginx -f
journalctl -u nginx --since "1 hour ago"

Networking

IP and Ports

ip addr
ip route
ss -tuln
ss -tulnp

ss -tulnp shows which process is occupying which port.

Connectivity

ping 1.1.1.1
curl -I https://example.com
curl http://127.0.0.1:3000

Don't just ping to test HTTP services. A successful ping doesn't mean the website is alive.

SSH

ssh root@1.2.3.4
ssh -p 2222 user@1.2.3.4
scp file.txt user@1.2.3.4:/tmp/

rsync

rsync -avz ./dist/ user@server:/var/www/app/
rsync -avz --delete ./dist/ user@server:/var/www/app/

--delete removes extra files on the destination side, so think carefully before using it.

Package Management

Debian / Ubuntu:

sudo apt update
sudo apt install nginx
sudo apt upgrade

CentOS / RHEL:

sudo yum install nginx
sudo dnf install nginx

Arch:

sudo pacman -S nginx

openSUSE:

sudo zypper install nginx

Commands vary across distributions. Make sure not to copy the wrong one for your system.

Disks and Mounting

Viewing Disks

df -h
du -sh *
du -sh /var/log

Finding large directories:

du -h --max-depth=1 / | sort -h

Block Devices

lsblk
blkid
sudo fdisk -l

Mounting

sudo mount /dev/sdb1 /mnt
sudo umount /mnt

Compression and Archiving

tar

tar -czvf archive.tar.gz folder/
tar -xzvf archive.tar.gz
tar -tzf archive.tar.gz

zip

zip -r archive.zip folder/
unzip archive.zip

gzip

gzip file.txt
gunzip file.txt.gz

Logs and Troubleshooting

dmesg
journalctl -xe
journalctl -u service-name -f
tail -f /var/log/syslog
tail -f /var/log/nginx/error.log

Port is occupied:

sudo lsof -i :80
sudo ss -tulnp | grep :80

If configuration changes don't take effect, first check if the service was restarted, then check the logs. Many problems aren't due to missing configurations, but because the service simply didn't reload them.

Shell Miscellany

Environment Variables

env
printenv
export NODE_ENV=production
echo $PATH

alias

alias ll='ls -lah'
alias gs='git status'

Add them to ~/.bashrc or ~/.zshrc to make them permanent.

Executing Scripts

chmod +x script.sh
./script.sh

Cron Jobs

crontab -e
crontab -l

Common One-Liners

Find large files:

find / -type f -size +500M 2>/dev/null

Search for errors in logs:

grep -R --line-number "ERROR" /var/log 2>/dev/null

View the size of each folder in the current directory:

du -h --max-depth=1 . | sort -h

Sync website build artifacts:

rsync -avz --delete ./dist/ user@server:/var/www/site/

View recent logs for a service:

journalctl -u nginx --since "2 hours ago" -f

Find the process occupying a port:

sudo ss -tulnp | grep :3000

Batch delete .tmp files:

find . -type f -name "*.tmp" -delete

It's best to remove -delete and preview the results before executing this command:

find . -type f -name "*.tmp"

Don't delete right away; deleting the wrong files is quite troublesome.

This is where Cloudflare Tunnel comes in handy. The logic is simple: your local machine actively connects to Cloudflare, and people outside access this tunnel via your domain name. You don't need to expose ports, and you don't have to care if your ISP provides a public IP.

Use Cases

• Running a website at home and wanting to temporarily expose it to the external network.
• Binding a domain to a NAS, panel, or test service.
• Avoiding opening a bunch of ports on the router.
• Wanting HTTPS but lacking a public IP.

Do not treat it as a universal reverse proxy. If you are running high-concurrency, high-traffic services, just use a proper server. Tunnel is more suited for personal services, test environments, and low-frequency access.

Prerequisites

Confirm these things first:

First, test if your local service is alive:

curl -I http://127.0.0.1:80

Seeing a normal response like 200, 301, or 302 is fine. If you can't even access it locally, don't mess with Tunnel yet, otherwise troubleshooting will be very abstract.

Final Result

After finishing, the external network will access your domain:

https://app.example.com

The request will enter through Cloudflare and then be forwarded to the intranet service via the active Tunnel established by your local machine. You don't need port mapping on the router, nor do you need a public IP at home.

Install cloudflared

cloudflared is the client for Cloudflare Tunnel.

On macOS, you can just use Homebrew:

brew install cloudflared

For Linux, just download the binary file:

curl -L 'https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64' -o ./cloudflared
chmod +x ./cloudflared
sudo mv ./cloudflared /usr/local/bin/cloudflared

Check if it is installed properly:

cloudflared --version

Having a version number is enough.

Log in to Cloudflare

Let the local cloudflared obtain Cloudflare account authorization:

cloudflared tunnel login

The command will provide a link. Copy and open it in your browser, log in to Cloudflare, select the domain you want to use, and then authorize it.

After successful authorization, the local machine will generate a certificate file. Don't randomly delete this file; it will be needed later to create the tunnel.

Create a Tunnel

Give the tunnel a name, for example, home-web:

cloudflared tunnel create home-web

The output will contain two key pieces of information:

Created tunnel home-web with id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Tunnel credentials written to /root/.cloudflared/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.json

Remember these two:

• Tunnel ID
• credentials file path

These will need to be filled in the configuration file later.

Write the Configuration File

Create the configuration directory:

sudo mkdir -p /etc/cloudflared
sudo nano /etc/cloudflared/config.yml

Example configuration:

tunnel: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
credentials-file: /root/.cloudflared/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.json

ingress:
  - hostname: app.example.com
    service: http://127.0.0.1:80

  - hostname: admin.example.com
    service: http://127.0.0.1:8080

  - service: http_status:404

Don't just copy the domain name here. Replace it with your own.

ingress is matched in order, so it's recommended to keep the last 404. Otherwise, it gets messy handling unmatched requests.

After writing the configuration, check it first:

cloudflared tunnel ingress validate

If it passes, continue.

Bind the Domain Name

Point the domain to this Tunnel:

cloudflared tunnel route dns home-web app.example.com
cloudflared tunnel route dns home-web admin.example.com

If a DNS record conflict is prompted, go to the Cloudflare dashboard, delete the old A, AAAA, and CNAME records, and execute it again.

Run Manually First

Don't rush to install the service, run it first to see:

cloudflared tunnel run home-web

Then visit your domain:

https://app.example.com

If it opens, the main process is fine.

If it doesn't open, prioritize checking these points:

• Is the local service still alive?
• Is the hostname written incorrectly?
• Has the Cloudflare DNS been pointed to the Tunnel?
• Is the server time completely off?
• Is the configuration file path correct?

Set up Auto-Start on Boot

After confirming that running manually is fine, install it as a systemd service:

sudo cloudflared service install
sudo systemctl enable --now cloudflared

Check the status:

sudo systemctl status cloudflared

View real-time logs:

journalctl -u cloudflared -f

If you can see a successful connection in the logs and the domain is accessible, you're pretty much done.

Common Commands

Some Security Advice

Tunnel does not mean you can leave everything unprotected.

If it's an admin panel, it's best to add another layer of login, or use Cloudflare Access to restrict access. Otherwise, even if the port isn't exposed, the service itself might still get scanned.

Simply put: treat anything accessible from the public network as a public service. Don't take chances.

Without a public IP, not knowing how to configure port forwarding, and ISPs potentially blocking ports... you spend ages messing around, and your friends still can't join. It's pretty frustrating.

I solve this using WireGuard + a VPS. The core idea is: put your home computer and the VPS into the same virtual local area network (VLAN) first, and then let players connect through the VPS or a virtual IP.

Use Case

This guide is for when you are running a Minecraft server at home or in a dorm, but your friends can't connect from the outside network.

• You don't have a public IP, or your public IP is unstable.
• You don't want to deal with complex manual port forwarding on your router.
• You have a VPS with internet access.
• You are okay with Minecraft traffic being relayed through the VPS.

If you already have a public IP and port forwarding works reliably, you don't need WireGuard.

Two Solutions

Look at your needs first. Don't just force everyone to install WireGuard right away.

For beginners, I recommend starting with Solution A. Get it running first; don't overcomplicate things from the start.

Prerequisites

You will need:

1. A VPS with a public IP. Debian/Ubuntu is the easiest to use.
2. The WireGuard client installed on the host computer.
3. VPS firewall and cloud provider security groups configured to allow:
   • UDP 51820
   • TCP 25565
4. A Minecraft server that runs normally on the host computer.

If you can't even connect to Minecraft locally, fix Minecraft first. Don't suspect WireGuard yet.

Final Result

Once finished, friends can connect to your Minecraft server via the VPS entry point. The host computer and the VPS will form a virtual local network using WireGuard, and the VPS will forward external player connections to your home server.

If you use Solution B, players will also join the same WireGuard network, creating an experience closer to a LAN multiplayer game.

Installing WireGuard on the VPS

Run this on your VPS:

sudo apt update
sudo apt install wireguard -y

Generate the server keys:

sudo mkdir -p /etc/wireguard
cd /etc/wireguard
wg genkey | sudo tee privatekey | wg pubkey | sudo tee publickey

View the public key:

sudo cat /etc/wireguard/publickey

Do not share the private key. You can share the public key.

Enable IP forwarding:

sudo sysctl -w net.ipv4.ip_forward=1
sudo sed -i '/net.ipv4.ip_forward=1/s/^#//' /etc/sysctl.conf
sudo sysctl -p

Solution A: Public Forwarding

In this solution, your friends do not need to install WireGuard. They just connect directly to VPS公网IP:25565.

1. Generate Keys on the Host Computer

Open the WireGuard client and add an empty tunnel. The client will automatically generate a private key and a public key.

You only need to copy the host computer's public key to paste into the VPS configuration later.

2. Configure the VPS

Edit the configuration file:

sudo nano /etc/wireguard/wg0.conf

Example:

[Interface]
Address = 10.0.0.1/24
ListenPort = 51820
PrivateKey = <VPS私钥>

PostUp = iptables -A FORWARD -i wg0 -j ACCEPT; iptables -t nat -A PREROUTING -p tcp --dport 25565 -j DNAT --to-destination 10.0.0.2
PostDown = iptables -D FORWARD -i wg0 -j ACCEPT; iptables -t nat -D PREROUTING -p tcp --dport 25565 -j DNAT --to-destination 10.0.0.2

[Peer]
PublicKey = <服主电脑公钥>
AllowedIPs = 10.0.0.2/32

10.0.0.2 is the host computer's virtual IP inside WireGuard.

3. Configure the Host Computer

Fill this into the WireGuard client:

[Interface]
PrivateKey = <服主电脑私钥>
Address = 10.0.0.2/24
DNS = 1.1.1.1

[Peer]
PublicKey = <VPS公钥>
Endpoint = <VPS公网IP>:51820
AllowedIPs = 10.0.0.0/24
PersistentKeepalive = 25

The PrivateKey here is usually already filled in by the client. Don't accidentally overwrite it with the wrong one.

4. Start and Test

Start it on the VPS:

sudo wg-quick up wg0
sudo systemctl enable wg-quick@wg0

Start WireGuard on the host computer.

Then test it on the host computer:

ping 10.0.0.1

If the ping goes through, the tunnel is connected.

Next, start the Minecraft server. Have your friends connect to:

<VPS公网IP>:25565

If they can't connect, check if 25565 is allowed on the VPS first, and then check if the local firewall is blocking Java.

Solution B: Full Mesh Network

This solution acts more like a true virtual local network. Everyone gets a 10.0.0.x address.

This is best for a steady group of friends playing long-term. The downside is obvious: everyone has to install the client, and if even one config is wrong, they won't be able to connect.

1. Collect Everyone's Public Keys

Have every player install WireGuard, add an empty tunnel, and send their public key to you.

Assign an IP to everyone:

Do not overlap IPs. If they overlap, it's game over.

2. VPS Configuration

[Interface]
Address = 10.0.0.1/24
ListenPort = 51820
PrivateKey = <VPS私钥>

[Peer]
PublicKey = <服主公钥>
AllowedIPs = 10.0.0.2/32

[Peer]
PublicKey = <玩家A公钥>
AllowedIPs = 10.0.0.3/32

[Peer]
PublicKey = <玩家B公钥>
AllowedIPs = 10.0.0.4/32

For every new person, add another [Peer].

3. Player Client Configuration

Everyone's configuration looks similar, just with different private keys and addresses.

Server Host:

[Interface]
PrivateKey = <服主自己的私钥>
Address = 10.0.0.2/24
DNS = 1.1.1.1

[Peer]
PublicKey = <VPS公钥>
Endpoint = <VPS公网IP>:51820
AllowedIPs = 10.0.0.0/24
PersistentKeepalive = 25

Player A:

[Interface]
PrivateKey = <玩家A自己的私钥>
Address = 10.0.0.3/24
DNS = 1.1.1.1

[Peer]
PublicKey = <VPS公钥>
Endpoint = <VPS公网IP>:51820
AllowedIPs = 10.0.0.0/24
PersistentKeepalive = 25

The private key must belong to that specific person. Do not just mass-send the exact same config file; it won't work.

4. Connecting to the Game

Start on VPS:

sudo wg-quick up wg0
sudo systemctl enable wg-quick@wg0

After everyone starts WireGuard, ping each other:

ping 10.0.0.1
ping 10.0.0.2

If the ping goes through, players can just connect to the host's virtual IP:

10.0.0.2:25565

Troubleshooting

A few common issues:

Check WireGuard status:

sudo wg

You are only truly connected if you see a latest handshake. If there's no handshake, don't even look at Minecraft; the problem is still at the network layer.

Final Thoughts

My personal recommendations:

• Temporary server: Solution A.
• Fixed group of friends playing long-term: Solution B.
• Don't want to explain configs to everyone: Solution A.
• Want lower latency and better privacy: Solution B.

Get it running first, then optimize. If you try to make everything perfect from the start when dealing with networks, you'll likely get stuck on a really stupid config error.