cloudflared-manager 0.1.0

package/cloudflared_manager.sh

@@ -0,0 +1,2727 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_NAME="$(basename "$0")"
+SETTINGS_FILE="${CLOUDFLARED_MANAGER_SETTINGS:-$HOME/.cloudflared-manager.env}"
+DEFAULT_LOGIN_CERT="$HOME/.cloudflared/cert.pem"
+DEFAULT_MANAGER_HOME="$HOME/.cloudflared-manager"
+
+CLOUDFLARED_BIN="${CLOUDFLARED_BIN:-$(command -v cloudflared || true)}"
+
+CLI_PROFILE_DIR=""
+CLI_DEFAULT_CONFIG_FILE=""
+CLI_ORIGIN_CERT=""
+CLI_MANAGER_ROOT=""
+SAVE_PROFILE=0
+
+SETTINGS_PROFILE_DIR=""
+SETTINGS_DEFAULT_CONFIG_FILE=""
+SETTINGS_ORIGIN_CERT=""
+SETTINGS_MANAGER_ROOT=""
+
+PROFILE_DIR=""
+DEFAULT_CONFIG_FILE=""
+ORIGIN_CERT=""
+MANAGER_ROOT=""
+APPS_DIR=""
+ARCHIVE_DIR=""
+
+META_NAME=""
+META_TUNNEL_NAME=""
+META_TUNNEL_ID=""
+META_HOSTNAME=""
+META_SERVICE=""
+META_APP_DIR=""
+META_CONFIG_FILE=""
+META_CREDENTIALS_FILE=""
+META_INGRESS_FILE=""
+META_PID_FILE=""
+META_LOG_FILE=""
+META_META_FILE=""
+META_CREATED_AT=""
+META_UPDATED_AT=""
+
+INGRESS_HOSTS=()
+INGRESS_SERVICES=()
+PARSED_INGRESS_HOSTNAME=""
+PARSED_INGRESS_SERVICE=""
+PARSED_MODIFY_INDEX=""
+PARSED_MODIFY_HOSTNAME=""
+PARSED_MODIFY_SERVICE=""
+
+REMOTE_FOUND=0
+REMOTE_TUNNEL_ID=""
+REMOTE_TUNNEL_NAME=""
+REMOTE_TUNNEL_CREATED_AT=""
+REMOTE_TUNNEL_CONNECTIONS="0"
+
+# 返回当前 UTC 时间，统一用于元数据时间戳。
+utc_now() {
+  date -u +"%Y-%m-%dT%H:%M:%SZ"
+}
+
+# 向标准错误输出文本。
+eprint() {
+  printf '%s\n' "$*" >&2
+}
+
+# 向标准输出打印普通信息。
+info() {
+  printf '%s\n' "$*"
+}
+
+# 输出警告信息。
+warn() {
+  eprint "警告: $*"
+}
+
+# 输出错误信息并退出。
+die() {
+  eprint "错误: $*"
+  exit 1
+}
+
+# 展开形如 ~ 或 ~/path 的用户目录写法。
+expand_tilde() {
+  local value="$1"
+  if [[ "$value" == "~" ]]; then
+    printf '%s\n' "$HOME"
+  elif [[ "$value" == "~/"* ]]; then
+    printf '%s/%s\n' "$HOME" "${value#~/}"
+  else
+    printf '%s\n' "$value"
+  fi
+}
+
+# 将相对路径转换为绝对路径，但不要求目标必须存在。
+normalize_path() {
+  local value
+  value="$(expand_tilde "$1")"
+  if [[ -z "$value" ]]; then
+    printf '\n'
+  elif [[ "$value" == /* ]]; then
+    printf '%s\n' "$value"
+  else
+    printf '%s/%s\n' "$PWD" "$value"
+  fi
+}
+
+# 在目标存在时尽量返回规范路径，否则返回归一化后的绝对路径。
+canonical_path() {
+  local value dir base
+  value="$(expand_tilde "$1")"
+  if [[ -d "$value" ]]; then
+    (
+      cd "$value"
+      pwd -P
+    )
+    return
+  fi
+  if [[ -e "$value" ]]; then
+    dir="$(dirname "$value")"
+    base="$(basename "$value")"
+    (
+      cd "$dir"
+      printf '%s/%s\n' "$(pwd -P)" "$base"
+    )
+    return
+  fi
+  normalize_path "$value"
+}
+
+# 确保目录存在。
+ensure_dir() {
+  mkdir -p "$1"
+}
+
+# 生成兼容 macOS 的临时文件路径。
+portable_mktemp() {
+  local prefix="$1"
+  mktemp "${TMPDIR:-/tmp}/${prefix}.XXXXXX"
+}
+
+# 返回路径的父目录。
+path_parent() {
+  dirname "$1"
+}
+
+# 返回路径的文件名部分。
+path_basename() {
+  basename "$1"
+}
+
+# 判断文件是否存在。
+file_exists() {
+  [[ -f "$1" ]]
+}
+
+# 判断目录是否存在。
+dir_exists() {
+  [[ -d "$1" ]]
+}
+
+# 判断命令是否可用。
+command_exists() {
+  command -v "$1" >/dev/null 2>&1
+}
+
+# 生成备份文件路径。
+backup_path() {
+  local original="$1"
+  local stamp
+  stamp="$(date +"%Y%m%d-%H%M%S")"
+  printf '%s/%s.bak-%s\n' "$(dirname "$original")" "$(basename "$original")" "$stamp"
+}
+
+# 备份文件，若源文件不存在则直接返回。
+backup_file() {
+  local original="$1"
+  local backup=""
+  if ! file_exists "$original"; then
+    return 0
+  fi
+  backup="$(backup_path "$original")"
+  cp "$original" "$backup"
+  printf '%s\n' "$backup"
+}
+
+# 将键值对写入制表符分隔的简单配置文件。
+write_kv_file() {
+  local file="$1"
+  shift
+  ensure_dir "$(dirname "$file")"
+  : >"$file"
+  while [[ $# -gt 1 ]]; do
+    printf '%s\t%s\n' "$1" "$2" >>"$file"
+    shift 2
+  done
+}
+
+# 读取用户保存的默认路径设置。
+load_settings() {
+  SETTINGS_PROFILE_DIR=""
+  SETTINGS_DEFAULT_CONFIG_FILE=""
+  SETTINGS_ORIGIN_CERT=""
+  SETTINGS_MANAGER_ROOT=""
+  if ! file_exists "$SETTINGS_FILE"; then
+    return 0
+  fi
+  while IFS=$'\t' read -r key value; do
+    case "$key" in
+      profile_dir) SETTINGS_PROFILE_DIR="$value" ;;
+      default_config_file) SETTINGS_DEFAULT_CONFIG_FILE="$value" ;;
+      origin_cert) SETTINGS_ORIGIN_CERT="$value" ;;
+      manager_root) SETTINGS_MANAGER_ROOT="$value" ;;
+    esac
+  done <"$SETTINGS_FILE"
+}
+
+# 保存当前解析出的路径设置。
+save_settings() {
+  write_kv_file "$SETTINGS_FILE" \
+    profile_dir "${PROFILE_DIR:-}" \
+    default_config_file "${DEFAULT_CONFIG_FILE:-}" \
+    origin_cert "${ORIGIN_CERT:-}" \
+    manager_root "${MANAGER_ROOT:-}"
+}
+
+# 在常见目录中自动发现一个可用的 profile 目录。
+discover_profile_dir() {
+  local candidates=()
+  local candidate=""
+  if [[ -n "${SETTINGS_PROFILE_DIR:-}" ]]; then
+    candidates+=("${SETTINGS_PROFILE_DIR}")
+  fi
+  if [[ -n "${CLOUDFLARED_PROFILE_DIR:-}" ]]; then
+    candidates+=("${CLOUDFLARED_PROFILE_DIR}")
+  fi
+  if [[ -n "${CLOUDFLARED_DIR:-}" ]]; then
+    candidates+=("${CLOUDFLARED_DIR}")
+  fi
+  candidates+=(
+    "$PWD/.cloudflared"
+    "$PWD/cloudflared"
+    "$HOME/.cloudflared"
+    "$HOME/cloudflared"
+  )
+  for candidate in "${candidates[@]}"; do
+    [[ -z "$candidate" ]] && continue
+    candidate="$(canonical_path "$candidate")"
+    if dir_exists "$candidate" && { file_exists "$candidate/config.yml" || file_exists "$candidate/cert.pem"; }; then
+      printf '%s\n' "$candidate"
+      return 0
+    fi
+  done
+  return 1
+}
+
+# 解析 profile、config、证书和管理目录的最终路径。
+resolve_paths() {
+  local anchor_dir=""
+  local discovered=""
+
+  load_settings
+
+  PROFILE_DIR="${CLI_PROFILE_DIR:-${CLOUDFLARED_PROFILE_DIR:-${CLOUDFLARED_DIR:-${SETTINGS_PROFILE_DIR:-}}}}"
+  DEFAULT_CONFIG_FILE="${CLI_DEFAULT_CONFIG_FILE:-${CLOUDFLARED_CONFIG_FILE:-${SETTINGS_DEFAULT_CONFIG_FILE:-}}}"
+  ORIGIN_CERT="${CLI_ORIGIN_CERT:-${CLOUDFLARED_ORIGIN_CERT:-${TUNNEL_ORIGIN_CERT:-${SETTINGS_ORIGIN_CERT:-}}}}"
+  MANAGER_ROOT="${CLI_MANAGER_ROOT:-${CLOUDFLARED_MANAGER_ROOT:-${SETTINGS_MANAGER_ROOT:-}}}"
+
+  if [[ -z "$PROFILE_DIR" && -z "$DEFAULT_CONFIG_FILE" && -z "$ORIGIN_CERT" ]]; then
+    discovered="$(discover_profile_dir || true)"
+    PROFILE_DIR="$discovered"
+  fi
+
+  if [[ -n "$PROFILE_DIR" ]]; then
+    PROFILE_DIR="$(canonical_path "$PROFILE_DIR")"
+  fi
+
+  if [[ -z "$DEFAULT_CONFIG_FILE" && -n "$PROFILE_DIR" ]]; then
+    DEFAULT_CONFIG_FILE="$PROFILE_DIR/config.yml"
+  fi
+  if [[ -n "$DEFAULT_CONFIG_FILE" ]]; then
+    DEFAULT_CONFIG_FILE="$(canonical_path "$DEFAULT_CONFIG_FILE")"
+  fi
+
+  if [[ -z "$ORIGIN_CERT" ]]; then
+    if [[ -n "$PROFILE_DIR" ]]; then
+      ORIGIN_CERT="$PROFILE_DIR/cert.pem"
+    elif file_exists "$DEFAULT_LOGIN_CERT"; then
+      ORIGIN_CERT="$DEFAULT_LOGIN_CERT"
+    fi
+  fi
+  if [[ -n "$ORIGIN_CERT" ]]; then
+    ORIGIN_CERT="$(canonical_path "$ORIGIN_CERT")"
+  fi
+
+  if [[ -z "$MANAGER_ROOT" ]]; then
+    if [[ -n "$PROFILE_DIR" ]]; then
+      anchor_dir="$PROFILE_DIR"
+    elif [[ -n "$DEFAULT_CONFIG_FILE" ]]; then
+      anchor_dir="$(dirname "$DEFAULT_CONFIG_FILE")"
+    elif [[ -n "$ORIGIN_CERT" ]]; then
+      anchor_dir="$(dirname "$ORIGIN_CERT")"
+    else
+      anchor_dir="$DEFAULT_MANAGER_HOME"
+    fi
+    MANAGER_ROOT="$anchor_dir/manager"
+    if [[ "$anchor_dir" == "$DEFAULT_MANAGER_HOME" ]]; then
+      MANAGER_ROOT="$DEFAULT_MANAGER_HOME"
+    fi
+  fi
+  MANAGER_ROOT="$(canonical_path "$MANAGER_ROOT")"
+  APPS_DIR="$MANAGER_ROOT/apps"
+  ARCHIVE_DIR="$MANAGER_ROOT/archive"
+}
+
+# 确保管理目录结构存在。
+ensure_manager_dirs() {
+  ensure_dir "$APPS_DIR"
+  ensure_dir "$ARCHIVE_DIR"
+}
+
+# 确保系统已经安装 cloudflared。
+ensure_cloudflared() {
+  if [[ -z "$CLOUDFLARED_BIN" ]]; then
+    die "cloudflared 未安装，请先执行 install。"
+  fi
+}
+
+# 如目标证书不存在，则尝试从默认登录位置自动导入。
+maybe_import_default_login_cert() {
+  if [[ -z "${ORIGIN_CERT:-}" ]]; then
+    return 0
+  fi
+  if file_exists "$ORIGIN_CERT"; then
+    return 0
+  fi
+  if ! file_exists "$DEFAULT_LOGIN_CERT"; then
+    return 0
+  fi
+  if [[ "$ORIGIN_CERT" == "$DEFAULT_LOGIN_CERT" ]]; then
+    return 0
+  fi
+  ensure_dir "$(dirname "$ORIGIN_CERT")"
+  cp "$DEFAULT_LOGIN_CERT" "$ORIGIN_CERT"
+  info "已自动导入登录证书到: $ORIGIN_CERT"
+}
+
+# 确保当前环境拥有可用于远端管理的 Origin 证书。
+ensure_logged_in() {
+  maybe_import_default_login_cert
+  if [[ -z "${ORIGIN_CERT:-}" ]]; then
+    die "未配置 Origin 证书路径，请使用 --origincert、--profile-dir 或执行 init/use。"
+  fi
+  if ! file_exists "$ORIGIN_CERT"; then
+    die "找不到 Origin 证书: $ORIGIN_CERT。请先执行 login 或 import-cert。"
+  fi
+}
+
+# 统一封装依赖 Origin 证书的 cloudflared tunnel 命令。
+remote_cmd() {
+  ensure_cloudflared
+  ensure_logged_in
+  "$CLOUDFLARED_BIN" tunnel --origincert "$ORIGIN_CERT" "$@"
+}
+
+# 校验应用名称是否符合目录和标识要求。
+validate_app_name() {
+  local name="$1"
+  if [[ ! "$name" =~ ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$ ]]; then
+    die "应用名非法。只允许字母、数字、点、下划线、短横线，且必须以字母或数字开头。"
+  fi
+}
+
+# 规范化并校验公网 hostname。
+normalize_hostname() {
+  local value="$1"
+  value="${value%%.}"
+  value="$(printf '%s' "$value" | tr '[:upper:]' '[:lower:]')"
+  if [[ ! "$value" =~ ^[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?(\.[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+$ ]]; then
+    die "主机名非法: $1"
+  fi
+  printf '%s\n' "$value"
+}
+
+# 规范化 service 地址，兼容 host:port 与多种协议写法。
+normalize_service() {
+  local value="$1"
+  local scheme=""
+  local host=""
+
+  if [[ "$value" == "hello_world" || "$value" == http_status:* ]]; then
+    printf '%s\n' "$value"
+    return 0
+  fi
+
+  if [[ "$value" == unix:* ]]; then
+    printf '%s\n' "$value"
+    return 0
+  fi
+
+  if [[ "$value" != *"://"* ]]; then
+    if [[ "$value" == *:* ]]; then
+      value="http://$value"
+    else
+      die "服务地址必须包含协议，或使用 host:port 形式，例如 http://localhost:5173"
+    fi
+  fi
+
+  if [[ "$value" =~ ^([A-Za-z][A-Za-z0-9+.-]*)://(\[[^]]+\]|[^/:?#]+) ]]; then
+    scheme="${BASH_REMATCH[1]}"
+    host="${BASH_REMATCH[2]}"
+  else
+    die "服务地址格式非法: $1"
+  fi
+
+  case "$scheme" in
+    http|https|tcp|ssh|rdp) ;;
+    *) die "不支持的服务协议: $scheme。支持 http、https、tcp、ssh、rdp、unix:、hello_world、http_status:*" ;;
+  esac
+
+  if [[ -z "$host" ]]; then
+    die "服务地址缺少主机名: $1"
+  fi
+
+  printf '%s\n' "$value"
+}
+
+# 从 service URL 中提取协议、主机和端口，供连通性检查复用。
+parse_service_url() {
+  local service="$1"
+  PARSED_SCHEME=""
+  PARSED_HOST=""
+  PARSED_PORT=""
+
+  if [[ "$service" =~ ^([A-Za-z][A-Za-z0-9+.-]*)://(\[[^]]+\]|[^/:?#]+)(:([0-9]+))? ]]; then
+    PARSED_SCHEME="${BASH_REMATCH[1]}"
+    PARSED_HOST="${BASH_REMATCH[2]}"
+    PARSED_PORT="${BASH_REMATCH[4]}"
+    PARSED_HOST="${PARSED_HOST#[}"
+    PARSED_HOST="${PARSED_HOST%]}"
+  fi
+}
+
+# 校验本地 service 是否可达，避免 tunnel 启动后立刻失败。
+local_target_reachable() {
+  local service="$1"
+  local timeout="${2:-2}"
+  local host=""
+  local port=""
+
+  if [[ "$service" == "hello_world" || "$service" == http_status:* ]]; then
+    return 0
+  fi
+
+  if [[ "$service" == unix:* ]]; then
+    local socket_path="${service#unix:}"
+    if ! file_exists "$socket_path"; then
+      die "Unix socket 不存在: $socket_path"
+    fi
+    return 0
+  fi
+
+  parse_service_url "$service"
+  host="$PARSED_HOST"
+  port="$PARSED_PORT"
+  if [[ -z "$host" ]]; then
+    die "服务地址格式非法: $service"
+  fi
+  case "$host" in
+    localhost|127.0.0.1|::1) ;;
+    *) return 0 ;;
+  esac
+
+  if [[ -z "$port" ]]; then
+    case "$PARSED_SCHEME" in
+      http) port="80" ;;
+      https) port="443" ;;
+      ssh) port="22" ;;
+      rdp) port="3389" ;;
+      *) die "服务地址缺少端口: $service" ;;
+    esac
+  fi
+
+  if ! command_exists nc; then
+    warn "系统没有 nc，跳过本地服务连通性检查。"
+    return 0
+  fi
+
+  if ! nc -z -G "$timeout" "$host" "$port" >/dev/null 2>&1; then
+    die "本地服务无法连接: $service"
+  fi
+}
+
+# 返回指定应用的根目录。
+app_dir() {
+  printf '%s/%s\n' "$APPS_DIR" "$1"
+}
+
+# 返回指定应用的元数据文件路径。
+meta_path() {
+  printf '%s/meta.env\n' "$(app_dir "$1")"
+}
+
+# 返回指定应用的配置文件路径。
+config_path() {
+  printf '%s/config.yml\n' "$(app_dir "$1")"
+}
+
+# 返回指定应用的凭据文件路径。
+credentials_path() {
+  printf '%s/credentials.json\n' "$(app_dir "$1")"
+}
+
+# 返回指定应用的 ingress 规则文件路径。
+ingress_path() {
+  printf '%s/ingress.tsv\n' "$(app_dir "$1")"
+}
+
+# 返回指定应用的 PID 文件路径。
+pid_path() {
+  printf '%s/run/cloudflared.pid\n' "$(app_dir "$1")"
+}
+
+# 返回指定应用的日志文件路径。
+log_path() {
+  printf '%s/logs/cloudflared.log\n' "$(app_dir "$1")"
+}
+
+# 返回指定应用的备份目录路径。
+backups_dir() {
+  printf '%s/backups\n' "$(app_dir "$1")"
+}
+
+# 从 config.yml 读取顶层字段值。
+read_top_level_config_value() {
+  local config_file="$1"
+  local key="$2"
+  awk -F': ' -v wanted="$key" '
+    $1 == wanted {
+      sub(/^[^:]+:[[:space:]]*/, "", $0)
+      print
+      exit
+    }
+  ' "$config_file"
+}
+
+# 从 config.yml 中读取第一个 ingress hostname。
+read_first_ingress_hostname() {
+  local config_file="$1"
+  awk '
+    /^[[:space:]]*-[[:space:]]*hostname:[[:space:]]*/ {
+      sub(/^[[:space:]]*-[[:space:]]*hostname:[[:space:]]*/, "", $0)
+      print
+      exit
+    }
+  ' "$config_file"
+}
+
+# 从 config.yml 中读取第一个 ingress service。
+read_first_ingress_service() {
+  local config_file="$1"
+  awk '
+    /^[[:space:]]*service:[[:space:]]*/ {
+      sub(/^[[:space:]]*service:[[:space:]]*/, "", $0)
+      print
+      exit
+    }
+  ' "$config_file"
+}
+
+# 从 credentials JSON 中提取 TunnelID。
+read_tunnel_id_from_credentials() {
+  local credentials_file="$1"
+  plutil -extract TunnelID raw -o - "$credentials_file" 2>/dev/null || true
+}
+
+# 清空当前进程内缓存的 ingress 规则。
+reset_ingress_rules() {
+  INGRESS_HOSTS=()
+  INGRESS_SERVICES=()
+}
+
+# 返回当前缓存中的 ingress 规则数量。
+ingress_rule_count() {
+  printf '%s\n' "${#INGRESS_HOSTS[@]}"
+}
+
+# 查找某个 hostname 在 ingress 规则中的位置，可选跳过指定序号。
+find_ingress_rule_index_by_hostname() {
+  local wanted="$1"
+  local skip_index="${2:--1}"
+  local i=0
+  while [[ "$i" -lt "${#INGRESS_HOSTS[@]}" ]]; do
+    if [[ "$i" != "$skip_index" && "${INGRESS_HOSTS[$i]}" == "$wanted" ]]; then
+      printf '%s\n' "$i"
+      return 0
+    fi
+    i=$((i + 1))
+  done
+  return 1
+}
+
+# 解析形如 hostname=service 的 ingress 简写。
+parse_ingress_spec() {
+  local spec="$1"
+  local hostname=""
+  local service=""
+
+  if [[ "$spec" != *=* ]]; then
+    die "ingress 规则格式非法: $spec。请使用 --ingress hostname=service"
+  fi
+
+  hostname="${spec%%=*}"
+  service="${spec#*=}"
+  [[ -n "$hostname" ]] || die "ingress 规则缺少 hostname: $spec"
+  [[ -n "$service" ]] || die "ingress 规则缺少 service: $spec"
+
+  PARSED_INGRESS_HOSTNAME="$(normalize_hostname "$hostname")"
+  PARSED_INGRESS_SERVICE="$(normalize_service "$service")"
+}
+
+# 解析形如 2:hostname=service 的批量修改简写。
+parse_modify_spec() {
+  local spec="$1"
+  local index_part=""
+  local ingress_part=""
+
+  if [[ "$spec" != *:* || "$spec" != *=* ]]; then
+    die "批量修改格式非法: $spec。请使用 --set N:hostname=service"
+  fi
+
+  index_part="${spec%%:*}"
+  ingress_part="${spec#*:}"
+  [[ "$index_part" =~ ^[1-9][0-9]*$ ]] || die "批量修改序号非法: $spec"
+
+  parse_ingress_spec "$ingress_part"
+  PARSED_MODIFY_INDEX="$index_part"
+  PARSED_MODIFY_HOSTNAME="$PARSED_INGRESS_HOSTNAME"
+  PARSED_MODIFY_SERVICE="$PARSED_INGRESS_SERVICE"
+}
+
+# 向当前缓存追加一条 ingress 规则，并确保 hostname 不重复。
+append_ingress_rule() {
+  local hostname="$1"
+  local service="$2"
+
+  if find_ingress_rule_index_by_hostname "$hostname" >/dev/null 2>&1; then
+    die "同一个 Tunnel 下不能重复使用主机名: $hostname"
+  fi
+
+  INGRESS_HOSTS+=("$hostname")
+  INGRESS_SERVICES+=("$service")
+}
+
+# 根据命令行参数组装本次要写入的 ingress 规则集合。
+build_requested_ingress_rules() {
+  local hostname="${1:-}"
+  local service="${2:-}"
+  shift 2 || true
+  local spec=""
+
+  reset_ingress_rules
+
+  if [[ -n "$hostname" || -n "$service" ]]; then
+    [[ -n "$hostname" ]] || die "缺少 --hostname"
+    [[ -n "$service" ]] || die "缺少 --service"
+    append_ingress_rule "$(normalize_hostname "$hostname")" "$(normalize_service "$service")"
+  fi
+
+  for spec in "$@"; do
+    parse_ingress_spec "$spec"
+    append_ingress_rule "$PARSED_INGRESS_HOSTNAME" "$PARSED_INGRESS_SERVICE"
+  done
+
+  if [[ "$(ingress_rule_count)" == "0" ]]; then
+    die "至少需要提供一条 ingress 规则。可使用 --hostname/--service，或重复传 --ingress hostname=service"
+  fi
+}
+
+# 从 ingress.tsv 读取全部规则到当前缓存。
+load_ingress_rules_file() {
+  local file="$1"
+  local hostname=""
+  local service=""
+
+  reset_ingress_rules
+  while IFS=$'\t' read -r hostname service; do
+    [[ -z "$hostname" ]] && continue
+    [[ -z "$service" ]] && continue
+    append_ingress_rule "$hostname" "$service"
+  done <"$file"
+}
+
+# 从当前缓存同步主规则，兼容旧版单规则字段。
+sync_primary_ingress_to_meta() {
+  if [[ "${#INGRESS_HOSTS[@]}" -gt 0 ]]; then
+    META_HOSTNAME="${INGRESS_HOSTS[0]}"
+    META_SERVICE="${INGRESS_SERVICES[0]}"
+  else
+    META_HOSTNAME=""
+    META_SERVICE=""
+  fi
+}
+
+# 将当前缓存中的 ingress 规则写回 ingress.tsv。
+save_ingress_rules() {
+  local i=0
+  ensure_dir "$(dirname "$META_INGRESS_FILE")"
+  : >"$META_INGRESS_FILE"
+  while [[ "$i" -lt "${#INGRESS_HOSTS[@]}" ]]; do
+    printf '%s\t%s\n' "${INGRESS_HOSTS[$i]}" "${INGRESS_SERVICES[$i]}" >>"$META_INGRESS_FILE"
+    i=$((i + 1))
+  done
+  sync_primary_ingress_to_meta
+}
+
+# 确保当前应用拥有 ingress 规则文件，旧数据会自动迁移。
+ensure_ingress_rules_loaded() {
+  if [[ -z "$META_INGRESS_FILE" && -n "$META_NAME" ]]; then
+    META_INGRESS_FILE="$(canonical_path "$(ingress_path "$META_NAME")")"
+  fi
+
+  if [[ -n "$META_INGRESS_FILE" && -f "$META_INGRESS_FILE" ]]; then
+    load_ingress_rules_file "$META_INGRESS_FILE"
+    sync_primary_ingress_to_meta
+    return 0
+  fi
+
+  reset_ingress_rules
+  if [[ -n "$META_HOSTNAME" && -n "$META_SERVICE" ]]; then
+    append_ingress_rule "$(normalize_hostname "$META_HOSTNAME")" "$(normalize_service "$META_SERVICE")"
+    sync_primary_ingress_to_meta
+    return 0
+  fi
+
+  die "找不到 ingress 规则文件: $META_INGRESS_FILE"
+}
+
+# 从现有 config.yml 中读取全部 hostname/service ingress 规则。
+load_ingress_rules_from_config() {
+  local config_file="$1"
+  local hostname=""
+  local service=""
+
+  reset_ingress_rules
+  while IFS=$'\t' read -r hostname service; do
+    [[ -z "$hostname" ]] && continue
+    [[ -z "$service" ]] && continue
+    append_ingress_rule "$(normalize_hostname "$hostname")" "$(normalize_service "$service")"
+  done < <(
+    awk '
+      /^[[:space:]]*-[[:space:]]*hostname:[[:space:]]*/ {
+        line = $0
+        sub(/^[[:space:]]*-[[:space:]]*hostname:[[:space:]]*/, "", line)
+        host = line
+        next
+      }
+      /^[[:space:]]*hostname:[[:space:]]*/ {
+        line = $0
+        sub(/^[[:space:]]*hostname:[[:space:]]*/, "", line)
+        host = line
+        next
+      }
+      /^[[:space:]]*service:[[:space:]]*/ {
+        line = $0
+        sub(/^[[:space:]]*service:[[:space:]]*/, "", line)
+        if (host != "") {
+          print host "\t" line
+          host = ""
+        }
+        next
+      }
+      /^[[:space:]]*-[[:space:]]*service:[[:space:]]*/ {
+        host = ""
+        next
+      }
+    ' "$config_file"
+  )
+
+  [[ "$(ingress_rule_count)" != "0" ]]
+}
+
+# 校验当前缓存中的全部本地服务是否可达。
+check_all_ingress_targets() {
+  local i=0
+  while [[ "$i" -lt "${#INGRESS_SERVICES[@]}" ]]; do
+    local_target_reachable "${INGRESS_SERVICES[$i]}"
+    i=$((i + 1))
+  done
+}
+
+# 为当前缓存中的全部 hostname 建立 DNS 路由。
+route_all_dns() {
+  local tunnel_name="$1"
+  local overwrite="${2:-0}"
+  local i=0
+  while [[ "$i" -lt "${#INGRESS_HOSTS[@]}" ]]; do
+    route_dns "$tunnel_name" "${INGRESS_HOSTS[$i]}" "$overwrite"
+    i=$((i + 1))
+  done
+}
+
+# 复制现有 config.yml，并把 credentials-file 改写到受管目录。
+copy_config_with_credentials_file() {
+  local source_config="$1"
+  local target_config="$2"
+  local target_credentials="$3"
+  ensure_dir "$(dirname "$target_config")"
+  awk -v credentials="$target_credentials" '
+    BEGIN { replaced = 0 }
+    /^credentials-file:[[:space:]]*/ {
+      print "credentials-file: " credentials
+      replaced = 1
+      next
+    }
+    { print }
+    END {
+      if (!replaced) {
+        print "credentials-file: " credentials
+      }
+    }
+  ' "$source_config" >"$target_config"
+}
+
+# 初始化某个应用的目录结构。
+init_app_dirs() {
+  local name="$1"
+  ensure_manager_dirs
+  ensure_dir "$(app_dir "$name")"
+  ensure_dir "$(dirname "$(pid_path "$name")")"
+  ensure_dir "$(dirname "$(log_path "$name")")"
+  ensure_dir "$(backups_dir "$name")"
+}
+
+# 判断某个应用是否已被接管。
+app_exists() {
+  file_exists "$(meta_path "$1")"
+}
+
+# 清空内存中的元数据变量，避免旧数据串用。
+reset_meta() {
+  META_NAME=""
+  META_TUNNEL_NAME=""
+  META_TUNNEL_ID=""
+  META_HOSTNAME=""
+  META_SERVICE=""
+  META_APP_DIR=""
+  META_CONFIG_FILE=""
+  META_CREDENTIALS_FILE=""
+  META_INGRESS_FILE=""
+  META_PID_FILE=""
+  META_LOG_FILE=""
+  META_META_FILE=""
+  META_CREATED_AT=""
+  META_UPDATED_AT=""
+  reset_ingress_rules
+}
+
+# 尝试把当前默认 config.yml 和现有凭据自动接管成受管应用。
+try_import_current_default_app() {
+  local name="$1"
+  local tunnel_name=""
+  local source_credentials=""
+  local tunnel_id=""
+
+  if [[ -z "${DEFAULT_CONFIG_FILE:-}" ]] || ! file_exists "$DEFAULT_CONFIG_FILE"; then
+    return 1
+  fi
+
+  tunnel_name="$(read_top_level_config_value "$DEFAULT_CONFIG_FILE" "tunnel")"
+  if [[ -z "$tunnel_name" || "$tunnel_name" != "$name" ]]; then
+    return 1
+  fi
+
+  source_credentials="$(read_top_level_config_value "$DEFAULT_CONFIG_FILE" "credentials-file")"
+
+  if [[ -z "$source_credentials" ]]; then
+    return 1
+  fi
+
+  if ! load_ingress_rules_from_config "$DEFAULT_CONFIG_FILE"; then
+    return 1
+  fi
+  if [[ "$(ingress_rule_count)" == "0" ]]; then
+    return 1
+  fi
+
+  source_credentials="$(canonical_path "$source_credentials")"
+  if ! file_exists "$source_credentials"; then
+    return 1
+  fi
+
+  tunnel_id="$(read_tunnel_id_from_credentials "$source_credentials")"
+  if [[ -z "$tunnel_id" && -n "${ORIGIN_CERT:-}" ]] && file_exists "$ORIGIN_CERT"; then
+    remote_lookup_by_name "$tunnel_name"
+    if [[ "$REMOTE_FOUND" == "1" ]]; then
+      tunnel_id="$REMOTE_TUNNEL_ID"
+    fi
+  fi
+
+  build_meta "$name" "$tunnel_name" "$tunnel_id" "${INGRESS_HOSTS[0]}" "${INGRESS_SERVICES[0]}"
+  cp "$source_credentials" "$META_CREDENTIALS_FILE"
+  save_ingress_rules
+  copy_config_with_credentials_file "$DEFAULT_CONFIG_FILE" "$META_CONFIG_FILE" "$META_CREDENTIALS_FILE"
+  save_meta
+  info "已自动接管现有默认配置为受管应用: $name"
+  return 0
+}
+
+# 从 meta.env 读取应用元数据到当前进程变量。
+load_meta() {
+  local name="$1"
+  local file
+  file="$(meta_path "$name")"
+  reset_meta
+  if ! file_exists "$file"; then
+    if ! try_import_current_default_app "$name"; then
+      die "未找到受管应用: $name。远端 Tunnel 存在，不代表已经被本脚本接管。请执行 adopt，或让默认 config.yml 指向该 Tunnel 后重试。"
+    fi
+    file="$(meta_path "$name")"
+  fi
+  while IFS=$'\t' read -r key value; do
+    case "$key" in
+      name) META_NAME="$value" ;;
+      tunnel_name) META_TUNNEL_NAME="$value" ;;
+      tunnel_id) META_TUNNEL_ID="$value" ;;
+      hostname) META_HOSTNAME="$value" ;;
+      service) META_SERVICE="$value" ;;
+      app_dir) META_APP_DIR="$value" ;;
+      config_file) META_CONFIG_FILE="$value" ;;
+      credentials_file) META_CREDENTIALS_FILE="$value" ;;
+      ingress_file) META_INGRESS_FILE="$value" ;;
+      pid_file) META_PID_FILE="$value" ;;
+      log_file) META_LOG_FILE="$value" ;;
+      meta_file) META_META_FILE="$value" ;;
+      created_at) META_CREATED_AT="$value" ;;
+      updated_at) META_UPDATED_AT="$value" ;;
+    esac
+  done <"$file"
+  if [[ -z "$META_INGRESS_FILE" ]]; then
+    META_INGRESS_FILE="$(canonical_path "$(ingress_path "$name")")"
+  fi
+  ensure_ingress_rules_loaded
+}
+
+# 将当前元数据变量写回 meta.env。
+save_meta() {
+  sync_primary_ingress_to_meta
+  META_UPDATED_AT="$(utc_now)"
+  write_kv_file "$META_META_FILE" \
+    name "$META_NAME" \
+    tunnel_name "$META_TUNNEL_NAME" \
+    tunnel_id "$META_TUNNEL_ID" \
+    hostname "$META_HOSTNAME" \
+    service "$META_SERVICE" \
+    app_dir "$META_APP_DIR" \
+    config_file "$META_CONFIG_FILE" \
+    credentials_file "$META_CREDENTIALS_FILE" \
+    ingress_file "$META_INGRESS_FILE" \
+    pid_file "$META_PID_FILE" \
+    log_file "$META_LOG_FILE" \
+    meta_file "$META_META_FILE" \
+    created_at "$META_CREATED_AT" \
+    updated_at "$META_UPDATED_AT"
+}
+
+# 根据输入参数构造一份完整的应用元数据。
+build_meta() {
+  local name="$1"
+  local tunnel_name="$2"
+  local tunnel_id="$3"
+  local hostname="$4"
+  local service="$5"
+  init_app_dirs "$name"
+  META_NAME="$name"
+  META_TUNNEL_NAME="$tunnel_name"
+  META_TUNNEL_ID="$tunnel_id"
+  META_HOSTNAME="$hostname"
+  META_SERVICE="$service"
+  META_APP_DIR="$(canonical_path "$(app_dir "$name")")"
+  META_CONFIG_FILE="$(canonical_path "$(config_path "$name")")"
+  META_CREDENTIALS_FILE="$(canonical_path "$(credentials_path "$name")")"
+  META_INGRESS_FILE="$(canonical_path "$(ingress_path "$name")")"
+  META_PID_FILE="$(canonical_path "$(pid_path "$name")")"
+  META_LOG_FILE="$(canonical_path "$(log_path "$name")")"
+  META_META_FILE="$(canonical_path "$(meta_path "$name")")"
+  META_CREATED_AT="$(utc_now)"
+  META_UPDATED_AT="$META_CREATED_AT"
+}
+
+# 渲染 cloudflared 所需的 config.yml 内容。
+render_config() {
+  local i=0
+
+  if [[ "$(ingress_rule_count)" == "0" ]]; then
+    die "当前应用没有可用的 ingress 规则，无法生成 config.yml"
+  fi
+
+  cat <<EOF
+tunnel: $META_TUNNEL_NAME
+credentials-file: $META_CREDENTIALS_FILE
+
+ingress:
+EOF
+  while [[ "$i" -lt "${#INGRESS_HOSTS[@]}" ]]; do
+    cat <<EOF
+  - hostname: ${INGRESS_HOSTS[$i]}
+    service: ${INGRESS_SERVICES[$i]}
+EOF
+    i=$((i + 1))
+  done
+  cat <<EOF
+  - service: http_status:404
+EOF
+}
+
+# 写入应用配置，可选先备份旧文件。
+write_config() {
+  local do_backup="${1:-1}"
+  if [[ "$do_backup" == "1" ]]; then
+    backup_file "$META_CONFIG_FILE" >/dev/null || true
+  fi
+  ensure_dir "$(dirname "$META_CONFIG_FILE")"
+  render_config >"$META_CONFIG_FILE"
+}
+
+# 使用 cloudflared 自带校验能力检查 config.yml 是否有效。
+validate_config() {
+  ensure_cloudflared
+  "$CLOUDFLARED_BIN" tunnel --config "$1" ingress validate >/dev/null
+}
+
+# 读取 PID 文件中的进程号。
+read_pid() {
+  local pid_file="$1"
+  if ! file_exists "$pid_file"; then
+    return 1
+  fi
+  tr -d '[:space:]' <"$pid_file"
+}
+
+# 查询指定 PID 对应的命令行。
+process_command() {
+  local pid="$1"
+  ps -p "$pid" -o command= 2>/dev/null || true
+}
+
+# 判断某个 PID 是否仍在运行，并可选校验其命令行特征。
+is_pid_running() {
+  local pid="$1"
+  local expected_hint="${2:-}"
+  local cmdline=""
+  if ! kill -0 "$pid" >/dev/null 2>&1; then
+    return 1
+  fi
+  if [[ -z "$expected_hint" ]]; then
+    return 0
+  fi
+  cmdline="$(process_command "$pid")"
+  if [[ -z "$cmdline" ]]; then
+    return 0
+  fi
+  [[ "$cmdline" == *"$expected_hint"* ]]
+}
+
+# 通过 pidfile 和 pgrep 双重方式定位当前应用的运行进程。
+find_running_pid() {
+  local pid=""
+  if pid="$(read_pid "$META_PID_FILE" 2>/dev/null || true)"; then
+    if [[ -n "$pid" ]] && is_pid_running "$pid" "$META_CONFIG_FILE"; then
+      printf '%s\n' "$pid"
+      return 0
+    fi
+  fi
+  rm -f "$META_PID_FILE"
+  while IFS= read -r pid; do
+    [[ -z "$pid" ]] && continue
+    if is_pid_running "$pid" "$META_CONFIG_FILE"; then
+      ensure_dir "$(dirname "$META_PID_FILE")"
+      printf '%s\n' "$pid" >"$META_PID_FILE"
+      printf '%s\n' "$pid"
+      return 0
+    fi
+  done < <(pgrep -f "$META_CONFIG_FILE" 2>/dev/null || true)
+  return 1
+}
+
+# 读取日志文件尾部若干行。
+read_log_tail() {
+  local log_file="$1"
+  local lines="$2"
+  if ! file_exists "$log_file"; then
+    return 0
+  fi
+  tail -n "$lines" "$log_file"
+}
+
+# 为指定 tunnel 拉取并写入凭据文件。
+issue_credentials() {
+  local tunnel_name="$1"
+  local output_file="$2"
+  ensure_dir "$(dirname "$output_file")"
+  remote_cmd token --cred-file "$output_file" "$tunnel_name" >/dev/null
+  if ! file_exists "$output_file"; then
+    die "写入凭据文件失败: $output_file"
+  fi
+}
+
+# 创建远端 tunnel，并尽量把凭据直接落到受管目录。
+create_remote_tunnel() {
+  local tunnel_name="$1"
+  local output_file="$2"
+  remote_lookup_by_name "$tunnel_name"
+  if [[ "$REMOTE_FOUND" == "1" ]]; then
+    die "远端 tunnel 已存在: $tunnel_name。请使用 adopt 或 add --use-existing。"
+  fi
+  ensure_dir "$(dirname "$output_file")"
+  remote_cmd create --cred-file "$output_file" "$tunnel_name" >/dev/null
+  if ! file_exists "$output_file"; then
+    warn "创建 tunnel 时未直接生成凭据文件，将尝试补发 token。"
+    issue_credentials "$tunnel_name" "$output_file"
+  fi
+  remote_lookup_by_name "$tunnel_name"
+  if [[ "$REMOTE_FOUND" != "1" ]]; then
+    die "Tunnel 已创建，但无法再次查询到: $tunnel_name"
+  fi
+}
+
+# 为 tunnel 绑定或覆盖 DNS 记录。
+route_dns() {
+  local tunnel_name="$1"
+  local hostname="$2"
+  local overwrite="${3:-0}"
+  if [[ "$overwrite" == "1" ]]; then
+    remote_cmd route dns --overwrite-dns "$tunnel_name" "$hostname" >/dev/null
+  else
+    remote_cmd route dns "$tunnel_name" "$hostname" >/dev/null
+  fi
+}
+
+# 将当前应用配置复制为默认 config.yml。
+activate_default_config() {
+  local backup=""
+  if [[ -z "${DEFAULT_CONFIG_FILE:-}" ]]; then
+    die "未配置默认配置文件路径，请使用 --config-file、--profile-dir 或 init/use。"
+  fi
+  ensure_dir "$(dirname "$DEFAULT_CONFIG_FILE")"
+  backup="$(backup_file "$DEFAULT_CONFIG_FILE" || true)"
+  cp "$META_CONFIG_FILE" "$DEFAULT_CONFIG_FILE"
+  if [[ -n "$backup" ]]; then
+    info "已备份默认配置: $backup"
+  fi
+}
+
+# 将应用目录归档到 archive 目录，便于后续追溯。
+archive_app_dir() {
+  local src="$1"
+  local stamp
+  stamp="$(date +"%Y%m%d-%H%M%S")"
+  ensure_manager_dirs
+  local dest="$ARCHIVE_DIR/$(basename "$src")-$stamp"
+  mv "$src" "$dest"
+  printf '%s\n' "$dest"
+}
+
+# 列出当前管理目录下的全部受管应用名称。
+managed_apps() {
+  if ! dir_exists "$APPS_DIR"; then
+    return 0
+  fi
+  local found=0
+  local entry=""
+  for entry in "$APPS_DIR"/*; do
+    [[ ! -d "$entry" ]] && continue
+    if file_exists "$entry/meta.env"; then
+      basename "$entry"
+      found=1
+    fi
+  done | sort
+  if [[ "$found" == "0" ]]; then
+    return 0
+  fi
+}
+
+# 统计 JSON 数组的元素个数。
+json_index_count() {
+  local file="$1"
+  local i=0
+  while plutil -type "$i" "$file" >/dev/null 2>&1; do
+    i=$((i + 1))
+  done
+  printf '%s\n' "$i"
+}
+
+# 从 JSON 中提取原始值。
+json_raw() {
+  plutil -extract "$2" raw -o - "$1" 2>/dev/null
+}
+
+# 按 tunnel 名称查询远端 tunnel 信息并写入缓存变量。
+remote_lookup_by_name() {
+  local tunnel_name="$1"
+  local tmp_json
+  local count=0
+  local i=0
+  local current_name=""
+  REMOTE_FOUND=0
+  REMOTE_TUNNEL_ID=""
+  REMOTE_TUNNEL_NAME=""
+  REMOTE_TUNNEL_CREATED_AT=""
+  REMOTE_TUNNEL_CONNECTIONS="0"
+
+  tmp_json="$(portable_mktemp "cloudflared-manager-remote")"
+  remote_cmd list --name "$tunnel_name" -o json >"$tmp_json"
+  count="$(json_index_count "$tmp_json")"
+  while [[ "$i" -lt "$count" ]]; do
+    current_name="$(json_raw "$tmp_json" "$i.name" || true)"
+    if [[ "$current_name" == "$tunnel_name" ]]; then
+      REMOTE_FOUND=1
+      REMOTE_TUNNEL_NAME="$current_name"
+      REMOTE_TUNNEL_ID="$(json_raw "$tmp_json" "$i.id" || true)"
+      REMOTE_TUNNEL_CREATED_AT="$(json_raw "$tmp_json" "$i.created_at" || true)"
+      REMOTE_TUNNEL_CONNECTIONS="$(json_raw "$tmp_json" "$i.connections" || printf '0')"
+      rm -f "$tmp_json"
+      return 0
+    fi
+    i=$((i + 1))
+  done
+  rm -f "$tmp_json"
+}
+
+# 生成单个应用的一行摘要信息。
+app_summary() {
+  local pid=""
+  local state="未运行"
+  local connections="0"
+  local count="0"
+
+  if pid="$(find_running_pid 2>/dev/null || true)"; then
+    [[ -n "$pid" ]] && state="运行中"
+  fi
+
+  if [[ -n "$CLOUDFLARED_BIN" && -n "${ORIGIN_CERT:-}" ]] && file_exists "$ORIGIN_CERT"; then
+    remote_lookup_by_name "$META_TUNNEL_NAME"
+    if [[ "$REMOTE_FOUND" == "1" ]]; then
+      connections="$REMOTE_TUNNEL_CONNECTIONS"
+    fi
+  fi
+
+  count="$(ingress_rule_count)"
+  printf '%s: 状态=%s，Tunnel=%s，主入口=%s -> %s，ingress=%s 条，连接数=%s\n' \
+    "$META_NAME" "$state" "$META_TUNNEL_NAME" "$META_HOSTNAME" "$META_SERVICE" "$count" "$connections"
+}
+
+# 确保运行所需的凭据文件存在，缺失时自动补发。
+ensure_credentials_present() {
+  if file_exists "$META_CREDENTIALS_FILE"; then
+    return 0
+  fi
+  if [[ -n "$CLOUDFLARED_BIN" && -n "${ORIGIN_CERT:-}" ]] && file_exists "$ORIGIN_CERT"; then
+    info "凭据文件不存在，尝试自动补发 token: $META_TUNNEL_NAME"
+    issue_credentials "$META_TUNNEL_NAME" "$META_CREDENTIALS_FILE"
+    return 0
+  fi
+  die "找不到凭据文件: $META_CREDENTIALS_FILE"
+}
+
+# 启动当前应用对应的 cloudflared 进程，支持前台和后台模式。
+start_app() {
+  local foreground="${1:-0}"
+  local skip_check="${2:-0}"
+  local pid=""
+  local cmd=()
+
+  if pid="$(find_running_pid 2>/dev/null || true)"; then
+    if [[ -n "$pid" ]]; then
+      die "应用已在运行: $META_NAME"
+    fi
+  fi
+
+  if [[ "$skip_check" == "0" ]]; then
+    check_all_ingress_targets
+  fi
+
+  if ! file_exists "$META_CONFIG_FILE"; then
+    die "找不到配置文件: $META_CONFIG_FILE"
+  fi
+
+  ensure_credentials_present
+  validate_config "$META_CONFIG_FILE"
+
+  cmd=(
+    "$CLOUDFLARED_BIN"
+    tunnel
+    --config "$META_CONFIG_FILE"
+    --no-autoupdate
+    --pidfile "$META_PID_FILE"
+    run "$META_TUNNEL_NAME"
+  )
+
+  if [[ "$foreground" == "1" ]]; then
+    "${cmd[@]}"
+    return 0
+  fi
+
+  ensure_dir "$(dirname "$META_LOG_FILE")"
+  nohup "${cmd[@]}" >>"$META_LOG_FILE" 2>&1 &
+  printf '%s\n' "$!" >"$META_PID_FILE"
+  sleep 2
+  if ! pid="$(find_running_pid 2>/dev/null || true)"; then
+    local tail_output=""
+    tail_output="$(read_log_tail "$META_LOG_FILE" 50 || true)"
+    die "cloudflared 启动后立即退出。最近日志如下：\n${tail_output:-"(暂无日志输出)"}"
+  fi
+}
+
+# 停止当前应用对应的 cloudflared 进程，可选强制结束。
+stop_app() {
+  local force="${1:-0}"
+  local pid=""
+  local deadline=0
+
+  if ! pid="$(find_running_pid 2>/dev/null || true)"; then
+    info "应用未运行: $META_NAME"
+    return 0
+  fi
+  if [[ -z "$pid" ]]; then
+    info "应用未运行: $META_NAME"
+    return 0
+  fi
+
+  kill "$pid" >/dev/null 2>&1 || true
+  deadline=$((SECONDS + 20))
+  while [[ "$SECONDS" -lt "$deadline" ]]; do
+    if ! is_pid_running "$pid" "$META_CONFIG_FILE"; then
+      rm -f "$META_PID_FILE"
+      info "已停止: $META_NAME"
+      return 0
+    fi
+    sleep 1
+  done
+
+  if [[ "$force" == "1" ]]; then
+    kill -9 "$pid" >/dev/null 2>&1 || true
+    rm -f "$META_PID_FILE"
+    info "已强制停止: $META_NAME"
+    return 0
+  fi
+
+  die "停止超时: $META_NAME。请重试 stop --force。"
+}
+
+# 打印命令行帮助。
+print_usage() {
+  cat <<EOF
+用法:
+  $SCRIPT_NAME [全局选项] <command> [command options]
+
+全局选项:
+  --profile-dir DIR
+      指定配置档目录。目录名不要求叫 .cloudflared。
+      如果同时不显式传 --config-file 和 --origincert，则默认会推导为：
+      DIR/config.yml 和 DIR/cert.pem
+
+  --cloudflared-dir DIR
+      --profile-dir 的兼容别名
+
+  --config-file FILE
+      指定默认 config.yml 的目标路径
+
+  --origincert FILE
+      指定 Origin 证书路径
+
+  --manager-root DIR
+      指定受管应用元数据目录
+      默认会落在 <profile-dir>/manager 或推导出的锚点目录下
+
+  --save-profile
+      将当前解析出来的路径保存到:
+      $SETTINGS_FILE
+
+命令:
+  doctor
+      查看当前脚本解析到的配置档目录、默认配置文件、Origin 证书、
+      管理目录、cloudflared 版本，以及远端 Tunnel 数量
+
+  init [--install] [--login]
+      初始化管理目录并保存当前路径设置
+      可选顺带安装 cloudflared、执行 tunnel login
+
+  use
+      仅保存当前路径设置，不做远端操作
+
+  install [--sudo-install]
+      在 macOS 上下载安装 cloudflared
+      不带 --sudo-install 时会直接打开 pkg 安装包
+
+  login
+      执行 cloudflared tunnel login
+      登录后会尝试把默认证书同步到当前 Origin 证书目标路径
+
+  import-cert [FILE]
+      把已有证书导入到当前 Origin 证书路径
+      默认来源为: $DEFAULT_LOGIN_CERT
+
+  tunnels
+      列出当前 Cloudflare 账号下的远端 Tunnel
+      这里只是远端列表，不代表已经被本脚本接管
+
+  list
+      列出已经被本脚本接管的本地受管应用
+
+  show NAME
+      查看某个受管应用的元数据和 config.yml 内容
+
+  add NAME [--hostname HOST --service URL] [--ingress HOST=URL ...] [其他参数]
+      创建新的远端 Tunnel，并在本地生成受管目录、配置、凭据和元数据
+      支持“一个 Tunnel + 多条 ingress 规则”
+      适合“远端还没创建”的场景
+
+  adopt NAME --tunnel-name NAME [--hostname HOST --service URL] [--ingress HOST=URL ...] [其他参数]
+      接管一个已经存在的远端 Tunnel
+      支持把多个 hostname/service 一次性纳入同一个 Tunnel
+      适合“脚本外已经创建过 Tunnel”的场景
+
+  modify NAME [--index N] [--hostname HOST] [--service URL] [--set N:HOST=URL ...] [其他参数]
+      修改某个受管应用的一条或多条 ingress 规则
+      如果应用当前在运行，默认会自动重启
+
+  ingress-list NAME
+      列出某个受管应用下的全部 ingress 规则
+
+  ingress-add NAME [--hostname HOST --service URL] [--ingress HOST=URL ...] [其他参数]
+      为某个 Tunnel 追加一条或多条 ingress 规则，并自动写入 DNS 路由
+
+  ingress-remove NAME [--hostname HOST ...] [--index N ...] [其他参数]
+      从某个 Tunnel 中移除一条或多条 ingress 规则
+      只会改本地配置，不会自动删除 Cloudflare 上旧 DNS 记录
+
+  start NAME
+      启动某个已经接管的应用
+
+  stop NAME
+      停止某个已经接管的应用
+
+  restart NAME
+      重启某个已经接管的应用
+
+  status [NAME]
+      查看一个或全部受管应用的状态、PID、配置文件、日志文件
+
+  logs NAME [-f]
+      查看日志，或持续跟随日志输出
+
+  activate NAME
+      将某个受管应用的 config.yml 复制为默认 config.yml
+
+  delete NAME [--delete-tunnel]
+      归档本地受管目录
+      可选顺带删除远端 Tunnel
+
+  help
+      显示本帮助
+
+常见场景示例:
+
+  1. 初始化一个新的配置档目录，并完成登录
+     $SCRIPT_NAME --profile-dir /opt/cf-profile init --login
+
+  2. 只检查当前脚本实际使用了哪些路径
+     $SCRIPT_NAME doctor
+
+  3. 使用完全拆开的路径，而不是依赖某个 .cloudflared 目录名
+     $SCRIPT_NAME \\
+       --config-file /srv/cloudflared/config.yml \\
+       --origincert /srv/cloudflared/cert.pem \\
+       --manager-root /srv/cloudflared/manager \\
+       doctor
+
+  4. 创建一个新的远端 Tunnel，并立即后台启动
+     $SCRIPT_NAME add admin-dev \\
+       --hostname admin.example.com \\
+       --service http://localhost:5173 \\
+       --start \\
+       --activate
+
+  5. 创建一个 Tunnel，同时挂多个域名/服务
+     $SCRIPT_NAME add wchros-main \\
+       --ingress admin.wchros.cn=http://localhost:8080 \\
+       --ingress api.wchros.cn=http://localhost:9000 \\
+       --ingress ssh.wchros.cn=ssh://localhost:22 \\
+       --start
+
+  6. 接管一个已经存在的远端 Tunnel
+     $SCRIPT_NAME adopt admin-dev \\
+       --tunnel-name wchros-admin-dev \\
+       --hostname admin.wchros.cn \\
+       --service http://localhost:8080 \\
+       --activate
+
+  7. 给现有 Tunnel 继续追加入口规则
+     $SCRIPT_NAME ingress-add wchros-main \\
+       --ingress static.wchros.cn=http://localhost:7000 \\
+       --ingress blog.wchros.cn=http://localhost:7100
+
+  8. 查看某个 Tunnel 下面有哪些入口规则
+     $SCRIPT_NAME ingress-list wchros-main
+
+  9. 查看远端 Tunnel 列表
+     $SCRIPT_NAME tunnels
+
+  10. 查看已经被脚本接管的本地应用
+     $SCRIPT_NAME list
+
+  11. 启动、查看状态和日志
+     $SCRIPT_NAME start admin-dev
+     $SCRIPT_NAME status admin-dev
+     $SCRIPT_NAME logs admin-dev -f
+
+  12. 一次修改多条 ingress 规则并自动重启
+     $SCRIPT_NAME modify wchros-main \\
+       --set 2:api.wchros.cn=http://localhost:9001 \\
+       --set 3:ssh.wchros.cn=ssh://localhost:2222
+
+  13. 一次删除多条 ingress 规则
+      $SCRIPT_NAME ingress-remove wchros-main --index 3 --hostname blog.wchros.cn
+
+  14. 删除本地接管记录，并顺带删除远端 Tunnel
+      $SCRIPT_NAME delete admin-dev --delete-tunnel
+
+说明:
+  - tunnels 看到的是“远端存在”
+  - list / start / stop / status 操作的是“本地已接管”
+  - 一个受管应用默认对应一个 Tunnel，但这个 Tunnel 下面可以有多条 ingress
+  - 如果远端 Tunnel 已存在，但本地未接管，请先用 adopt
+EOF
+}
+
+# 输出当前环境、路径解析和远端连接情况。
+cmd_doctor() {
+  local remote_count="未知"
+  printf '设置文件: %s\n' "$SETTINGS_FILE"
+  printf 'Profile 目录: %s\n' "${PROFILE_DIR:-"(未设置)"}"
+  printf '默认配置文件: %s\n' "${DEFAULT_CONFIG_FILE:-"(未设置)"}"
+  printf 'Origin 证书: %s\n' "${ORIGIN_CERT:-"(未设置)"}"
+  printf '管理根目录: %s\n' "$MANAGER_ROOT"
+  printf '管理根目录存在: %s\n' "$(dir_exists "$MANAGER_ROOT" && printf 是 || printf 否)"
+  printf '应用目录: %s\n' "$APPS_DIR"
+  printf '归档目录: %s\n' "$ARCHIVE_DIR"
+  if [[ -n "$CLOUDFLARED_BIN" ]]; then
+    printf 'cloudflared 路径: %s\n' "$CLOUDFLARED_BIN"
+    printf 'cloudflared 版本: %s\n' "$("$CLOUDFLARED_BIN" --version 2>/dev/null || true)"
+  else
+    printf 'cloudflared: 未安装\n'
+  fi
+  printf 'Origin 证书存在: %s\n' "$(file_exists "${ORIGIN_CERT:-/nonexistent}" && printf 是 || printf 否)"
+  printf '默认登录证书存在: %s\n' "$(file_exists "$DEFAULT_LOGIN_CERT" && printf 是 || printf 否)"
+  printf '受管应用数量: %s\n' "$(managed_apps | wc -l | tr -d '[:space:]')"
+  if [[ -n "$CLOUDFLARED_BIN" && -n "${ORIGIN_CERT:-}" ]] && file_exists "$ORIGIN_CERT"; then
+    local tmp_json
+    tmp_json="$(portable_mktemp "cloudflared-manager-doctor")"
+    if remote_cmd list -o json >"$tmp_json" 2>/dev/null; then
+      remote_count="$(json_index_count "$tmp_json")"
+    fi
+    rm -f "$tmp_json"
+  fi
+  printf '远端 Tunnel 数量: %s\n' "$remote_count"
+}
+
+# 保存当前 profile 到设置文件。
+cmd_use() {
+  ensure_manager_dirs
+  save_settings
+  info "已保存当前配置档。"
+  info "配置档目录: ${PROFILE_DIR:-"(未设置)"}"
+  info "默认配置文件: ${DEFAULT_CONFIG_FILE:-"(未设置)"}"
+  info "Origin 证书: ${ORIGIN_CERT:-"(未设置)"}"
+  info "管理根目录: $MANAGER_ROOT"
+}
+
+# 初始化管理目录，可选顺带安装和登录。
+cmd_init() {
+  local do_install=0
+  local do_login=0
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --install) do_install=1; shift ;;
+      --login) do_login=1; shift ;;
+      -h|--help)
+        cat <<EOF
+用法:
+  $SCRIPT_NAME [全局选项] init [--install] [--login]
+EOF
+        return 0
+        ;;
+      *)
+        die "init 不支持的参数: $1"
+        ;;
+    esac
+  done
+
+  ensure_manager_dirs
+  if [[ -n "${DEFAULT_CONFIG_FILE:-}" ]]; then
+    ensure_dir "$(dirname "$DEFAULT_CONFIG_FILE")"
+  fi
+  if [[ -n "${ORIGIN_CERT:-}" ]]; then
+    ensure_dir "$(dirname "$ORIGIN_CERT")"
+  fi
+  if [[ "$do_install" == "1" ]]; then
+    cmd_install --sudo-install
+  fi
+  save_settings
+  if [[ "$do_login" == "1" ]]; then
+    cmd_login
+  fi
+  info "初始化完成。"
+}
+
+# 在 macOS 上下载安装 cloudflared。
+cmd_install() {
+  local sudo_install=0
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --sudo-install) sudo_install=1; shift ;;
+      -h|--help)
+        cat <<EOF
+用法:
+  $SCRIPT_NAME install [--sudo-install]
+EOF
+        return 0
+        ;;
+      *)
+        die "install 不支持的参数: $1"
+        ;;
+    esac
+  done
+
+  if [[ -n "$CLOUDFLARED_BIN" ]]; then
+    info "cloudflared 已安装：$("$CLOUDFLARED_BIN" --version)"
+    return 0
+  fi
+  if [[ "$(uname -s)" != "Darwin" ]]; then
+    die "自动安装目前只支持 macOS。"
+  fi
+
+  local arch pkg_name url pkg_path
+  arch="$(uname -m)"
+  case "$arch" in
+    x86_64) pkg_name="cloudflared-amd64.pkg" ;;
+    arm64) pkg_name="cloudflared-arm64.pkg" ;;
+    *) die "不支持的 macOS 架构: $arch" ;;
+  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
+    open "$pkg_path"
+    info "已打开安装包: $pkg_path"
+  fi
+}
+
+# 执行 cloudflared tunnel login，并同步默认证书到目标位置。
+cmd_login() {
+  ensure_cloudflared
+  "$CLOUDFLARED_BIN" tunnel login
+  maybe_import_default_login_cert
+  if [[ -n "${ORIGIN_CERT:-}" ]] && file_exists "$ORIGIN_CERT"; then
+    info "当前 Origin 证书: $ORIGIN_CERT"
+  else
+    warn "登录完成，但尚未在目标位置发现证书。默认登录证书可能仍在: $DEFAULT_LOGIN_CERT"
+  fi
+  save_settings
+}
+
+# 从现有证书文件导入一份 Origin 证书到当前目标位置。
+cmd_import_cert() {
+  local source="${1:-$DEFAULT_LOGIN_CERT}"
+  source="$(canonical_path "$source")"
+  if [[ -z "${ORIGIN_CERT:-}" ]]; then
+    die "当前没有目标 Origin 证书路径，请先通过 --origincert、--profile-dir 或 init/use 指定。"
+  fi
+  if ! file_exists "$source"; then
+    die "来源证书不存在: $source"
+  fi
+  ensure_dir "$(dirname "$ORIGIN_CERT")"
+  cp "$source" "$ORIGIN_CERT"
+  info "已导入证书: $ORIGIN_CERT"
+}
+
+# 列出全部受管应用。
+cmd_list() {
+  local name=""
+  local any=0
+  while IFS= read -r name; do
+    [[ -z "$name" ]] && continue
+    any=1
+    load_meta "$name"
+    app_summary
+  done < <(managed_apps)
+  if [[ "$any" == "0" ]]; then
+    info "没有受管应用。"
+  fi
+}
+
+# 展示单个应用的元数据和配置内容。
+cmd_show() {
+  local name="${1:-}"
+  local i=0
+  [[ -z "$name" ]] && die "show 需要 NAME"
+  load_meta "$name"
+  cat <<EOF
+应用名称: $META_NAME
+Tunnel 名称: $META_TUNNEL_NAME
+Tunnel ID: $META_TUNNEL_ID
+主入口主机名: $META_HOSTNAME
+主入口服务地址: $META_SERVICE
+ingress 规则数: $(ingress_rule_count)
+应用目录: $META_APP_DIR
+配置文件: $META_CONFIG_FILE
+凭据文件: $META_CREDENTIALS_FILE
+ingress 文件: $META_INGRESS_FILE
+PID 文件: $META_PID_FILE
+日志文件: $META_LOG_FILE
+元数据文件: $META_META_FILE
+创建时间: $META_CREATED_AT
+更新时间: $META_UPDATED_AT
+
+# ingress 规则
+EOF
+  while [[ "$i" -lt "${#INGRESS_HOSTS[@]}" ]]; do
+    printf '  %s. %s -> %s\n' "$((i + 1))" "${INGRESS_HOSTS[$i]}" "${INGRESS_SERVICES[$i]}"
+    i=$((i + 1))
+  done
+  cat <<EOF
+
+# config.yml
+EOF
+  cat "$META_CONFIG_FILE"
+}
+
+# 列出当前账号下的远端 tunnels。
+cmd_tunnels() {
+  local tmp_json count=0 i=0 name="" id="" created_at="" connections=""
+  tmp_json="$(portable_mktemp "cloudflared-manager-tunnels")"
+  remote_cmd list -o json >"$tmp_json"
+  count="$(json_index_count "$tmp_json")"
+  if [[ "$count" == "0" ]]; then
+    info "没有远端 tunnels。"
+    rm -f "$tmp_json"
+    return 0
+  fi
+  while [[ "$i" -lt "$count" ]]; do
+    name="$(json_raw "$tmp_json" "$i.name" || true)"
+    id="$(json_raw "$tmp_json" "$i.id" || true)"
+    created_at="$(json_raw "$tmp_json" "$i.created_at" || true)"
+    connections="$(json_raw "$tmp_json" "$i.connections" || printf '0')"
+    printf '%s | ID=%s | 连接数=%s | 创建时间=%s\n' "$name" "$id" "$connections" "$created_at"
+    i=$((i + 1))
+  done
+  rm -f "$tmp_json"
+}
+
+# 创建新的远端 tunnel，并接管到本地管理目录。
+cmd_add() {
+  local name="${1:-}"
+  local hostname=""
+  local service=""
+  local tunnel_name=""
+  local ingress_specs=()
+  local use_existing=0
+  local overwrite_dns=0
+  local skip_check=0
+  local do_start=0
+  local foreground=0
+  local activate=0
+
+  [[ -z "$name" ]] && die "add 需要 NAME"
+  shift
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --hostname) hostname="${2:-}"; shift 2 ;;
+      --service) service="${2:-}"; shift 2 ;;
+      --ingress) ingress_specs+=("${2:-}"); shift 2 ;;
+      --tunnel-name) tunnel_name="${2:-}"; shift 2 ;;
+      --use-existing) use_existing=1; shift ;;
+      --overwrite-dns) overwrite_dns=1; shift ;;
+      --skip-check) skip_check=1; shift ;;
+      --start) do_start=1; shift ;;
+      --foreground) foreground=1; shift ;;
+      --activate) activate=1; shift ;;
+      -h|--help)
+        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
+        ;;
+      *)
+        die "add 不支持的参数: $1"
+        ;;
+    esac
+  done
+
+  validate_app_name "$name"
+  ensure_cloudflared
+  ensure_logged_in
+
+  if app_exists "$name"; then
+    die "受管应用已存在: $name"
+  fi
+
+  build_requested_ingress_rules "$hostname" "$service" "${ingress_specs[@]}"
+  if [[ "$skip_check" == "0" ]]; then
+    check_all_ingress_targets
+  fi
+  [[ -z "$tunnel_name" ]] && tunnel_name="$name"
+
+  build_meta "$name" "$tunnel_name" "" "${INGRESS_HOSTS[0]}" "${INGRESS_SERVICES[0]}"
+  remote_lookup_by_name "$tunnel_name"
+  if [[ "$REMOTE_FOUND" == "1" ]]; then
+    if [[ "$use_existing" != "1" ]]; then
+      die "远端 tunnel 已存在: $tunnel_name。请使用 adopt 或 add --use-existing。"
+    fi
+    META_TUNNEL_ID="$REMOTE_TUNNEL_ID"
+    issue_credentials "$tunnel_name" "$META_CREDENTIALS_FILE"
+  else
+    create_remote_tunnel "$tunnel_name" "$META_CREDENTIALS_FILE"
+    META_TUNNEL_ID="$REMOTE_TUNNEL_ID"
+  fi
+
+  route_all_dns "$tunnel_name" "$overwrite_dns"
+  save_ingress_rules
+  write_config 0
+  save_meta
+
+  if [[ "$activate" == "1" ]]; then
+    activate_default_config
+  fi
+  if [[ "$do_start" == "1" ]]; then
+    start_app "$foreground" "$skip_check"
+  fi
+  info "已添加受管应用: $name"
+}
+
+# 接管已有的远端 tunnel。
+cmd_adopt() {
+  local name="${1:-}"
+  local tunnel_name=""
+  local hostname=""
+  local service=""
+  local ingress_specs=()
+  local ensure_dns=0
+  local overwrite_dns=0
+  local skip_check=0
+  local activate=0
+
+  [[ -z "$name" ]] && die "adopt 需要 NAME"
+  shift
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --tunnel-name) tunnel_name="${2:-}"; shift 2 ;;
+      --hostname) hostname="${2:-}"; shift 2 ;;
+      --service) service="${2:-}"; shift 2 ;;
+      --ingress) ingress_specs+=("${2:-}"); shift 2 ;;
+      --ensure-dns) ensure_dns=1; shift ;;
+      --overwrite-dns) overwrite_dns=1; shift ;;
+      --skip-check) skip_check=1; shift ;;
+      --activate) activate=1; shift ;;
+      -h|--help)
+        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
+        ;;
+      *)
+        die "adopt 不支持的参数: $1"
+        ;;
+    esac
+  done
+
+  [[ -z "$tunnel_name" ]] && die "adopt 缺少 --tunnel-name"
+
+  validate_app_name "$name"
+  ensure_cloudflared
+  ensure_logged_in
+
+  if app_exists "$name"; then
+    die "受管应用已存在: $name"
+  fi
+
+  build_requested_ingress_rules "$hostname" "$service" "${ingress_specs[@]}"
+  if [[ "$skip_check" == "0" ]]; then
+    check_all_ingress_targets
+  fi
+
+  remote_lookup_by_name "$tunnel_name"
+  if [[ "$REMOTE_FOUND" != "1" ]]; then
+    die "远端 tunnel 不存在: $tunnel_name"
+  fi
+
+  build_meta "$name" "$tunnel_name" "$REMOTE_TUNNEL_ID" "${INGRESS_HOSTS[0]}" "${INGRESS_SERVICES[0]}"
+  issue_credentials "$tunnel_name" "$META_CREDENTIALS_FILE"
+  if [[ "$ensure_dns" == "1" ]]; then
+    route_all_dns "$tunnel_name" "$overwrite_dns"
+  fi
+  save_ingress_rules
+  write_config 0
+  save_meta
+
+  if [[ "$activate" == "1" ]]; then
+    activate_default_config
+  fi
+  info "已接管远端 tunnel: $name"
+}
+
+# 修改既有应用的主机名或服务地址，并按需自动重启。
+cmd_modify() {
+  local name="${1:-}"
+  local new_hostname=""
+  local new_service=""
+  local index="1"
+  local modify_specs=()
+  local overwrite_dns=0
+  local skip_check=0
+  local no_restart=0
+  local activate=0
+  local was_running=0
+  local pid=""
+  local current_index=0
+  local current_hostname=""
+  local current_service=""
+  local help_text=""
+  local pending_hosts=()
+  local pending_services=()
+  local changed_indices=()
+  local changed_count=0
+  local spec=""
+  local changed_index=""
+  local candidate_index=0
+  local candidate_hostname=""
+  local candidate_service=""
+  local planned_modify_flags=()
+  local i=0
+  local j=0
+  local has_hostname_change=0
+
+  help_text="$(cat <<EOF
+用法:
+  $SCRIPT_NAME modify NAME [--index N] [--hostname HOST] [--service URL] [--set N:HOST=URL ...] [--overwrite-dns] [--skip-check] [--no-restart] [--activate]
+
+说明:
+  - 旧写法仍可用：默认修改第 1 条，或配合 --index 修改单条
+  - 批量写法：重复传 --set N:hostname=service
+  - 使用 --set 时，不要再混用 --index / --hostname / --service
+EOF
+)"
+
+  if [[ "$name" == "-h" || "$name" == "--help" ]]; then
+    printf '%s\n' "$help_text"
+    return 0
+  fi
+  [[ -z "$name" ]] && die "modify 需要 NAME"
+  shift
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --hostname) new_hostname="${2:-}"; shift 2 ;;
+      --service) new_service="${2:-}"; shift 2 ;;
+      --index) index="${2:-}"; shift 2 ;;
+      --set) modify_specs+=("${2:-}"); shift 2 ;;
+      --overwrite-dns) overwrite_dns=1; shift ;;
+      --skip-check) skip_check=1; shift ;;
+      --no-restart) no_restart=1; shift ;;
+      --activate) activate=1; shift ;;
+      -h|--help)
+        printf '%s\n' "$help_text"
+        return 0
+        ;;
+      *)
+        die "modify 不支持的参数: $1"
+        ;;
+    esac
+  done
+
+  load_meta "$name"
+  if pid="$(find_running_pid 2>/dev/null || true)"; then
+    [[ -n "$pid" ]] && was_running=1
+  fi
+
+  if [[ "${#modify_specs[@]}" -gt 0 ]]; then
+    if [[ -n "$new_hostname" || -n "$new_service" || "$index" != "1" ]]; then
+      die "使用 --set 批量修改时，不要再混用 --index / --hostname / --service"
+    fi
+
+    pending_hosts=("${INGRESS_HOSTS[@]}")
+    pending_services=("${INGRESS_SERVICES[@]}")
+    i=0
+    while [[ "$i" -lt "${#INGRESS_HOSTS[@]}" ]]; do
+      planned_modify_flags+=(0)
+      i=$((i + 1))
+    done
+
+    for spec in "${modify_specs[@]}"; do
+      parse_modify_spec "$spec"
+      candidate_index=$((PARSED_MODIFY_INDEX - 1))
+      if [[ "$candidate_index" -lt 0 || "$candidate_index" -ge "${#INGRESS_HOSTS[@]}" ]]; then
+        die "批量修改序号超出范围: $PARSED_MODIFY_INDEX。当前共有 $(ingress_rule_count) 条规则。"
+      fi
+      if [[ "${planned_modify_flags[$candidate_index]}" == "1" ]]; then
+        die "同一条 ingress 不能在一次批量修改里重复指定: $PARSED_MODIFY_INDEX"
+      fi
+      planned_modify_flags[$candidate_index]=1
+      if [[ "$skip_check" == "0" ]]; then
+        local_target_reachable "$PARSED_MODIFY_SERVICE"
+      fi
+      pending_hosts[$candidate_index]="$PARSED_MODIFY_HOSTNAME"
+      pending_services[$candidate_index]="$PARSED_MODIFY_SERVICE"
+    done
+
+    i=0
+    while [[ "$i" -lt "${#pending_hosts[@]}" ]]; do
+      j=$((i + 1))
+      while [[ "$j" -lt "${#pending_hosts[@]}" ]]; do
+        if [[ "${pending_hosts[$i]}" == "${pending_hosts[$j]}" ]]; then
+          die "批量修改后出现重复主机名: ${pending_hosts[$i]}"
+        fi
+        j=$((j + 1))
+      done
+      i=$((i + 1))
+    done
+
+    i=0
+    while [[ "$i" -lt "${#INGRESS_HOSTS[@]}" ]]; do
+      if [[ "${INGRESS_HOSTS[$i]}" != "${pending_hosts[$i]}" || "${INGRESS_SERVICES[$i]}" != "${pending_services[$i]}" ]]; then
+        changed_indices+=("$i")
+      fi
+      i=$((i + 1))
+    done
+
+    changed_count="${#changed_indices[@]}"
+    if [[ "$changed_count" == "0" ]]; then
+      info "没有变更。"
+      return 0
+    fi
+
+    for changed_index in "${changed_indices[@]}"; do
+      candidate_hostname="${pending_hosts[$changed_index]}"
+      current_hostname="${INGRESS_HOSTS[$changed_index]}"
+      if [[ "$candidate_hostname" != "$current_hostname" ]]; then
+        route_dns "$META_TUNNEL_NAME" "$candidate_hostname" "$overwrite_dns"
+        has_hostname_change=1
+      fi
+    done
+
+    backup_file "$META_META_FILE" >/dev/null || true
+    backup_file "$META_CONFIG_FILE" >/dev/null || true
+    backup_file "$META_INGRESS_FILE" >/dev/null || true
+    INGRESS_HOSTS=("${pending_hosts[@]}")
+    INGRESS_SERVICES=("${pending_services[@]}")
+  else
+    [[ "$index" =~ ^[1-9][0-9]*$ ]] || die "--index 必须是大于等于 1 的整数"
+    current_index=$((index - 1))
+    if [[ "$current_index" -ge "${#INGRESS_HOSTS[@]}" ]]; then
+      die "ingress 序号超出范围: $index。当前共有 $(ingress_rule_count) 条规则。"
+    fi
+    current_hostname="${INGRESS_HOSTS[$current_index]}"
+    current_service="${INGRESS_SERVICES[$current_index]}"
+
+    if [[ -n "$new_hostname" ]]; then
+      new_hostname="$(normalize_hostname "$new_hostname")"
+    else
+      new_hostname="$current_hostname"
+    fi
+    if [[ -n "$new_service" ]]; then
+      new_service="$(normalize_service "$new_service")"
+    else
+      new_service="$current_service"
+    fi
+
+    if [[ "$skip_check" == "0" ]]; then
+      local_target_reachable "$new_service"
+    fi
+
+    if [[ "$new_hostname" == "$current_hostname" && "$new_service" == "$current_service" ]]; then
+      info "没有变更。"
+      return 0
+    fi
+
+    if [[ "$new_hostname" != "$current_hostname" ]] && find_ingress_rule_index_by_hostname "$new_hostname" "$current_index" >/dev/null 2>&1; then
+      die "同一个 Tunnel 下已存在该主机名: $new_hostname"
+    fi
+
+    if [[ "$new_hostname" != "$current_hostname" ]]; then
+      route_dns "$META_TUNNEL_NAME" "$new_hostname" "$overwrite_dns"
+      has_hostname_change=1
+    fi
+
+    backup_file "$META_META_FILE" >/dev/null || true
+    backup_file "$META_CONFIG_FILE" >/dev/null || true
+    backup_file "$META_INGRESS_FILE" >/dev/null || true
+    INGRESS_HOSTS[$current_index]="$new_hostname"
+    INGRESS_SERVICES[$current_index]="$new_service"
+    changed_count=1
+  fi
+
+  if [[ "$has_hostname_change" == "1" ]]; then
+    warn "cloudflared CLI 不会删除旧 DNS 记录。如果旧 hostname 不再使用，请到 Cloudflare 手工清理。"
+  fi
+
+  save_ingress_rules
+  write_config 0
+  save_meta
+
+  if [[ "$activate" == "1" ]]; then
+    activate_default_config
+  fi
+  if [[ "$was_running" == "1" && "$no_restart" == "0" ]]; then
+    stop_app 0
+    start_app 0 "$skip_check"
+    if [[ "${#modify_specs[@]}" -gt 0 ]]; then
+      info "已批量修改 ${changed_count} 条 ingress 并重启: $META_NAME"
+    else
+      info "已修改并重启: $META_NAME"
+    fi
+  else
+    if [[ "${#modify_specs[@]}" -gt 0 ]]; then
+      info "已批量修改 ingress 规则数量: ${changed_count}"
+    else
+      info "已修改: $META_NAME"
+    fi
+  fi
+}
+
+# 列出指定应用的全部 ingress 规则。
+cmd_ingress_list() {
+  local name="${1:-}"
+  local i=0
+  [[ -z "$name" ]] && die "ingress-list 需要 NAME"
+
+  load_meta "$name"
+  printf '应用名称: %s\n' "$META_NAME"
+  printf 'Tunnel 名称: %s\n' "$META_TUNNEL_NAME"
+  printf 'ingress 规则数: %s\n' "$(ingress_rule_count)"
+  while [[ "$i" -lt "${#INGRESS_HOSTS[@]}" ]]; do
+    printf '  %s. %s -> %s\n' "$((i + 1))" "${INGRESS_HOSTS[$i]}" "${INGRESS_SERVICES[$i]}"
+    i=$((i + 1))
+  done
+}
+
+# 为指定应用追加一批新的 ingress 规则。
+cmd_ingress_add() {
+  local name="${1:-}"
+  local hostname=""
+  local service=""
+  local ingress_specs=()
+  local overwrite_dns=0
+  local skip_check=0
+  local no_restart=0
+  local activate=0
+  local was_running=0
+  local pid=""
+  local requested_hosts=()
+  local requested_services=()
+  local i=0
+  local candidate_hostname=""
+  local candidate_service=""
+
+  if [[ "$name" == "-h" || "$name" == "--help" ]]; then
+    cat <<EOF
+用法:
+  $SCRIPT_NAME ingress-add NAME [--hostname HOST --service URL] [--ingress HOST=URL ...] [--overwrite-dns] [--skip-check] [--no-restart] [--activate]
+
+说明:
+  - 兼容旧写法：使用一组 --hostname 和 --service
+  - 批量写法：重复传 --ingress hostname=service
+  - 可以混用，但同一个 hostname 不能重复
+EOF
+    return 0
+  fi
+  [[ -z "$name" ]] && die "ingress-add 需要 NAME"
+  shift
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --hostname) hostname="${2:-}"; shift 2 ;;
+      --service) service="${2:-}"; shift 2 ;;
+      --ingress) ingress_specs+=("${2:-}"); shift 2 ;;
+      --overwrite-dns) overwrite_dns=1; shift ;;
+      --skip-check) skip_check=1; shift ;;
+      --no-restart) no_restart=1; shift ;;
+      --activate) activate=1; shift ;;
+      -h|--help)
+        cmd_ingress_add --help
+        return 0
+        ;;
+      *)
+        die "ingress-add 不支持的参数: $1"
+        ;;
+    esac
+  done
+
+  load_meta "$name"
+  if pid="$(find_running_pid 2>/dev/null || true)"; then
+    [[ -n "$pid" ]] && was_running=1
+  fi
+
+  if [[ -n "$hostname" || -n "$service" ]]; then
+    [[ -n "$hostname" ]] || die "ingress-add 缺少 --hostname"
+    [[ -n "$service" ]] || die "ingress-add 缺少 --service"
+    requested_hosts+=("$(normalize_hostname "$hostname")")
+    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 [[ "${#requested_hosts[@]}" == "0" ]]; then
+    die "至少需要提供一条 ingress 规则。可使用 --hostname/--service，或重复传 --ingress hostname=service"
+  fi
+
+  i=0
+  while [[ "$i" -lt "${#requested_hosts[@]}" ]]; do
+    candidate_hostname="${requested_hosts[$i]}"
+    candidate_service="${requested_services[$i]}"
+
+    if find_ingress_rule_index_by_hostname "$candidate_hostname" >/dev/null 2>&1; then
+      die "同一个 Tunnel 下已存在该主机名: $candidate_hostname"
+    fi
+    if [[ "$i" -gt 0 ]]; then
+      local prior=0
+      while [[ "$prior" -lt "$i" ]]; do
+        if [[ "${requested_hosts[$prior]}" == "$candidate_hostname" ]]; then
+          die "本次批量新增中出现重复主机名: $candidate_hostname"
+        fi
+        prior=$((prior + 1))
+      done
+    fi
+    if [[ "$skip_check" == "0" ]]; then
+      local_target_reachable "$candidate_service"
+    fi
+    i=$((i + 1))
+  done
+
+  i=0
+  while [[ "$i" -lt "${#requested_hosts[@]}" ]]; do
+    route_dns "$META_TUNNEL_NAME" "${requested_hosts[$i]}" "$overwrite_dns"
+    i=$((i + 1))
+  done
+
+  backup_file "$META_META_FILE" >/dev/null || true
+  backup_file "$META_CONFIG_FILE" >/dev/null || true
+  backup_file "$META_INGRESS_FILE" >/dev/null || true
+  i=0
+  while [[ "$i" -lt "${#requested_hosts[@]}" ]]; do
+    append_ingress_rule "${requested_hosts[$i]}" "${requested_services[$i]}"
+    i=$((i + 1))
+  done
+  save_ingress_rules
+  write_config 0
+  save_meta
+
+  if [[ "$activate" == "1" ]]; then
+    activate_default_config
+  fi
+  if [[ "$was_running" == "1" && "$no_restart" == "0" ]]; then
+    stop_app 0
+    start_app 0 "$skip_check"
+    info "已新增 ingress 并重启: $META_NAME"
+  else
+    info "已新增 ingress 规则数量: ${#requested_hosts[@]}"
+  fi
+}
+
+# 从指定应用批量移除 ingress 规则。
+cmd_ingress_remove() {
+  local name="${1:-}"
+  local hostnames=()
+  local indices=()
+  local no_restart=0
+  local activate=0
+  local was_running=0
+  local pid=""
+  local remove_flags=()
+  local remaining_hosts=()
+  local remaining_services=()
+  local removed_hosts=()
+  local total_rules=0
+  local remove_count=0
+  local i=0
+  local current_index=0
+  local hostname=""
+  local index=""
+
+  if [[ "$name" == "-h" || "$name" == "--help" ]]; then
+    cat <<EOF
+用法:
+  $SCRIPT_NAME ingress-remove NAME [--hostname HOST ...] [--index N ...] [--no-restart] [--activate]
+
+说明:
+  - 可重复传 --hostname
+  - 可重复传 --index
+  - 两种写法可以混用，脚本会自动去重
+EOF
+    return 0
+  fi
+  [[ -z "$name" ]] && die "ingress-remove 需要 NAME"
+  shift
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --hostname) hostnames+=("${2:-}"); shift 2 ;;
+      --index) indices+=("${2:-}"); shift 2 ;;
+      --no-restart) no_restart=1; shift ;;
+      --activate) activate=1; shift ;;
+      -h|--help)
+        cmd_ingress_remove --help
+        return 0
+        ;;
+      *)
+        die "ingress-remove 不支持的参数: $1"
+        ;;
+    esac
+  done
+
+  if [[ "${#hostnames[@]}" == "0" && "${#indices[@]}" == "0" ]]; then
+    die "ingress-remove 至少需要一个 --hostname 或 --index"
+  fi
+
+  load_meta "$name"
+  if [[ "$(ingress_rule_count)" == "1" ]]; then
+    die "至少需要保留一条 ingress 规则。请直接删除整个应用，或先新增其他规则。"
+  fi
+  if pid="$(find_running_pid 2>/dev/null || true)"; then
+    [[ -n "$pid" ]] && was_running=1
+  fi
+
+  total_rules="${#INGRESS_HOSTS[@]}"
+  i=0
+  while [[ "$i" -lt "$total_rules" ]]; do
+    remove_flags+=(0)
+    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
+
+  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
+
+  i=0
+  while [[ "$i" -lt "$total_rules" ]]; do
+    if [[ "${remove_flags[$i]}" == "1" ]]; then
+      removed_hosts+=("${INGRESS_HOSTS[$i]}")
+      remove_count=$((remove_count + 1))
+    else
+      remaining_hosts+=("${INGRESS_HOSTS[$i]}")
+      remaining_services+=("${INGRESS_SERVICES[$i]}")
+    fi
+    i=$((i + 1))
+  done
+
+  if [[ "$remove_count" == "0" ]]; then
+    die "未找到要删除的 ingress 规则。"
+  fi
+  if [[ "${#remaining_hosts[@]}" == "0" ]]; then
+    die "至少需要保留一条 ingress 规则。当前删除范围会把全部规则删空。"
+  fi
+
+  backup_file "$META_META_FILE" >/dev/null || true
+  backup_file "$META_CONFIG_FILE" >/dev/null || true
+  backup_file "$META_INGRESS_FILE" >/dev/null || true
+  INGRESS_HOSTS=("${remaining_hosts[@]}")
+  INGRESS_SERVICES=("${remaining_services[@]}")
+  save_ingress_rules
+  write_config 0
+  save_meta
+  warn "已从配置中移除 ${#removed_hosts[@]} 条 ingress。Cloudflare 上旧 DNS 记录不会自动删除，如已弃用请手工清理。"
+
+  if [[ "$activate" == "1" ]]; then
+    activate_default_config
+  fi
+  if [[ "$was_running" == "1" && "$no_restart" == "0" ]]; then
+    stop_app 0
+    start_app 0 0
+    info "已移除 ingress 并重启: $META_NAME"
+  else
+    info "已移除 ingress 规则数量: ${#removed_hosts[@]}"
+  fi
+}
+
+# 删除本地受管应用，可选同步删除远端 tunnel。
+cmd_delete() {
+  local name="${1:-}"
+  local delete_tunnel=0
+  local force=0
+  local archived=""
+
+  [[ -z "$name" ]] && die "delete 需要 NAME"
+  shift
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --delete-tunnel) delete_tunnel=1; shift ;;
+      --force) force=1; shift ;;
+      -h|--help)
+        cat <<EOF
+用法:
+  $SCRIPT_NAME delete NAME [--delete-tunnel] [--force]
+EOF
+        return 0
+        ;;
+      *)
+        die "delete 不支持的参数: $1"
+        ;;
+    esac
+  done
+
+  load_meta "$name"
+  if find_running_pid >/dev/null 2>&1; then
+    stop_app "$force"
+  fi
+
+  if [[ "$delete_tunnel" == "1" ]]; then
+    if [[ "$force" == "1" ]]; then
+      remote_cmd delete --force "$META_TUNNEL_NAME" >/dev/null
+    else
+      remote_cmd delete "$META_TUNNEL_NAME" >/dev/null
+    fi
+    warn "cloudflared tunnel delete 不会清理历史 DNS 记录。如果旧主机名已弃用，请到 Cloudflare 手工删除。"
+  fi
+
+  archived="$(archive_app_dir "$META_APP_DIR")"
+  info "已归档本地应用目录: $archived"
+}
+
+# 启动指定应用。
+cmd_start() {
+  local name="${1:-}"
+  local foreground=0
+  local skip_check=0
+  [[ -z "$name" ]] && die "start 需要 NAME"
+  shift
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --foreground) foreground=1; shift ;;
+      --skip-check) skip_check=1; shift ;;
+      -h|--help)
+        cat <<EOF
+用法:
+  $SCRIPT_NAME start NAME [--foreground] [--skip-check]
+EOF
+        return 0
+        ;;
+      *)
+        die "start 不支持的参数: $1"
+        ;;
+    esac
+  done
+
+  load_meta "$name"
+  start_app "$foreground" "$skip_check"
+  if [[ "$foreground" == "0" ]]; then
+    info "已启动: $name"
+    info "日志文件: $META_LOG_FILE"
+  fi
+}
+
+# 停止指定应用。
+cmd_stop() {
+  local name="${1:-}"
+  local force=0
+  [[ -z "$name" ]] && die "stop 需要 NAME"
+  shift
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --force) force=1; shift ;;
+      -h|--help)
+        cat <<EOF
+用法:
+  $SCRIPT_NAME stop NAME [--force]
+EOF
+        return 0
+        ;;
+      *)
+        die "stop 不支持的参数: $1"
+        ;;
+    esac
+  done
+
+  load_meta "$name"
+  stop_app "$force"
+}
+
+# 重启指定应用。
+cmd_restart() {
+  local name="${1:-}"
+  local force=0
+  local skip_check=0
+  [[ -z "$name" ]] && die "restart 需要 NAME"
+  shift
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --force) force=1; shift ;;
+      --skip-check) skip_check=1; shift ;;
+      -h|--help)
+        cat <<EOF
+用法:
+  $SCRIPT_NAME restart NAME [--force] [--skip-check]
+EOF
+        return 0
+        ;;
+      *)
+        die "restart 不支持的参数: $1"
+        ;;
+    esac
+  done
+
+  load_meta "$name"
+  if find_running_pid >/dev/null 2>&1; then
+    stop_app "$force"
+  fi
+  start_app 0 "$skip_check"
+  info "已重启: $name"
+}
+
+# 查看单个或全部应用状态。
+cmd_status() {
+  local name="${1:-}"
+  local pid=""
+  if [[ -n "$name" ]]; then
+    load_meta "$name"
+    app_summary
+    if pid="$(find_running_pid 2>/dev/null || true)"; then
+      [[ -n "$pid" ]] && printf '  进程 PID=%s\n' "$pid"
+    fi
+    printf '  配置文件=%s\n' "$META_CONFIG_FILE"
+    printf '  日志文件=%s\n' "$META_LOG_FILE"
+    return 0
+  fi
+
+  local any=0
+  while IFS= read -r name; do
+    [[ -z "$name" ]] && continue
+    any=1
+    load_meta "$name"
+    app_summary
+    if pid="$(find_running_pid 2>/dev/null || true)"; then
+      [[ -n "$pid" ]] && printf '  进程 PID=%s\n' "$pid"
+    fi
+    printf '  配置文件=%s\n' "$META_CONFIG_FILE"
+    printf '  日志文件=%s\n' "$META_LOG_FILE"
+  done < <(managed_apps)
+  if [[ "$any" == "0" ]]; then
+    info "没有受管应用。"
+  fi
+}
+
+# 查看或持续跟随应用日志。
+cmd_logs() {
+  local name="${1:-}"
+  local follow=0
+  local lines=100
+  [[ -z "$name" ]] && die "logs 需要 NAME"
+  shift
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      -f|--follow) follow=1; shift ;;
+      -n|--lines) lines="${2:-}"; shift 2 ;;
+      -h|--help)
+        cat <<EOF
+用法:
+  $SCRIPT_NAME logs NAME [-f|--follow] [-n|--lines N]
+EOF
+        return 0
+        ;;
+      *)
+        die "logs 不支持的参数: $1"
+        ;;
+    esac
+  done
+
+  load_meta "$name"
+  if [[ "$follow" == "1" ]]; then
+    if ! file_exists "$META_LOG_FILE"; then
+      die "日志文件不存在: $META_LOG_FILE"
+    fi
+    tail -f -n "$lines" "$META_LOG_FILE"
+    return 0
+  fi
+  if ! file_exists "$META_LOG_FILE"; then
+    info "(日志为空)"
+    return 0
+  fi
+  tail -n "$lines" "$META_LOG_FILE"
+}
+
+# 将某个应用配置复制到默认 config.yml。
+cmd_activate() {
+  local name="${1:-}"
+  [[ -z "$name" ]] && die "activate 需要 NAME"
+  load_meta "$name"
+  activate_default_config
+  info "已将受管应用配置激活为默认配置: $META_NAME"
+}
+
+# 解析全局命令行参数。
+parse_global_options() {
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --profile-dir|--cloudflared-dir)
+        CLI_PROFILE_DIR="${2:-}"
+        [[ -z "$CLI_PROFILE_DIR" ]] && die "$1 需要参数"
+        shift 2
+        ;;
+      --config-file|--default-config)
+        CLI_DEFAULT_CONFIG_FILE="${2:-}"
+        [[ -z "$CLI_DEFAULT_CONFIG_FILE" ]] && die "$1 需要参数"
+        shift 2
+        ;;
+      --origincert)
+        CLI_ORIGIN_CERT="${2:-}"
+        [[ -z "$CLI_ORIGIN_CERT" ]] && die "$1 需要参数"
+        shift 2
+        ;;
+      --manager-root)
+        CLI_MANAGER_ROOT="${2:-}"
+        [[ -z "$CLI_MANAGER_ROOT" ]] && die "$1 需要参数"
+        shift 2
+        ;;
+      --save-profile)
+        SAVE_PROFILE=1
+        shift
+        ;;
+      -h|--help)
+        print_usage
+        exit 0
+        ;;
+      --)
+        shift
+        break
+        ;;
+      -*)
+        die "未知全局参数: $1"
+        ;;
+      *)
+        break
+        ;;
+    esac
+  done
+  REMAINING_ARGS=("$@")
+}
+
+# 主入口：解析全局参数并分发到具体命令。
+main() {
+  local cmd=""
+  parse_global_options "$@"
+  set -- "${REMAINING_ARGS[@]}"
+  resolve_paths
+  if [[ "$SAVE_PROFILE" == "1" ]]; then
+    save_settings
+  fi
+
+  cmd="${1:-help}"
+  shift || true
+  case "$cmd" in
+    doctor) cmd_doctor "$@" ;;
+    init) cmd_init "$@" ;;
+    use) cmd_use "$@" ;;
+    install) cmd_install "$@" ;;
+    login) cmd_login "$@" ;;
+    import-cert) cmd_import_cert "$@" ;;
+    list) cmd_list "$@" ;;
+    show) cmd_show "$@" ;;
+    tunnels) cmd_tunnels "$@" ;;
+    add) cmd_add "$@" ;;
+    adopt) cmd_adopt "$@" ;;
+    modify) cmd_modify "$@" ;;
+    ingress-list) cmd_ingress_list "$@" ;;
+    ingress-add) cmd_ingress_add "$@" ;;
+    ingress-remove) cmd_ingress_remove "$@" ;;
+    delete) cmd_delete "$@" ;;
+    start) cmd_start "$@" ;;
+    stop) cmd_stop "$@" ;;
+    restart) cmd_restart "$@" ;;
+    status) cmd_status "$@" ;;
+    logs) cmd_logs "$@" ;;
+    activate) cmd_activate "$@" ;;
+    help) print_usage ;;
+    *)
+      die "未知命令: $cmd。可用 help 查看帮助。"
+      ;;
+  esac
+}
+
+main "$@"