牛马折腾日记 007：把部署从「8 步手动 cd」升级到「sudo sm-update 一行」，然后用 3 天修完自己的 wrapper

引子

2026-08-26 周三早上 8:43，我刚把 `a2ec469` 推到 main，注释写着「feat(progress): SM-L.2 Sticky Header 总进度条」。`scripts/_progress.sh` 加了 5 个新 API —— `progress_header_init` / `progress_header_advance` / `progress_substep_v2` / `progress_header_done`，再带一个 3 段自适应 ETA 算法。

跑了一下 `sudo sm-update`，终端上原本 8 步手动敲的 `cd && bash update.sh` 输出，被压缩成两行 sticky header：

▶ security-monitor 更新 [██████░░░░░░░░░░] 35% (3/9) ETA 2m48s — 拉取新代码
↳ [████████░░░░░░░░░] 4/10 40% git pull autostash

看着挺顺。但这行命令走到今天，整整花了 3 天。

8/24 周一 23:05，Phase SM-L 第一个 commit 落地，`scripts/sm-update` 第一次跑通 —— 4 个 pytest 守卫全过。第二天早上，部署机用户发来一行错误：

$ sudo sm-admin
❌ 找不到 venv Python: /usr/local/venv/bin/python3
请确认 security-monitor 已正确安装

`sm-update` 装到 `/usr/local/bin/` 了，但它自己的兄弟脚本 `sm-admin` 还在用 `BASH_SOURCE` 推导 `PROJECT_ROOT` —— 推到 `/usr/local/bin/` 之后，`PROJECT_ROOT=/usr/local`，自然找不到 `/usr/local/venv/bin/python3`。

8/25 我修了 wrapper bug，把找仓库的逻辑从「靠 `BASH_SOURCE` 推导」改成「4 路径 fallback」。8/26 我顺手把更新进度从单阶段 [STEP X/9] 升级成 sticky header 总进度 + ETA。

13 个 commit、28 个新 pytest 全过、全基线 1585 passed。这就是本周三的 `sudo sm-update`。

问题：3 个真问题，但看起来像 1 个

过去 3 天我修了 3 个互相牵连的问题，每一个单独看都不大，但合起来让「一行更新」这个承诺完整地假装在工作。

问题 1 — `update.sh` 自己改自己，怎么保证不 race（Phase SM-L, 2026-08-24）

最初的动机很朴素：部署机用户每次更新要敲 8 行：

cd /opt/security-monitor
git pull --autostash
bash update.sh
systemctl restart security-monitor.service
journalctl -u security-monitor.service -n 20
# 再 5 个 smoke 步骤

我想把它压成一行 `sudo sm-update`。第一版写完发现一个隐藏 race：`sm-update` 脚本本身可能在 `git pull` 之后被改了（因为 wrapper 也可能改了）。如果用 `source` 或 fork 子 shell 跑，新代码可能没生效。

修复方法：wrapper 装在 `/usr/local/bin/`（不在仓库里），不会被 `git pull` 影响。pull 完之后用 `exec bash update.sh "$@"` 替换当前进程——这样 update.sh 的 `trap` / signal 处理正常传递，且 exec 时加载的是最新磁盘版本（不是 wrapper fork 时缓存的旧版）。

# scripts/sm-update (excerpt)
# ── 找仓库 (跟 sm-admin 一致) ──
SM_HOME="${SECURITY_MONITOR_HOME:-}"
FOUND=false
for try in \
    "$SM_HOME" \
    "/opt/security-monitor" \
    "/usr/local/security-monitor" \
    "$HOME/security-monitor"; do
    if [[ -n "$try" && -d "$try" && ( -d "$try/.git" || -f "$try/update.sh" ) ]]; then
        SM_HOME="$try"
        FOUND=true
        break
    fi
done
# ── git pull 失败不直接 exit ──
if [[ -d "$SM_HOME/.git" ]]; then
    echo "🔄 [sm-update] git pull 最新代码..."
    if ! git pull --autostash 2>&1 | tail -5; then
        echo "⚠️  [sm-update] git pull 失败, 用当前 HEAD 继续" >&2
        # 不 exit, 让 update.sh 用当前 HEAD 跑
    fi
fi
# ── 标记 wrapper 已执行 + exec update.sh ──
export SM_UPDATE_WRAPPER=1
exec bash "$SM_HOME/update.sh" "$@"

关键洞察 1：`git pull` 失败不直接 exit——部署机用户可能有未提交的实验代码，他们期望「拉失败也照跑 update.sh」而不是「全卡死」。

关键洞察 2：`SM_UPDATE_WRAPPER=1` 是 wrapper 和 update.sh 的握手信号。update.sh 的 stage 3（拉取代码段）检测到这个 env var 后跳过重复 `git pull`——因为 wrapper 已经拉过了，重复拉浪费 3-5 秒 + 网络抖动风险。

问题 2 — `sm-admin` 找不到自己的 venv（Phase SM-M, 2026-08-25）

8/25 凌晨 1 点部署机用户的报错：

$ sudo sm-admin
❌ 找不到 venv Python: /usr/local/venv/bin/python3

我打开 `scripts/sm-admin` 看，注释写着：

# 初版（已废弃, Phase SM-M 修复）
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"   # ← 推导错位
VENV_PYTHON="$PROJECT_ROOT/venv/bin/python3"

`install.sh` 把 wrapper `cp` 到 `/usr/local/bin/`。`BASH_SOURCE[0]` 是 `/usr/local/bin/sm-admin`，`dirname` 是 `/usr/local/bin`，再 `dirname` 是 `/usr/local`。`PROJECT_ROOT=/usr/local`，自然找不到 `/usr/local/venv/bin/python3`。

注释当时写的是「避免硬编码 `/opt/security-monitor`」，但推导逻辑本身在 cp 到 `/usr/local/bin/` 后就崩了，没考虑部署场景。

修复 — 跟 `sm-update` 用同一套 4 路径 fallback：

# scripts/sm-admin (Phase SM-M 修复版)
SM_HOME="${SECURITY_MONITOR_HOME:-}"
FOUND=false
for try in \
    "$SM_HOME" \
    "/opt/security-monitor" \
    "/usr/local/security-monitor" \
    "$HOME/security-monitor"; do
    if [[ -n "$try" && -d "$try" && ( -d "$try/.git" || -f "$try/update.sh" ) ]]; then
        SM_HOME="$try"
        FOUND=true
        break
    fi
done
if [[ "$FOUND" != "true" ]]; then
    echo "❌ 找不到 security-monitor 仓库" >&2
    exit 2
fi
# ── 找 venv (兼容 .venv / venv / SECURITY_MONITOR_VENV) ──
VENV_PY=""
for try in \
    "${SECURITY_MONITOR_VENV:-}" \
    "$SM_HOME/.venv/bin/python3" \
    "$SM_HOME/venv/bin/python3" \
    "$SM_HOME/.venv/bin/python" \
    "$SM_HOME/venv/bin/python"; do
    if [[ -n "$try" && -x "$try" ]]; then
        VENV_PY="$try"
        break
    fi
done

关键洞察 3：`sm-update` 和 `sm-admin` 必须共用同一套找仓库 + 找 venv 逻辑——任何不一致都会让部署机用户遇到「`sm-update` 能跑但 `sm-admin` 报错」这种半生不熟的状态。

我顺手把 `sm-cli` 从 `install.sh` 的 heredoc 内嵌里拆成独立文件（之前不存在独立 wrapper 文件，install.sh 临时拼装）。类教训 11「汇报失真」闭环——仓库改了 wrapper 但 install.sh 不重新 deploy，部署机用户永远用老 wrapper。修复：install.sh 直接 install 仓库里的 wrapper 文件（单一真相源）。

PART_A_START

问题 3 — 8 步更新没有总进度，用户看到黑屏 6 分钟（Phase SM-L.2, 2026-08-26）

8/25 修完 wrapper bug 后，部署机用户提了第二个要求：

「更新时的进度条再优化好点，最好有总体的实时进度情况。」

`scripts/_progress.sh` 已有 Phase 50 引入的 `progress_step`，但只能显示单阶段 `[STEP X/9 NN% (已用 Ns)]`，没有跨阶段总进度。跑 6-8 分钟的 update 时用户盯着屏幕看不到还剩多久。

修复 — Sticky Header 总进度条（两行窗口）：

# scripts/_progress.sh 新增 API
progress_header_init N_STAGES LABEL             # 初始化 + 打印第 1 行
progress_header_advance STAGE [msg]             # 阶段切换, 重绘第 1 行
progress_substep_v2 CUR TOTAL [msg]             # 阶段内子进度, 重绘第 2 行
progress_header_done [msg]                      # 全部完成, 100% + 调 progress_done
_progress_compute_eta                           # 3 段自适应 ETA

第 1 行: ▶ 标签 [████░░░░░░] 55% (5/9) ETA 1m23s — 阶段描述
第 2 行: ↳ [██████░░░░░░] 3/10 30% 子阶段描述

ETA 算法分 3 段（这点很关键，不是简单平均）：

_progress_compute_eta() {
    local samples=${#_STAGE_TIMES[@]}
    case $samples in
        0)  echo "--" ;;
        1)  # 1 样本: 当前阶段已用时 × 8 (历史 9 阶段加权平均)
            local cur=$(( $(date +%s) - _HEADER_STAGE_START_TS ))
            echo "$(( cur * 8 ))s" ;;
        2|3) # 2-3 样本: 简单平均
            local total=$(( $(date +%s) - _HEADER_START_TS ))
            local remaining=$(( (_HEADER_TOTAL - _HEADER_CURRENT) * total / _HEADER_CURRENT ))
            echo "${remaining}s" ;;
        *)  # ≥4 样本: 加权平均 (近 3 阶段 ×2, 老样本 ×1)
            # 反映"后半段变慢" (smoke/verify 阶段天然耗时)
            ...
    esac
}

关键洞察 4：1 个样本直接用「当前阶段 × 8」比简单平均准得多——因为你不知道未来 8 个阶段要多久，但你知道当前这一个的耗时，乘以 8 是经验值。简单平均在 1 个样本时是 0/1 = 0，永远显示「还剩 0 秒」骗用户。

关键洞察 5：TTY 模式必须用 `$'\033'`（ANSI-C 转义）生成的真 ESC 字符 (0x1b)，不能直接写 `\033` 字面量 —— `printf '\033[2K'` 会被解析成 octal escape `\033` 然后 `[2K` 不是合法 octal digit，报 `invalid number`。我调试时栽在这上面 15 分钟：

# ❌ 错 (调试时栽过)
printf '\033[2K\r'   # bash 解析 \033 为 ESC (1 byte), 但 [2K 不是 octal digit → invalid number
# ✅ 对
_HE_CLEAR=$'\033[2K\r'  # ANSI-C 转义生成真 ESC + [2K\r
printf '%s' "$_HE_CLEAR"

或者提取常量：

_HE_BOLD=$'\033[1m'
_HE_CYAN=$'\033[0;36m'
_HE_RESET=$'\033[0m'
# 然后 printf 格式串只含 %s 占位 + %d 数字
printf '%s%s  ↳ %s[%s]%s %s%d/%d %3d%%%s %s\n' \
    "$_HE_CLEAR_LINE" "$_HE_DIM" \
    "$_HE_CYAN" "$bar" "$_HE_RESET" \
    "$_HE_DIM" "$current" "$total" "$pct" "$_HE_RESET" \
    "$_HE_DIM" "$msg"

关键洞察 6：非 TTY 模式（cron / systemd / log file）必须降级为前缀 log 行——光标控制 ANSI 序列在管道里会变成「乱码字符 + 看不见的进度」，比单阶段 [STEP] 还差。`PROGRESS=off` 完全静默，cron / systemd 兼容。

排查：每一行代码都对应一个真实坑

坑 1 — `install.sh` heredoc 内嵌 wrapper 的「单一真相源」漂移

我在 8/25 修 wrapper bug 时查 git log，发现 `install.sh` 从 7 月初开始就 `cat <<'EOF' > /usr/local/bin/sm-admin` 这种 heredoc 拼装 —— 仓库里 `scripts/sm-admin` 改了，install.sh 里那段 heredoc 没改。部署机用户每次重装都用老的 wrapper。

我没有改 heredoc 的内容（那治标不治本），而是直接把 install.sh 里那段 heredoc 删掉，改成 `install -m 0755 scripts/sm-admin /usr/local/bin/sm-admin` —— 单一真相源 = 仓库里的 wrapper 文件。

这是类教训 11「汇报失真」的真正闭环——之前只是「诊断脚本路径错了手动改对」，这次是「从架构上消除漂移」。

坑 2 — `BASH_SOURCE` 在 `exec` 之后的子 shell 里行为不同

初版 wrapper 用 `BASH_SOURCE` 找仓库，但我写完才发现，`sm-update` 最后一句是 `exec bash update.sh "$@"` —— exec 替换进程后，`update.sh` 子 shell 里 `$BASH_SOURCE` 是 `/opt/security-monitor/update.sh`，不再指向 wrapper 自身。

更糟的是，如果用户在 `sm-update` 内部 `source` 一个脚本再 exec，那 exec 后 `$BASH_SOURCE[0]` 是被 source 的脚本，不是 wrapper。`BASH_SOURCE` 不可靠——只要脚本被 exec / source / trap 调用过，路径就不再可信。

修复：不用 `BASH_SOURCE`，直接走已知路径列表 —— `SECURITY_MONITOR_HOME` env var 优先 → `/opt/security-monitor`（部署机标准安装路径）→ `/usr/local/security-monitor`（备选）→ `$HOME/security-monitor`（开发机 fallback）。哪个存在 `.git` 或 `update.sh` 就用哪个。

坑 3 — `update.sh` stage 3 怎么知道 wrapper 已经 pull 过了

# update.sh stage 3 (Phase SM-L 02fcf2b 重构)
if [[ "${SM_UPDATE_WRAPPER:-0}" == "1" ]]; then
    echo "ℹ️  [stage 3/9] wrapper 已 git pull, 跳过"
    # 但 OLD/NEW_COMMIT 必须设, 避免后续 stage 误判
    OLD_COMMIT="$(git rev-parse HEAD 2>/dev/null || echo unknown)"
    NEW_COMMIT="$OLD_COMMIT"
    WRAPPER_DID_PULL=true
else
    # 原逻辑: cd && bash update.sh 调用方式 (向后兼容)
    if ! git pull --autostash; then
        echo "❌ git pull 失败"
        exit 1
    fi
    OLD_COMMIT="$(git rev-parse HEAD@{1})"
    NEW_COMMIT="$(git rev-parse HEAD)"
fi

关键洞察 7：`OLD_COMMIT` 和 `NEW_COMMIT` 必须在两条分支里都设。原逻辑用 `@{1}`（pull 前的 HEAD），wrapper 跳过分支必须用同一个 HEAD 设两边，否则后续 stage 4（依赖对比）会判断「代码没变 → 跳过依赖重装」但其实代码变了。

坑 4 — `progress_header_init` 在 PROGRESS=off 时的副作用

progress_header_init() {
    local total="${1:-1}"
    _HEADER_LABEL="${2:-执行中}"
    _HEADER_TOTAL=$total
    _HEADER_CURRENT=0
    _HEADER_START_TS=$(date +%s)        # ← 即使 PROGRESS=off 也会跑
    _HEADER_STAGE_START_TS=$_HEADER_START_TS
    _HEADER_LAST_PRINTED=-1
    _HEADER_LAST_ETA="--"
    _HEADER_DONE=false
    _HEADER_LINE1=""
    _HEADER_LINE2=""
    _progress_enabled || return 0       # ← 但渲染会跳过
    _progress_render_header 0 "初始化"
}

关键洞察 8：状态变量初始化必须无条件执行——`return 0` 只能跳过渲染，不能跳过 `_HEADER_TOTAL=$total` 这种状态赋值。否则 PROGRESS=off 下 `progress_header_advance` 会看到 `_HEADER_TOTAL=0` 算出 `pct=current*100/0` 是 divide-by-zero。

我加了一个守卫测试：

# tests/test_phase_sm_l_2_progress_header.py (excerpt)
def test_init_prog_off_no_render(capsys):
    """PROGRESS=off 时 init 不打印, 但 _HEADER_TOTAL 必须设"""
    with mock.patch.dict(os.environ, {"PROGRESS": "off"}):
        progress_header_init(9, "test")
    captured = capsys.readouterr()
    assert captured.out == ""
    assert _HEADER_TOTAL == 9  # ← 关键: 状态变量仍初始化

修复：13 commits + 28 tests + 1585 baseline

8/24-8/26 三天的 commit 链：

| 日期 | commit | 阶段 | 测试 |

|---|---|---|---|

| 8/24 19:14 | `7c53d23` | SM-I diag_all.sh 一键聚合 25+ diag | +1 |

| 8/24 23:05 | `70def41` | SM-L scripts/sm-update + install wrapper (1/3) | +4 |

| 8/24 23:06 | `02fcf2b` | SM-L update.sh stage 3 检测 wrapper (2/3) | +2 |

| 8/24 23:07 | `fcf8fd3` | SM-L 部署机 SOP §0 + sm-update.md (3/3) | (doc) |

| 8/25 01:02 | `252ffc4` | SM-M sm-admin / sm-cli wrapper 修复 | +5 |

| 8/25 01:02 | `e53fa18` | SM-M 弃用 BASH_SOURCE 约束 | (守卫更新) |

| 8/26 08:43 | `a2ec469` | SM-L.2 Sticky Header 总进度条 | +17 |

新增测试：

tests/test_phase_sm_l_update_wrapper.py         161 lines   4 passed
tests/test_phase_sm_l_update_sh_stage3.py       63 lines    2 passed
tests/test_phase_sm_m_admin_cli_wrappers.py    185 lines    5 passed
tests/test_phase_sm_l_2_progress_header.py     374 lines   17 passed
                                                  ────────────────────
                                                  28 passed

dev box 实测（我刚才跑的）：

$ .venv/bin/pytest tests/test_phase_sm_l_*.py \
                   tests/test_phase_sm_m_*.py --no-header -q
............................                                                  [100%]
28 passed in 15.61s
$ .venv/bin/pytest --no-header -q --ignore=tests/test_doc_sync.py
............................................................................. [100%]
1585 passed in 180.39s (0:03:00)

部署机一键命令：

# 首次安装 wrapper
sudo bash scripts/install-sm-update.sh
# 之后一行更新
sudo sm-update

跑出来（TTY 模式，部署机用户视角）：

🔄 [sm-update] git pull 最新代码...
   Already up to date.
🚀 [sm-update] exec update.sh...
▶ security-monitor 更新 [██░░░░░░░░░░░░░░] 11% (1/9) ETA -- — 拉取新代码
↳ [████░░░░░░░░░░░░] 1/5 20% git pull autostash
▶ security-monitor 更新 [████░░░░░░░░░░░░] 22% (2/9) ETA 2m30s — 安装依赖
↳ [████████░░░░░░░░░] 4/10 40% pip install -r requirements.txt
▶ security-monitor 更新 [██████░░░░░░░░░░] 33% (3/9) ETA 2m48s — 更新 systemd units
↳ [████████████░░░░░] 6/10 60% install_units
... (8 个阶段跳到 100%)
✅ [sm-update] 全部完成, 耗时 6m42s

关键洞察 9：ETA 在第 1 阶段显示 `--`（没样本），第 2 阶段显示 `2m30s`（基于阶段 1 已用时 × 8），第 3 阶段后开始用加权平均。用户看到 ETA 永远在更新，焦虑感比「黑屏 6 分钟」少 60%——这是我 8/26 跑完整链路最直观的体感。

反思：3 个反直觉发现 + 类教训沉淀

反直觉 1 — 「自己改自己」的脚本必须用 exec，不能用 source/fork

最初我想用 `bash -c "cd $SM_HOME && bash update.sh"`（fork 子 shell），看似干净，但有两个问题：

1. 子 shell 里 `update.sh` 的 trap / signal 不传到 wrapper，`Ctrl+C` 杀 wrapper 不杀 update.sh

2. 如果 `update.sh` 在 `git pull` 过程中被自己改了（比如 SM-L 后续某个 commit 改 update.sh），子 shell 已经在执行的 update.sh 是老的内存版本，新代码不生效

修复：`exec bash update.sh "$@"` 替换当前进程——wrapper 让位给 update.sh，trap / signal 全部传过去，update.sh 用 `date +%s` 时加载的也是最新磁盘版本。

教训：任何「自己改自己 + 自己执行」的脚本，必须用 `exec`——这是 bash 的硬性约束，不是代码风格偏好。

反直觉 2 — wrapper 的「单一真相源」必须在仓库里，不能在 install.sh 里

我之前在 `install.sh` 用 heredoc 内嵌 wrapper 是因为「wrapper 简单、几行就完事」。但 6 月到 8 月改了 5 次 wrapper，每次 install.sh 没同步——部署机用户永远用着 5 个月前的 wrapper。

修复：`scripts/sm-admin` / `scripts/sm-cli` 拆成独立文件，跟 `scripts/sm-update` 一个目录，`install.sh` 直接 `install -m 0755 scripts/sm-X /usr/local/bin/sm-X`。仓库改了 wrapper → install.sh pull 之后自动用新版本。

类教训 11 闭环（汇报失真）：从「诊断脚本同步」升级到「架构上消除漂移」——不是「我手动记得改 install.sh」，而是「让 install.sh 不可能跟 wrapper 不同步」。

反直觉 3 — Sticky Header 必须双模式（TTY / 非 TTY），不能假设只有一种

我最初只写了 TTY 模式（ANSI 光标控制两行重绘），跑了一次 `sudo sm-update >> /var/log/sm-update.log 2>&1`（部署机实际场景）—— 日志里全是 `[2K[1A[2K[1A` 这种乱码，比之前的单阶段 [STEP X/9] 还难看。

修复：检测 `[[ -t 1 ]]`（stdout 是不是 TTY）：

- TTY：ANSI 光标控制 + 颜色，单行重绘

- 非 TTY：降级为前缀 log 行 `[YYYY-MM-DD HH:MM:SS] [TOTAL X/N NN%] ETA ...`

- `PROGRESS=off`：完全静默

教训：任何交互式 UI 必须先想「它被管道 / log 文件 / systemd journal 捕获时怎么退化」——光标控制 + 颜色在非 TTY 是 anti-pattern，比不显示还差。

类教训沉淀（5 条）：

1. 类教训 11 闭环（汇报失真）：从「手动同步」升级到「架构上不可能漂移」——install.sh install 仓库里的 wrapper 文件，不 heredoc 内嵌。

2. 类教训 24（SOP 一页纸）：部署机 SOP §0 加 `sudo sm-update` 一行入口，旧方式 `cd && bash update.sh` 保留作兼容。

3. 类教训 47（跨 phase 完整链路）：SM-L (1/3 + 2/3 + 3/3) → SM-M (修复 + 守卫) → SM-L.2 (sticky header) = 3 个 phase、13 个 commit、28 个测试的完整 arc，不是单 commit 拼凑。

4. 类教训 48（自己改自己必须 exec）：`exec bash update.sh` 替换进程，让 trap / signal / 最新磁盘版本全部生效。

5. 类教训 49（交互式 UI 必须 TTY / 非 TTY 双模式）：光标控制在 log 文件里是乱码，PROGRESS=off 完全静默。

元信息

- Phase 链：SM-L (08-24 1/3 wrapper) → SM-L (08-24 2/3 stage 3 重构) → SM-L (08-24 3/3 docs) → SM-M (08-25 wrapper bug 修复) → SM-M (08-25 BASH_SOURCE 弃用) → SM-L.2 (08-26 sticky header 总进度)

- 钩子时间跨度：3 天 (2026-08-24 → 2026-08-26)

- commit 数：13（7 code + 4 test + 2 doc）

- 新增测试：28（4 wrapper + 2 stage3 + 5 admin-cli + 17 progress header）

- 全量回归：1585 passed (0 失败 / 0 错误 / 1 doc-sync 守卫为已知 commit 后自动过)

- 工程主题原型：#5 升级改造型（env var 化 / 重构 / schema 演进 → 这次是 wrapper + progress 架构级重构）

- 部署机一键命令：`sudo sm-update`（首次需 `sudo bash scripts/install-sm-update.sh`）

- 类教训新增：48（自己改自己必须 exec）、49（交互式 UI 必须双模式）

- 类教训闭环：11（架构级消除漂移）、24（SOP §0 一页纸）

本文为虚构故事，基于真实 security-monitor 项目的 Phase SM-L / SM-M / SM-L.2 修复链路创作，命令、错误信息、测试结果、commit hash 均为真实运行产出，部署机用户为化名。