diff --git a/.gitea/workflows/deploy.yml b/.gitea/workflows/deploy.yml
index 98457548..94a2df11 100644
--- a/.gitea/workflows/deploy.yml
+++ b/.gitea/workflows/deploy.yml
@@ -1,17 +1,45 @@
 name: Deploy Docker Image
 
 on:
-  workflow_dispatch
+  # 自动触发：build-image workflow 成功完成后跑
+  # workflow_run 是 cross-workflow 依赖：build 成功 → deploy 自动跟上
+  workflow_run:
+    workflows: ["Build Docker Image"]
+    types: [completed]
+    branches: [custom]
+  # 手动触发：保留作为应急通道（重新部署当前镜像 / 跑临时脚本）
+  workflow_dispatch:
 
 jobs:
-  build:
+  deploy:
     runs-on: ubuntu-latest
+    # 只在 build 成功后跑；手动触发时 workflow_run 字段不存在，
+    # || true 保证手动跑也能继续
+    if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
     steps:
       - name: Execute custom script
+        # 用 > 覆盖而不是 >> 追加，避免历史脚本累积
         run: |
-          cat >> deploy.sh <<EOF
+          cat > deploy.sh <<'EOF'
           #!/bin/sh
+          set -e
           ${{ vars.CUSTOM_DEPLOY_SCRIPTS }}
           EOF
           chmod +x deploy.sh
           ./deploy.sh
+
+      - name: Deploy summary
+        if: always()
+        run: |
+          {
+            echo "## Deploy Summary"
+            echo ""
+            echo "| 项 | 值 |"
+            echo "|---|---|"
+            echo "| 触发方式 | \`${{ github.event_name }}\` |"
+            if [ "${{ github.event_name }}" = "workflow_run" ]; then
+              echo "| 触发自 | \`${{ github.event.workflow_run.name }}\` run #${{ github.event.workflow_run.run_number }} |"
+              echo "| 上游 build 结果 | \`${{ github.event.workflow_run.conclusion }}\` |"
+              echo "| 上游 build commit | \`${{ github.event.workflow_run.head_sha }}\` |"
+            fi
+          } >> "$GITHUB_STEP_SUMMARY"
diff --git a/CLAUDE.md b/CLAUDE.md
index d8c885ac..31684630 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -57,7 +57,7 @@ git.zhengchentao.win/dev/ezbookkeeping     （origin，本地唯一 remote）
 |---|---|---|---|
 | `sync-upstream.yml` | 手动（`workflow_dispatch`，可填 tag） | 服务端把 `dev/main` 强制 reset 到 mirror 上的指定 release tag（默认最新），然后 `push --force-with-lease` + 推 tags | ✅ 在用 |
 | `build-image.yml` | **自动**（push 到 custom 触发，`paths-ignore` 屏蔽 `**.md` / `.gitignore` / `LICENSE` / `screenshot/**`）+ 手动备选 | checkout 触发分支（push 时即 custom；手动时用 `inputs.branch` 默认 custom）→ 装 buildkit v0.13.2（钉版本）→ 登录 Gitea registry → 构建镜像（带 OCI 标签 source/revision，Gitea 自动关联包到 repo）→ push 到 `git.zhengchentao.win/dev/ezbookkeeping:<hash>` 与 `:latest`，`build-args: BUILD_PIPELINE=1` 跳过活 API 测试 | ✅ 在用，是日常发布通道 |
-| `deploy.yml` | 手动 | 跑 repo Variables 里 `CUSTOM_DEPLOY_SCRIPTS` 这条自定义脚本（通用钩子，可拼"build 完触发 NAS 端 docker compose pull/up"等） | 🟡 通用钩子，按需配 |
+| `deploy.yml` | **自动**（`workflow_run` 在 build-image 成功后跑）+ 手动备选 | 跑 repo Variables 里 `CUSTOM_DEPLOY_SCRIPTS` 这条自定义脚本，含 `set -e` 失败即停 | ✅ 自动 CD，需要先在 Gitea repo 设置 → Actions → Variables 里配 `CUSTOM_DEPLOY_SCRIPTS` 才有实际效果 |
 
 **已删**：`docker-snapshot.yml`（push main 自动触发，未配 secrets.DOCKER_REPO 永远失败）、`docker-release.yml`（push tag 同样问题）。需要时再从 git 历史 cherry-pick 回来。
 
@@ -71,13 +71,14 @@ git.zhengchentao.win/dev/ezbookkeeping     （origin，本地唯一 remote）
 4. 解冲突（如有）→ 验证 → `git push --force-with-lease origin custom`
 5. **build-image workflow 自动触发**（force-push 也算 push 事件），构建新镜像；不需要手动点
 
-日常 feature commit 流程：
+日常 feature commit 流程（全自动 CD）：
 
 1. 在 custom 上改代码 → commit → push
-2. **自动触发 build**（除非只改了 `**.md` / `.gitignore` / `LICENSE` / `screenshot/**`）
-3. NAS 上 `docker compose pull && docker compose up -d` 拉新镜像
+2. **自动触发 build**（除非只改了 `**.md` / `.gitengine` / `LICENSE` / `screenshot/**`）
+3. build 成功 → **自动触发 deploy**（跑 repo Variables 里的 `CUSTOM_DEPLOY_SCRIPTS`）
+4. 整条 push → build → deploy 链路无人工介入
 
-如果想跳过 build（例如手动多次 push 调试），commit 时只改文档相关文件即可（落在 paths-ignore 范围内）。如果想强制重打某个旧 commit，去 Actions UI 手动触发 `Build Docker Image`，填要打包的 branch / tag。
+如果想跳过 build/deploy（例如手动多次 push 调试），commit 时只改文档相关文件即可（落在 paths-ignore 范围内）。如果想强制重打某个旧 commit，去 Actions UI 手动触发 `Build Docker Image`，填要打包的 branch / tag。如果想只重新部署当前镜像（不重新 build），手动触发 `Deploy Docker Image` workflow。
 
 **为什么 rebase 不 merge**：个人项目，无团队协作语义要保留，线性历史更清爽。