SKILL.md 5.91 KB

name: android-cloudflare-tunnel description: 在 Android/Termux 上通过 Cloudflare Tunnel 将本地服务暴露到公网——安装、Quick Tunnel、正式命名隧道、故障排查。触发词:cloudflare tunnel、反向代理、公网访问、内网穿透、trycloudflare、cloudflared。 version: 1.0

category: android

Cloudflare Tunnel on Android/Termux

将本地 Web 服务(如 Flask、Hermes Dashboard、WeChat Viewer)通过 Cloudflare Tunnel 暴露到公网,无需公网 IP、无需开端口。

安装

apt update && apt install -y cloudflared

Termux 官方仓库自带,aarch64 架构原生支持。不要从 GitHub Releases 下载(容易被墙超时)。

Quick Tunnel(零配置,测试用)

cloudflared tunnel --url http://localhost:5001

生成临时 URL https://<random>.trycloudflare.com。重启进程 URL 会变。

适用场景:快速测试、临时分享。不适合生产(无 SLA、URL 不固定)。

正式命名 Tunnel(永久 URL)

需要:Cloudflare 账号 + 域名 DNS 托管在 Cloudflare。

# 1. 登录(浏览器打开授权链接)
cloudflared tunnel login

# 2. 创建隧道
cloudflared tunnel create wechat-viewer

# 3. 绑定 DNS(把子域名指向隧道)
cloudflared tunnel route dns wechat-viewer wechat.your-domain.com

# 4. 启动
cloudflared tunnel run wechat-viewer --url http://localhost:5001

如果 OAuth 回调 URL 被墙(cloudflared tunnel login 报 i/o timeout),浏览器会下载 cert.pem 到本地。手动复制到 ~/.cloudflared/cert.pem 即可。

故障排查

Quick Tunnel 连接成功但 curl 返回 404

症状:cloudflared 日志显示 Registered tunnel connection,但访问 URL 返回 HTTP 404(Cloudflare 边缘返回,非本地服务返回)。

根因:~/.cloudflared/cert.pem 存在(来自之前 cloudflared tunnel login 的残留)。cloudflared 加载该凭据后使用错误的认证路径,导致请求无法路由到本地。

修复:

rm -f ~/.cloudflared/cert.pem ~/.cloudflared/config.yml ~/.cloudflared/*.json

清理后重启 cloudflared 即可。cert.pem 只用于命名隧道,Quick Tunnel 不需要它。

新建隧道失败 Post api.trycloudflare.com: EOF

症状:cloudflared tunnel --url ... 立即退出,报 failed to request quick Tunnel: Post "https://api.trycloudflare.com/tunnel": EOF。

根因:api.trycloudflare.com 从当前网络不可达(可能被墙)。

诊断:

curl -s --connect-timeout 5 https://api.trycloudflare.com/tunnel -X POST
# HTTP 000 = 不通
# HTTP 200 = 正常

修复:切换网络(WiFi ↔ 移动数据),或等待网络恢复。api.cloudflare.com 通常走不同线路,可能仍然可达(用 curl https://api.cloudflare.com/cdn-cgi/trace 验证)。

隧道断连(QUIC timeout)

症状:运行一段时间后日志出现 timeout: no recent network activity,自动重连后可能成功也可能持续失败。

Quick Tunnel 无 SLA,网络波动时这是正常现象。cloudflared 会自动重试。如在生产环境使用,建议走正式命名隧道(稳定性更好)。

本地服务必须先启动

cloudflared 启动时不会检查目标端口是否可达。先确保 Flask/Web 服务已在监听,再启动隧道。隧道运行期间重启本地服务后无需重启隧道(cloudflared 会继续转发新请求)。

⚠️ 看门狗探测把健康隧道当异常杀掉(2026-08-13 实测)

症状:隧道进程每 10 分钟闪断一次(Registered tunnel connection 后又消失),公网间歇性 502/530。

根因:wechat-viewer 看门狗用 curl https://task.hexdo.com/api/doctor 探测隧道,只认 200。但 /api/doctor 不在登录白名单,公网未登录请求返回 302(跳 /login)——302 恰恰证明请求已穿透隧道到达 origin。看门狗误判异常 → pkill 重启隧道 → 死循环。

修复:看门狗判定改为接受 200 或 302([ "$PUBLIC_CODE" != "200" ] && [ "$PUBLIC_CODE" != "302" ] 才重启)。

教训:探测隧道健康时,用「能否拿到 origin 的任意响应」判断,不要对未登录端点期望 200;或者把探测端点放进公开白名单。

⚠️ Cloudflare edge 国内间歇性不可达 → VPN 可解(2026-08-13 两次实测)

症状:隧道日志全是 DialContext error: dial tcp 198.41.x.x:7844 i/o timeout(或 443 也超时),公网 task.hexdo.com 无法访问;本地 Flask 正常(5001 → 200)、国内网站(百度)正常。

根因:Cloudflare edge 在国内出口间歇性被墙/不可达(443+7844 全超时 = 整体不可达,不是 QUIC 单端口问题)。配置 protocol: http2 也救不了(http2 也要连 edge)。

解法:开 VPN(全局代理)——cloudflared 流量走代理出口后自动恢复,无需手动重启(重试窗口 8-32 秒内自动注册成功)。日志特征:连接 IP 变为 198.18.x.x(VPN fake-ip 段)、location=sinXX(新加坡边缘)。诊断命令:

# 测 Cloudflare 可达性(443 和 7844 都超时 = 整体被墙)
timeout 8 curl -s -o /dev/null -w '%{http_code}' https://www.cloudflare.com
timeout 8 bash -c 'echo > /dev/tcp/198.41.200.73/7844' && echo 7844-OK || echo 7844-FAIL
# 隧道是否已走 VPN 恢复(看日志里的 198.18.x.x 和 Registered tunnel connection)
tr -d '\000' < ~/.cloudflared/tunnel.log | tail -5

其他坑:

  • tunnel.log 可能被并发写坏(多个 cloudflared 重启实例 + > tunnel.log 截断)→ 出现 NUL 字节刷屏,用 tr -d '\000' 过滤查看;看门狗下次重启会自动重建日志文件。
  • 看门狗在公网不通时会反复重启隧道(网络没恢复时重启无效但无害),网络恢复后隧道自动连上。

配合登录认证

公网暴露后必须加登录保护。Flask session auth 完整实现参考:references/flask-session-auth.md