diff --git a/.claude/skills/cftunnel.md b/.claude/skills/cftunnel.md index e2cd5f9..8f8b6c2 100644 --- a/.claude/skills/cftunnel.md +++ b/.claude/skills/cftunnel.md @@ -1,20 +1,38 @@ # cftunnel — Cloudflare Tunnel 管理 -快速管理 Cloudflare Tunnel 的 CLI 工具，3 条命令搞定内网穿透。 +快速管理 Cloudflare Tunnel 的 CLI 工具，内网穿透从未如此简单。 ## 安装 ```bash -# macOS / Linux -curl -fsSL https://github.com/qingchencloud/cftunnel/releases/latest/download/cftunnel_$(uname -s | tr A-Z a-z)_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/') -o /usr/local/bin/cftunnel && chmod +x /usr/local/bin/cftunnel +curl -fsSL https://raw.githubusercontent.com/qingchencloud/cftunnel/main/install.sh | bash ``` -## 快速上手 +## 首次使用前需要两个参数 + +### 1. API Token（API 令牌） + +引导用户打开 https://dash.cloudflare.com/profile/api-tokens 创建自定义令牌，添加 3 条权限： + +``` +帐户 │ Cloudflare Tunnel │ 编辑 +区域 │ DNS │ 编辑 ← 注意选「DNS」不是「DNS 设置」 +区域 │ 区域设置 │ 读取 +``` + +第 2、3 行需将左侧下拉框从「帐户」切换为「区域」。区域资源选择用户的域名。 + +### 2. Account ID（账户 ID） + +- 方式 A: https://dash.cloudflare.com → 点击域名 → 右下角「API」区域 +- 方式 B: 首页 → 账户名称旁「⋯」→ 复制账户 ID + +## 使用流程 ```bash -cftunnel init # 配置认证 +cftunnel init # 配置认证（需要 Token + Account ID） cftunnel create my-tunnel # 创建隧道 -cftunnel add myapp 3000 --domain myapp.example.com # 添加路由 +cftunnel add myapp 3000 --domain myapp.example.com # 添加路由（自动创建 CNAME） cftunnel up # 启动隧道 ``` @@ -22,26 +40,22 @@ cftunnel up # 启动隧道 | 命令 | 说明 | |------|------| -| `init` | 配置认证（支持 `--token`/`--account` 非交互模式） | +| `init [--token --account]` | 配置认证 | | `create <名称>` | 创建隧道 | | `add <名称> <端口> --domain <域名>` | 添加路由（自动创建 CNAME） | | `remove <名称>` | 删除路由（清理 DNS） | | `list` | 列出所有路由 | -| `up` | 启动隧道 | -| `down` | 停止隧道 | +| `up` / `down` | 启停隧道 | | `status` | 查看状态 | | `destroy [--force]` | 删除隧道 + 所有 DNS 记录 | | `reset [--force]` | 完全重置（删隧道 + 清本地配置） | -| `install` | 注册系统服务（开机自启） | -| `uninstall` | 卸载系统服务 | +| `install` / `uninstall` | 系统服务（开机自启） | | `logs [-f]` | 查看日志 | | `version [--check]` | 版本信息 / 检查更新 | | `update` | 自动更新到最新版 | -## CF API Token 权限 +## 注意事项 -``` -帐户 │ Cloudflare Tunnel │ 编辑 -区域 │ DNS │ 编辑 -区域 │ 区域设置 │ 读取 -``` +- 执行操作前确认用户已完成 `init` 和 `create` +- 域名必须是用户 CF 账户中已有域名的子域名 +- 一个隧道可挂载多条路由（多域名 → 不同本地端口） diff --git a/README.md b/README.md index 82a56f3..c3bbdc1 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,36 @@ # cftunnel -Cloudflare Tunnel 一键管理工具 — 3 条命令搞定内网穿透。 +[![GitHub release](https://img.shields.io/github/v/release/qingchencloud/cftunnel)](https://github.com/qingchencloud/cftunnel/releases) +[![Go Report Card](https://goreportcard.com/badge/github.com/qingchencloud/cftunnel)](https://goreportcard.com/report/github.com/qingchencloud/cftunnel) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) -把 Cloudflare Tunnel 的繁琐配置流程（装 cloudflared → 登录 → 创建隧道 → 写 config → 配 DNS → 注册服务）封装成简单的 CLI 命令。 +**Cloudflare Tunnel 一键管理 CLI** — 让本地项目秒变公网可访问。 + +> 用 AI 写了个前端页面想给客户看？本地跑着 API 想让远程同事调试？开发环境需要接收 Webhook？ +> +> 一条命令，你的 `localhost` 就有了公网域名。 + +cftunnel 把 Cloudflare Tunnel 的繁琐流程（装 cloudflared → 登录 → 创建隧道 → 写 config → 配 DNS → 注册服务）封装成 4 条命令，**5 分钟搞定内网穿透，免费、安全、无需公网 IP**。 + +## 为什么选 cftunnel？ + +| 对比项 | 原生 cloudflared | cftunnel | +|--------|-----------------|----------| +| 创建隧道 | 登录浏览器 + 手动配置 | `cftunnel create my-tunnel` | +| DNS 记录 | 手动去 Dashboard 创建 CNAME | `cftunnel add` 自动创建 | +| 多路由管理 | 手动编辑 YAML 配置 | `cftunnel add/remove/list` | +| 开机自启 | 手动写 systemd/launchd | `cftunnel install` | +| 清理资源 | 手动删隧道 + 删 DNS + 删配置 | `cftunnel destroy` 一键清理 | +| AI 集成 | 无 | 内置 Skills，AI 助手直接管理 | ## 特性 -- **分步初始化** — `init` 配置认证，`create` 创建隧道，职责清晰 -- **自动 DNS** — 添加路由时自动创建 CNAME 记录 -- **进程托管** — 自动下载 cloudflared，支持注册系统服务开机自启 -- **自动更新** — 内置版本检查和自更新 +- **极简操作** — `init` → `create` → `add` → `up`，4 步搞定 +- **自动 DNS** — 添加路由时自动创建 CNAME 记录，删除时自动清理 +- **进程托管** — 自动下载 cloudflared，支持 macOS launchd / Linux systemd 开机自启 +- **自动更新** — 内置版本检查和一键自更新 - **AI 友好** — 内置 Claude Code / OpenClaw Skills，AI 助手可直接管理隧道 +- **跨平台** — 支持 macOS (Intel/Apple Silicon) + Linux (amd64/arm64) ## 安装 @@ -50,9 +70,14 @@ make build ### 1. 准备 Cloudflare API Token -登录 [Cloudflare Dashboard](https://dash.cloudflare.com) → 右上角头像 → 我的个人资料 → API 令牌 → 创建令牌 → 创建自定义令牌 → 开始使用 +> 前提：你需要一个 Cloudflare 账户和至少一个已添加的域名。 -添加 3 条权限（点「+ 添加更多」逐条添加）： +**创建 API 令牌：** + +1. 打开 [API 令牌页面](https://dash.cloudflare.com/profile/api-tokens) +2. 点击「创建令牌」→「创建自定义令牌」→「开始使用」 +3. 令牌名称随意填写（如 `cftunnel`） +4. 添加 3 条权限（点「+ 添加更多」逐条添加）： ``` ┌──────────────────────────────────────────────────┐ @@ -62,9 +87,15 @@ make build └──────────────────────────────────────────────────┘ ``` -> **注意**: 第 2、3 行需先将左侧「帐户」切换为「区域」 +> **注意**: 第 2、3 行需先将左侧下拉框从「帐户」切换为「区域」。DNS 权限请选择「DNS」而非「DNS 设置」，两者不同。 -区域资源 → 包括 → 特定区域 → 选择你的域名 +5. 区域资源 → 包括 → 特定区域 → 选择你的域名 +6. 点击「继续以显示摘要」→「创建令牌」→ **立即复制令牌**（只显示一次） + +**获取账户 ID（任选其一）：** + +- **方式 A**: [Cloudflare 首页](https://dash.cloudflare.com) → 点击域名 → 页面右下角「API」区域 → 复制「账户 ID」 +- **方式 B**: 首页 → 账户名称旁「⋯」→ 复制账户 ID ### 2. 初始化认证 @@ -191,11 +222,11 @@ routes: ## AI 助手集成 -cftunnel 内置了 AI 助手 Skills，让 Claude Code、OpenClaw 等 AI 编码助手可以直接管理你的隧道。 +cftunnel 内置了 AI 助手 Skills，让 Claude Code、OpenClaw 等 AI 编码助手可以直接帮你管理隧道。 ### Claude Code -将项目克隆到本地后，Claude Code 会自动加载 `.claude/skills/cftunnel.md`，你可以直接对 Claude Code 说： +将项目克隆到本地后，Claude Code 会自动加载 `.claude/skills/cftunnel.md`，你可以直接说： ``` 帮我用 cftunnel 把本地 3000 端口暴露到 dev.example.com @@ -203,39 +234,82 @@ cftunnel 内置了 AI 助手 Skills，让 Claude Code、OpenClaw 等 AI 编码 ### OpenClaw / 其他 AI 助手 -复制以下提示词给你的 AI 助手： +复制以下提示词给你的 AI 助手，即可让它帮你操作 cftunnel： + +
+点击展开完整提示词 ``` -你可以使用 cftunnel CLI 工具管理 Cloudflare Tunnel。 +你是一个熟悉 cftunnel 的运维助手。cftunnel 是 Cloudflare Tunnel 的 CLI 管理工具，用于内网穿透。 -安装: curl -fsSL https://raw.githubusercontent.com/qingchencloud/cftunnel/main/install.sh | bash +## 安装 -常用命令: -- cftunnel init --token --account # 配置认证 -- cftunnel create <名称> # 创建隧道 -- cftunnel add <名称> <端口> --domain <域名> # 添加路由 -- cftunnel remove <名称> # 删除路由 -- cftunnel up / down # 启停隧道 -- cftunnel status # 查看状态 -- cftunnel list # 列出路由 -- cftunnel destroy --force # 删除隧道 -- cftunnel install # 注册系统服务 +curl -fsSL https://raw.githubusercontent.com/qingchencloud/cftunnel/main/install.sh | bash -执行命令前请确认用户已完成 cftunnel init 和 cftunnel create。 -添加路由时会自动创建 DNS CNAME 记录，删除时自动清理。 +## 首次使用前，需要引导用户准备两个参数 + +1. API Token（API 令牌）: + - 打开 https://dash.cloudflare.com/profile/api-tokens + - 点击「创建令牌」→「创建自定义令牌」→「开始使用」 + - 添加 3 条权限（点「+ 添加更多」逐条添加）: + 帐户 | Cloudflare Tunnel | 编辑 + 区域 | DNS | 编辑（注意: 选「DNS」不是「DNS 设置」） + 区域 | 区域设置 | 读取 + - 第 2、3 行需先将左侧下拉框从「帐户」切换为「区域」 + - 区域资源 → 包括 → 特定区域 → 选择域名 + - 创建后立即复制令牌（只显示一次） + +2. Account ID（账户 ID）: + - 方式 A: https://dash.cloudflare.com → 点击域名 → 右下角「API」区域 → 账户 ID + - 方式 B: 首页 → 账户名称旁「⋯」→ 复制账户 ID + +## 使用流程 + +# 第 1 步: 配置认证（需要上面两个参数） +cftunnel init --token --account + +# 第 2 步: 创建隧道 +cftunnel create <隧道名称> + +# 第 3 步: 添加路由（自动创建 DNS CNAME 记录） +cftunnel add <路由名称> <本地端口> --domain <完整域名> + +# 第 4 步: 启动 +cftunnel up + +## 其他命令 + +- cftunnel down # 停止隧道 +- cftunnel status # 查看状态 +- cftunnel list # 列出所有路由 +- cftunnel remove <名称> # 删除路由（自动清理 DNS） +- cftunnel destroy # 删除隧道 + 所有 DNS 记录 +- cftunnel install # 注册系统服务（开机自启） +- cftunnel logs -f # 实时查看日志 +- cftunnel update # 自动更新 cftunnel + +## 注意事项 + +- 执行任何操作前，先确认用户已完成 init 和 create +- 添加路由时会自动创建 DNS CNAME 记录，删除时自动清理 +- 一个隧道可以挂载多条路由（多个域名指向不同本地端口） +- 域名必须是用户 Cloudflare 账户中已有的域名的子域名 ``` +
+ ## 开发 ```bash -# 构建 -make build - -# 发版（推送 tag 自动触发 GitHub Actions） -git tag v0.1.0 -git push --tags +make build # 本地构建 +git tag v0.x.0 && git push --tags # 推送 tag 自动触发 GitHub Actions 发版 ``` +## 交流 + +- QQ 群: [OpenClaw 交流群](https://qm.qq.com/q/qUfdR0jJVS) +- Issues: [GitHub Issues](https://github.com/qingchencloud/cftunnel/issues) + ## License MIT diff --git a/skills/openclaw-cftunnel.md b/skills/openclaw-cftunnel.md index ff5ef16..2828011 100644 --- a/skills/openclaw-cftunnel.md +++ b/skills/openclaw-cftunnel.md @@ -1,32 +1,57 @@ # cftunnel — Cloudflare Tunnel CLI -一键管理 Cloudflare Tunnel 的开源工具。 +一键管理 Cloudflare Tunnel 的开源工具，内网穿透从未如此简单。 -## 快速上手 +## 首次使用前需要两个参数 + +### 1. API Token（API 令牌） + +引导用户打开 https://dash.cloudflare.com/profile/api-tokens 创建自定义令牌，添加 3 条权限： + +``` +帐户 │ Cloudflare Tunnel │ 编辑 +区域 │ DNS │ 编辑 ← 注意选「DNS」不是「DNS 设置」 +区域 │ 区域设置 │ 读取 +``` + +第 2、3 行需将左侧下拉框从「帐户」切换为「区域」。区域资源选择用户的域名。 + +### 2. Account ID（账户 ID） + +- 方式 A: https://dash.cloudflare.com → 点击域名 → 右下角「API」区域 +- 方式 B: 首页 → 账户名称旁「⋯」→ 复制账户 ID + +## 使用流程 ```bash -cftunnel init # 配置认证 +cftunnel init # 配置认证（需要 Token + Account ID） cftunnel create my-tunnel # 创建隧道 -cftunnel add myapp 3000 --domain myapp.example.com # 添加路由 -cftunnel up # 启动 +cftunnel add myapp 3000 --domain myapp.example.com # 添加路由（自动创建 CNAME） +cftunnel up # 启动隧道 ``` ## 全部命令 - `init [--token --account]` — 配置 API 认证 - `create <名称>` — 创建隧道 -- `add <名称> <端口> --domain <域名>` — 添加路由 -- `remove <名称>` — 删除路由 +- `add <名称> <端口> --domain <域名>` — 添加路由（自动创建 CNAME） +- `remove <名称>` — 删除路由（自动清理 DNS） - `list` — 列出路由 - `up` / `down` — 启停隧道 - `status` — 查看状态 -- `destroy [--force]` — 删除隧道 +- `destroy [--force]` — 删除隧道 + 所有 DNS 记录 - `reset [--force]` — 完全重置 -- `install` / `uninstall` — 系统服务 +- `install` / `uninstall` — 系统服务（开机自启） - `logs [-f]` — 查看日志 -- `version [--check]` — 版本信息 +- `version [--check]` — 版本信息 / 检查更新 - `update` — 自动更新 +## 注意事项 + +- 执行操作前确认用户已完成 `init` 和 `create` +- 域名必须是用户 CF 账户中已有域名的子域名 +- 一个隧道可挂载多条路由（多域名 → 不同本地端口） + ## 仓库 https://github.com/qingchencloud/cftunnel