{"id":45483396,"url":"https://github.com/qingchencloud/cftunnel","last_synced_at":"2026-03-01T02:00:41.477Z","repository":{"id":339970667,"uuid":"1163979872","full_name":"qingchencloud/cftunnel","owner":"qingchencloud","description":"全协议内网穿透 CLI — Cloud 模式免费 HTTP/WS 穿透 + Relay 模式自建中继 TCP/UDP 全协议 | Cloudflare Tunnel + frp 双引擎","archived":false,"fork":false,"pushed_at":"2026-02-26T17:28:31.000Z","size":6842,"stargazers_count":77,"open_issues_count":2,"forks_count":13,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-28T04:12:59.819Z","etag":null,"topics":["ai-coding","ai-friendly","cli","cloudflare","cloudflare-tunnel","cross-platform","devtools","frp","frpc","frps","golang","homelab","intranet-penetration","nat-traversal","port-forwarding","reverse-proxy","self-hosted","tcp-tunnel","tunnel","udp-tunnel"],"latest_commit_sha":null,"homepage":"https://cftunnel.qt.cool","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qingchencloud.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-22T13:05:31.000Z","updated_at":"2026-02-28T04:04:45.000Z","dependencies_parsed_at":"2026-02-28T01:04:30.346Z","dependency_job_id":null,"html_url":"https://github.com/qingchencloud/cftunnel","commit_stats":null,"previous_names":["qingchencloud/cftunnel"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/qingchencloud/cftunnel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qingchencloud%2Fcftunnel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qingchencloud%2Fcftunnel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qingchencloud%2Fcftunnel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qingchencloud%2Fcftunnel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qingchencloud","download_url":"https://codeload.github.com/qingchencloud/cftunnel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qingchencloud%2Fcftunnel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29958378,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T01:47:18.291Z","status":"online","status_checked_at":"2026-03-01T02:00:07.437Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-coding","ai-friendly","cli","cloudflare","cloudflare-tunnel","cross-platform","devtools","frp","frpc","frps","golang","homelab","intranet-penetration","nat-traversal","port-forwarding","reverse-proxy","self-hosted","tcp-tunnel","tunnel","udp-tunnel"],"created_at":"2026-02-22T16:36:00.840Z","updated_at":"2026-03-01T02:00:41.396Z","avatar_url":"https://github.com/qingchencloud.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# cftunnel\n\n[![GitHub release](https://img.shields.io/github/v/release/qingchencloud/cftunnel)](https://github.com/qingchencloud/cftunnel/releases)\n[![Go Report Card](https://img.shields.io/badge/go%20report-A+-brightgreen?style=flat\u0026logo=go)](https://goreportcard.com/report/github.com/qingchencloud/cftunnel)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n**全协议内网穿透工具** — Cloud 模式免费穿透 HTTP/WS + Relay 模式自建中继 TCP/UDP 全协议。\n\n[双模式对比](#compare) · [安装](#install) · [快速上手](#quickstart) · [中继服务端部署](#relay-server) · [命令参考](#commands) · [故障排查](#troubleshooting) · [AI 助手集成](#ai) · [交流](#contact)\n\n关联项目：[cftunnel-app 桌面客户端](https://github.com/qingchencloud/cftunnel-app)（[下载](https://github.com/qingchencloud/cftunnel-app/releases)） · [ClawApp](https://github.com/qingchencloud/clawapp) · [OpenClaw 中文翻译](https://github.com/1186258278/OpenClawChineseTranslation)\n\n\u003cp align=\"center\"\u003e\n  \u003cvideo src=\"docs/videos/promo.mp4\" width=\"720\" controls\u003e\u003c/video\u003e\n\u003c/p\u003e\n\n\u003e 本地跑着服务想让外面访问？游戏服务器需要公网端口？SSH 远程连接没有公网 IP？\n\u003e\n\u003e cftunnel 提供两种穿透模式，一个工具覆盖所有场景。\n\n**Cloud 模式**（基于 Cloudflare，免费 HTTP/WS 穿透）：\n\n```bash\ncftunnel quick 3000\n# ✔ 隧道已启动: https://xxx-yyy-zzz.trycloudflare.com\n```\n\n**Relay 模式**（自建中继，TCP/UDP 全协议穿透）：\n\n```bash\ncftunnel quick 25565 --relay\n# ✔ 中继穿透: tcp://localhost:25565 → 远程端口 25565\n```\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/terminal-demo.gif\" alt=\"cftunnel 演示\" width=\"720\"\u003e\n\u003c/p\u003e\n\n\u003ch2 id=\"compare\"\u003e双模式对比\u003c/h2\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/compare-chart.gif\" alt=\"功能对比\" width=\"720\"\u003e\n\u003c/p\u003e\n\n| 对比项 | Cloud 模式 | Relay 模式 |\n|--------|-----------|-----------|\n| 引擎 | cloudflared (Cloudflare Tunnel) | frpc/frps (frp) |\n| 协议 | HTTP / HTTPS / WebSocket | TCP / UDP / HTTP / 全协议 |\n| 需要 | Cloudflare 账户（免费） | 自备公网服务器 |\n| 域名 | 自动分配 `*.trycloudflare.com` 或自有域名 | 通过 IP + 端口访问 |\n| 加密 | Cloudflare 全程加密 + 全球 CDN | 自行配置（frp 内置 token 鉴权） |\n| 费用 | 免费 | 服务器费用（最低 $3/月） |\n| 典型场景 | Web / API / Webhook / 前端预览 | 游戏服务器 / 数据库 / SSH / 远程桌面 |\n| 快速启动 | `cftunnel quick 3000` | `cftunnel quick 25565 --relay` |\n| 系统服务 | `cftunnel install` | `cftunnel relay install` |\n\n两种模式独立共存，互不干扰，可以同时使用。\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#cftunnel\"\u003e⬆ 回到顶部\u003c/a\u003e\u003c/p\u003e\n\n\u003ch2 id=\"features\"\u003e特性\u003c/h2\u003e\n\n**Cloud 模式（Cloudflare Tunnel）：**\n- **免域名模式** — `cftunnel quick \u003c端口\u003e`，零配置生成 `*.trycloudflare.com` 临时公网地址\n- **访问保护** — `--auth user:pass` 一键启用密码保护，内置鉴权代理中间件\n- **极简操作** — `init` → `create` → `add` → `up`，4 步搞定自有域名穿透\n- **自动 DNS** — 添加路由时自动创建 CNAME 记录，删除时自动清理\n\n**Relay 模式（自建中继）：**\n- **全协议穿透** — TCP / UDP / HTTP，游戏服务器、数据库、SSH、远程桌面\n- **一键部署** — 服务端 `curl | bash` 或 Docker Compose，客户端 `relay init` 即连\n- **快速穿透** — `cftunnel quick \u003c端口\u003e --relay`，无需预配置规则\n\n**通用：**\n- **跨平台** — macOS (Intel/Apple Silicon) + Linux (amd64/arm64) + Windows (amd64/arm64)\n- **进程托管** — 自动下载引擎二进制，支持 macOS launchd / Linux systemd / Windows Service\n- **自动更新** — 内置版本检查和一键自更新\n- **便携模式** — 程序同级目录放 `portable` 空文件，配置/日志/二进制就地存储\n- **桌面客户端** — [cftunnel-app](https://github.com/qingchencloud/cftunnel-app) 提供可视化 GUI\n- **AI 友好** — 内置 Claude Code / OpenClaw Skills，AI 助手可直接管理隧道\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#cftunnel\"\u003e⬆ 回到顶部\u003c/a\u003e\u003c/p\u003e\n\n\u003ch2 id=\"architecture\"\u003e架构原理\u003c/h2\u003e\n\ncftunnel 提供两种穿透引擎，按场景选择：\n\n**Cloud 模式** — 流量经过 Cloudflare 全球 CDN，自带 HTTPS，无需公网 IP：\n\n```\nlocalhost:3000 → cftunnel → cloudflared → Cloudflare Edge → 公网用户\n                 (管理层)    (隧道进程)     (全球 CDN)       (通过域名访问)\n```\n\n**Relay 模式** — 流量经过你的公网服务器，支持全协议：\n\n```\nlocalhost:25565 → cftunnel → frpc → 你的公网服务器(frps) → 远程访问\n                  (管理层)   (客户端)   (中继服务端)        (通过 IP:端口)\n```\n\ncftunnel 本身是管理层，负责配置管理、进程编排、二进制下载，不经手流量。\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#cftunnel\"\u003e⬆ 回到顶部\u003c/a\u003e\u003c/p\u003e\n\n\u003ch2 id=\"install\"\u003e安装\u003c/h2\u003e\n\n### 一键安装（推荐）\n\n**macOS / Linux：**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/qingchencloud/cftunnel/main/install.sh | bash\n```\n\n**Windows（PowerShell）：**\n\n```powershell\nirm https://raw.githubusercontent.com/qingchencloud/cftunnel/main/install.ps1 | iex\n```\n\n### 手动下载\n\n从 [Releases](https://github.com/qingchencloud/cftunnel/releases) 下载对应平台的二进制文件。\n\n### 从源码构建\n\n```bash\ngit clone https://github.com/qingchencloud/cftunnel.git\ncd cftunnel \u0026\u0026 make build\n```\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#cftunnel\"\u003e⬆ 回到顶部\u003c/a\u003e\u003c/p\u003e\n\n\u003ch2 id=\"quickstart\"\u003e快速上手\u003c/h2\u003e\n\n### 方式一：免域名模式（零配置）\n\n无需账户、Token、域名，装好就能用：\n\n```bash\ncftunnel quick 3000\n# ✔ 隧道已启动: https://xxx-yyy-zzz.trycloudflare.com\n```\n\n需要密码保护？加上 `--auth`：\n\n```bash\ncftunnel quick 3000 --auth admin:secret123\n```\n\n\u003e 适合临时分享和调试，Ctrl+C 退出后域名自动失效。\n\n### 方式二：自有域名模式（Cloudflare）\n\n\u003e 前提：需要 Cloudflare 账户和至少一个已添加的域名。\n\n1. 创建 [API 令牌](https://dash.cloudflare.com/profile/api-tokens)（需要 3 条权限：Cloudflare Tunnel 编辑 + DNS 编辑 + 区域设置读取）\n2. 获取账户 ID（Cloudflare 首页 → 点击域名 → 右下角「API」区域）\n\n```bash\ncftunnel init --token \u003cyour-token\u003e --account \u003caccount-id\u003e\ncftunnel create my-tunnel\ncftunnel add myapp 3000 --domain app.example.com\ncftunnel up\n# 搞定！app.example.com → localhost:3000\n```\n\n### 方式三：中继模式（全协议穿透）\n\n\u003e 前提：需要一台公网服务器（任意云服务商的 VPS 即可）。\n\n**第 1 步：部署服务端**（见下方 [中继服务端部署](#relay-server)）\n\n**第 2 步：客户端配置**\n\n```bash\n# 使用服务端输出的连接命令\ncftunnel relay init --server 1.2.3.4:7000 --token abc123\n\n# 添加穿透规则\ncftunnel relay add minecraft --local 25565 --remote 25565 --proto tcp\ncftunnel relay add ssh --local 22 --remote 6022 --proto tcp\n\n# 启动\ncftunnel relay up\n\n# 开机自启\ncftunnel relay install\n```\n\n**快速穿透（无需预配置规则）：**\n\n```bash\ncftunnel quick 25565 --relay              # TCP 穿透\ncftunnel quick 9987 --relay --proto udp   # UDP 穿透\n```\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#cftunnel\"\u003e⬆ 回到顶部\u003c/a\u003e\u003c/p\u003e\n\n\u003ch2 id=\"relay-server\"\u003e中继服务端部署\u003c/h2\u003e\n\nRelay 模式需要一台公网服务器运行 frps 服务端。提供三种部署方式：\n\n### 方式 A：SSH 远程安装（推荐）\n\n在本地一条命令搞定服务端安装 + 客户端配置：\n\n```bash\ncftunnel relay server setup --host 1.2.3.4 --user root --key ~/.ssh/id_ed25519\n# ✔ SSH 连接成功\n# ✔ frps 远程安装完成! 本地已自动配置\n```\n\n支持密码认证（`--password` 交互输入）和全交互模式（不传参数自动引导）。\n\n### 方式 B：一键脚本\n\n在公网服务器上执行：\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/qingchencloud/cftunnel/main/install-relay.sh | bash\n```\n\n脚本自动完成：下载 frps → 生成随机 token → 注册 systemd → 输出客户端连接命令。\n\n### 方式 C：Docker Compose\n\n```bash\nmkdir -p cftunnel-relay \u0026\u0026 cd cftunnel-relay\ncurl -fsSLO https://raw.githubusercontent.com/qingchencloud/cftunnel/main/docker/relay-server/docker-compose.yml\ncurl -fsSLO https://raw.githubusercontent.com/qingchencloud/cftunnel/main/docker/relay-server/frps.toml.example\ncp frps.toml.example frps.toml\n# 编辑 frps.toml，设置你的 auth.token\ndocker compose up -d\n```\n\n\u003e 记得在服务器防火墙放行 7000 端口和穿透使用的端口。\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#cftunnel\"\u003e⬆ 回到顶部\u003c/a\u003e\u003c/p\u003e\n\n\u003ch2 id=\"commands\"\u003e命令参考\u003c/h2\u003e\n\n### Cloud 模式\n\n| 命令 | 说明 |\n|------|------|\n| `cftunnel quick \u003c端口\u003e` | 免域名穿透，生成临时域名 |\n| `cftunnel quick \u003c端口\u003e --auth user:pass` | 免域名 + 密码保护 |\n| `cftunnel init` | 配置 Cloudflare 认证信息 |\n| `cftunnel create \u003c名称\u003e` | 创建 Tunnel |\n| `cftunnel add \u003c名称\u003e \u003c端口\u003e --domain \u003c域名\u003e` | 添加路由（自动创建 CNAME） |\n| `cftunnel remove \u003c名称\u003e` | 删除路由（自动清理 DNS） |\n| `cftunnel list` | 列出所有路由 |\n| `cftunnel up / down` | 启停 cloudflared |\n| `cftunnel status` | 查看隧道状态 |\n| `cftunnel logs [-f]` | 查看日志 |\n| `cftunnel install / uninstall` | 注册/卸载系统服务 |\n| `cftunnel destroy [--force]` | 删除隧道 + DNS + 配置 |\n| `cftunnel reset [--force]` | 完全重置 |\n\n### Relay 模式\n\n| 命令 | 说明 |\n|------|------|\n| `cftunnel relay init --server \u003cIP:端口\u003e --token \u003c密钥\u003e` | 配置中继服务器 |\n| `cftunnel relay add \u003c名称\u003e --local \u003c端口\u003e --proto tcp` | 添加 TCP 规则 |\n| `cftunnel relay add \u003c名称\u003e --local \u003c端口\u003e --proto udp` | 添加 UDP 规则 |\n| `cftunnel relay remove \u003c名称\u003e` | 删除规则 |\n| `cftunnel relay list` | 列出所有规则 |\n| `cftunnel relay up / down` | 启停 frpc |\n| `cftunnel relay status` | 查看连接状态 |\n| `cftunnel relay check [规则名]` | 检测链路连通性和延迟 |\n| `cftunnel relay logs [-f]` | 查看日志 |\n| `cftunnel relay install / uninstall` | 注册/卸载系统服务 |\n| `cftunnel relay server install` | 安装 frps 服务端（仅 Linux） |\n| `cftunnel relay server setup` | SSH 远程安装 frps 服务端 |\n| `cftunnel quick \u003c端口\u003e --relay` | 通过中继快速穿透 |\n| `cftunnel quick \u003c端口\u003e --relay --proto udp` | UDP 快速穿透 |\n\n### 版本管理\n\n| 命令 | 说明 |\n|------|------|\n| `cftunnel version [--check]` | 显示版本 / 检查更新 |\n| `cftunnel update` | 自动更新到最新版 |\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#cftunnel\"\u003e⬆ 回到顶部\u003c/a\u003e\u003c/p\u003e\n\n\u003ch2 id=\"config\"\u003e配置文件\u003c/h2\u003e\n\n配置存储在 `~/.cftunnel/config.yml`：\n\n```yaml\nversion: 1\n\n# Cloud 模式配置\nauth:\n  api_token: \"your-token\"\n  account_id: \"your-account-id\"\ntunnel:\n  id: \"tunnel-uuid\"\n  name: \"my-tunnel\"\n  token: \"tunnel-run-token\"\nroutes:\n  - name: myapp\n    hostname: app.example.com\n    service: http://localhost:3000\n\n# Relay 模式配置（与 Cloud 模式独立共存）\nrelay:\n  server: \"1.2.3.4:7000\"\n  token: \"your-relay-token\"\n  rules:\n    - name: minecraft\n      proto: tcp\n      local_port: 25565\n      remote_port: 25565\n    - name: game-voice\n      proto: udp\n      local_port: 9987\n      remote_port: 9987\n```\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#cftunnel\"\u003e⬆ 回到顶部\u003c/a\u003e\u003c/p\u003e\n\n\u003ch2 id=\"troubleshooting\"\u003e故障排查\u003c/h2\u003e\n\n### QUIC 连接超时\n\n**现象：** `failed to dial to edge with quic: timeout`\n\n**解决：** cftunnel v0.6.1+ 已默认使用 HTTP/2（TCP）。重装服务即可：`cftunnel uninstall \u0026\u0026 cftunnel install`\n\n### DNS 被 fake-ip 劫持\n\n**现象：** cloudflared 连接到 `198.18.0.x`\n\n**解决：** 将 `cloudflared` 进程加入代理软件 TUN 绕行列表，或将 `*.argotunnel.com` 加入 fake-ip-filter。\n\n### Cloudflare 1033 错误\n\n**现象：** DNS CNAME 指向旧 Tunnel ID\n\n**解决：** `cftunnel remove \u003c名称\u003e` 再 `cftunnel add` 重建路由。\n\n### Cloudflare 530 错误\n\n**现象：** cloudflared 未连接到 Edge\n\n**解决：** `cftunnel logs -f` 查看实时日志，根据具体错误参考上述方案。\n\n### Relay 模式连接失败\n\n**现象：** `relay up` 后 `relay status` 显示未连接\n\n**排查步骤：**\n1. 一键检测链路：`cftunnel relay check`（检测服务器、本地服务、远程端口连通性）\n2. 确认服务器 frps 在运行：`ssh 服务器 \"systemctl status frps\"`\n3. 确认防火墙放行 7000 端口\n4. 确认 token 一致：`cftunnel relay status` 查看服务器地址和 token\n5. 查看日志：`cftunnel relay logs -f`\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#cftunnel\"\u003e⬆ 回到顶部\u003c/a\u003e\u003c/p\u003e\n\n\u003ch2 id=\"ai\"\u003eAI 助手集成\u003c/h2\u003e\n\ncftunnel 内置 AI 助手 Skills，让 Claude Code、OpenClaw 等 AI 编码助手可以直接管理隧道。\n\n### Claude Code\n\n项目克隆到本地后，Claude Code 自动加载 Skills，你可以直接说：\n\n```\n帮我用 cftunnel quick 把本地 3000 端口临时分享出去\n帮我用 cftunnel relay 把本地 25565 端口穿透出去\n```\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#cftunnel\"\u003e⬆ 回到顶部\u003c/a\u003e\u003c/p\u003e\n\n\u003ch2 id=\"dev\"\u003e开发\u003c/h2\u003e\n\n```bash\nmake build              # 本地构建\ngit tag v0.x.0 \u0026\u0026 git push --tags  # 推送 tag 自动触发 GitHub Actions 发版\n```\n\n\u003ch2 id=\"contact\"\u003e交流\u003c/h2\u003e\n\n- 官网: [cftunnel.qt.cool](https://cftunnel.qt.cool)\n- QQ 群: [OpenClaw 交流群](https://qm.qq.com/q/qUfdR0jJVS)\n- Issues: [GitHub Issues](https://github.com/qingchencloud/cftunnel/issues)\n\n\u003ch2 id=\"license\"\u003eLicense\u003c/h2\u003e\n\nMIT\n\n---\n\n由 [武汉晴辰天下网络科技有限公司](https://qingchencloud.com) 开源维护\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqingchencloud%2Fcftunnel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqingchencloud%2Fcftunnel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqingchencloud%2Fcftunnel/lists"}