From eaec032f5c27f5e48b589943a3a4cccb0193a6d5 Mon Sep 17 00:00:00 2001
From: xiaoxia <dev@xiaoxiajianji.com>
Date: Thu, 1 Oct 2026 12:08:05 +0800
Subject: [PATCH] docs: add Docker credential and Watchtower configuration to
 DEPLOYMENT.md

- Document staging server docker credential setup for ACR and Gitea registry
- Add Watchtower container configuration details
- Document image tag strategy (commit SHA + dev stable tag)
- Include server migration recovery steps
---
 docs/DEPLOYMENT.md | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md
index 649d7217e..6ef2899d3 100644
--- a/docs/DEPLOYMENT.md
+++ b/docs/DEPLOYMENT.md
@@ -104,6 +104,43 @@ Staging 当前可以保持 no-op；Production 开启前必须先验证 SMTP/Redi
 
 ---
 
+## Staging 服务器 Docker 凭证配置
+
+Staging 服务器（116.62.226.203）需要配置 ACR 和 Gitea Registry 凭证，否则 docker pull 和 Watchtower 自动更新会失败。
+
+### 凭证文件位置
+- Docker 配置文件：`/root/.docker/config.json`
+- 包含两个 registry 的认证信息：
+  - `xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com`（阿里云 ACR）
+  - `git.xiaoxiajianji.com`（Gitea 容器镜像仓库）
+
+### 服务器迁移后恢复步骤
+```bash
+# 1. 登录 ACR
+docker login xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com -u <ACR_USERNAME>
+
+# 2. 登录 Gitea Registry
+docker login git.xiaoxiajianji.com -u xiaoxia -p <GITEA_REGISTRY_TOKEN>
+
+# 3. 重启 Watchtower（确保挂载最新 config.json）
+docker restart watchtower
+```
+
+### Watchtower 配置
+- 容器名：`watchtower`
+- 检查间隔：300 秒（5 分钟）
+- 监控容器：`xiaoxia-api-staging`、`xiaoxia-worker-staging`、`xiaoxia-web-staging`
+- 必须挂载 `-v /root/.docker/config.json:/config.json` 才能拉取私有镜像
+- 必须挂载 `-v /var/run/docker.sock:/var/run/docker.sock` 才能管理容器
+- 容器使用 `:dev` 稳定 tag，Watchtower 通过检测 `:dev` tag 的 digest 变化来发现更新
+
+### 镜像 Tag 策略
+- CI 每次构建推送三种 tag：`${GITHUB_SHA}`（精确版本）、`${GITHUB_REF_NAME}`（分支名）、`:dev`（滚动 tag，仅 develop 分支）
+- Staging 容器统一使用 `:dev` tag 启动，确保 Watchtower 能自动发现新版本
+- Migration（alembic）使用 commit SHA tag 执行，不依赖 Watchtower
+
+---
+
 ## Gitea Actions 约定
 
 - `develop` 分支触发 staging 部署。