1. 为什么“常用命令”这类需求，十有八九是XY问题
先说结论：当有人问“Cloudflare Tunnel 常用命令有哪些”的时候，他真正想解决的大概率不是“记不全命令”，而是“我的服务外网访问不了，不知道该从哪里下手”。这就是典型的XY问题。X是你问出来的那个问题，Y是你实际想解决的问题。
这种场景在运维群和论坛里太常见了。有人拿着cloudflared tunnel list、cloudflared tunnel run、cloudflared tunnel ingress validate这些命令代码碎片挨个试，试完还是不行就跑来问“Tunnel的常用命令有哪些？”。可问题从来不在命令多少，而在于他可能压根没分清：到底是隧道进程没起来，是DNS记录没生效，是Cloudflare边缘回源失败，还是他后端的Web服务本身挂了。命令背得再多，也只是把X问题做得更熟练，Y问题纹丝不动。
“常用命令大全”这类需求本身也容易陷入同样陷阱。我见过有人花了几天整理git常用命令总结，真正提交代码时遇到冲突照样慌；也有人把linux常用命令大全运维背得滚瓜烂熟，线上服务器磁盘满了却不知道用df -h先看一眼再du定位。命令是工具，不是目标。Cloudflare Tunnel相关命令也一样，你要的不是“全部命令”，而是一条能解决问题的诊断路径。
那怎么看自己是不是在问XY问题？三个信号：第一，问题描述里只出现了你想用的工具，没有出现你的实际架构；第二，没有贴日志或复现步骤，只说“不行”；第三，一上来就要“所有命令”“完整清单”，而不是“某个场景下该用什么”。如果三条里中了两条，恭喜，你已经陷进X问题里了。下面这篇文章我打算先把Cloudflare Tunnel的常用命令讲透，再把真正该掌握的排查思路串起来，让你下次遇到问题能直接定位，而不是背完命令还在原地打转。
2. Cloudflare Tunnel 核心命令速查与背后原理
2.1 生命周期五件套：login / create / route / run / delete
Cloudflare Tunnel的命令其实很少，真正贯穿隧道生命周期的就五条：login、create、route dns、run、delete。先说这几条，后面所有的排查都建立在它们之上。
cloudflared tunnel login，这条命令会打开浏览器让你选择域名并授权。它的作用不是创建隧道，而是生成本地证书，默认存放在~/.cloudflared/cert.pem。这个证书决定了你后续能用哪个账号、对哪些域名做操作。很多新手在这步卡住，浏览器打开后选了域名授权，但终端还停在“Waiting for login to complete...”没反应。多数情况是终端预览环境不支持回调跳转，直接把弹出的localhost链接完整复制到本机浏览器就行。注意，login是按账号授权的，不是按隧道授权。换了一台服务器，要重新login一次。
cloudflared tunnel create <隧道名>，创建的是“命名隧道”。它会在~/.cloudflared/下生成一个<隧道ID>.json文件，这个文件就是隧道的身份证。你后续的run、route、delete都可以直接用隧道名或隧道ID指代它。这里有个很多人忽视的点：隧道ID和cert.pem都要保存好，换机器后缺了<隧道ID>.json，run会直接报“找不到凭据”。
cloudflared tunnel route dns <隧道名> <域名>，这条命令干的事情是添加一条CNAME记录，把域名解析到<隧道ID>.cfargotunnel.com。它本质是把你自己的域名“绑定”到这条隧道上。如果你是在Cloudflare官网通过Dashboard创建隧道，它不会在本地生成隧道ID文件，而是给你一个Token，后面用run --token跑，这是两种不同创建方式，后面第3部分会专门对比。
cloudflared tunnel run <隧道名>，启动隧道进程，和Cloudflare边缘节点建立持久连接，把公网流量转发到本地的config.yml里配置的服务。你去看cloudflared tunnel list的输出，会看到每条隧道后面跟着连接状态和上次活跃时间。这里我建议把run放在systemd或Docker里跑，不要直接挂在终端。终端一关隧道就断，这是新手最常见的“没访问一会儿就挂了”的原因。
cloudflared tunnel delete <隧道名>，删除隧道前必须先删掉绑定DNS记录，否则要加--force。删隧道不等于删本地<隧道ID>.json，清理不彻底的话下次create同名隧道会冲突。这个细节官方文档写得不算明显，但实际踩的人非常多。
整个生命周期的逻辑可以用一句话串起来：login拿到操作权限，create造出隧道身份，route dns把域名和隧道系起来，run让隧道真正跑起来，delete是回收站。掌握了这一条线，命令就不是死记硬背，而是有前因后果的。
2.2 调试三兄弟：--url临时隧道 / ingress validate / list
顺着生命周期再往下，有三个调试命令你在排障时会频繁用到。
第一个是cloudflared tunnel --url http://localhost:3000，不需要登录、不需要创建隧道，它会快速生成一个https://<随机字符串>.trycloudflare.com的临时公网地址，直接暴露你本地的Web服务。这个机制特别适合开发联调场景，比如本地起了个前端项目，想让同事或者微信支付的回调临时访问一下，不用去折腾域名和DNS。缺点也很明显：URL每次启动都会变，没法用于固定域名，也不能挂正式环境。
第二个是cloudflared tunnel ingress validate，它会读取本地的config.yml，校验ingress规则有没有语法错误、hostname有没有重复、service格式对不对。这个命令在改完配置后务必执行一次。它不会真正连远端，只是做本地静态校验，报错信息比如Duplicate hostname、service URL scheme missing都能在启动之前就暴露出来。我自己每次改配置必跑一遍，能省掉很多“改了配置但看不懂日志”的时间。
第三个是cloudflared tunnel list，列出当前账号下所有命名隧道，包括隧道ID、名称、创建时间、连接状态。排障的第一步基本都从它开始：先确认你要访问的那条隧道是不是真的存在、当前有没有连接。
这三条命令加上前面的生命周期命令，已经能覆盖90%的日常操作。但请注意，这里还没有出现“出错了怎么查”的命令，那是后面第4部分的重点。
2.3 Docker部署时，环境变量比命令行参数更好用
现在很多人跑Cloudflare Tunnel都是基于Docker，因为不用污染宿主机环境，一条docker run就起来了。对比裸机部署，Docker方式里使用最频繁的其实不是命令行参数，而是环境变量。
官方镜像cloudflare/cloudflared最核心的变量就是TUNNEL_TOKEN。你在Cloudflare Dashboard的Zero Trust面板里创建隧道后，会拿到一个Token，Docker运行时只需：
docker run -d --name cloudflared \ --restart=unless-stopped \ -e TUNNEL_TOKEN=你的Token \ cloudflare/cloudflared:latest \ tunnel --no-autoupdate run --token 你的Token这里最关键的一点是，通过Token方式运行时不需要本地cert.pem和<隧道ID>.json，因为Token本身就是一次性打包好的身份凭据。很多人在容器里找不到~/.cloudflared目录就开始怀疑自己的部署方式有问题，其实Token模式压根不强依赖那些文件。
如果你是通过本地create创建的命名隧道，再用Docker启动，则需要把宿主机的~/.cloudflared/目录挂载进容器：
docker run -d --name cloudflared \ -v ~/.cloudflared:/etc/cloudflared \ --network host \ cloudflare/cloudflared:latest \ tunnel --config /etc/cloudflared/config.yml run <隧道名>关于--network host，我认为能用就不要省。它让cloudflared直接共享宿主机网络栈，访问localhost:8080这类地址时就是访问宿主机上的服务。如果你用默认的bridge网络，localhost指向的是容器自己，你几乎一定会遇到“隧道起来了但页面502”的尴尬局面。
另外TUNNEL_INGRESS变量可以让你不写config.yml就定义ingress规则。官方支持把这个变量设成一个JSON数组，格式长这样：
-e TUNNEL_INGRESS='[{"hostname":"app.example.com","service":"http://web:8080"},{"service":"http_status:404"}]'最后一条{"service":"http_status:404"}是兜底规则，所有没匹配到具体hostname的请求都返回404。我个人强烈建议不管用什么方式部署都保留这个兜底，否则Cloudflare边缘拿到一条没有匹配规则的请求时，行为会变得很不直观，排障会更痛苦。
命令行参数和环境变量的关系，可以看成是“两套表达方式”：命令行适合临时调试，环境变量适合写进compose文件长期运行。比如cloudflared tunnel run --token xxx对应环境变量TUNNEL_TOKEN，--url对应TUNNEL_URL，--config对应TUNNEL_CONFIG_FILE。至于用哪套，取决于你要不要上编排系统。跑在K8s里就老老实实用环境变量，跑在单机上命令行完全够用。
3. 实操：三步把本地服务跑通一个稳定的 Tunnel
3.1 准备阶段：安装并确认cloudflared可用
第2部分讲了命令，这一部分我们完整走一遍实操。目标很简单：一台服务器（或者一台家里的小主机），上面跑着一个Web服务，端口是8080，我们要用app.example.com通过Cloudflare Tunnel把它暴露到公网。
第一步是安装cloudflared。Debian/Ubuntu直接用官方仓库装：
sudo apt-get update sudo apt-get install -y cloudflared cloudflared --version安装完先确认版本号能正常输出。如果你是在较老的系统上装，可能遇到缺少依赖的问题，直接用官方预先编译好的二进制包也行：
wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 chmod +x cloudflared-linux-amd64 sudo mv cloudflared-linux-amd64 /usr/local/bin/cloudflared这里有个职业习惯想分享给你：装完后先跑一下cloudflared tunnel --help，不用看全，只看你关心的那几个命令是否存在。不同版本的参数可能有差异，比如老版本用cloudflared tunnel route，新版本可能已经改了写法。先确认版本再往下走，能避免后面拿着旧教程踩坑。
3.2 创建隧道、绑定域名、编写config.yml
然后执行登录授权：
cloudflared tunnel login浏览器打开后选择example.com所在账号，授权成功后终端显示Successfully logged in。紧接着创建命名隧道：
cloudflared tunnel create app-tunnel成功后终端会打印隧道ID和凭据文件路径，类似/home/user/.cloudflared/<隧道ID>.json。然后绑定域名：
cloudflared tunnel route dns app-tunnel app.example.com这一步会在Cloudflare侧对app.example.com创建一条CNAME记录，指向<隧道ID>.cfargotunnel.com。如果这里提示E_DNS_RECORD_EXISTS，说明同名记录已经存在，先去DNS面板删掉旧记录再重新执行。
接下来编写配置文件，位置是~/.cloudflared/config.yml，内容如下：
tunnel: app-tunnel credentials-file: /home/user/.cloudflared/<隧道ID>.json ingress: - hostname: app.example.com service: http://localhost:8080 - service: http_status:404注意credentials-file必须是绝对路径，写~/.cloudflared是可以的，但你在systemd服务里跑的时候，~不一定展开成你想要的路径，我吃过这个亏，直接写绝对路径最省心。写完后立刻校验：
cloudflared tunnel ingress validate如果输出Validating rules... OK，说明配置没问题。到这一步，隧道还没在跑，域名也解析不出什么内容，千万别急着去浏览器访问。
3.3 正式启动：从前台到后台再到服务化管理
前台启动最方便观察首次运行情况：
cloudflared tunnel run app-tunnel看到日志出现Registered tunnel connection之类的信息，再开第二个终端用curl -I https://app.example.com验证。如果首页能正常返回200，说明流程通了。
这时候立刻把进程交给systemd托管，防止终端退出后隧道失联：
cloudflared service install sudo systemctl enable cloudflared sudo systemctl start cloudflaredcloudflared service install会自动读取~/.cloudflared/config.yml，把它注册成systemd服务。启动后确认状态：
sudo systemctl status cloudflared sudo journalctl -u cloudflared -f --no-pager日志里如果能看到多条连接状态由connecting变成connected，说明它和Cloudflare边缘的几条连接都建好了。到这里，一个稳定可用的Tunnel就算完整落地了。后面你再改配置，只需三步：vi ~/.cloudflared/config.yml、cloudflared tunnel ingress validate、sudo systemctl restart cloudflared。
4. 当“Y”真实问题出现时：从报错定位到可用的排查命令
4.1 三种典型报错：凭据缺失、隧道未注册、证书过期
命令流程走通了，但真正检验你是否理解这套东西的时刻，是在你接到“外网打不开”的报障消息时。我按自己在群里帮人看问题的经验，整理了三个出现频率最高的报错。
第一个是error: unable to find credentials file。启动run时cloudflared在你指定的路径下找不到JSON凭据文件。原因通常是：第一，你换了用户运行，比如之前用root创建的隧道，现在用ubuntu用户去run；第二，你在Docker里挂载路径写错了；第三，你直接把原来的配置文件拷到新机器，但没一起拷凭据文件。解决办法很简单：确认当前运行用户的家目录下有<隧道ID>.json，路径和config.yml里credentials-file完全一致。
第二个是ERR Tunnel not found、INVALID_REQUEST这类注册失败报错。意思是Cloudflare侧不认识你提供的隧道ID或Token。这种情况最常见的原因是：你在A账号创建了隧道，然后跑到B账号控制的域名下用；或者Token是从Dashboard复制的，复制时包含了换行符，导致认证失败。你重新复制Token时注意别带空格；用命名隧道的，检查一下cloudflared tunnel list输出里到底有没有这个名字的隧道。
第三个是certificate has expired或token is expired。cert.pem的有效期我记得是十年左右，Token模式一般是一段时间有效，长时间挂机之后可能出现Token过期。解决方案分别是重新执行cloudflared tunnel login重新授权，或者去Dashboard生成一个新Token刷新部署。这类问题和你的Web服务本身没有任何关系，如果是刚接手别人留下的系统，先看证书和Token，再去折腾后端。
4.2 日志与系统命令组合：从日志金矿里捞线索
报错信息只是线索，真正完整的证据链在日志里。裸机部署用journalctl，Docker部署用docker logs。这里说两个高频组合：
sudo journalctl -u cloudflared -f --no-pager | grep -i error-f是持续跟踪，--no-pager防止日志太多卡在less里。先不跟grep，把最近几十行都看一遍，再去抓error级别。很多时候你觉得没线索，其实是filter太早，把上下文丢了。
Docker场景则常用：
docker logs --tail 200 cloudflared输出量很大时，先看时间范围内最后几行，再搜关键词。日志里反复出现的connection、register、reconnect这几个关键词是有分量的。Registered tunnel connection说明注册成功；频繁Reconnecting说明网络到Cloudflare边缘的链路不稳定；Unable to unmarshal说明config.yml写错了。
另外一个很容易漏掉的排查来源是Cloudflare Dashboard的Analytics。在Zero Trust面板里选中对应的隧道，能看到小时级别的流量和请求统计。如果面板上有请求记录，但服务器日志完全没有对应报文，问题大概率出在ingress规则和本地服务之间。如果面板上压根没有记录，说明请求根本没到Cloudflare边缘，那就要去查域名解析。
4.3 常见问题速查表
这里放一张速查表，适合贴在屏幕上，遇到问题先对号入座。
| 症状 | 可能原因 | 优先命令/操作 |
|---|---|---|
| 域名访问超时 | DNS记录未生效或CNAME指向错误 | dig app.example.com +short确认是否返回<隧道ID>.cfargotunnel.com |
| 页面显示523 Origin Unreachable | 隧道进程和边缘连接断了 | cloudflared tunnel list看连接状态，重启cloudflared进程 |
| 页面显示522 Connection timed out | 隧道进程到边缘建连超时，多为本地出网问题 | 检查journalctl -u cloudflared里connection日志，确认cloudflared运行正常 |
| 页面显示524 Timeout | 本地Web服务响应过慢 | curl -I http://localhost:8080直连本地服务，检查后端耗时 |
| 502 Bad Gateway反复出现 | ingress配置的service地址错误 | cloudflared tunnel ingress validate+ 确认localhost是否写对，Docker记得考虑网络模式 |
ERR Tunnel not found | 隧道ID/Token和账号不匹配 | cloudflared tunnel list核对隧道名，Dashboard重新生成Token |
| 打开页面提示证书错误 | 证书过期或域名SSL模式异常 | cloudflared tunnel login重新授权，检查SSL/TLS加密模式 |
这张表的逻辑其实是把一条访问链路切成五段：客户端到Cloudflare边缘、边缘到Tunnel连接、Tunnel到本地服务、本地服务本身、Cloudflare域名配置。任何一段出问题，表现都会不一样。所以你下次遇到“打不开”，别一上来就怀疑Cloudflare Tunnel整体坏了。先用curl -I https://你的域名看HTTP状态码：能拿到状态码说明链路通到了边缘；拿不到说明解析或边缘就没通。再curl -I http://localhost:8080测本地。两头一夹，问题落在哪一段马上就清楚了。
5. 别让X问题吞掉真正的Y问题：推荐一整套排查顺序
5.1 分层排查，不打乱仗
最后这部分，我想把前面所有命令收敛成一整套排查顺序。这套顺序的核心是先确认问题边界，再动手跑命令。
顺序大概是这样的：
- 先确认现象：直接
curl -I https://app.example.com，记录HTTP状态码。 - 再确认DNS：
dig app.example.com +short，看看结果是不是<隧道ID>.cfargotunnel.com。 - 确认隧道本体：
cloudflared tunnel list，看目标隧道是否正常在线。 - 确认本地进程：
systemctl status cloudflared或docker ps | grep cloudflared。 - 确认配置：
cloudflared tunnel ingress validate。 - 确认上游服务：
curl -I http://localhost:8080。
每一步都是上一层的证据，也是下一层的铺垫。如果你一上来就重启cloudflared，但它本身没病，那是在白折腾。我在实际排障中见过最浪费时间的操作，就是“不管三七二十一，把所有服务全重启一遍”。重启一时爽，问题却像打地鼠一样换个地方冒出来。
5.2 我实际排查时必问的五个问题
如果你是在帮别人远程看问题，文字沟通效率很低，上面这套命令也很难直接甩给对方。我给自己的规矩是先问五个问题：
- 你的服务是什么架构，是Docker还是裸机跑？
- 访问域名直接返回什么？是超时、526、还是空白页？
cloudflared的最近一条日志是什么，贴原文出来？- 这个服务之前是好的吗？最近做过什么改动？
- 本地直连服务通不通？
curl http://localhost:端口号有反应吗？
这五个问题问完，大多数XY问题就已经被消解了。你会发现对方想表达的“常用命令有哪些”，其实转化成“我的config.yml里service写成了https，现在一直502怎么改”这种具体问题。到这一步，具体问题配具体命令，答案很容易出来。
这套思路不只适用于Cloudflare Tunnel。你学习linux常用命令大全、背git常用命令总结、查docker常用命令，其实都应该先问自己一句：我现在到底要解决什么？需要查昨天哪个日志文件变大，就去学du和ls；需要找出容器里谁在疯狂刷日志，就去学docker logs加grep；需要看某条隧道为什么连不上边缘，才需要看cloudflared tunnel list和journalctl。把Y问题定义清楚，X问题的命令自然会出现在你手边。
我现在维护的几条隧道里，有一条已经连续跑了将近一年没动过。不是我运气好，而是当初部署时就把systemd、日志、DNS记录和config.yml四件套一次配齐了。平时唯一要做的就是偶尔看一眼journalctl -u cloudflared有没有刷错误。真正让我省心的不是记住了多少命令，而是出了一次问题之后，终于学会了按照链路去排查——那比背下所有命令有价值得多。
