Merge feature/deploy-config-rollback: 部署脚本把配置纳入回滚闭环

上一轮 446 次重启循环的根因不是代码，是 deploy.sh 把 config.yaml 当作部署范围之外的东西：健康检查失败后只回滚二进制，坏配置仍在，于是旧二进制照样解析不了，服务在 systemd 重启循环里空转。修法是把配置变成一等部署对象：--config 投放 + 重启前 -check 预检 + 回滚时二进制与配置一起恢复。预检位置比预检本身更重要——排在 restart 之前，坏配置才会在服务仍健康时被拦下。
2026-09-19 16:39:15 +00:00 · 2026-09-05 09:47:04 +08:00
parent ef92ce4d82 c524831616
commit 3cdb16c906
2 changed files with 176 additions and 13 deletions
--- a/cmd/llmsproxy/main.go
+++ b/cmd/llmsproxy/main.go
@ -23,8 +23,24 @@ import (

 func main() {
 	cfgPath := flag.String("config", "config.yaml", "path to gateway config file")
+	checkOnly := flag.Bool("check", false, "validate the config file and exit (0 = valid, 1 = invalid); nothing is started and no file is written")
 	flag.Parse()

+	// -check is the deploy-time preflight: parse and validate the config
+	// without starting the Lua VM, touching runtime.json, or binding a port.
+	// It deliberately does NOT call EnsureDefault, so a missing file is an
+	// error here instead of being silently created.
+	if *checkOnly {
+		if _, err := os.Stat(*cfgPath); err != nil {
+			log.Fatalf("[llmsproxy] check: %v", err)
+		}
+		if _, err := config.Load(*cfgPath); err != nil {
+			log.Fatalf("[llmsproxy] check: %v", err)
+		}
+		log.Printf("[llmsproxy] check: %s is valid", *cfgPath)
+		return
+	}
+
 	created, err := config.EnsureDefault(*cfgPath)
 	if err != nil {
 		log.Fatalf("[llmsproxy] config: %v", err)
--- a/deploy.sh
+++ b/deploy.sh
@ -10,6 +10,16 @@
 #   4. systemctl restart → 服务中断仅在 Go 进程重启瞬间 (<500ms)
 #   5. 健康检查确认新进程正常
 #
+# 配置文件（2026-09-05 起）：
+#   本脚本不再假设 config.yaml 与部署无关。实测教训：给源加 headers 时
+#   漏删原有的 `headers: {}` → YAML 重复键 → 进程启动即退出 → 健康检查
+#   失败 → 旧的 rollback 只恢复二进制，配置错误仍在，于是旧二进制也起不来，
+#   服务陷入 systemd 重启循环（当时累计 446 次）。
+#   因此：
+#   - 支持 --config <file> 投放一份待部署配置（原子 rename 到 TARGET_CONFIG）
+#   - 重启前先用新二进制 `-check` 预检配置，不合法就地失败，绝不重启服务
+#   - rollback 同时恢复二进制与配置文件，回滚后再次 -check 才重启
+#
 # 注意事项：
 #   - 本服务依赖自身（推理依赖），restart 前后会短暂中断，
 #     但重试机制（systemd RestartSec=5 + 客户端 retry）可自愈
@ -19,6 +29,7 @@ set -euo pipefail

 # ---------- 配置 ----------
 readonly TARGET_BIN="/usr/local/bin/llmsproxy"
+readonly TARGET_CONFIG="/etc/llmsproxy/config.yaml"
 readonly TARGET_ADAPTERS="/etc/llmsproxy/adapters"
 readonly REPO_DIR="/home/program/llmsproxy"
 readonly HEALTH_URL="http://127.0.0.1:8081/v1/models"
@ -28,8 +39,40 @@ readonly BIN_NAME="llmsproxy"
 readonly TMP_DIR="/tmp/llmsproxy-deploy"
 # 同文件系统暂存文件（用于原子 rename）
 readonly STAGING_BIN="${TARGET_BIN}.staging"
-# 回滚备份：健康检查失败时从这里恢复旧二进制
+readonly STAGING_CONFIG="${TARGET_CONFIG}.staging"
+# 回滚备份：健康检查失败时从这里恢复旧二进制 / 旧配置
 readonly BACKUP_BIN="${TARGET_BIN}.bak"
+readonly BACKUP_CONFIG="${TARGET_CONFIG}.rollback.bak"
+
+# 待部署配置（--config <file> 指定；为空 = 不改动线上配置）
+NEW_CONFIG_SRC=""
+
+usage() {
+    cat <<'EOF'
+用法: ./deploy.sh [--config <file>]
+
+  --config <file>   投放这份配置到 /etc/llmsproxy/config.yaml（原子替换）。
+                    省略时不改动线上配置，只部署二进制与适配器。
+                    无论是否指定，重启前都会用新二进制 -check 预检线上配置。
+
+流程: 构建 → 适配器同步 → 备份(二进制+配置) → 原子替换 → 配置预检
+      → 重启 → 健康检查 → 失败则回滚(二进制+配置)并重启
+EOF
+}
+
+parse_args() {
+    while (( $# > 0 )); do
+        case "$1" in
+            --config)
+                [[ $# -ge 2 ]] || { echo "--config 需要一个文件参数" >&2; exit 2; }
+                NEW_CONFIG_SRC="$2"
+                shift 2
+                ;;
+            -h|--help) usage; exit 0 ;;
+            *) echo "未知参数: $1" >&2; usage; exit 2 ;;
+        esac
+    done
+}

 # ---------- 日志 ----------
 log()  { printf '\033[1;34m[%s]\033[0m %s\n' "$(date +%H:%M:%S)" "$*"; }
@ -40,7 +83,7 @@ fail() { err "$@"; exit 1; }
 # ---------- 清理 ----------
 cleanup() {
    log "清理临时文件"
-    rm -rf "$TMP_DIR" "$STAGING_BIN"
+    rm -rf "$TMP_DIR" "$STAGING_BIN" "$STAGING_CONFIG"
 }
 trap cleanup EXIT

@ -52,6 +95,18 @@ precheck() {
    command -v systemctl &>/dev/null || fail "未找到 systemctl"
    [[ $(id -u) -eq 0 ]] || fail "需要 root 权限"

+    if [[ -n "$NEW_CONFIG_SRC" ]]; then
+        [[ -f "$NEW_CONFIG_SRC" ]] || fail "待部署配置不存在: $NEW_CONFIG_SRC"
+        # 同一文件比对：--config 指向线上文件本身时没有"投放"动作可做，
+        # 但仍然会走重启前的 -check 预检。
+        if [[ "$(readlink -f "$NEW_CONFIG_SRC")" == "$(readlink -f "$TARGET_CONFIG" 2>/dev/null)" ]]; then
+            warn "--config 指向线上配置本身，跳过投放（仍会预检）"
+            NEW_CONFIG_SRC=""
+        else
+            log "待部署配置: $NEW_CONFIG_SRC → $TARGET_CONFIG"
+        fi
+    fi
+
    OLD_SIZE=$(stat -c%s "$TARGET_BIN" 2>/dev/null || echo 0)
    OLD_SHA256=$(sha256sum "$TARGET_BIN" 2>/dev/null | awk '{print $1}')

@ -59,8 +114,10 @@ precheck() {
    log "go: $(go version)"
 }

-# ---------- 备份旧二进制（用于回滚）----------
-backup_old_binary() {
+# ---------- 备份旧二进制 + 旧配置（用于回滚）----------
+# 配置也必须备份：启动失败常常是配置问题，只回滚二进制会让旧二进制
+# 继续吃坏配置，服务照样起不来。
+backup_old_state() {
    log "备份旧二进制到 $BACKUP_BIN"
    if [[ -f "$TARGET_BIN" ]]; then
        cp -f "$TARGET_BIN" "$BACKUP_BIN"
@ -68,6 +125,13 @@ backup_old_binary() {
    else
        warn "旧二进制不存在，跳过备份（无回滚点）"
    fi
+
+    if [[ -f "$TARGET_CONFIG" ]]; then
+        cp -f "$TARGET_CONFIG" "$BACKUP_CONFIG"
+        log "✓ 旧配置已备份到 $BACKUP_CONFIG (sha256=$(sha256sum "$BACKUP_CONFIG" | awk '{print $1}' | cut -c1-16))"
+    else
+        warn "线上配置不存在: $TARGET_CONFIG（首次部署？无配置回滚点）"
+    fi
 }

 # ---------- 构建 ----------
@ -89,8 +153,13 @@ build() {
    if [[ "$NEW_SIZE" -eq "$OLD_SIZE" ]]; then
        NEW_SHA256=$(sha256sum "$NEW_BIN" | awk '{print $1}')
        if [[ "$NEW_SHA256" == "$OLD_SHA256" ]]; then
-            warn "新二进制与旧版本完全一致（sha256 相同），跳过部署"
-            exit 0
+            # 二进制无变化。只有在同时也没有待部署配置时才能直接退出；
+            # 否则会造成“--config 指定了新配置却被静默丢弃”。
+            if [[ -z "$NEW_CONFIG_SRC" ]]; then
+                warn "新二进制与旧版本完全一致（sha256 相同）且无待部署配置，跳过部署"
+                exit 0
+            fi
+            log "二进制无变化（sha256 相同），但有待部署配置，继续"
        fi
    fi

@ -140,6 +209,41 @@ atomic_replace_binary() {
    log "✓ 二进制已原子替换 (sha256=${NEW_SHA256:0:16})"
 }

+# ---------- 原子替换配置 ----------
+# 与二进制同一套 copy→rename 手法：先落到 /etc 上的 .staging，再 rename(2)。
+# 只有 --config 指定了来源时才动线上配置。
+atomic_replace_config() {
+    [[ -n "$NEW_CONFIG_SRC" ]] || return 0
+
+    log "原子替换配置"
+    log "  copy → $STAGING_CONFIG (同文件系统暂存)"
+    cp -f "$NEW_CONFIG_SRC" "$STAGING_CONFIG"
+    chmod 0644 "$STAGING_CONFIG"
+
+    log "  rename → $TARGET_CONFIG (原子)"
+    mv -f "$STAGING_CONFIG" "$TARGET_CONFIG"
+    log "✓ 配置已原子替换 (sha256=$(sha256sum "$TARGET_CONFIG" | awk '{print $1}' | cut -c1-16))"
+}
+
+# ---------- 配置预检 ----------
+# 用刚部署的新二进制解析线上配置。`-check` 只做 parse + ApplyDefaults，
+# 不启动 Lua VM、不碰 runtime.json、不绑端口，因此可以安全地在服务仍在
+# 运行时执行。不合法就在重启前失败——这正是上次事故缺的那一步。
+verify_config() {
+    log "配置预检（新二进制 -check）"
+    [[ -f "$TARGET_CONFIG" ]] || fail "线上配置不存在: $TARGET_CONFIG"
+
+    local out
+    if out=$("$TARGET_BIN" -check -config "$TARGET_CONFIG" 2>&1); then
+        log "✓ 配置合法"
+        return 0
+    fi
+
+    err "配置预检失败，未重启服务（线上进程仍在跑旧配置）："
+    printf '%s\n' "$out" >&2
+    return 1
+}
+
 # ---------- 同步适配器 ----------
 sync_adapters() {
    log "同步适配器"
@ -206,20 +310,49 @@ healthcheck() {
 }

 # ---------- 回滚 ----------
-# 健康检查失败时恢复旧二进制并重启，保证推理服务可用。
+# 健康检查失败时恢复旧二进制**和旧配置**并重启，保证推理服务可用。
 # 这是最后一道保险：即使新版本启动失败（编译错误、配置不兼容、
 # panic on start 等），也能让旧版本继续服务，避免推理能力丢失。
+#
+# 为什么必须一并回滚配置：启动失败最常见的原因就是配置本身不合法
+# （实测：YAML 重复键）。只恢复二进制的话，旧二进制照样解析不了坏配置，
+# 服务继续在 systemd 重启循环里空转。
 rollback() {
    err "健康检查失败，启动回滚流程"
-    if [[ ! -f "$BACKUP_BIN" ]]; then
-        err "无回滚备份 ($BACKUP_BIN 不存在)，无法自动恢复"
+
+    local restored_any=0
+    if [[ -f "$BACKUP_BIN" ]]; then
+        log "恢复旧二进制"
+        cp -f "$BACKUP_BIN" "$TARGET_BIN"
+        chmod 0755 "$TARGET_BIN"
+        restored_any=1
+    else
+        err "无二进制回滚备份 ($BACKUP_BIN 不存在)"
+    fi
+
+    # 只在本次真的换过配置时才回滚配置，避免把用户在部署期间
+    # 通过 WebUI 做的合法改动一起抹掉。
+    if [[ -n "$NEW_CONFIG_SRC" && -f "$BACKUP_CONFIG" ]]; then
+        log "恢复旧配置"
+        cp -f "$BACKUP_CONFIG" "$TARGET_CONFIG"
+        chmod 0644 "$TARGET_CONFIG"
+        restored_any=1
+    fi
+
+    if (( restored_any == 0 )); then
+        err "无任何回滚点，无法自动恢复"
        err "请手动检查: systemctl status llmsproxy.service && journalctl -u llmsproxy -n 50"
        return 1
    fi

-    log "恢复旧二进制"
-    cp -f "$BACKUP_BIN" "$TARGET_BIN"
-    chmod 0755 "$TARGET_BIN"
+    # 回滚后先验证恢复出来的组合真的能解析，再重启——否则只是把
+    # 重启循环换个二进制继续跑。
+    if ! "$TARGET_BIN" -check -config "$TARGET_CONFIG" >/dev/null 2>&1; then
+        err "回滚后的配置仍不合法，拒绝重启（避免 systemd 重启风暴）"
+        err "  手动修复 $TARGET_CONFIG 后执行: $TARGET_BIN -check -config $TARGET_CONFIG"
+        err "  备份可用: 二进制=$BACKUP_BIN 配置=$BACKUP_CONFIG"
+        return 1
+    fi

    log "重启服务（旧版本）"
    systemctl restart llmsproxy.service || {
@ -248,18 +381,32 @@ print_summary() {
    log "═════════════════════════════════════════════"
    log "部署完成"
    log "  二进制: $TARGET_BIN"
+    log "  配置:   $TARGET_CONFIG$([[ -n "$NEW_CONFIG_SRC" ]] && echo "  (本次已替换)" || echo "  (未改动)")"
    log "  适配器: $TARGET_ADAPTERS"
    log "═════════════════════════════════════════════"
 }

 # ---------- 主流程 ----------
+# 顺序要点：配置投放与预检都排在 restart_service **之前**，
+# 于是坏配置在服务仍然健康时就被拦下，根本不会触发重启。
 main() {
+    parse_args "$@"
    log "═══ llmsproxy 原子部署开始 ═══"
    precheck
    build
    sync_adapters
-    backup_old_binary
+    backup_old_state
    atomic_replace_binary
+    atomic_replace_config
+    if ! verify_config; then
+        # 配置不合法：服务还没重启，只需把二进制/配置退回原状。
+        err "配置预检失败，回退本次改动（服务未受影响）"
+        [[ -f "$BACKUP_BIN" ]] && cp -f "$BACKUP_BIN" "$TARGET_BIN" && chmod 0755 "$TARGET_BIN"
+        if [[ -n "$NEW_CONFIG_SRC" && -f "$BACKUP_CONFIG" ]]; then
+            cp -f "$BACKUP_CONFIG" "$TARGET_CONFIG" && chmod 0644 "$TARGET_CONFIG"
+        fi
+        exit 1
+    fi
    restart_service
    if ! healthcheck; then
        rollback || true