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
2026-10-01 12:08:05 +08:00
parent ebc851b12b
commit eaec032f5c
1 changed files with 37 additions and 0 deletions
@@ -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 部署。