部署优化

2026-06-13 22:16:14 +08:00
parent 21dd9957f0
commit 73a94e6be3
28 changed files with 899 additions and 129 deletions
--- a/docs/Docker部署指南.md
+++ b/docs/Docker部署指南.md
@@ -10,8 +10,9 @@

 ```text
 浏览器
-  ├─ :8082  player (Nginx) ── /api、/uploads ──► api (NestJS :3000)
-  └─ :8081  admin  (Nginx) ── /api ────────────► api (NestJS :3000)
+  └─ 宝塔/Nginx HTTPS 反代
+      ├─ 127.0.0.1:8082  player (Nginx) ── /api、/uploads ──► api (NestJS :3000)
+      └─ 127.0.0.1:8081  admin  (Nginx) ── /api、/uploads ──► api (NestJS :3000)

 api ──► postgres:5432
    └──► redis:6379
@@ -19,9 +20,9 @@ api ──► postgres:5432

 | 容器 | 默认端口 | 说明 |
 |------|----------|------|
-| `thebet365-player` | 8082 | 玩家 H5 前台 |
-| `thebet365-admin` | 8081 | 管理后台（平台 + 代理） |
-| `thebet365-api` | 3000 | NestJS API / Swagger |
+| `thebet365-player` | 127.0.0.1:8082 | 玩家 H5 前台 |
+| `thebet365-admin` | 127.0.0.1:8081 | 管理后台（平台 + 代理） |
+| `thebet365-api` | 不对外暴露 | NestJS API / Swagger / 健康检查 |
 | `thebet365-postgres` | 不对外暴露 | PostgreSQL 16 |
 | `thebet365-redis` | 不对外暴露 | Redis 7 |

@@ -58,6 +59,10 @@ cp .env.docker.example .env.docker

 - `POSTGRES_PASSWORD` — 数据库密码
 - `JWT_SECRET` — 足够长的随机字符串
+- `IMAGE_TAG=latest` — 首次部署可保留；后续用 `--tag` 发布时脚本会写回真实版本
+- `BIND_ADDR=127.0.0.1` — 默认只允许宝塔本机反代访问 player/admin 端口
+- `RUN_MIGRATIONS_ON_START=false` — 迁移由部署脚本执行，API 容器启动时不重复跑迁移
+- `BACKUP_RETENTION_DAYS=` — 留空表示不自动清理备份；填数字时脚本会清理更旧备份
 - `SEED_DATABASE=false` — 保持默认即可；首次部署脚本会在没有 `admin` 时一次性执行生产 seed

 ### 3. 首次部署
@@ -81,12 +86,14 @@ chmod +x scripts/*.sh
 ./scripts/deploy-first.sh --no-build
 ```

-如果上传的是 `thebet365-images.tar`，可让脚本自动加载镜像：
+如果上传的是版本化镜像包，可让脚本自动加载镜像并记录发布 tag：

 ```bash
-./scripts/deploy-first.sh --images thebet365-images.tar
+./scripts/deploy-first.sh --images thebet365-images-v1.2.3.tar --tag v1.2.3
 ```

+镜像包文件名符合 `thebet365-images-<tag>.tar` 时，脚本也会自动推断 tag；显式传 `--tag` 更清晰。
+
 如需全量初始化生产数据（会清空业务表，仅限全新库或明确重置）：

 ```bash
@@ -104,10 +111,10 @@ docker compose -f docker-compose.prod.yml --env-file .env.docker logs -f api

 | 服务 | 地址 |
 |------|------|
-| 玩家前台 | http://服务器IP:8082 |
-| 管理后台 | http://服务器IP:8081 |
+| 玩家前台 | 宝塔绑定的玩家域名，或服务器本机 `http://127.0.0.1:8082` |
+| 管理后台 | 宝塔绑定的管理域名，或服务器本机 `http://127.0.0.1:8081` |

-API 只在 Docker 网络内暴露，前端容器通过 `/api` 代理到 API。外层域名反代由宝塔网站配置处理。
+API 只在 Docker 网络内暴露，前端容器通过 `/api` 代理到 API。player/admin 默认只绑定 `127.0.0.1`，外层域名和 HTTPS 由宝塔网站反代处理。临时需要公网 IP 直连时，才在 `.env.docker` 中设置 `BIND_ADDR=0.0.0.0`。

 ---

@@ -171,6 +178,9 @@ docker compose -f docker-compose.prod.yml --env-file .env.docker up -d --build a
 # 手动备份数据库
 ./scripts/backup-db.sh

+# 完整生产备份：数据库 + uploads
+./scripts/backup-prod.sh --prefix pre-release
+
 # 全量初始化（生产上线：仅 admin + WC2026 赛事，会先备份到 ./backups/）
 CONFIRM=YES ./scripts/prod-init-db.sh
 # Windows PowerShell:
@@ -178,6 +188,9 @@ CONFIRM=YES ./scripts/prod-init-db.sh

 # 查看 API 日志
 docker compose -f docker-compose.prod.yml --env-file .env.docker logs -f api
+
+# 回滚应用镜像到指定 tag（不自动回滚数据库）
+./scripts/rollback.sh --to v1.2.2
 ```

 根目录 `package.json` 快捷脚本（需已存在 `.env.docker`）：
@@ -197,21 +210,27 @@ pnpm docker:ps
 |------|------|
 | `postgres_data` | 数据库 |
 | `redis_data` | Redis |
-| `uploads_data` | Banner 等用户上传文件 |
+| `uploads_data` | Banner、充值截图、支付二维码等用户上传文件 |

-备份 PostgreSQL 示例：
+备份示例：

 ```bash
+# 仅数据库：生成 backups/thebet365-db-*.sql.gz 和 .sha256
 ./scripts/backup-db.sh
+
+# 数据库 + uploads：生成 .sql.gz、.tar.gz 和对应 .sha256
+./scripts/backup-prod.sh --prefix manual
 ```

+`BACKUP_RETENTION_DAYS` 留空时不自动删除历史备份；设置为数字时，部署和备份脚本会清理更早的备份文件。
+
 ---

 ## 八、后续更新部署

 **推荐：先删旧代码再解压新 zip**（避免 `packages/shared/public/球员` 等中文目录残留导致 Vite 构建失败）。

-本地构建并导出镜像的详细步骤见：[docker/镜像构建与导出.md](./docker/镜像构建与导出.md)（脚本位于 `docs/docker/build-and-export-images.ps1` / `build-and-export-images.sh`）。
+推荐主流程是：本地或构建机生成版本化镜像包 → 上传 tar 与 manifest → 服务器执行 `deploy-update.sh --images ... --tag ...`。详细步骤见：[docker/镜像构建与导出.md](./docker/镜像构建与导出.md)（脚本位于 `docs/docker/build-and-export-images.ps1` / `build-and-export-images.sh`）。

 ### 方式 A：服务器直接拉代码并构建

@@ -233,19 +252,30 @@ cd /www/wwwroot/thebet365

 ```bash
 cd /www/wwwroot/thebet365
-./scripts/deploy-update.sh --images thebet365-images.tar
+./scripts/deploy-update.sh --images thebet365-images-v1.2.3.tar --tag v1.2.3
 ```

 更新脚本默认会：

- 先备份 PostgreSQL 到 `./backups/`
- 构建或加载新镜像
+- 先备份 PostgreSQL 与 uploads 到 `./backups/`，并生成 `.sha256`
+- 构建或加载指定 tag 的新镜像
 - 使用新 API 镜像执行 `prisma migrate deploy`
 - 启动/替换 API、玩家端、管理端容器
+- 等待 API、玩家端、管理端健康检查通过
 - 执行 `prisma migrate status` 检查数据库迁移状态
+- 将当前发布写入 `.deploy/current-release.env`，并保留上一次发布到 `.deploy/previous-release.env`

 除非已经手工确认有其他备份，否则不要使用 `--no-backup`。

+### 回滚应用镜像
+
+```bash
+cd /www/wwwroot/thebet365
+./scripts/rollback.sh --to v1.2.2
+```
+
+回滚脚本只切换 `api` / `player` / `admin` 镜像 tag，不自动恢复数据库。若新版本包含不可逆迁移或已写入不兼容数据，需要先按 `backups/` 中的 `.sql.gz` 备份手工恢复 PostgreSQL，再执行镜像回滚。
+
 ---

 ## 九、故障排查
@@ -256,21 +286,36 @@ cd /www/wwwroot/thebet365
 docker logs thebet365-api
 ```

-常见原因：数据库未就绪（稍等重试）、`DATABASE_URL` 密码与 `POSTGRES_PASSWORD` 不一致。
+常见原因：数据库未就绪（稍等重试）、`DATABASE_URL` 密码与 `POSTGRES_PASSWORD` 不一致、`/api/health/ready` 检查 DB/Redis 失败。

 ### 2. 前端 502 / 接口失败

-确认 `thebet365-api` 为 running，且 player/admin 容器能解析主机名 `api`（同一 compose 网络）。
+确认 `thebet365-api` 为 healthy，且 player/admin 容器能解析主机名 `api`（同一 compose 网络）。

-### 3. 构建慢或内存不足
+```bash
+docker compose -f docker-compose.prod.yml --env-file .env.docker ps
+docker compose -f docker-compose.prod.yml --env-file .env.docker logs --tail=120 api
+```
+
+### 3. player/admin 端口无法从公网 IP 直连
+
+生产默认只绑定 `127.0.0.1`，需要通过宝塔网站反代访问。临时调试公网 IP 直连时，在 `.env.docker` 中设置：
+
+```bash
+BIND_ADDR=0.0.0.0
+```
+
+然后重新执行部署脚本。
+
+### 4. 构建慢或内存不足

 首次 `docker compose build` 会安装 pnpm 依赖并编译三端，建议服务器 ≥ 2 GB 内存；可在低峰期构建。

-### 4. 端口被占用
+### 5. 端口被占用

 修改 `.env.docker` 中的 `PLAYER_PORT` / `ADMIN_PORT` 后重新部署。API 不对公网映射端口。

-### 5. player/admin 构建报错 `ENOENT ... packages/shared/public/球员`
+### 6. player/admin 构建报错 `ENOENT ... packages/shared/public/球员`

 旧版中文目录 `球员` 在 Linux 上编码异常。确认已使用含 `packages/shared/public/players/` 的新代码包，并：

--- a/docs/docker/build-and-export-images.ps1
+++ b/docs/docker/build-and-export-images.ps1
@@ -1,13 +1,15 @@
 # 构建 api / player / admin 生产镜像并导出为 tar
 # 用法（在项目根目录或本目录执行均可）:
 #   .\docs\docker\build-and-export-images.ps1
+#   .\docs\docker\build-and-export-images.ps1 -Tag v1.2.3
 #   .\build-and-export-images.ps1 -UseCache
 #   .\build-and-export-images.ps1 -ExportOnly

 param(
+  [string]$Tag = $env:IMAGE_TAG,
  [switch]$UseCache,
  [switch]$ExportOnly,
-  [string]$Output = "thebet365-images.tar"
+  [string]$Output = ""
 )

 $ErrorActionPreference = "Stop"
@@ -18,6 +20,21 @@ $ComposeFile = "docker-compose.prod.yml"
 $EnvFile = ".env.docker"
 $Services = @("api", "player", "admin")

+function Get-DefaultTag {
+  try {
+    $short = (& git rev-parse --short HEAD 2>$null).Trim()
+    if ($short) { return $short }
+  } catch {}
+  return Get-Date -Format "yyyyMMdd-HHmmss"
+}
+
+function Assert-ImageTag {
+  param([string]$Value)
+  if ($Value -notmatch '^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$') {
+    throw "镜像 tag 不合法: $Value"
+  }
+}
+
 if (-not (Test-Path $ComposeFile)) {
  throw "未找到 $ComposeFile（当前目录: $Root）"
 }
@@ -31,8 +48,16 @@ if (-not (Test-Path $EnvFile)) {
  }
 }

+if ([string]::IsNullOrWhiteSpace($Tag)) {
+  $Tag = Get-DefaultTag
+}
+Assert-ImageTag $Tag
+if ([string]::IsNullOrWhiteSpace($Output)) {
+  $Output = "thebet365-images-$Tag.tar"
+}
+
 if (-not $ExportOnly) {
-  Write-Host "==> 构建镜像: $($Services -join ', ')"
+  Write-Host "==> 构建镜像: $($Services -join ', ') (tag: $Tag)"
  $buildArgs = @(
    "compose", "-f", $ComposeFile, "--env-file", $EnvFile, "build"
  )
@@ -40,28 +65,72 @@ if (-not $ExportOnly) {
    $buildArgs += "--no-cache"
  }
  $buildArgs += $Services
-  & docker @buildArgs
-  if ($LASTEXITCODE -ne 0) { throw "docker build 失败，退出码 $LASTEXITCODE" }
+  $oldImageTag = $env:IMAGE_TAG
+  try {
+    $env:IMAGE_TAG = $Tag
+    & docker @buildArgs
+    if ($LASTEXITCODE -ne 0) { throw "docker build 失败，退出码 $LASTEXITCODE" }
+  } finally {
+    $env:IMAGE_TAG = $oldImageTag
+  }
 }

 $OutputPath = if ([System.IO.Path]::IsPathRooted($Output)) { $Output } else { Join-Path $Root $Output }

 Write-Host "==> 导出镜像 -> $OutputPath"
 & docker save `
-  thebet365-api:latest `
-  thebet365-player:latest `
-  thebet365-admin:latest `
+  "thebet365-api:${Tag}" `
+  "thebet365-player:${Tag}" `
+  "thebet365-admin:${Tag}" `
  -o $OutputPath
 if ($LASTEXITCODE -ne 0) { throw "docker save 失败，退出码 $LASTEXITCODE" }

+$manifestPath = if ($OutputPath.EndsWith(".tar")) {
+  $OutputPath.Substring(0, $OutputPath.Length - 4) + ".manifest.txt"
+} else {
+  "$OutputPath.manifest.txt"
+}
+
+$gitCommit = "unknown"
+$gitDirty = "unknown"
+try {
+  $gitCommit = (& git rev-parse HEAD 2>$null).Trim()
+  & git diff --quiet
+  $diffExit = $LASTEXITCODE
+  & git diff --cached --quiet
+  $cachedExit = $LASTEXITCODE
+  $gitDirty = if ($diffExit -eq 0 -and $cachedExit -eq 0) { "false" } else { "true" }
+} catch {}
+
+$tarHash = (Get-FileHash -Algorithm SHA256 $OutputPath).Hash.ToLowerInvariant()
+$apiImageId = (& docker image inspect "thebet365-api:${Tag}" --format "{{.Id}}").Trim()
+$playerImageId = (& docker image inspect "thebet365-player:${Tag}" --format "{{.Id}}").Trim()
+$adminImageId = (& docker image inspect "thebet365-admin:${Tag}" --format "{{.Id}}").Trim()
+
+@(
+  "tag=$Tag"
+  "built_at=$((Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ"))"
+  "git_commit=$gitCommit"
+  "git_dirty=$gitDirty"
+  "tar=$([System.IO.Path]::GetFileName($OutputPath))"
+  "tar_sha256=$tarHash"
+  "api_image=thebet365-api:${Tag}"
+  "api_image_id=$apiImageId"
+  "player_image=thebet365-player:${Tag}"
+  "player_image_id=$playerImageId"
+  "admin_image=thebet365-admin:${Tag}"
+  "admin_image_id=$adminImageId"
+) | Set-Content -Encoding UTF8 $manifestPath
+
 $sizeMb = [math]::Round((Get-Item $OutputPath).Length / 1MB, 2)
 Write-Host "完成: $OutputPath (${sizeMb} MB)"
+Write-Host "Manifest: $manifestPath"

 Write-Host @"

 服务器首次部署:
-  ./scripts/deploy-first.sh --images thebet365-images.tar
+  ./scripts/deploy-first.sh --images $([System.IO.Path]::GetFileName($OutputPath)) --tag $Tag

 服务器后续更新:
-  ./scripts/deploy-update.sh --images thebet365-images.tar
+  ./scripts/deploy-update.sh --images $([System.IO.Path]::GetFileName($OutputPath)) --tag $Tag
 "@
--- a/docs/docker/build-and-export-images.sh
+++ b/docs/docker/build-and-export-images.sh
@@ -2,6 +2,7 @@
 # 构建 api / player / admin 生产镜像并导出为 tar
 # 用法:
 #   ./docs/docker/build-and-export-images.sh
+#   ./docs/docker/build-and-export-images.sh --tag v1.2.3
 #   ./build-and-export-images.sh --use-cache
 #   ./build-and-export-images.sh --export-only

@@ -13,25 +14,44 @@ cd "$ROOT"

 COMPOSE_FILE="docker-compose.prod.yml"
 ENV_FILE=".env.docker"
-OUTPUT="thebet365-images.tar"
+OUTPUT=""
 SERVICES=(api player admin)
 NO_CACHE=1
 EXPORT_ONLY=0
+TAG="${IMAGE_TAG:-}"
+
+default_tag() {
+  if command -v git >/dev/null 2>&1 && git rev-parse --short HEAD >/dev/null 2>&1; then
+    git rev-parse --short HEAD
+  else
+    date +%Y%m%d-%H%M%S
+  fi
+}
+
+validate_tag() {
+  printf '%s' "$1" | grep -Eq '^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$' ||
+    { echo "错误: 镜像 tag 不合法: $1" >&2; exit 1; }
+}

 usage() {
  cat <<'EOF'
 用法: docs/docker/build-and-export-images.sh [选项]

 选项:
+  --tag TAG        镜像 tag（默认当前 git 短提交号；非 git 目录则用时间戳）
  --use-cache      构建时使用 Docker 缓存（默认 --no-cache）
-  --export-only    跳过构建，仅导出已有 latest 镜像
-  --output PATH    导出文件路径（默认项目根目录 thebet365-images.tar）
+  --export-only    跳过构建，仅导出已有指定 tag 镜像
+  --output PATH    导出文件路径（默认项目根目录 thebet365-images-<tag>.tar）
  -h, --help       显示帮助
 EOF
 }

 while [[ $# -gt 0 ]]; do
  case "$1" in
+    --tag)
+      TAG="${2:?缺少 --tag 参数值}"
+      shift 2
+      ;;
    --use-cache) NO_CACHE=0; shift ;;
    --export-only) EXPORT_ONLY=1; shift ;;
    --output)
@@ -44,28 +64,32 @@ while [[ $# -gt 0 ]]; do
 done

 if [[ ! -f "$COMPOSE_FILE" ]]; then
-  echo "错误: 未找到 $COMPOSE_FILE（目录: $ROOT）" >&2
+  echo "错误: 未找到 ${COMPOSE_FILE}（目录: ${ROOT}）" >&2
  exit 1
 fi

 if [[ ! -f "$ENV_FILE" ]]; then
  if [[ -f ".env.docker.example" ]]; then
-    echo "警告: 未找到 $ENV_FILE，将使用 .env.docker.example（生产部署请复制为 .env.docker 并修改密钥）"
+    echo "警告: 未找到 ${ENV_FILE}，将使用 .env.docker.example（生产部署请复制为 .env.docker 并修改密钥）"
    ENV_FILE=".env.docker.example"
  else
-    echo "错误: 未找到 $ENV_FILE 或 .env.docker.example" >&2
+    echo "错误: 未找到 ${ENV_FILE} 或 .env.docker.example" >&2
    exit 1
  fi
 fi

+TAG="${TAG:-$(default_tag)}"
+validate_tag "$TAG"
+OUTPUT="${OUTPUT:-thebet365-images-$TAG.tar}"
+
 if [[ "$EXPORT_ONLY" -eq 0 ]]; then
-  echo "==> 构建镜像: ${SERVICES[*]}"
+  echo "==> 构建镜像: ${SERVICES[*]} (tag: $TAG)"
  BUILD_ARGS=(compose -f "$COMPOSE_FILE" --env-file "$ENV_FILE" build)
  if [[ "$NO_CACHE" -eq 1 ]]; then
    BUILD_ARGS+=(--no-cache)
  fi
  BUILD_ARGS+=("${SERVICES[@]}")
-  docker "${BUILD_ARGS[@]}"
+  IMAGE_TAG="$TAG" docker "${BUILD_ARGS[@]}"
 fi

 OUTPUT_PATH="$OUTPUT"
@@ -75,23 +99,59 @@ fi

 echo "==> 导出镜像 -> $OUTPUT_PATH"
 docker save \
-  thebet365-api:latest \
-  thebet365-player:latest \
-  thebet365-admin:latest \
+  "thebet365-api:$TAG" \
+  "thebet365-player:$TAG" \
+  "thebet365-admin:$TAG" \
  -o "$OUTPUT_PATH"

+MANIFEST_PATH="${OUTPUT_PATH%.tar}.manifest.txt"
+BUILT_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+GIT_COMMIT="unknown"
+GIT_DIRTY="unknown"
+if command -v git >/dev/null 2>&1 && git rev-parse HEAD >/dev/null 2>&1; then
+  GIT_COMMIT="$(git rev-parse HEAD)"
+  if git diff --quiet && git diff --cached --quiet; then
+    GIT_DIRTY="false"
+  else
+    GIT_DIRTY="true"
+  fi
+fi
+
+CHECKSUM="unavailable"
+if command -v sha256sum >/dev/null 2>&1; then
+  CHECKSUM="$(sha256sum "$OUTPUT_PATH" | awk '{print $1}')"
+elif command -v shasum >/dev/null 2>&1; then
+  CHECKSUM="$(shasum -a 256 "$OUTPUT_PATH" | awk '{print $1}')"
+fi
+
+{
+  echo "tag=$TAG"
+  echo "built_at=$BUILT_AT"
+  echo "git_commit=$GIT_COMMIT"
+  echo "git_dirty=$GIT_DIRTY"
+  echo "tar=$(basename "$OUTPUT_PATH")"
+  echo "tar_sha256=$CHECKSUM"
+  echo "api_image=thebet365-api:$TAG"
+  echo "api_image_id=$(docker image inspect "thebet365-api:$TAG" --format '{{.Id}}')"
+  echo "player_image=thebet365-player:$TAG"
+  echo "player_image_id=$(docker image inspect "thebet365-player:$TAG" --format '{{.Id}}')"
+  echo "admin_image=thebet365-admin:$TAG"
+  echo "admin_image_id=$(docker image inspect "thebet365-admin:$TAG" --format '{{.Id}}')"
+} > "$MANIFEST_PATH"
+
 if command -v du >/dev/null 2>&1; then
  SIZE="$(du -h "$OUTPUT_PATH" | awk '{print $1}')"
  echo "完成: $OUTPUT_PATH ($SIZE)"
 else
  echo "完成: $OUTPUT_PATH"
 fi
+echo "Manifest: $MANIFEST_PATH"

-cat <<'EOF'
+cat <<EOF

 服务器首次部署:
-  ./scripts/deploy-first.sh --images thebet365-images.tar
+  ./scripts/deploy-first.sh --images $(basename "$OUTPUT_PATH") --tag $TAG

 服务器后续更新:
-  ./scripts/deploy-update.sh --images thebet365-images.tar
+  ./scripts/deploy-update.sh --images $(basename "$OUTPUT_PATH") --tag $TAG
 EOF
--- a/docs/docker/镜像构建与导出.md
+++ b/docs/docker/镜像构建与导出.md
@@ -15,7 +15,7 @@
 | `docs/docker/build-and-export-images.ps1` | Windows（PowerShell） |
 | `docs/docker/build-and-export-images.sh` | Linux / macOS / Git Bash |

-两个脚本行为一致：在**项目根目录**执行 compose 构建 → 导出为根目录下的 `thebet365-images.tar`（默认）。
+两个脚本行为一致：在**项目根目录**执行 compose 构建 → 导出为根目录下的 `thebet365-images-<tag>.tar`（默认），并生成同名 `.manifest.txt`。

 ---

@@ -30,6 +30,7 @@
 生产环境务必在 `.env.docker` 中配置：

 - `POSTGRES_PASSWORD`、`JWT_SECRET`
+- `IMAGE_TAG`、`BIND_ADDR`、`RUN_MIGRATIONS_ON_START` 保持 `.env.docker.example` 默认即可，部署脚本会按 `--tag` 写回真实版本
 - `CHUANGLAN_ACCOUNT`、`CHUANGLAN_PASSWORD`（短信注册）
 - `SEED_DATABASE=false`（生产建议保持 false，由部署脚本按需一次性 seed）

@@ -58,9 +59,10 @@ chmod +x docs/docker/build-and-export-images.sh

 | PowerShell | Bash | 说明 |
 |------------|------|------|
+| `-Tag v1.2.3` | `--tag v1.2.3` | 指定镜像 tag；未指定时默认当前 Git 短提交号 |
 | （默认） | （默认） | `--no-cache` 全量构建，适合发版 |
 | `-UseCache` | `--use-cache` | 使用 Docker 缓存，构建更快 |
-| `-ExportOnly` | `--export-only` | 跳过构建，仅导出已有 `latest` 镜像 |
+| `-ExportOnly` | `--export-only` | 跳过构建，仅导出已有指定 tag 镜像 |
 | `-Output my.tar` | `--output my.tar` | 自定义导出文件名 |

 示例：仅重新导出已有镜像
@@ -79,17 +81,18 @@ chmod +x docs/docker/build-and-export-images.sh

 | 镜像名 | 说明 |
 |--------|------|
-| `thebet365-api:latest` | NestJS API（含 Prisma 迁移入口） |
-| `thebet365-player:latest` | 玩家前台（Nginx 静态资源） |
-| `thebet365-admin:latest` | 管理后台（Nginx 静态资源） |
+| `thebet365-api:<tag>` | NestJS API（迁移由部署脚本执行） |
+| `thebet365-player:<tag>` | 玩家前台（Nginx 静态资源） |
+| `thebet365-admin:<tag>` | 管理后台（Nginx 静态资源） |

 导出文件默认路径：

 ```text
-<项目根目录>/thebet365-images.tar
+<项目根目录>/thebet365-images-<tag>.tar
+<项目根目录>/thebet365-images-<tag>.manifest.txt
 ```

-该文件已加入 `.gitignore`，**请勿提交到 Git**。
+这些文件已加入 `.gitignore`，**请勿提交到 Git**。manifest 会记录 tag、构建时间、Git commit、镜像 ID 和 tar 的 SHA-256，便于服务器核对发布包。

 ---

@@ -99,7 +102,8 @@ chmod +x docs/docker/build-and-export-images.sh

 将以下内容传到服务器同一目录（如 `/www/wwwroot/thebet365`）：

- `thebet365-images.tar`
+- `thebet365-images-<tag>.tar`
+- `thebet365-images-<tag>.manifest.txt`
 - `docker-compose.prod.yml`
 - `.env.docker`（或服务器上已有配置）
 - `docker/nginx/` 等 compose 依赖目录（若仅 load 镜像、不 rebuild，compose 文件仍需要）
@@ -111,16 +115,16 @@ chmod +x docs/docker/build-and-export-images.sh
 ```bash
 cd /www/wwwroot/thebet365
 chmod +x scripts/*.sh
-./scripts/deploy-first.sh --images thebet365-images.tar
+./scripts/deploy-first.sh --images thebet365-images-v1.2.3.tar --tag v1.2.3
 ```

 后续更新同一个服务器时：

 ```bash
-./scripts/deploy-update.sh --images thebet365-images.tar
+./scripts/deploy-update.sh --images thebet365-images-v1.2.3.tar --tag v1.2.3
 ```

-更新脚本会先备份数据库，再用新 API 镜像执行 `prisma migrate deploy`，最后替换运行中的容器。
+更新脚本会先备份数据库与 uploads，再用新 API 镜像执行 `prisma migrate deploy`，最后替换运行中的容器并等待健康检查通过。

 ### 3. 验证

@@ -131,8 +135,8 @@ docker logs thebet365-api --tail 50

 浏览器访问（端口以 `.env.docker` 为准）：

- 玩家端：`http://服务器IP:8082`
- 管理端：`http://服务器IP:8081`
+- 玩家端：经宝塔反代访问，或服务器本机 `http://127.0.0.1:8082`
+- 管理端：经宝塔反代访问，或服务器本机 `http://127.0.0.1:8081`

 ---

@@ -140,10 +144,10 @@ docker logs thebet365-api --tail 50

 | 方式 | 优点 | 缺点 |
 |------|------|------|
-| **本地 build + 导出 tar** | 不占用服务器 CPU/内存；可重复部署同一包 | 需上传较大 tar（约 200–300 MB） |
+| **本地 build + 导出 tar** | 不占用服务器 CPU/内存；有 tag 与 manifest，可重复部署同一包 | 需上传较大 tar（约 200–300 MB） |
 | **服务器 `docker compose build`** | 无需传 tar | 首次/全量构建慢，小内存机器易失败 |

-发版推荐流程：**本地或构建机执行脚本 → 上传 tar → 服务器执行 `deploy-update.sh --images thebet365-images.tar`**。
+发版推荐流程：**本地或构建机执行脚本 → 上传 tar + manifest → 服务器执行 `deploy-update.sh --images thebet365-images-<tag>.tar --tag <tag>`**。

 ---

@@ -162,9 +166,9 @@ find packages/shared/public -mindepth 1 -maxdepth 1 -type d \
  ! -name flags ! -name players -exec rm -rf {} +
 ```

-### 3. `docker load` 后 `up -d` 仍拉取或重建镜像
+### 3. `docker load` 后部署仍找不到镜像

-确保 compose 中 `image` 与 load 的 tag 一致（`thebet365-api:latest` 等），且使用同一 `docker-compose.prod.yml`。
+确保上传的 tar 中包含 `thebet365-api:<tag>`、`thebet365-player:<tag>`、`thebet365-admin:<tag>`，并且服务器执行部署时传入同一个 `--tag <tag>`。

 ### 4. API 启动后不断重启

@@ -182,7 +186,8 @@ docker logs thebet365-api
 thebet365/
 ├── docker-compose.prod.yml
 ├── .env.docker.example
-├── thebet365-images.tar             # 导出产物（默认，已 gitignore）
+├── thebet365-images-<tag>.tar       # 导出产物（默认，已 gitignore）
+├── thebet365-images-<tag>.manifest.txt
 ├── docker/
 │   ├── api/Dockerfile
 │   ├── player/Dockerfile
--- a/docs/项目启动指南.md
+++ b/docs/项目启动指南.md
@@ -387,7 +387,8 @@ cd /www/wwwroot/thebet365
 ./scripts/deploy-update.sh --pull
 ```

- 更新脚本会先备份数据库，再构建新镜像、执行 Prisma 迁移并替换容器
+- 更新脚本会先备份数据库与 uploads，再构建新镜像、执行 Prisma 迁移、替换容器并等待健康检查
+- 使用离线镜像包时推荐 `./scripts/deploy-update.sh --images thebet365-images-<tag>.tar --tag <tag>`，发布状态会记录到 `.deploy/current-release.env`
 - **不要**把 `.env.docker` 提交到 Git；服务器上单独保留
 - `release/*.zip` 为旧打包方式，Git 同步后不必再生成上传

--- a/docs/默认数据说明.md
+++ b/docs/默认数据说明.md
@@ -192,7 +192,7 @@ pnpm db:seed
 CONFIRM=YES ./scripts/prod-init-db.sh
 ```

-该脚本会先备份 PostgreSQL，再执行 Prisma 迁移，然后以 production 模式清空业务表并写入 `admin`、WC2026 小组赛 72 场和 48 强优胜盘。
+该脚本会先备份 PostgreSQL 到 `backups/*.sql.gz` 并生成 `.sha256`，再执行 Prisma 迁移，然后以 production 模式清空业务表并写入 `admin`、WC2026 小组赛 72 场和 48 强优胜盘。

 ---