From 1bd48215389d82867ae5a4fc990196685d7c3fe5 Mon Sep 17 00:00:00 2001 From: YokiiroBW Date: Mon, 27 Jul 2026 05:42:03 +0800 Subject: [PATCH] chore: script the deployment discipline There was no shell script anywhere in either repo, so every deployment was typed by hand and every deployment re-exposed the same pitfalls: rollback copies left in the plugin scan directory, wrong ownership, stale pycache, deploying the companion before memory, and a rollback pointer left aimed at an older backup. ops/deploy-plugin.sh fixes the order: local test gate, remote backup with the LATEST_M6 pointer updated, stop, memory before companion (the companion probes the memory bridge at startup and caches a negative result if the peer is absent), ownership and modes, a scan-directory residue check that exits non-zero on any .old/.new/.bak, remote compileall with PYTHONPYCACHEPREFIX, start, then verification of service state and plugin-level error count. The ownership rule was documented two ways -- root:root in the errata, astrbot:astrbot in the M6.1.8 record. The service runs as User=astrbot, so astrbot:astrbot is correct and the script now says so in a comment. Also noted, in the script and the errata: QQ's official platform rate-limits bot session starts, and restarting eight times within an hour made the qq_official adapter fail to log in. Batch deployments should batch restarts. Co-Authored-By: Claude Opus 5 --- docs/运维陪伴错题本.md | 11 +++ ops/deploy-plugin.sh | 150 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 161 insertions(+) create mode 100644 ops/deploy-plugin.sh diff --git a/docs/运维陪伴错题本.md b/docs/运维陪伴错题本.md index 925199d..29dc64b 100644 --- a/docs/运维陪伴错题本.md +++ b/docs/运维陪伴错题本.md @@ -611,3 +611,14 @@ docs\运维陪伴错题本.md - 修复或规避:三条防线各管一段。①去掉六处的 `group_mode` 门控——清理是临时文件的生命周期,不是群聊功能的一部分;②forward 侧拆出内层函数、外层 `try/finally` 收口,正常与异常路径都清;③**准备新图之前先按存活时长清扫该 namespace**(`PREPARED_IMAGE_MAX_AGE_SECONDS = 30 分钟`),这一条不依赖任何一条 return 走到,覆盖异常与取消。没有采用「把 260 行函数整体包进 try/finally」的方案:那需要整体改缩进,风险大于收益,而按时长清扫对取消路径的覆盖反而更彻底。 - 预防规则:临时资源的释放要绑在申请点的同一个作用域(`try/finally`),不能散落在下游各个 return 分支。只要清理逻辑出现在 `if <业务条件>:` 里面,就该警觉——释放不该有业务条件。此外,凡是可能被 `wait_for` 取消的协程,`except Exception` 都不算兜底,必须另有一条不依赖控制流的回收路径。 - 验证证据:`tests/test_b7_image_temp_files.py` 8 项(按时长清扫、准备时先清扫、清理点不再被门控、forward 侧正常/异常/取消三条路径都清理)。全量 243 项通过;联合 E2E 146/146。 + +## 2026-07-27 — 部署纪律固化成脚本,顺带定死属主规则的冲突 + +- 阶段:P5 部署可重复性 +- 类型:部署 / 环境 +- 现象:仓库里没有任何 `.sh`/`.ps1`,每次部署都是手打命令,于是每次都在重新暴露同一批历史问题(回滚副本落在扫描目录、属主权限、旧 pycache、部署顺序、备份指针没更新)。更麻烦的是属主规则本身两处冲突:本错题本早期写 `root:root`,M6.1.8 记录写 `astrbot:astrbot`,脚本化之前必须先定一个。 +- 根因:纪律只写在文档里,执行靠人记。文档条目一多,执行时就会漏掉其中一两条,而漏掉哪一条每次都不一样。 +- 修复或规避:新增 `ops/deploy-plugin.sh`,把顺序写死:本地测试门禁 → 远端备份并更新 `LATEST_M6` 指针 → 停服 → **记忆先于陪伴**(陪伴启动时会探测记忆插件的桥,对端不在会落进负缓存)→ 属主 `astrbot:astrbot`、目录 0755、文件 0644 → 扫描目录残留检查(`.old`/`.new`/`.bak` 一律报错退出)→ 远端 compileall(带 `PYTHONPYCACHEPREFIX`)→ 启动 → 验证服务与插件级错误数。属主之争按实机与 systemd 配置定案:服务以 `User=astrbot` 运行,因此是 `astrbot:astrbot`,错题本早期那条 `root:root` 是错的。 +- 附带记录:QQ 官方平台对 bot 会话启动次数有限流,一小时内反复重启会让 `qq_official` 适配器登录失败(`self._ws_ap["session_start_limit"]` 为 None → `TypeError`)。这次连续 8 次重启后触发了一次。批量部署要合并重启次数,脚本末尾也写了这条提醒。 +- 预防规则:写进错题本的部署纪律,如果三次以上部署都要手动重复,就该固化成脚本。两份文档对同一条规则给出不同值时,以实机与服务配置为准,并在固化时把结论写进代码注释——否则下一次还会再争一遍。 +- 验证证据:`ops/deploy-plugin.sh`(`bash -n` 通过、参数校验与 both+文件列表的互斥校验实测生效)。 diff --git a/ops/deploy-plugin.sh b/ops/deploy-plugin.sh new file mode 100644 index 0000000..f07078f --- /dev/null +++ b/ops/deploy-plugin.sh @@ -0,0 +1,150 @@ +#!/usr/bin/env bash +# 双插件 VM 部署脚本。 +# +# 把错题本里逐条踩出来的部署纪律固化成步骤,避免每次部署重新暴露同一批历史问题: +# - 回滚副本留在插件扫描目录里 → AstrBot 当成插件去导入,启动日志出 ERRO +# - 属主/权限不对(0700)→ 服务读不到 main.py +# - 旧 pycache 权限 → compileall 误报 +# - 先部署陪伴后部署记忆 → 陪伴启动时对端不在,桥探测落进负缓存 +# - 备份指针不更新 → 回滚会把之后的真机修复一并抹掉 +# +# 用法: +# ops/deploy-plugin.sh [文件...] +# 不给文件 = 整目录替换;给文件 = 只替换这些文件(相对插件根目录) +# 环境变量 VM 指定目标主机,默认 astrbot-vm(需已配置 ssh 免密) +# +# 示例: +# ops/deploy-plugin.sh companion daily_state.py planning.py +# ops/deploy-plugin.sh both + +set -euo pipefail + +VM="${VM:-astrbot-vm}" +TARGET="${1:-}" +shift || true +FILES=("$@") + +# 本脚本随陪伴插件仓库走;两个插件仓库是项目根目录下的同级目录 +COMPANION_SRC="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +PROJECT_ROOT="$(cd "$COMPANION_SRC/.." && pwd)" +MEMORY_SRC="$PROJECT_ROOT/astrbot_plugin_memory_companion-main" +if [ ! -d "$MEMORY_SRC" ]; then + echo "错误: 找不到记忆插件仓库 $MEMORY_SRC(两个仓库应是项目根下的同级目录)" >&2 + exit 1 +fi + +PLUGIN_DIR=/var/lib/astrbot/data/plugins +BACKUP_ROOT=/var/lib/astrbot/ops-replace-backups +PY=/var/lib/astrbot/.local/share/uv/tools/astrbot/bin/python +# 服务以 astrbot 身份运行(systemd User=astrbot),所以属主必须是 astrbot:astrbot。 +# 错题本早期写过 root:root,那是错的——按实机与 systemd 配置为准。 +OWNER=astrbot:astrbot +STAMP="$(date +%Y%m%d-%H%M%S)" + +die() { echo "错误: $*" >&2; exit 1; } + +case "$TARGET" in + memory|companion|both) ;; + *) die "用法: $0 [文件...]" ;; +esac + +if [ "$TARGET" = both ] && [ ${#FILES[@]} -gt 0 ]; then + die "both 模式不接受文件列表:两个插件的文件名会混在一起" +fi + +echo "==> 目标主机 $VM 备份时间戳 $STAMP" + +# ---------- 1. 本地门禁:不让没通过测试的代码上机 ---------- +echo "==> 本地测试" +if [ "$TARGET" = companion ] || [ "$TARGET" = both ]; then + (cd "$COMPANION_SRC" && python -m pytest tests -q) || die "陪伴侧测试未通过" +fi +if [ "$TARGET" = memory ] || [ "$TARGET" = both ]; then + (cd "$MEMORY_SRC" && python -m pytest tests -q) || die "记忆侧测试未通过" +fi + +# ---------- 2. 远端备份,并把回滚指针指向这次 ---------- +BACKUP="$BACKUP_ROOT/deploy-$STAMP" +echo "==> 远端备份 $BACKUP" +ssh -o BatchMode=yes "$VM" "sudo mkdir -p '$BACKUP' +for name in astrbot_plugin_memory_companion_ops astrbot_plugin_private_companion_ops; do + sudo tar czf '$BACKUP'/plugin-\$name.tar.gz -C '$PLUGIN_DIR' \$name + sudo cp -r '$PLUGIN_DIR'/\$name '$BACKUP'/before-\$name +done +sudo cp /var/lib/astrbot/data/config/astrbot_plugin_*_ops_config.json '$BACKUP'/ 2>/dev/null || true +# 回滚副本一律落在备份区,绝不留在插件扫描目录里 +echo '$BACKUP' | sudo tee '$BACKUP_ROOT/LATEST_M6' >/dev/null" + +push_one() { + local src="$1" name="$2" + local dest="$PLUGIN_DIR/$name" + if [ ${#FILES[@]} -eq 0 ]; then + echo "==> 整目录替换 $name" + tar czf - -C "$src" --exclude=__pycache__ --exclude=.git --exclude=.tmp . \ + | ssh -o BatchMode=yes "$VM" "cat > /tmp/$name.tar.gz" + ssh -o BatchMode=yes "$VM" "sudo rm -rf '$dest' && sudo mkdir -p '$dest' \ + && sudo tar xzf /tmp/$name.tar.gz -C '$dest' && rm -f /tmp/$name.tar.gz" + else + echo "==> 增量替换 $name: ${FILES[*]}" + for f in "${FILES[@]}"; do + [ -f "$src/$f" ] || die "本地不存在: $src/$f" + scp -q "$src/$f" "$VM:/tmp/$(basename "$f")" + ssh -o BatchMode=yes "$VM" "sudo mkdir -p \"\$(dirname '$dest/$f')\" \ + && sudo cp '/tmp/$(basename "$f")' '$dest/$f' && rm -f '/tmp/$(basename "$f")'" + done + fi + ssh -o BatchMode=yes "$VM" "sudo chown -R $OWNER '$dest' +sudo find '$dest' -type d -exec chmod 755 {} + +sudo find '$dest' -type f -exec chmod 644 {} + +# 扫描目录里不允许留任何非插件目录(.old/.new/.bak 会被当成插件导入) +leftovers=\$(sudo find '$PLUGIN_DIR' -maxdepth 1 -name '*.old' -o -maxdepth 1 -name '*.new' -o -maxdepth 1 -name '*.bak' | head) +if [ -n \"\$leftovers\" ]; then echo \"错误: 插件扫描目录残留 \$leftovers\" >&2; exit 1; fi +# PYTHONPYCACHEPREFIX 避开旧 pycache 的权限问题 +sudo -u astrbot env PYTHONPYCACHEPREFIX=/tmp/pycache-deploy '$PY' -m compileall -q '$dest' >/dev/null \ + || { echo '错误: 远端 compileall 未通过' >&2; exit 1; }" +} + +# ---------- 3. 停服 → 记忆先于陪伴 → 启动 ---------- +echo "==> 停服" +ssh -o BatchMode=yes "$VM" "sudo systemctl stop astrbot" + +# 顺序有讲究:陪伴启动时会探测记忆插件的桥,对端不在会落进负缓存 +if [ "$TARGET" = memory ] || [ "$TARGET" = both ]; then + push_one "$MEMORY_SRC" astrbot_plugin_memory_companion_ops +fi +if [ "$TARGET" = companion ] || [ "$TARGET" = both ]; then + push_one "$COMPANION_SRC" astrbot_plugin_private_companion_ops +fi + +echo "==> 启动" +ssh -o BatchMode=yes "$VM" "sudo systemctl start astrbot" +sleep 60 + +# ---------- 4. 验证 ---------- +echo "==> 验证" +ssh -o BatchMode=yes "$VM" ' +state=$(systemctl is-active astrbot) +restarts=$(systemctl show astrbot -p NRestarts --value) +echo "服务: $state NRestarts=$restarts" +[ "$state" = active ] || exit 1 +plugin_errors=$(sudo journalctl -u astrbot --since "3 min ago" --no-pager 2>/dev/null \ + | grep -E "ERRO|Traceback" | grep -ci companion || true) +echo "插件相关错误: $plugin_errors" +sudo journalctl -u astrbot --since "3 min ago" --no-pager 2>/dev/null \ + | grep -E "Loading plugin astrbot_plugin_(memory|private)_companion_ops" || true +[ "$plugin_errors" = "0" ] || { echo "存在插件错误,考虑回滚" >&2; exit 1; }' + +cat < 完成。回滚: + BK=\$(sudo cat $BACKUP_ROOT/LATEST_M6) + sudo systemctl stop astrbot + sudo rm -rf $PLUGIN_DIR/astrbot_plugin_{memory,private}_companion_ops + sudo cp -r "\$BK/before-astrbot_plugin_memory_companion_ops" $PLUGIN_DIR/astrbot_plugin_memory_companion_ops + sudo cp -r "\$BK/before-astrbot_plugin_private_companion_ops" $PLUGIN_DIR/astrbot_plugin_private_companion_ops + sudo chown -R $OWNER $PLUGIN_DIR/astrbot_plugin_{memory,private}_companion_ops + sudo systemctl start astrbot + +注意:QQ 官方平台对会话启动次数有限流,短时间内反复重启会让 qq_official +适配器登录失败(session_start_limit 为 None)。批量部署时请合并重启次数。 +MSG