Skip to content

Commit 4b3bfd5

Browse files
author
admin
committed
feat: 添加 README + 安装脚本 + 自动更新配置
- README 完整文档（安装/快速上手/命令参考/AI提示词） - install.sh 一键安装脚本 - config 新增 self_update.auto_check 配置项 - up 命令启动时自动检查更新提示
1 parent ddc893c commit 4b3bfd5

4 files changed

Lines changed: 272 additions & 4 deletions

File tree

‎README.md‎

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
# cftunnel
2+
3+
Cloudflare Tunnel 一键管理工具 — 3 条命令搞定内网穿透。
4+
5+
把 Cloudflare Tunnel 的繁琐配置流程（装 cloudflared → 登录 → 创建隧道 → 写 config → 配 DNS → 注册服务）封装成简单的 CLI 命令。
6+
7+
## 特性
8+
9+
- **一键初始化** — 交互式向导，输入 Token 即可创建隧道
10+
- **自动 DNS** — 添加路由时自动创建 CNAME 记录
11+
- **进程托管** — 自动下载 cloudflared，支持注册系统服务开机自启
12+
- **自动更新** — 内置版本检查和自更新
13+
- **AI 友好** — 内置 Claude Code / OpenClaw Skills，AI 助手可直接管理隧道
14+
15+
## 安装
16+
17+
### 一键安装（推荐）
18+
19+
```bash
20+
curl -fsSL https://raw.githubusercontent.com/qingchencloud/cftunnel/main/install.sh | bash
21+
```
22+
23+
### 手动下载
24+
25+
从 [Releases](https://github.com/qingchencloud/cftunnel/releases) 下载对应平台的二进制文件：
26+
27+
```bash
28+
# macOS Apple Silicon
29+
curl -fsSL https://github.com/qingchencloud/cftunnel/releases/latest/download/cftunnel_darwin_arm64.tar.gz | tar xz -C /usr/local/bin/
30+
31+
# macOS Intel
32+
curl -fsSL https://github.com/qingchencloud/cftunnel/releases/latest/download/cftunnel_darwin_amd64.tar.gz | tar xz -C /usr/local/bin/
33+
34+
# Linux amd64
35+
curl -fsSL https://github.com/qingchencloud/cftunnel/releases/latest/download/cftunnel_linux_amd64.tar.gz | tar xz -C /usr/local/bin/
36+
37+
# Linux arm64
38+
curl -fsSL https://github.com/qingchencloud/cftunnel/releases/latest/download/cftunnel_linux_arm64.tar.gz | tar xz -C /usr/local/bin/
39+
```
40+
41+
### 从源码构建
42+
43+
```bash
44+
git clone https://github.com/qingchencloud/cftunnel.git
45+
cd cftunnel
46+
make build
47+
```
48+
49+
## 快速上手
50+
51+
### 1. 准备 Cloudflare API Token
52+
53+
登录 [Cloudflare Dashboard](https://dash.cloudflare.com) → 右上角头像 → 我的个人资料 → API 令牌 → 创建令牌 → 创建自定义令牌 → 开始使用
54+
55+
添加 3 条权限（点「+ 添加更多」逐条添加）：
56+
57+
```
58+
┌──────────────────────────────────────────────────┐
59+
│ 第 1 行: 帐户 │ Cloudflare Tunnel │ 编辑 │
60+
│ 第 2 行: 区域 │ DNS │ 编辑 │
61+
│ 第 3 行: 区域 │ 区域设置 │ 读取 │
62+
└──────────────────────────────────────────────────┘
63+
```
64+
65+
> **注意**: 第 2、3 行需先将左侧「帐户」切换为「区域」
66+
67+
区域资源 → 包括 → 特定区域 → 选择你的域名
68+
69+
### 2. 初始化
70+
71+
```bash
72+
# 交互式（推荐）
73+
cftunnel init
74+
75+
# 非交互式
76+
cftunnel init --token <your-token> --account <account-id> --name my-tunnel
77+
```
78+
79+
### 3. 添加路由
80+
81+
```bash
82+
# 将 app.example.com 指向本地 3000 端口
83+
cftunnel add myapp 3000 --domain app.example.com
84+
```
85+
86+
### 4. 启动隧道
87+
88+
```bash
89+
cftunnel up
90+
```
91+
92+
搞定！现在可以通过 `app.example.com` 访问你本地的 3000 端口服务了。
93+
94+
## 命令参考
95+
96+
### 配置管理
97+
98+
| 命令 | 说明 |
99+
|------|------|
100+
| `cftunnel init` | 交互式初始化（支持 `--token`/`--account`/`--name`） |
101+
| `cftunnel add <名称> <端口> --domain <域名>` | 添加路由（自动创建 CNAME） |
102+
| `cftunnel remove <名称>` | 删除路由（自动清理 DNS） |
103+
| `cftunnel list` | 列出所有路由 |
104+
105+
### 运行管理
106+
107+
| 命令 | 说明 |
108+
|------|------|
109+
| `cftunnel up` | 启动隧道（自动下载 cloudflared） |
110+
| `cftunnel down` | 停止隧道 |
111+
| `cftunnel status` | 查看隧道状态 |
112+
| `cftunnel logs [-f]` | 查看日志（`-f` 实时跟踪） |
113+
114+
### 系统服务
115+
116+
| 命令 | 说明 |
117+
|------|------|
118+
| `cftunnel install` | 注册系统服务（macOS launchd / Linux systemd） |
119+
| `cftunnel uninstall` | 卸载系统服务 |
120+
121+
### 隧道生命周期
122+
123+
| 命令 | 说明 |
124+
|------|------|
125+
| `cftunnel destroy [--force]` | 删除隧道 + 所有 DNS 记录 |
126+
| `cftunnel reset [--force]` | 完全重置（删隧道 + 清本地配置） |
127+
128+
### 版本管理
129+
130+
| 命令 | 说明 |
131+
|------|------|
132+
| `cftunnel version [--check]` | 显示版本 / 检查更新 |
133+
| `cftunnel update` | 自动更新到最新版 |
134+
135+
## 典型使用场景
136+
137+
### 场景 1: 暴露本地开发服务
138+
139+
```bash
140+
cftunnel init
141+
cftunnel add dev 3000 --domain dev.example.com
142+
cftunnel up
143+
# 现在 dev.example.com 指向 localhost:3000
144+
```
145+
146+
### 场景 2: Webhook 接收
147+
148+
```bash
149+
cftunnel add webhook 9801 --domain webhook.example.com
150+
cftunnel up
151+
cftunnel install # 开机自启
152+
```
153+
154+
### 场景 3: 多服务同时暴露
155+
156+
```bash
157+
cftunnel add api 8080 --domain api.example.com
158+
cftunnel add web 3000 --domain web.example.com
159+
cftunnel add admin 8888 --domain admin.example.com
160+
cftunnel list
161+
```
162+
163+
## 配置文件
164+
165+
配置存储在 `~/.cftunnel/config.yml`：
166+
167+
```yaml
168+
version: 1
169+
auth:
170+
api_token: "your-token"
171+
account_id: "your-account-id"
172+
tunnel:
173+
id: "tunnel-uuid"
174+
name: "my-tunnel"
175+
token: "tunnel-run-token"
176+
routes:
177+
- name: myapp
178+
hostname: app.example.com
179+
service: http://localhost:3000
180+
zone_id: "auto-detected"
181+
dns_record_id: "auto-created"
182+
```
183+
184+
## AI 助手集成
185+
186+
cftunnel 内置了 AI 助手 Skills，让 Claude Code、OpenClaw 等 AI 编码助手可以直接管理你的隧道。
187+
188+
### Claude Code
189+
190+
将项目克隆到本地后，Claude Code 会自动加载 `.claude/skills/cftunnel.md`，你可以直接对 Claude Code 说：
191+
192+
```
193+
帮我用 cftunnel 把本地 3000 端口暴露到 dev.example.com
194+
```
195+
196+
### OpenClaw / 其他 AI 助手
197+
198+
复制以下提示词给你的 AI 助手：
199+
200+
```
201+
你可以使用 cftunnel CLI 工具管理 Cloudflare Tunnel。
202+
203+
安装: curl -fsSL https://raw.githubusercontent.com/qingchencloud/cftunnel/main/install.sh | bash
204+
205+
常用命令:
206+
- cftunnel init --token <TOKEN> --account <ACCOUNT_ID> --name <名称> # 初始化
207+
- cftunnel add <名称> <端口> --domain <域名> # 添加路由
208+
- cftunnel remove <名称> # 删除路由
209+
- cftunnel up / down # 启停隧道
210+
- cftunnel status # 查看状态
211+
- cftunnel list # 列出路由
212+
- cftunnel destroy --force # 删除隧道
213+
- cftunnel install # 注册系统服务
214+
215+
执行命令前请确认用户已完成 cftunnel init 初始化。
216+
添加路由时会自动创建 DNS CNAME 记录，删除时自动清理。
217+
```
218+
219+
## 开发
220+
221+
```bash
222+
# 构建
223+
make build
224+
225+
# 发版（推送 tag 自动触发 GitHub Actions）
226+
git tag v0.1.0
227+
git push --tags
228+
```
229+
230+
## License
231+
232+
MIT

‎cmd/up.go‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import (
55

66
"github.com/qingchencloud/cftunnel/internal/config"
77
"github.com/qingchencloud/cftunnel/internal/daemon"
8+
"github.com/qingchencloud/cftunnel/internal/selfupdate"
89
"github.com/spf13/cobra"
910
)
1011

@@ -23,6 +24,14 @@ var upCmd = &cobra.Command{
2324
if cfg.Tunnel.Token == "" {
2425
return fmt.Errorf("请先运行 cftunnel init")
2526
}
27+
// 自动检查更新（非阻塞，仅提示）
28+
if cfg.SelfUpdate.AutoCheck {
29+
if latest, err := selfupdate.LatestVersion(); err == nil {
30+
if latest != "v"+Version && latest != Version {
31+
fmt.Printf("发现新版本: %s → %s (运行 cftunnel update 更新)\n", Version, latest)
32+
}
33+
}
34+
}
2635
return daemon.Start(cfg.Tunnel.Token)
2736
},
2837
}

‎install.sh‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
#!/bin/bash
2+
set -e
3+
4+
REPO="qingchencloud/cftunnel"
5+
INSTALL_DIR="/usr/local/bin"
6+
7+
OS=$(uname -s | tr A-Z a-z)
8+
ARCH=$(uname -m)
9+
case "$ARCH" in
10+
x86_64) ARCH="amd64" ;;
11+
aarch64|arm64) ARCH="arm64" ;;
12+
*) echo "不支持的架构: $ARCH"; exit 1 ;;
13+
esac
14+
15+
URL="https://github.com/$REPO/releases/latest/download/cftunnel_${OS}_${ARCH}.tar.gz"
16+
echo "正在下载 cftunnel ($OS/$ARCH)..."
17+
TMP=$(mktemp -d)
18+
curl -fsSL "$URL" | tar xz -C "$TMP"
19+
sudo install -m 755 "$TMP/cftunnel" "$INSTALL_DIR/cftunnel"
20+
rm -rf "$TMP"
21+
echo "cftunnel 已安装到 $INSTALL_DIR/cftunnel"
22+
echo "运行 cftunnel init 开始使用"

‎internal/config/config.go‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,12 @@ import (
88
)
99

1010
type Config struct {
11-
Version int `yaml:"version"`
12-
Auth AuthConfig `yaml:"auth"`
13-
Tunnel TunnelConfig `yaml:"tunnel"`
14-
Routes []RouteConfig `yaml:"routes"`
11+
Version int `yaml:"version"`
12+
Auth AuthConfig `yaml:"auth"`
13+
Tunnel TunnelConfig `yaml:"tunnel"`
14+
Routes []RouteConfig `yaml:"routes"`
1515
Cloudflared CloudflaredConfig `yaml:"cloudflared"`
16+
SelfUpdate SelfUpdateConfig `yaml:"self_update"`
1617
}
1718

1819
type AuthConfig struct {
@@ -39,6 +40,10 @@ type CloudflaredConfig struct {
3940
AutoUpdate bool `yaml:"auto_update"`
4041
}
4142

43+
type SelfUpdateConfig struct {
44+
AutoCheck bool `yaml:"auto_check"` // 启动时自动检查 cftunnel 更新
45+
}
46+
4247
func Dir() string {
4348
home, _ := os.UserHomeDir()
4449
return filepath.Join(home, ".cftunnel")

0 commit comments

Comments
 (0)