--- 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、无需开端口。 ## 安装 ```bash apt update && apt install -y cloudflared ``` Termux 官方仓库自带,aarch64 架构原生支持。不要从 GitHub Releases 下载(容易被墙超时)。 ## Quick Tunnel(零配置,测试用) ```bash cloudflared tunnel --url http://localhost:5001 ``` 生成临时 URL `https://.trycloudflare.com`。重启进程 URL 会变。 **适用场景**:快速测试、临时分享。不适合生产(无 SLA、URL 不固定)。 ## 正式命名 Tunnel(永久 URL) 需要:Cloudflare 账号 + 域名 DNS 托管在 Cloudflare。 ```bash # 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 加载该凭据后使用错误的认证路径,导致请求无法路由到本地。 **修复**: ```bash 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` 从当前网络不可达(可能被墙)。 **诊断**: ```bash 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(新加坡边缘)。诊断命令: ```bash # 测 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`