部署优化

2026-06-13 22:16:14 +08:00
parent 21dd9957f0
commit 73a94e6be3
28 changed files with 899 additions and 129 deletions
--- 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