运维与排障
上线检查清单
text
□ nginx -t 通过，且 nginx -V 里能看到模块（或 modules-enabled 里有链接）
□ 凭据来源只有一个（credentials / token / token_file / quick 四选一）
□ 凭据文件对 worker 用户可读（chmod 600 + chown www-data）
□ inject_listen 指向的 listen 在同一个 nginx 里存在
□ 大上传的 client_max_body_size / client_body_timeout 已放开
□ 用了 realip 的话，set_real_ip_from 与新地址一致（见「真实客户端 IP」）
□ worker_connections / worker_rlimit_nofile 有余量（每条在途注入连接 = 1 个连接槽 + 2 个 fd）
□ allow/deny、limit_req/limit_conn 里按 127.0.0.1 写的键已按需更新
□ 重启（restart）而不是 reload看日志
bash
grep -E 'cfd_tunnel' /var/log/nginx/error.log | tail -50- 成功注册：NOTICE
cfd_tunnel: 已注册到边缘（location=…），注入目标 … - 多隧道带前缀：
cfd_tunnel: [edge-a] …（扁平那条不带前缀，与 0.10.0 逐字节一致） - 失败一律 ERR，并且带原因：连接边缘失败、凭据读取失败、token 解析失败、provisioning 失败、 裸TCP 流被丢弃、注入目标不存在、纯端口有歧义……
- 要协议细节：
cfd_tunnel_verbose on（INFO 级，量大，别长期开）
排障对照表
| 症状 | 可能原因 | 怎么办 |
|---|---|---|
完全没有 cfd_tunnel 日志 | 模块没加载 / 三种凭据来源都没写 / 配置被 include 漏掉 | nginx -V 看模块；补凭据；确认 include modules-enabled/*.conf |
| 「读取凭据 … 失败」 | 权限或路径 | chown www-data、chmod 600、绝对路径 |
| 「token 不是合法的 base64」 | 内联 token 尾部有空白（不 trim） | 删掉空白，或改用 token_file（会 TrimSpace） |
| 「token 带 endpoint/region」 | token 里有 e（如 FedRAMP） | 本模块只连一个 cfd_tunnel_edge，这条不支持 |
| 注册成功但访问 404 | Host 没命中任何 server_name，落到默认 server | 写 server_name，或用 host_override |
| 访问落到错的后端 | 多条隧道指向同一端口 | 让每条隧道用不同的 inject_listen |
| 上传大文件 413 | client_max_body_size 默认 1m | 放开到需要的大小 |
| 上传大文件 504 / 断 | client_body_timeout 默认 60s | 放开 client_body_timeout |
$remote_addr 全是 127.0.0.1 | 没配 realip 或 inject_source_addr | 见 真实客户端 IP |
隧道请求被 deny 掉 | realip 让地址变了 | 规则按新地址写 |
| 边缘回 502 | 远程规则命中不支持的 service | 本地写 inject_listen，或改 dashboard 的 ingress |
| ssh / rdp 连不上 | 裸 TCP 不支持（定案） | 用 cloudflared，或用别的方案 |
| 连接反复重连 | 边缘不可达 / 证书校验失败 / 代理没配 | 看 ERR 行；cfd_tunnel_verbose on；cfd_tunnel_ca_file |
日志字典
完整的消息清单（含频道与级别）见 日志与错误消息。
重启 vs reload
bash
nginx -t && systemctl restart nginx # 必须 restartload_module 发生在配置解析之前，reload 不会重新加载动态模块 —— 升了 .deb 之后尤其注意。
快速隧道运维
bash
cfd-quick-url # 最新一条临时地址
cfd-quick-url -a # 全部
grep -c '快速隧道临时地址' /var/log/nginx/error.log临时隧道重启即换地址、失败不重试，只适合演示与自测。
抓现场
bash
# worker 崩溃调用栈（配置里先有 env CFD_CRASH_BACKTRACE;）
CFD_CRASH_BACKTRACE=/var/log/nginx/crash.txt nginx
addr2line -f -C -e /usr/lib/nginx/modules/ngx_http_cfd_tunnel_module.so <偏移>
# 死循环
kill -ABRT <worker_pid>