cloudflared-manager

一个偏自动化的 cloudflared 管理脚本，Unix 平台主入口是 cloudflared_manager.sh，Windows 可使用 cloudflared_manager.ps1。

它解决两个实际问题：

• 不再把路径强绑到 ~/.cloudflared 或目录名必须叫 .cloudflared
• 把 profile_dir、config.yml、cert.pem、manager_root 四个概念拆开，支持任意路径组合

主要能力

• 管理远端 tunnel：add、adopt、modify、delete、tunnels
• 管理本地运行：start、stop、restart、status、logs
• 管理默认 profile：init、use、login、import-cert、activate
• 管理多入口规则：ingress-list、ingress-add、ingress-remove
• 自动处理：
  • login 后自动同步默认 cert.pem 到目标路径
  • 启动前会提示本地 service 连通性异常，但默认不阻止执行
  • credentials.json 缺失时自动补发 token
  • add 时优先把 credentials 直接写入受管目录
  • 旧版单规则应用会自动迁移成 ingress.tsv

为什么保留脚本版

这个仓库现在保留脚本版本（Bash + PowerShell），是为了减少环境漂移带来的问题。Unix 入口只依赖：

• bash
• cloudflared
• macOS：plutil、curl、tail、nc
• Linux：python3、curl、tail、nc

不依赖 jq、Python 第三方库，也不要求固定的 .cloudflared 目录名。

平台支持

| 平台 | 底层入口 | 当前状态 | install 行为 | | --- | --- | --- | --- | | macOS | cloudflared_manager.sh | 完整支持 | 官方 pkg（可选 --sudo-install），下载失败回退 brew | | Linux | cloudflared_manager.sh | 完整支持 | 官方二进制，--sudo-install 安装到 /usr/local/bin，否则 ~/.local/bin | | Windows | cloudflared_manager.ps1 | 完整支持 | 优先 winget/choco/scoop，失败回退下载官方 exe |

推荐入口：

• Unix（macOS/Linux）：./cloudflared_manager.sh ...
• Windows PowerShell：.\cloudflared_manager.ps1 ...
• 交互包装层：node ./cloudflared_manager.mjs ...（会按平台自动分发到底层脚本）

交互式入口

核心逻辑仍然在 shell 脚本里，但仓库现在额外提供了一个 Node 交互式包装层：

• cloudflared_manager.sh
  • 适合熟悉命令行参数、希望直接执行命令的人
• cloudflared_manager.mjs
  • 适合通过菜单和提示一步步操作的人

本地用法：

node ./cloudflared_manager.mjs
npm exec --yes -- cloudflared-manager

如果你已经保存了 profile，也可以直接进入菜单；如果要带自定义全局参数进入交互模式，可以这样：

node ./cloudflared_manager.mjs --profile-dir /opt/cloudflare-prod interactive

发布到 npm 之后，就可以直接用：

npx cloudflared-manager

首次进入交互模式时，如果当前机器还没有安装 cloudflared，会先主动提示安装。对 login、tunnels、add、adopt、modify、start、restart、delete --delete-tunnel 这类依赖 cloudflared 的动作，交互层也会在执行前自动拦一下，避免你先报错再回头安装。

交互层会先调用脚本内置的 install：

• macOS：可选择直接 sudo 安装官方 pkg，不提权时会先打开安装器，下载失败会回退到 brew install cloudflared
• Linux：会下载安装官方二进制；带 --sudo-install 安装到 /usr/local/bin，否则安装到 ~/.local/bin
• Windows（PowerShell 入口）：优先尝试 winget/choco/scoop，失败时回退下载官方 exe

交互模式里提供了常用菜单；如果某些高级参数菜单里还没覆盖，可以用“执行自定义命令”直接透传到底层管理脚本（Unix Bash / Windows PowerShell）。 主菜单同时支持两种选择方式：

• 直接输入编号后回车
• 使用方向键或 j/k 上下移动，h/l 返回或确认
• 使用 gg 跳到首项，G 跳到末项
• 使用 Ctrl+u / Ctrl+d 做半页跳转
• 顶部会显示当前所处层级的父级面包屑路径，不与当前页面标题重复
• 在二级菜单中，按 Esc 或左方向键可直接返回上一级
• 菜单列表已收敛为单行选项，当前项说明与快捷键会合并显示在底部状态栏，减少视觉噪音
• 底部状态栏默认只显示核心按键；gg/G、Ctrl+u/d 等高级快捷键仍然可用
• 顶部会显示更宽、更均衡的品牌标题框，并把当前菜单标题并入标题框；菜单编号按两位数显示，便于纵向对齐
• 菜单编号可直接输入 1 或 01，0 或 00，两种写法都能识别
• 进入交互模式后会直接显示菜单主体，不再额外输出冗余提示行
• 默认已保存设置时不再额外显示 设置: 行；只有显式传入自定义全局参数时才展示
• 二级菜单会按功能分组显示，例如应用页会拆成“查看 / 运行 / Ingress / 配置与管理”
• 标题框与底部状态栏会按终端宽度自动裁剪，避免长文本把界面撑乱

交互菜单已经拆成一级、二级结构：

• 一级菜单按“环境与登录 / 新建与接管 / 现有应用管理 / 远端与高级”分类
• 进入“现有应用管理”后，会先列出当前 profile 下的受管应用，再进入该应用的专属子菜单
• 应用相关操作会优先提供选择列表，尽量不再要求手输应用名称
• 如果手动输入了列表外的应用名，交互层会先提示“将尝试按默认 config.yml 自动接管”，失败时再提示使用 add 或 adopt
• 接管已有 tunnel 时，可先直接输入远端 tunnel 名称；留空时再列出当前账号下的远端 tunnels 供选择
• add、adopt、modify、ingress-add、ingress-remove 等录入流程会在输入时即时校验格式，尽量不把错误留到 shell 执行阶段
• add、adopt 现在是“先录入、再汇总确认”的表单式流程，执行前可重填应用名、Tunnel 名称、ingress 规则，并切换布尔选项
• modify、ingress-add、ingress-remove 现在会先读取当前 ingress，展示变更前后对比，再决定是否执行
• 确认页会额外展示彩色变更摘要和最终命令预览，便于在执行前快速复核

配色也改成了更适合深浅背景的高对比方案：

• 主操作：青色
• 次操作：绿色
• 辅助操作：黄色
• 危险操作：红色
• 返回/返回上一级：蓝色
• 提示说明：灰色
• 当前选中项：高对比高亮，并保留前缀指示，避免在黑底终端里看不清

在交互模式的录入型子流程中，输入 back、返回 或 ..，会直接取消当前操作并回到主菜单。

在菜单页里输入 back、返回 或 ..，则等同于选择当前菜单的 00 返回项。

路径模型

脚本支持 4 个独立概念：

• --profile-dir DIR
  • 可选。只是一个“默认锚点目录”，不要求目录名叫 .cloudflared
• --config-file FILE
  • 默认配置文件目标路径
• --origincert FILE
  • Cloudflare origin cert 路径
• --manager-root DIR
  • 受管应用元数据目录

你可以只传其中一部分，也可以全部拆开。

例如：

./cloudflared_manager.sh \
  --config-file /srv/cf/configs/default.yml \
  --origincert /srv/cf/certs/prod.pem \
  --manager-root /srv/cf/manager \
  doctor

也可以走一个任意命名的 profile：

./cloudflared_manager.sh \
  --profile-dir /opt/cloudflare-prod \
  init --login

快速开始

下文示例默认使用 Unix 入口（./cloudflared_manager.sh）。在 Windows PowerShell 中，把入口替换为 .\cloudflared_manager.ps1 即可，参数语义保持一致。

如果你要从零开始初始化一台新机器，最短路径通常就是这一条：

./cloudflared_manager.sh --profile-dir /opt/cloudflare-prod init --install --login

Windows PowerShell 示例：

.\cloudflared_manager.ps1 --profile-dir D:\cloudflare\prod init --install --login

如果你走的是 npm 入口，也可以直接：

npx cloudflared-manager init --install --login

1. 保存默认 profile

./cloudflared_manager.sh --profile-dir /opt/cloudflare-prod init
./cloudflared_manager.sh --profile-dir /opt/cloudflare-prod use

2. 登录 Cloudflare

./cloudflared_manager.sh --profile-dir /opt/cloudflare-prod login

如果 cloudflared tunnel login 仍把证书落到默认的 ~/.cloudflared/cert.pem，脚本会自动复制到你指定的目标路径。

3. 新建并托管一个 tunnel

./cloudflared_manager.sh add admin-dev \
  --hostname admin.example.com \
  --service http://localhost:5173 \
  --start \
  --activate

4. 一个 Tunnel 同时挂多个入口

./cloudflared_manager.sh add wchros-main \
  --ingress admin.example.com=http://localhost:8080 \
  --ingress api.example.com=http://localhost:9000 \
  --ingress ssh.example.com=ssh://localhost:22 \
  --start

5. 接管已有 tunnel

./cloudflared_manager.sh adopt admin-dev \
  --tunnel-name existing-tunnel \
  --hostname admin.example.com \
  --service http://localhost:5173 \
  --activate

6. 后续追加、移除或批量修改入口规则

./cloudflared_manager.sh ingress-list wchros-main
./cloudflared_manager.sh ingress-add wchros-main \
  --ingress static.example.com=http://localhost:7000 \
  --ingress blog.example.com=http://localhost:7100
./cloudflared_manager.sh ingress-remove wchros-main --index 2 --hostname blog.example.com
./cloudflared_manager.sh modify wchros-main \
  --set 1:admin.example.com=http://localhost:8081 \
  --set 2:api.example.com=http://localhost:9001

常用命令

./cloudflared_manager.sh help
./cloudflared_manager.sh doctor
./cloudflared_manager.sh list
./cloudflared_manager.sh ingress-list wchros-main
./cloudflared_manager.sh status
./cloudflared_manager.sh logs admin-dev -f
./cloudflared_manager.sh modify wchros-main --set 2:api.example.com=http://localhost:9001
./cloudflared_manager.sh modify admin-dev --service http://localhost:8080
./cloudflared_manager.sh delete admin-dev --delete-tunnel

PowerShell 对应示例：

.\cloudflared_manager.ps1 help
.\cloudflared_manager.ps1 doctor
.\cloudflared_manager.ps1 list
.\cloudflared_manager.ps1 status
.\cloudflared_manager.ps1 logs admin-dev -f
.\cloudflared_manager.ps1 modify wchros-main --set 2:api.example.com=http://localhost:9001
.\cloudflared_manager.ps1 delete admin-dev --delete-tunnel

开发与验收

本地最小检查：

bash -n cloudflared_manager.sh
node --check cloudflared_manager.mjs
./cloudflared_manager.sh doctor
./cloudflared_manager.sh modify -h
./cloudflared_manager.sh status

CI（.github/workflows/smoke.yml）会在 push、pull_request、workflow_dispatch 下执行三平台冒烟：

• Unix（ubuntu-latest + macos-latest）：Bash 语法、Node 语法、核心命令 -h 与 doctor
• Windows（windows-latest）：PowerShell 入口命令 -h 与 doctor，以及 Node 包装层分发冒烟

说明

• 一个受管应用默认对应一个 Tunnel，但这个 Tunnel 下面可以挂多条 ingress
• modify 既支持旧的单条写法，也支持批量 --set N:hostname=service
• 如果你只是同一台机器上暴露多个域名/服务，通常优先考虑“1 个 Tunnel + 多 ingress”
• modify 和 delete --delete-tunnel 不会自动清理旧 DNS 记录，这仍需要你到 Cloudflare 侧手工处理
• install 目前支持 macOS/Linux/Windows(PowerShell)：平台内优先走原生安装路径，失败后再回退
• Windows 的 PowerShell 入口已覆盖 Bash 的核心命令（含 add/adopt/modify/ingress/delete）
• 仓库内置三平台冒烟 CI：macOS + Linux + Windows，在 push、pull_request 和手动触发（workflow_dispatch）时执行
• 仓库保留脚本版（Bash + PowerShell），不再维护 Python 入口