cloudflared-manager

一个偏自动化、面向 macOS 的 cloudflared 管理脚本，主入口是 cloudflared_manager.sh。

它解决两个实际问题：

• 不再把路径强绑到 ~/.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

为什么只保留 shell 版

这个仓库现在只保留 shell 版本，是为了减少环境漂移带来的问题。脚本只依赖：

• bash
• cloudflared
• macOS 自带工具：plutil、curl、tail、nc

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

交互式入口

核心逻辑仍然在 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 的动作，交互层也会在执行前自动拦一下，避免你先报错再回头安装。

在 macOS 上，交互层会先调用脚本内置的 install：

• 可以选择直接 sudo 安装官方 pkg
• 如果不想立刻提权，也可以只打开官方安装器
• 如果 GitHub 官方安装包下载失败，会自动回退到 brew install cloudflared

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

• 直接输入编号后回车
• 使用方向键或 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 时，会优先列出当前账号下的远端 tunnels 供选择
• add、adopt、modify、ingress-add、ingress-remove 等录入流程会在输入时即时校验格式，尽量不把错误留到 shell 执行阶段
• add、adopt 现在是“先录入、再汇总确认”的表单式流程，执行前可重填应用名、Tunnel 名称、ingress 规则，并切换布尔选项
• modify、ingress-add、ingress-remove 现在会先读取当前 ingress，展示变更前后对比，再决定是否执行
• 确认页会额外展示彩色变更摘要和最终命令预览，便于在执行前快速复核

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

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

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

路径模型

脚本支持 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

快速开始

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

./cloudflared_manager.sh --profile-dir /opt/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

说明

• 一个受管应用默认对应一个 Tunnel，但这个 Tunnel 下面可以挂多条 ingress
• modify 既支持旧的单条写法，也支持批量 --set N:hostname=service
• 如果你只是同一台机器上暴露多个域名/服务，通常优先考虑“1 个 Tunnel + 多 ingress”
• modify 和 delete --delete-tunnel 不会自动清理旧 DNS 记录，这仍需要你到 Cloudflare 侧手工处理
• install 目前按 macOS 设计，优先官方 pkg，下载失败时会回退到 Homebrew
• 仓库只保留 shell 版，不再维护 Python 入口