fix(deploy): retain the active release when rollback failsHEADmain

[Problem]
- Failed rollback could delete a directory still used by current.

[Root Cause]
- Failure cleanup did not check the active symlink target.

[Solution]
- Preserve release directories still referenced by current.
- Document the self-hosted publishing and manual rollback procedure.

[Impact]
- Blog deployment cleanup is safer; article content remains unchanged.

2 files changed, 51 insertions, 2 deletions

diff --git a/deploy/README.md b/deploy/README.md
new file mode 100644
index 00000000..3f9821af
--- /dev/null
+++ b/deploy/README.md
@@ -0,0 +1,39 @@
+# 博客部署
+
+博客：https://blog.somhairle.bid/
+源码：https://git.somhairle.bid/blog.git/
+历史归档：https://github.com/i-shm/blog-archive
+
+## 日常发布
+
+工作区为 `/home/somhairle/projects/blog`。文章放在 `source/_posts/`，配图放在 `source/img/`。提交到 main 后执行 `git push origin main`。
+
+本机 origin 的读取地址为 HTTPS，pushurl 为 `/home/somhairle/git/blog.git`，使用本机文件权限推送。外部 HTTPS 写入需要现有 Git 服务认证；匿名 POST 被拒绝。未将任何认证信息写入仓库。
+
+裸仓库 post-receive 写入 `deploy.signal`，`blog-deploy.path` 触发 `blog-deploy.service`。构建从 main 读取源码，以 `/home/somhairle/.hermes/node/bin` 中的 Node/npm 运行 Hexo。成功后原子切换 releases/current，保留最近五个发布目录。构建错误和日志中的 ERROR/FATAL/CoercionError 会阻止发布。
+
+## 部署文件
+
+- `scripts/build.sh` 对应 `/home/somhairle/blog-deploy/scripts/build.sh`。
+- `git-hook/post-receive` 对应 `/home/somhairle/git/blog.git/hooks/post-receive`，需要可执行权限。
+- `systemd/` 中两个 unit 安装到 `~/.config/systemd/user/`；执行 `systemctl --user daemon-reload` 和 `systemctl --user enable --now blog-deploy.path`。
+- Compose 与 nginx 配置安装到 `/home/somhairle/blog-deploy/`，以 `docker compose up -d` 启动。容器只监听 `127.0.0.1:8091`，只读挂载 releases 父目录，current 使用相对软链接。
+- Cloudflare Tunnel 的 blog.somhairle.bid ingress 指向 `http://127.0.0.1:8091`；原配置备份在 `/home/somhairle/blog-deploy/config-backup/`。不要修改其他域名规则。
+
+## 验证
+
+检查 `systemctl --user status blog-deploy.service` 的退出码与日志；一次性服务执行完成后 inactive 属正常状态，path 单元应持续 active。查看 `/home/somhairle/blog-deploy/releases/current` 的软链接目标，对照 main 提交短哈希。构建日志位于 `/home/somhairle/blog-deploy/logs/`。
+
+在公网打开首页、具体文章及图片，核对实际正文和图片加载。不要只依据构建成功判断上线。
+
+迁移时已验证 main push 自动触发构建并发布；注入 CoercionError 后构建退出1且 current 不变。178 篇文章、266 个 source 文件迁移前后哈希一致。浏览器已核对最新日记原文及月亮图片。
+
+## 手动回滚
+
+暂停 `blog-deploy.path`，等待正在运行的 blog-deploy.service 完成。对 `/home/somhairle/blog-deploy/work/build.lock` 取得排他锁后，在 releases 内选择已确认完整的旧 `v-*` 目录，创建指向该目录名的相对临时软链接，然后使用原子 rename 替换 current。不要删除当前链接仍指向的目录。公网验证后重新启用 path。
+
+回滚仅切换网站版本，main 源码不会倒退。下一次推送会再次发布 main；若要长期恢复旧内容，应另行提交 revert。未提供自动回滚脚本。
+
+## GitHub 归档
+
+原 GitHub 仓库已改名为 blog-archive 并设为只读归档，Pages 工作流停用，旧 i-shm.github.io 首页返回404。GitHub Pages DELETE API 返回422，站点配置元数据仍存在，不能将此状态描述为 API 删除成功。生产发布不再依赖 GitHub。
diff --git a/deploy/scripts/build.sh b/deploy/scripts/build.sh
index b76d6ec0..e598700a 100755
--- a/deploy/scripts/build.sh
+++ b/deploy/scripts/build.sh
@@ -113,12 +113,22 @@ while :; do
               && echo "rolled back to $prev" >> "$LOG" \
               || echo "ROLLBACK FAILED: current -> $DEST_NAME stays" >> "$LOG"
           fi
-          rm -rf -- "$RELEASES/$DEST_NAME"
+          live=$(readlink "$RELEASES/current" 2>/dev/null || true)
+          if [ "$live" != "$DEST_NAME" ]; then
+            rm -rf -- "$RELEASES/$DEST_NAME"
+          else
+            echo "kept $DEST_NAME: current still points at it" >> "$LOG"
+          fi
           RC_LAST=1
         fi
       fi
       if [ "$OK" -eq 0 ]; then
-        rm -rf -- "$RELEASES/$DEST_NAME"
+        live=$(readlink "$RELEASES/current" 2>/dev/null || true)
+        if [ "$live" != "$DEST_NAME" ]; then
+          rm -rf -- "$RELEASES/$DEST_NAME"
+        else
+          echo "kept $DEST_NAME: current still points at it" >> "$LOG"
+        fi
         echo "==== build $TS FAILED at publish, previous release kept ====" >> "$LOG"
         RC_LAST=1
       fi