cloudflared-manager 0.1.0 → 0.1.2

package/README.md

@@ -58,6 +58,14 @@ node ./cloudflared_manager.mjs --profile-dir /opt/cloudflare-prod interactive
 npx cloudflared-manager
 ```
 
+首次进入交互模式时，如果当前机器还没有安装 `cloudflared`，会先主动提示安装。对 `login`、`tunnels`、`add`、`adopt`、`modify`、`start`、`restart`、`delete --delete-tunnel` 这类依赖 `cloudflared` 的动作，交互层也会在执行前自动拦一下，避免你先报错再回头安装。
+
+在 macOS 上，交互层会先调用脚本内置的 `install`：
+
+- 可以选择直接 `sudo` 安装官方 `pkg`
+- 如果不想立刻提权，也可以只打开官方安装器
+- 如果 GitHub 官方安装包下载失败，会自动回退到 `brew install cloudflared`
+
 交互模式里提供了常用菜单；如果某些高级参数菜单里还没覆盖，可以用“执行自定义命令”直接透传到底层 shell 脚本。
 主菜单同时支持两种选择方式：
 
@@ -135,6 +143,18 @@ npx cloudflared-manager
 
 ## 快速开始
 
+如果你要从零开始初始化一台新机器，最短路径通常就是这一条：
+
+```bash
+./cloudflared_manager.sh --profile-dir /opt/cloudflare-prod init --install --login
+```
+
+如果你走的是 npm 入口，也可以直接：
+
+```bash
+npx cloudflared-manager init --install --login
+```
+
 ### 1. 保存默认 profile
 
 ```bash
@@ -213,5 +233,5 @@ npx cloudflared-manager
 - `modify` 既支持旧的单条写法，也支持批量 `--set N:hostname=service`
 - 如果你只是同一台机器上暴露多个域名/服务，通常优先考虑“1 个 Tunnel + 多 ingress”
 - `modify` 和 `delete --delete-tunnel` 不会自动清理旧 DNS 记录，这仍需要你到 Cloudflare 侧手工处理
-- `install` 目前按 macOS 设计
+- `install` 目前按 macOS 设计，优先官方 `pkg`，下载失败时会回退到 Homebrew
 - 仓库只保留 shell 版，不再维护 Python 入口

package/cloudflared_manager.mjs

@@ -285,6 +285,99 @@ function runShell(baseArgs, commandArgs, options = {}) {
   };
 }
 
+// 返回当前可用的 cloudflared 可执行文件路径。
+function resolveCloudflaredBinary() {
+  const explicitBin = (process.env.CLOUDFLARED_BIN ?? "").trim();
+  if (explicitBin.length > 0) {
+    const explicitResult = spawnSync("bash", ["-lc", '[[ -x "$CLOUDFLARED_BIN" ]]'], {
+      env: process.env,
+    });
+    if ((explicitResult.status ?? 1) === 0) {
+      return explicitBin;
+    }
+  }
+
+  const result = spawnSync("bash", ["-lc", "command -v cloudflared || true"], {
+    encoding: "utf8",
+  });
+  if (result.error) {
+    return "";
+  }
+  return (result.stdout ?? "").trim();
+}
+
+// 判断当前机器是否已经安装 cloudflared。
+function isCloudflaredInstalled() {
+  return resolveCloudflaredBinary().length > 0;
+}
+
+// 在交互模式中引导安装 cloudflared，成功后返回 true。
+async function installCloudflaredInteractive(rl, baseArgs, options = {}) {
+  if (isCloudflaredInstalled()) {
+    return true;
+  }
+
+  if (options.confirm !== false) {
+    const prompt = options.prompt ?? "是否现在安装 cloudflared";
+    if (!(await askYesNo(rl, prompt, true))) {
+      return false;
+    }
+  }
+
+  const installArgs = ["install"];
+  if (process.platform === "darwin") {
+    const useSudoInstall = await askYesNo(
+      rl,
+      "是否直接使用 sudo 安装（否则只打开官方 pkg 安装器）",
+      true,
+    );
+    if (useSudoInstall) {
+      installArgs.push("--sudo-install");
+    }
+  }
+
+  runShell(baseArgs, installArgs);
+
+  if (isCloudflaredInstalled()) {
+    console.log("已检测到 cloudflared，可继续后续操作。");
+    return true;
+  }
+
+  if (process.platform === "darwin" && !installArgs.includes("--sudo-install")) {
+    console.log("已打开 cloudflared 官方安装器。完成安装后，回到这里继续即可。");
+  } else {
+    console.log("安装命令已执行，但当前仍未检测到 cloudflared。请完成安装后再继续。");
+  }
+  return false;
+}
+
+// 在首次进入交互模式时，主动提示安装 cloudflared。
+async function maybeOfferCloudflaredInstall(rl, baseArgs) {
+  if (isCloudflaredInstalled()) {
+    return;
+  }
+
+  console.log("检测到当前机器尚未安装 cloudflared。");
+  console.log("登录 Cloudflare、查看远端 Tunnel、创建或启动 Tunnel 之前，需要先安装它。");
+  if (await askYesNo(rl, "是否现在安装 cloudflared", true)) {
+    await installCloudflaredInteractive(rl, baseArgs, { confirm: false });
+  } else {
+    console.log("已跳过安装。你仍可先执行 doctor 或 init，后续需要时再安装。");
+  }
+}
+
+// 某些交互动作依赖 cloudflared，执行前先确保已安装。
+async function ensureCloudflaredForAction(rl, baseArgs, label) {
+  if (isCloudflaredInstalled()) {
+    return true;
+  }
+
+  console.log(`${label}前需要先安装 cloudflared。`);
+  return installCloudflaredInteractive(rl, baseArgs, {
+    prompt: "是否现在安装 cloudflared",
+  });
+}
+
 // 读取一行输入，可选提供默认值。
 async function ask(rl, label, options = {}) {
   const suffix =
@@ -1751,6 +1844,9 @@ async function handleAction(rl, baseArgs, action, context = {}) {
         runShell(baseArgs, ["list"]);
         return { keepRunning: true };
       case "3":
+        if (!(await ensureCloudflaredForAction(rl, baseArgs, "查看远端 Tunnel"))) {
+          return { keepRunning: true };
+        }
         runShell(baseArgs, ["tunnels"]);
         return { keepRunning: true };
       case "4":
@@ -1766,6 +1862,9 @@ async function handleAction(rl, baseArgs, action, context = {}) {
         return { keepRunning: true };
       case "5":
         {
+          if (!(await ensureCloudflaredForAction(rl, baseArgs, "创建新 Tunnel"))) {
+            return { keepRunning: true };
+          }
           const addState = await runAddWizard(rl, baseArgs);
           if (!addState) {
             console.log("已取消创建新 tunnel。");
@@ -1779,6 +1878,9 @@ async function handleAction(rl, baseArgs, action, context = {}) {
         }
       case "6":
         {
+          if (!(await ensureCloudflaredForAction(rl, baseArgs, "接管已有 Tunnel"))) {
+            return { keepRunning: true };
+          }
           const adoptState = await runAdoptWizard(rl, baseArgs);
           if (!adoptState) {
             console.log("已取消接管已有 tunnel。");
@@ -1800,6 +1902,9 @@ async function handleAction(rl, baseArgs, action, context = {}) {
         }
         if (!name) return { keepRunning: true };
         {
+          if (!(await ensureCloudflaredForAction(rl, baseArgs, "修改 ingress"))) {
+            return { keepRunning: true };
+          }
           const modifyState = await runModifyWizard(rl, baseArgs, name);
           if (!modifyState) {
             console.log("已取消修改 ingress。");
@@ -1823,6 +1928,9 @@ async function handleAction(rl, baseArgs, action, context = {}) {
         }
         if (!name) return { keepRunning: true };
         {
+          if (!(await ensureCloudflaredForAction(rl, baseArgs, "新增 ingress"))) {
+            return { keepRunning: true };
+          }
           const addState = await runIngressAddWizard(rl, baseArgs, name);
           if (!addState) {
             console.log("已取消新增 ingress。");
@@ -1862,6 +1970,9 @@ async function handleAction(rl, baseArgs, action, context = {}) {
           });
         }
         if (!name) return { keepRunning: true };
+        if (!(await ensureCloudflaredForAction(rl, baseArgs, "启动应用"))) {
+          return { keepRunning: true };
+        }
         runShell(baseArgs, ["start", name]);
         return { keepRunning: true };
       case "11":
@@ -1884,6 +1995,9 @@ async function handleAction(rl, baseArgs, action, context = {}) {
           });
         }
         if (!name) return { keepRunning: true };
+        if (!(await ensureCloudflaredForAction(rl, baseArgs, "重启应用"))) {
+          return { keepRunning: true };
+        }
         runShell(baseArgs, ["restart", name]);
         return { keepRunning: true };
       case "13":
@@ -1929,18 +2043,42 @@ async function handleAction(rl, baseArgs, action, context = {}) {
         }
         if (!name) return { keepRunning: true };
         args = ["delete", name];
-        if (await askYesNo(rl, "是否同时删除远端 tunnel", false)) args.push("--delete-tunnel");
+        if (await askYesNo(rl, "是否同时删除远端 tunnel", false)) {
+          if (!(await ensureCloudflaredForAction(rl, baseArgs, "删除远端 Tunnel"))) {
+            return { keepRunning: true };
+          }
+          args.push("--delete-tunnel");
+        }
         runShell(baseArgs, args);
         return { keepRunning: true, nextMenuKey: "app_picker", clearAppName: true };
       case "17":
         args = ["init"];
-        if (await askYesNo(rl, "是否同时执行 login", false)) args.push("--login");
+        if (!isCloudflaredInstalled()) {
+          if (await askYesNo(rl, "检测到未安装 cloudflared，是否在初始化时一并安装", true)) {
+            args.push("--install");
+          }
+        }
+        if (await askYesNo(rl, "是否同时执行 login", false)) {
+          if (!isCloudflaredInstalled() && !args.includes("--install")) {
+            if (await askYesNo(rl, "login 需要先安装 cloudflared，是否在初始化时一并安装", true)) {
+              args.push("--install");
+            } else {
+              console.log("已跳过 login。完成安装后可在“环境与登录 -> 登录 Cloudflare”中继续。");
+            }
+          }
+          if (isCloudflaredInstalled() || args.includes("--install")) {
+            args.push("--login");
+          }
+        }
         runShell(baseArgs, args);
         return { keepRunning: true };
       case "18":
         runShell(baseArgs, ["use"]);
         return { keepRunning: true };
       case "19":
+        if (!(await ensureCloudflaredForAction(rl, baseArgs, "登录 Cloudflare"))) {
+          return { keepRunning: true };
+        }
         runShell(baseArgs, ["login"]);
         return { keepRunning: true };
       case "20": {
@@ -1996,6 +2134,7 @@ async function runInteractive(baseArgs) {
   });
 
   try {
+    await maybeOfferCloudflaredInstall(rl, baseArgs);
     let keepRunning = true;
     let currentMenuKey = MAIN_MENU_KEY;
     let currentAppName = "";

package/cloudflared_manager.sh

@@ -160,6 +160,22 @@ dir_exists() {
   [[ -d "$1" ]]
 }
 
+# 判断数组是否至少包含一个元素，兼容 macOS Bash 3 在 set -u 下的空数组行为。
+array_has_items() {
+  local array_name="$1"
+  eval "[[ \${${array_name}[0]+_} == _ ]]"
+}
+
+# 返回数组长度，兼容 macOS Bash 3 在 set -u 下的空数组行为。
+array_length() {
+  local array_name="$1"
+  if array_has_items "$array_name"; then
+    eval "printf '%s\n' \"\${#${array_name}[@]}\""
+  else
+    printf '0\n'
+  fi
+}
+
 # 判断命令是否可用。
 command_exists() {
   command -v "$1" >/dev/null 2>&1
@@ -323,7 +339,7 @@ ensure_manager_dirs() {
 # 确保系统已经安装 cloudflared。
 ensure_cloudflared() {
   if [[ -z "$CLOUDFLARED_BIN" ]]; then
-    die "cloudflared 未安装，请先执行 install。"
+    die "cloudflared 未安装。请先执行 install，或使用 init --install --login 完成首次初始化。"
   fi
 }
 
@@ -1620,6 +1636,7 @@ EOF
 # 在 macOS 上下载安装 cloudflared。
 cmd_install() {
   local sudo_install=0
+  local arch pkg_name url pkg_path
   while [[ $# -gt 0 ]]; do
     case "$1" in
       --sudo-install) sudo_install=1; shift ;;
@@ -1644,7 +1661,6 @@ EOF
     die "自动安装目前只支持 macOS。"
   fi
 
-  local arch pkg_name url pkg_path
   arch="$(uname -m)"
   case "$arch" in
     x86_64) pkg_name="cloudflared-amd64.pkg" ;;
@@ -1653,13 +1669,32 @@ EOF
   esac
   url="https://github.com/cloudflare/cloudflared/releases/latest/download/$pkg_name"
   pkg_path="/tmp/$pkg_name"
-  curl -L --fail -o "$pkg_path" "$url"
-  if [[ "$sudo_install" == "1" ]]; then
-    sudo installer -pkg "$pkg_path" -target /
-  else
+  if curl -L --fail -o "$pkg_path" "$url"; then
+    if [[ "$sudo_install" == "1" ]]; then
+      sudo installer -pkg "$pkg_path" -target /
+      CLOUDFLARED_BIN="${CLOUDFLARED_BIN:-$(command -v cloudflared || true)}"
+      if [[ -n "$CLOUDFLARED_BIN" ]]; then
+        info "cloudflared 已安装：$("$CLOUDFLARED_BIN" --version)"
+      fi
+      return 0
+    fi
     open "$pkg_path"
     info "已打开安装包: $pkg_path"
+    return 0
+  fi
+
+  warn "官方下载失败，尝试改用 Homebrew 安装。"
+  if ! command_exists brew; then
+    die "未找到 Homebrew，且 cloudflared 官方安装包下载失败。请稍后重试，或先安装 Homebrew。"
   fi
+
+  HOMEBREW_NO_AUTO_UPDATE=1 brew install cloudflared
+  CLOUDFLARED_BIN="${CLOUDFLARED_BIN:-$(command -v cloudflared || true)}"
+  if [[ -n "$CLOUDFLARED_BIN" ]]; then
+    info "cloudflared 已安装：$("$CLOUDFLARED_BIN" --version)"
+    return 0
+  fi
+  die "Homebrew 安装 cloudflared 后仍未检测到可执行文件。"
 }
 
 # 执行 cloudflared tunnel login，并同步默认证书到目标位置。
@@ -1777,6 +1812,18 @@ cmd_add() {
   local foreground=0
   local activate=0
 
+  if [[ "$name" == "-h" || "$name" == "--help" ]]; then
+    cat <<EOF
+用法:
+  $SCRIPT_NAME add NAME [--hostname HOST --service URL] [--ingress HOST=URL ...] [--tunnel-name NAME] [--use-existing] [--overwrite-dns] [--skip-check] [--start] [--foreground] [--activate]
+
+说明:
+  - 兼容旧写法：使用一组 --hostname 和 --service
+  - 多 ingress 写法：重复传 --ingress hostname=service
+  - 可以混用，首条规则会作为“主入口”展示
+EOF
+    return 0
+  fi
   [[ -z "$name" ]] && die "add 需要 NAME"
   shift
 
@@ -1818,7 +1865,11 @@ EOF
     die "受管应用已存在: $name"
   fi
 
-  build_requested_ingress_rules "$hostname" "$service" "${ingress_specs[@]}"
+  if array_has_items ingress_specs; then
+    build_requested_ingress_rules "$hostname" "$service" "${ingress_specs[@]}"
+  else
+    build_requested_ingress_rules "$hostname" "$service"
+  fi
   if [[ "$skip_check" == "0" ]]; then
     check_all_ingress_targets
   fi
@@ -1863,6 +1914,17 @@ cmd_adopt() {
   local skip_check=0
   local activate=0
 
+  if [[ "$name" == "-h" || "$name" == "--help" ]]; then
+    cat <<EOF
+用法:
+  $SCRIPT_NAME adopt NAME --tunnel-name NAME [--hostname HOST --service URL] [--ingress HOST=URL ...] [--ensure-dns] [--overwrite-dns] [--skip-check] [--activate]
+
+说明:
+  - 至少要提供一条 ingress 规则
+  - 如果远端 DNS 已经配好，可不传 --ensure-dns
+EOF
+    return 0
+  fi
   [[ -z "$name" ]] && die "adopt 需要 NAME"
   shift
 
@@ -1903,7 +1965,11 @@ EOF
     die "受管应用已存在: $name"
   fi
 
-  build_requested_ingress_rules "$hostname" "$service" "${ingress_specs[@]}"
+  if array_has_items ingress_specs; then
+    build_requested_ingress_rules "$hostname" "$service" "${ingress_specs[@]}"
+  else
+    build_requested_ingress_rules "$hostname" "$service"
+  fi
   if [[ "$skip_check" == "0" ]]; then
     check_all_ingress_targets
   fi
@@ -2002,7 +2068,7 @@ EOF
     [[ -n "$pid" ]] && was_running=1
   fi
 
-  if [[ "${#modify_specs[@]}" -gt 0 ]]; then
+  if array_has_items modify_specs; then
     if [[ -n "$new_hostname" || -n "$new_service" || "$index" != "1" ]]; then
       die "使用 --set 批量修改时，不要再混用 --index / --hostname / --service"
     fi
@@ -2052,7 +2118,7 @@ EOF
       i=$((i + 1))
     done
 
-    changed_count="${#changed_indices[@]}"
+    changed_count="$(array_length changed_indices)"
     if [[ "$changed_count" == "0" ]]; then
       info "没有变更。"
       return 0
@@ -2132,13 +2198,13 @@ EOF
   if [[ "$was_running" == "1" && "$no_restart" == "0" ]]; then
     stop_app 0
     start_app 0 "$skip_check"
-    if [[ "${#modify_specs[@]}" -gt 0 ]]; then
+    if array_has_items modify_specs; then
       info "已批量修改 ${changed_count} 条 ingress 并重启: $META_NAME"
     else
       info "已修改并重启: $META_NAME"
     fi
   else
-    if [[ "${#modify_specs[@]}" -gt 0 ]]; then
+    if array_has_items modify_specs; then
       info "已批量修改 ingress 规则数量: ${changed_count}"
     else
       info "已修改: $META_NAME"
@@ -2226,18 +2292,20 @@ EOF
     requested_services+=("$(normalize_service "$service")")
   fi
 
-  for candidate_service in "${ingress_specs[@]}"; do
-    parse_ingress_spec "$candidate_service"
-    requested_hosts+=("$PARSED_INGRESS_HOSTNAME")
-    requested_services+=("$PARSED_INGRESS_SERVICE")
-  done
+  if array_has_items ingress_specs; then
+    for candidate_service in "${ingress_specs[@]}"; do
+      parse_ingress_spec "$candidate_service"
+      requested_hosts+=("$PARSED_INGRESS_HOSTNAME")
+      requested_services+=("$PARSED_INGRESS_SERVICE")
+    done
+  fi
 
-  if [[ "${#requested_hosts[@]}" == "0" ]]; then
+  if [[ "$(array_length requested_hosts)" == "0" ]]; then
     die "至少需要提供一条 ingress 规则。可使用 --hostname/--service，或重复传 --ingress hostname=service"
   fi
 
   i=0
-  while [[ "$i" -lt "${#requested_hosts[@]}" ]]; do
+  while [[ "$i" -lt "$(array_length requested_hosts)" ]]; do
     candidate_hostname="${requested_hosts[$i]}"
     candidate_service="${requested_services[$i]}"
 
@@ -2340,7 +2408,7 @@ EOF
     esac
   done
 
-  if [[ "${#hostnames[@]}" == "0" && "${#indices[@]}" == "0" ]]; then
+  if [[ "$(array_length hostnames)" == "0" && "$(array_length indices)" == "0" ]]; then
     die "ingress-remove 至少需要一个 --hostname 或 --index"
   fi
 
@@ -2359,21 +2427,25 @@ EOF
     i=$((i + 1))
   done
 
-  for hostname in "${hostnames[@]}"; do
-    hostname="$(normalize_hostname "$hostname")"
-    current_index="$(find_ingress_rule_index_by_hostname "$hostname" 2>/dev/null || true)"
-    [[ -n "$current_index" ]] || die "未找到要删除的 ingress 主机名: $hostname"
-    remove_flags[$current_index]=1
-  done
+  if array_has_items hostnames; then
+    for hostname in "${hostnames[@]}"; do
+      hostname="$(normalize_hostname "$hostname")"
+      current_index="$(find_ingress_rule_index_by_hostname "$hostname" 2>/dev/null || true)"
+      [[ -n "$current_index" ]] || die "未找到要删除的 ingress 主机名: $hostname"
+      remove_flags[$current_index]=1
+    done
+  fi
 
-  for index in "${indices[@]}"; do
-    [[ "$index" =~ ^[1-9][0-9]*$ ]] || die "--index 必须是大于等于 1 的整数"
-    current_index=$((index - 1))
-    if [[ "$current_index" -lt 0 || "$current_index" -ge "$total_rules" ]]; then
-      die "要删除的 ingress 序号超出范围: $index"
-    fi
-    remove_flags[$current_index]=1
-  done
+  if array_has_items indices; then
+    for index in "${indices[@]}"; do
+      [[ "$index" =~ ^[1-9][0-9]*$ ]] || die "--index 必须是大于等于 1 的整数"
+      current_index=$((index - 1))
+      if [[ "$current_index" -lt 0 || "$current_index" -ge "$total_rules" ]]; then
+        die "要删除的 ingress 序号超出范围: $index"
+      fi
+      remove_flags[$current_index]=1
+    done
+  fi
 
   i=0
   while [[ "$i" -lt "$total_rules" ]]; do
@@ -2390,7 +2462,7 @@ EOF
   if [[ "$remove_count" == "0" ]]; then
     die "未找到要删除的 ingress 规则。"
   fi
-  if [[ "${#remaining_hosts[@]}" == "0" ]]; then
+  if [[ "$(array_length remaining_hosts)" == "0" ]]; then
     die "至少需要保留一条 ingress 规则。当前删除范围会把全部规则删空。"
   fi
 
@@ -2402,7 +2474,7 @@ EOF
   save_ingress_rules
   write_config 0
   save_meta
-  warn "已从配置中移除 ${#removed_hosts[@]} 条 ingress。Cloudflare 上旧 DNS 记录不会自动删除，如已弃用请手工清理。"
+  warn "已从配置中移除 $(array_length removed_hosts) 条 ingress。Cloudflare 上旧 DNS 记录不会自动删除，如已弃用请手工清理。"
 
   if [[ "$activate" == "1" ]]; then
     activate_default_config
@@ -2412,7 +2484,7 @@ EOF
     start_app 0 0
     info "已移除 ingress 并重启: $META_NAME"
   else
-    info "已移除 ingress 规则数量: ${#removed_hosts[@]}"
+    info "已移除 ingress 规则数量: $(array_length removed_hosts)"
   fi
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudflared-manager",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Interactive wrapper and shell-first manager for cloudflared tunnels",
   "type": "module",
   "bin": {