cloudflared-manager 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +63 -0
- package/README.md +217 -0
- package/cloudflared_manager.mjs +2080 -0
- package/cloudflared_manager.sh +2727 -0
- package/package.json +26 -0
package/AGENTS.md
ADDED
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Repository Guidelines
|
|
2
|
+
|
|
3
|
+
## Project Structure & Module Organization
|
|
4
|
+
|
|
5
|
+
This repository is intentionally small:
|
|
6
|
+
|
|
7
|
+
- `cloudflared_manager.sh`: the main Bash CLI for managing Cloudflare Tunnels, local configs, metadata, and multi-ingress workflows.
|
|
8
|
+
- `README.md`: user-facing usage guide and examples.
|
|
9
|
+
- Runtime state is not stored in the repo. Managed app metadata, credentials, logs, and generated configs live outside the repo, typically under a user-selected manager root such as `~/.cloudflared/manager/`.
|
|
10
|
+
|
|
11
|
+
Keep new logic in `cloudflared_manager.sh` unless the project is intentionally split into multiple scripts.
|
|
12
|
+
|
|
13
|
+
## Build, Test, and Development Commands
|
|
14
|
+
|
|
15
|
+
There is no build step. Use these commands during development:
|
|
16
|
+
|
|
17
|
+
- `bash -n cloudflared_manager.sh`
|
|
18
|
+
Checks shell syntax.
|
|
19
|
+
- `./cloudflared_manager.sh -h`
|
|
20
|
+
Verifies top-level help text and examples.
|
|
21
|
+
- `./cloudflared_manager.sh doctor`
|
|
22
|
+
Confirms path resolution and local `cloudflared` discovery.
|
|
23
|
+
- `./cloudflared_manager.sh modify -h`
|
|
24
|
+
Spot-checks subcommand help after CLI changes.
|
|
25
|
+
|
|
26
|
+
For safe behavior testing, use disposable paths under `/tmp`:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
./cloudflared_manager.sh --manager-root /tmp/cf-manager-test ingress-list demo
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Coding Style & Naming Conventions
|
|
33
|
+
|
|
34
|
+
- Write Bash compatible with the current script style: `set -euo pipefail`, 2-space indentation, and small helper functions.
|
|
35
|
+
- Add a short comment above each function explaining its purpose.
|
|
36
|
+
- Use `cmd_*` names for command handlers, uppercase for environment/config variables, and clear Chinese user-facing output where practical.
|
|
37
|
+
- Prefer simple POSIX/macOS utilities already used in the repo (`awk`, `plutil`, `tail`, `nc`).
|
|
38
|
+
|
|
39
|
+
## Testing Guidelines
|
|
40
|
+
|
|
41
|
+
There is no dedicated automated test suite yet. For each behavior change:
|
|
42
|
+
|
|
43
|
+
- run `bash -n cloudflared_manager.sh`
|
|
44
|
+
- verify related `-h` output
|
|
45
|
+
- test the changed path with a temporary manager root under `/tmp`
|
|
46
|
+
|
|
47
|
+
Avoid testing against production tunnels unless the change explicitly requires remote verification.
|
|
48
|
+
|
|
49
|
+
## Commit & Pull Request Guidelines
|
|
50
|
+
|
|
51
|
+
Follow the existing conventional style from Git history:
|
|
52
|
+
|
|
53
|
+
- `feat: ...`
|
|
54
|
+
- `fix: ...`
|
|
55
|
+
- `docs: ...`
|
|
56
|
+
- `style: ...`
|
|
57
|
+
- `refactor: ...`
|
|
58
|
+
|
|
59
|
+
Keep commits focused. PRs should summarize user-visible CLI changes, list the verification commands you ran, and note any Cloudflare-side side effects such as DNS route creation.
|
|
60
|
+
|
|
61
|
+
## Security & Configuration Tips
|
|
62
|
+
|
|
63
|
+
Never commit `cert.pem`, tunnel credentials, generated `config.yml`, logs, or copied manager state. Use redacted examples in docs and prefer `/tmp` fixtures for local validation.
|
package/README.md
ADDED
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
# cloudflared-manager
|
|
2
|
+
|
|
3
|
+
一个偏自动化、面向 macOS 的 `cloudflared` 管理脚本，主入口是 [`cloudflared_manager.sh`](./cloudflared_manager.sh)。
|
|
4
|
+
|
|
5
|
+
它解决两个实际问题：
|
|
6
|
+
|
|
7
|
+
- 不再把路径强绑到 `~/.cloudflared` 或目录名必须叫 `.cloudflared`
|
|
8
|
+
- 把 `profile_dir`、`config.yml`、`cert.pem`、`manager_root` 四个概念拆开，支持任意路径组合
|
|
9
|
+
|
|
10
|
+
## 主要能力
|
|
11
|
+
|
|
12
|
+
- 管理远端 tunnel：`add`、`adopt`、`modify`、`delete`、`tunnels`
|
|
13
|
+
- 管理本地运行：`start`、`stop`、`restart`、`status`、`logs`
|
|
14
|
+
- 管理默认 profile：`init`、`use`、`login`、`import-cert`、`activate`
|
|
15
|
+
- 管理多入口规则：`ingress-list`、`ingress-add`、`ingress-remove`
|
|
16
|
+
- 自动处理：
|
|
17
|
+
- `login` 后自动同步默认 `cert.pem` 到目标路径
|
|
18
|
+
- 启动前自动检查本地 service 可达性
|
|
19
|
+
- `credentials.json` 缺失时自动补发 token
|
|
20
|
+
- `add` 时优先把 credentials 直接写入受管目录
|
|
21
|
+
- 旧版单规则应用会自动迁移成 `ingress.tsv`
|
|
22
|
+
|
|
23
|
+
## 为什么只保留 shell 版
|
|
24
|
+
|
|
25
|
+
这个仓库现在只保留 shell 版本，是为了减少环境漂移带来的问题。脚本只依赖：
|
|
26
|
+
|
|
27
|
+
- `bash`
|
|
28
|
+
- `cloudflared`
|
|
29
|
+
- macOS 自带工具：`plutil`、`curl`、`tail`、`nc`
|
|
30
|
+
|
|
31
|
+
不依赖 `jq`、Python 第三方库，也不要求固定的 `.cloudflared` 目录名。
|
|
32
|
+
|
|
33
|
+
## 交互式入口
|
|
34
|
+
|
|
35
|
+
核心逻辑仍然在 shell 脚本里，但仓库现在额外提供了一个 Node 交互式包装层：
|
|
36
|
+
|
|
37
|
+
- `cloudflared_manager.sh`
|
|
38
|
+
- 适合熟悉命令行参数、希望直接执行命令的人
|
|
39
|
+
- `cloudflared_manager.mjs`
|
|
40
|
+
- 适合通过菜单和提示一步步操作的人
|
|
41
|
+
|
|
42
|
+
本地用法：
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
node ./cloudflared_manager.mjs
|
|
46
|
+
npm exec --yes -- cloudflared-manager
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
如果你已经保存了 profile，也可以直接进入菜单；如果要带自定义全局参数进入交互模式，可以这样：
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
node ./cloudflared_manager.mjs --profile-dir /opt/cloudflare-prod interactive
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
发布到 npm 之后，就可以直接用：
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
npx cloudflared-manager
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
交互模式里提供了常用菜单；如果某些高级参数菜单里还没覆盖，可以用“执行自定义命令”直接透传到底层 shell 脚本。
|
|
62
|
+
主菜单同时支持两种选择方式：
|
|
63
|
+
|
|
64
|
+
- 直接输入编号后回车
|
|
65
|
+
- 使用方向键或 `j/k` 上下移动，`h/l` 返回或确认
|
|
66
|
+
- 使用 `gg` 跳到首项，`G` 跳到末项
|
|
67
|
+
- 使用 `Ctrl+u` / `Ctrl+d` 做半页跳转
|
|
68
|
+
- 顶部会显示当前所处层级的父级面包屑路径，不与当前页面标题重复
|
|
69
|
+
- 在二级菜单中，按 `Esc` 或左方向键可直接返回上一级
|
|
70
|
+
- 菜单列表已收敛为单行选项，当前项说明与快捷键会合并显示在底部状态栏，减少视觉噪音
|
|
71
|
+
- 底部状态栏默认只显示核心按键；`gg/G`、`Ctrl+u/d` 等高级快捷键仍然可用
|
|
72
|
+
- 顶部会显示更宽、更均衡的品牌标题框，并把当前菜单标题并入标题框；菜单编号按两位数显示，便于纵向对齐
|
|
73
|
+
- 菜单编号可直接输入 `1` 或 `01`，`0` 或 `00`，两种写法都能识别
|
|
74
|
+
- 进入交互模式后会直接显示菜单主体，不再额外输出冗余提示行
|
|
75
|
+
- 默认已保存设置时不再额外显示 `设置:` 行；只有显式传入自定义全局参数时才展示
|
|
76
|
+
- 二级菜单会按功能分组显示，例如应用页会拆成“查看 / 运行 / Ingress / 配置与管理”
|
|
77
|
+
- 标题框与底部状态栏会按终端宽度自动裁剪，避免长文本把界面撑乱
|
|
78
|
+
|
|
79
|
+
交互菜单已经拆成一级、二级结构：
|
|
80
|
+
|
|
81
|
+
- 一级菜单按“环境与登录 / 新建与接管 / 现有应用管理 / 远端与高级”分类
|
|
82
|
+
- 进入“现有应用管理”后，会先列出当前 profile 下的受管应用，再进入该应用的专属子菜单
|
|
83
|
+
- 应用相关操作会优先提供选择列表，尽量不再要求手输应用名称
|
|
84
|
+
- 如果手动输入了列表外的应用名，交互层会先提示“将尝试按默认 config.yml 自动接管”，失败时再提示使用 `add` 或 `adopt`
|
|
85
|
+
- 接管已有 tunnel 时，会优先列出当前账号下的远端 tunnels 供选择
|
|
86
|
+
- `add`、`adopt`、`modify`、`ingress-add`、`ingress-remove` 等录入流程会在输入时即时校验格式，尽量不把错误留到 shell 执行阶段
|
|
87
|
+
- `add`、`adopt` 现在是“先录入、再汇总确认”的表单式流程，执行前可重填应用名、Tunnel 名称、ingress 规则，并切换布尔选项
|
|
88
|
+
- `modify`、`ingress-add`、`ingress-remove` 现在会先读取当前 ingress，展示变更前后对比，再决定是否执行
|
|
89
|
+
- 确认页会额外展示彩色变更摘要和最终命令预览，便于在执行前快速复核
|
|
90
|
+
|
|
91
|
+
配色也改成了更适合深浅背景的高对比方案：
|
|
92
|
+
|
|
93
|
+
- 主操作：青色
|
|
94
|
+
- 次操作：绿色
|
|
95
|
+
- 辅助操作：黄色
|
|
96
|
+
- 危险操作：红色
|
|
97
|
+
- 返回/返回上一级：蓝色
|
|
98
|
+
- 提示说明：灰色
|
|
99
|
+
- 当前选中项：高对比高亮，并保留前缀指示，避免在黑底终端里看不清
|
|
100
|
+
|
|
101
|
+
在交互模式的任意子流程中，输入 `back`、`返回` 或 `..`，可以直接取消当前操作并回到主菜单。
|
|
102
|
+
|
|
103
|
+
## 路径模型
|
|
104
|
+
|
|
105
|
+
脚本支持 4 个独立概念：
|
|
106
|
+
|
|
107
|
+
- `--profile-dir DIR`
|
|
108
|
+
- 可选。只是一个“默认锚点目录”，不要求目录名叫 `.cloudflared`
|
|
109
|
+
- `--config-file FILE`
|
|
110
|
+
- 默认配置文件目标路径
|
|
111
|
+
- `--origincert FILE`
|
|
112
|
+
- Cloudflare origin cert 路径
|
|
113
|
+
- `--manager-root DIR`
|
|
114
|
+
- 受管应用元数据目录
|
|
115
|
+
|
|
116
|
+
你可以只传其中一部分，也可以全部拆开。
|
|
117
|
+
|
|
118
|
+
例如：
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
./cloudflared_manager.sh \
|
|
122
|
+
--config-file /srv/cf/configs/default.yml \
|
|
123
|
+
--origincert /srv/cf/certs/prod.pem \
|
|
124
|
+
--manager-root /srv/cf/manager \
|
|
125
|
+
doctor
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
也可以走一个任意命名的 profile：
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
./cloudflared_manager.sh \
|
|
132
|
+
--profile-dir /opt/cloudflare-prod \
|
|
133
|
+
init --login
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
## 快速开始
|
|
137
|
+
|
|
138
|
+
### 1. 保存默认 profile
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
./cloudflared_manager.sh --profile-dir /opt/cloudflare-prod init
|
|
142
|
+
./cloudflared_manager.sh --profile-dir /opt/cloudflare-prod use
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### 2. 登录 Cloudflare
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
./cloudflared_manager.sh --profile-dir /opt/cloudflare-prod login
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
如果 `cloudflared tunnel login` 仍把证书落到默认的 `~/.cloudflared/cert.pem`，脚本会自动复制到你指定的目标路径。
|
|
152
|
+
|
|
153
|
+
### 3. 新建并托管一个 tunnel
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
./cloudflared_manager.sh add admin-dev \
|
|
157
|
+
--hostname admin.example.com \
|
|
158
|
+
--service http://localhost:5173 \
|
|
159
|
+
--start \
|
|
160
|
+
--activate
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
### 4. 一个 Tunnel 同时挂多个入口
|
|
164
|
+
|
|
165
|
+
```bash
|
|
166
|
+
./cloudflared_manager.sh add wchros-main \
|
|
167
|
+
--ingress admin.example.com=http://localhost:8080 \
|
|
168
|
+
--ingress api.example.com=http://localhost:9000 \
|
|
169
|
+
--ingress ssh.example.com=ssh://localhost:22 \
|
|
170
|
+
--start
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
### 5. 接管已有 tunnel
|
|
174
|
+
|
|
175
|
+
```bash
|
|
176
|
+
./cloudflared_manager.sh adopt admin-dev \
|
|
177
|
+
--tunnel-name existing-tunnel \
|
|
178
|
+
--hostname admin.example.com \
|
|
179
|
+
--service http://localhost:5173 \
|
|
180
|
+
--activate
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
### 6. 后续追加、移除或批量修改入口规则
|
|
184
|
+
|
|
185
|
+
```bash
|
|
186
|
+
./cloudflared_manager.sh ingress-list wchros-main
|
|
187
|
+
./cloudflared_manager.sh ingress-add wchros-main \
|
|
188
|
+
--ingress static.example.com=http://localhost:7000 \
|
|
189
|
+
--ingress blog.example.com=http://localhost:7100
|
|
190
|
+
./cloudflared_manager.sh ingress-remove wchros-main --index 2 --hostname blog.example.com
|
|
191
|
+
./cloudflared_manager.sh modify wchros-main \
|
|
192
|
+
--set 1:admin.example.com=http://localhost:8081 \
|
|
193
|
+
--set 2:api.example.com=http://localhost:9001
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
## 常用命令
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
./cloudflared_manager.sh help
|
|
200
|
+
./cloudflared_manager.sh doctor
|
|
201
|
+
./cloudflared_manager.sh list
|
|
202
|
+
./cloudflared_manager.sh ingress-list wchros-main
|
|
203
|
+
./cloudflared_manager.sh status
|
|
204
|
+
./cloudflared_manager.sh logs admin-dev -f
|
|
205
|
+
./cloudflared_manager.sh modify wchros-main --set 2:api.example.com=http://localhost:9001
|
|
206
|
+
./cloudflared_manager.sh modify admin-dev --service http://localhost:8080
|
|
207
|
+
./cloudflared_manager.sh delete admin-dev --delete-tunnel
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
## 说明
|
|
211
|
+
|
|
212
|
+
- 一个受管应用默认对应一个 Tunnel，但这个 Tunnel 下面可以挂多条 `ingress`
|
|
213
|
+
- `modify` 既支持旧的单条写法，也支持批量 `--set N:hostname=service`
|
|
214
|
+
- 如果你只是同一台机器上暴露多个域名/服务，通常优先考虑“1 个 Tunnel + 多 ingress”
|
|
215
|
+
- `modify` 和 `delete --delete-tunnel` 不会自动清理旧 DNS 记录，这仍需要你到 Cloudflare 侧手工处理
|
|
216
|
+
- `install` 目前按 macOS 设计
|
|
217
|
+
- 仓库只保留 shell 版，不再维护 Python 入口
|