feat: 短信调试日志、Tawk 客服、手机号校验放宽与 Docker 文档

API - 短信发码/验码/创蓝全链路结构化日志（手机号脱敏） - 新增 SMS_DEBUG_LOG_CODE，联调时可输出验证码与 sessionId（对应创蓝批次号） - 注册成功、短信找回密码成功写入审计相关日志 - 放宽手机号归一化：移除区号白名单与 10～15 位长度限制 Player - 公告走马灯滚动周期调整为 35 秒 - 在线客服接入 Tawk.to（tawk.html），登录用户透传昵称/头像/ID - 三语补充 support.connecting 文案部署与文档 - docker-compose 与 .env.docker.example 增加 SMS_DEBUG_LOG_CODE - 新增 docs/短信调试与日志说明.md、docs/docker 镜像构建导出脚本与说明 - Docker 部署指南补充镜像构建文档链接 - .gitignore 忽略 thebet365-images.tar 与 docker-build.log Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-12 14:08:00 +08:00
parent ff89c31b51
commit cb9a1e8708
21 changed files with 870 additions and 34 deletions
--- a/docs/docker/build-and-export-images.ps1
+++ b/docs/docker/build-and-export-images.ps1
@@ -0,0 +1,65 @@
+# 构建 api / player / admin 生产镜像并导出为 tar
+# 用法（在项目根目录或本目录执行均可）:
+#   .\docs\docker\build-and-export-images.ps1
+#   .\build-and-export-images.ps1 -UseCache
+#   .\build-and-export-images.ps1 -ExportOnly
+
+param(
+  [switch]$UseCache,
+  [switch]$ExportOnly,
+  [string]$Output = "thebet365-images.tar"
+)
+
+$ErrorActionPreference = "Stop"
+$Root = (Resolve-Path (Join-Path $PSScriptRoot "../..")).Path
+Set-Location $Root
+
+$ComposeFile = "docker-compose.prod.yml"
+$EnvFile = ".env.docker"
+$Services = @("api", "player", "admin")
+
+if (-not (Test-Path $ComposeFile)) {
+  throw "未找到 $ComposeFile（当前目录: $Root）"
+}
+
+if (-not (Test-Path $EnvFile)) {
+  if (Test-Path ".env.docker.example") {
+    Write-Warning "未找到 .env.docker，使用 .env.docker.example（生产请复制并修改密钥）"
+    $EnvFile = ".env.docker.example"
+  } else {
+    throw "未找到 .env.docker 或 .env.docker.example"
+  }
+}
+
+if (-not $ExportOnly) {
+  Write-Host "==> 构建镜像: $($Services -join ', ')"
+  $buildArgs = @(
+    "compose", "-f", $ComposeFile, "--env-file", $EnvFile, "build"
+  )
+  if (-not $UseCache) {
+    $buildArgs += "--no-cache"
+  }
+  $buildArgs += $Services
+  & docker @buildArgs
+  if ($LASTEXITCODE -ne 0) { throw "docker build 失败，退出码 $LASTEXITCODE" }
+}
+
+$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 `
+  -o $OutputPath
+if ($LASTEXITCODE -ne 0) { throw "docker save 失败，退出码 $LASTEXITCODE" }
+
+$sizeMb = [math]::Round((Get-Item $OutputPath).Length / 1MB, 2)
+Write-Host "完成: $OutputPath (${sizeMb} MB)"
+
+Write-Host @"
+
+服务器加载:
+  docker load -i thebet365-images.tar
+  docker compose -f docker-compose.prod.yml --env-file .env.docker up -d
+"@
--- a/docs/docker/build-and-export-images.sh
+++ b/docs/docker/build-and-export-images.sh
@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# 构建 api / player / admin 生产镜像并导出为 tar
+# 用法:
+#   ./docs/docker/build-and-export-images.sh
+#   ./build-and-export-images.sh --use-cache
+#   ./build-and-export-images.sh --export-only
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+cd "$ROOT"
+
+COMPOSE_FILE="docker-compose.prod.yml"
+ENV_FILE=".env.docker"
+OUTPUT="thebet365-images.tar"
+SERVICES=(api player admin)
+NO_CACHE=1
+EXPORT_ONLY=0
+
+usage() {
+  cat <<'EOF'
+用法: docs/docker/build-and-export-images.sh [选项]
+
+选项:
+  --use-cache      构建时使用 Docker 缓存（默认 --no-cache）
+  --export-only    跳过构建，仅导出已有 latest 镜像
+  --output PATH    导出文件路径（默认项目根目录 thebet365-images.tar）
+  -h, --help       显示帮助
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --use-cache) NO_CACHE=0; shift ;;
+    --export-only) EXPORT_ONLY=1; shift ;;
+    --output)
+      OUTPUT="${2:?缺少 --output 参数值}"
+      shift 2
+      ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "未知参数: $1" >&2; usage; exit 1 ;;
+  esac
+done
+
+if [[ ! -f "$COMPOSE_FILE" ]]; then
+  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 并修改密钥）"
+    ENV_FILE=".env.docker.example"
+  else
+    echo "错误: 未找到 $ENV_FILE 或 .env.docker.example" >&2
+    exit 1
+  fi
+fi
+
+if [[ "$EXPORT_ONLY" -eq 0 ]]; then
+  echo "==> 构建镜像: ${SERVICES[*]}"
+  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[@]}"
+fi
+
+OUTPUT_PATH="$OUTPUT"
+if [[ "$OUTPUT" != /* ]] && [[ "$OUTPUT" != [A-Za-z]:* ]]; then
+  OUTPUT_PATH="$ROOT/$OUTPUT"
+fi
+
+echo "==> 导出镜像 -> $OUTPUT_PATH"
+docker save \
+  thebet365-api:latest \
+  thebet365-player:latest \
+  thebet365-admin:latest \
+  -o "$OUTPUT_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
+
+cat <<'EOF'
+
+服务器加载:
+  docker load -i thebet365-images.tar
+  docker compose -f docker-compose.prod.yml --env-file .env.docker up -d
+EOF
--- a/docs/docker/镜像构建与导出.md
+++ b/docs/docker/镜像构建与导出.md
@@ -0,0 +1,202 @@
+# Docker 镜像构建与导出
+
+本文档说明如何在本地或 CI 机器上**构建** `api` / `player` / `admin` 三个生产镜像，并**导出**为 tar 包，便于上传到服务器离线加载部署。
+
+> 全栈部署流程见上级文档：[Docker部署指南.md](../Docker部署指南.md)
+
+---
+
+## 一、脚本位置
+
+脚本与本文档同目录 `docs/docker/`：
+
+| 文件 | 适用环境 |
+|------|----------|
+| `docs/docker/build-and-export-images.ps1` | Windows（PowerShell） |
+| `docs/docker/build-and-export-images.sh` | Linux / macOS / Git Bash |
+
+两个脚本行为一致：在**项目根目录**执行 compose 构建 → 导出为根目录下的 `thebet365-images.tar`（默认）。
+
+---
+
+## 二、前置条件
+
+1. 已安装 **Docker** 与 **Docker Compose v2**（`docker compose`）
+2. 项目根目录存在 `docker-compose.prod.yml`
+3. 环境变量文件（二选一）：
+   - **推荐**：`.env.docker`（从 `.env.docker.example` 复制并修改）
+   - 若无 `.env.docker`，脚本会回退使用 `.env.docker.example` 并给出警告
+
+生产环境务必在 `.env.docker` 中配置：
+
+- `POSTGRES_PASSWORD`、`JWT_SECRET`
+- `CHUANGLAN_ACCOUNT`、`CHUANGLAN_PASSWORD`（短信注册）
+- `SEED_DATABASE`（首次 `true`，灌完数据后改 `false`）
+
+---
+
+## 三、使用方法
+
+### Windows
+
+在项目根目录打开 PowerShell：
+
+```powershell
+.\docs\docker\build-and-export-images.ps1
+```
+
+### Linux / Git Bash
+
+在项目根目录：
+
+```bash
+chmod +x docs/docker/build-and-export-images.sh
+./docs/docker/build-and-export-images.sh
+```
+
+### 可选参数
+
+| PowerShell | Bash | 说明 |
+|------------|------|------|
+| （默认） | （默认） | `--no-cache` 全量构建，适合发版 |
+| `-UseCache` | `--use-cache` | 使用 Docker 缓存，构建更快 |
+| `-ExportOnly` | `--export-only` | 跳过构建，仅导出已有 `latest` 镜像 |
+| `-Output my.tar` | `--output my.tar` | 自定义导出文件名 |
+
+示例：仅重新导出已有镜像
+
+```powershell
+.\docs\docker\build-and-export-images.ps1 -ExportOnly
+```
+
+```bash
+./docs/docker/build-and-export-images.sh --export-only
+```
+
+---
+
+## 四、构建产物
+
+| 镜像名 | 说明 |
+|--------|------|
+| `thebet365-api:latest` | NestJS API（含 Prisma 迁移入口） |
+| `thebet365-player:latest` | 玩家前台（Nginx 静态资源） |
+| `thebet365-admin:latest` | 管理后台（Nginx 静态资源） |
+
+导出文件默认路径：
+
+```text
+<项目根目录>/thebet365-images.tar
+```
+
+该文件已加入 `.gitignore`，**请勿提交到 Git**。
+
+---
+
+## 五、上传到服务器并加载
+
+### 1. 上传
+
+将以下内容传到服务器同一目录（如 `/www/wwwroot/thebet365`）：
+
+- `thebet365-images.tar`
+- `docker-compose.prod.yml`
+- `.env.docker`（或服务器上已有配置）
+- `docker/nginx/` 等 compose 依赖目录（若仅 load 镜像、不 rebuild，compose 文件仍需要）
+
+可用 SCP、宝塔文件管理、rsync 等。
+
+### 2. 加载镜像
+
+```bash
+cd /www/wwwroot/thebet365
+docker load -i thebet365-images.tar
+```
+
+确认镜像：
+
+```bash
+docker images | grep thebet365
+```
+
+### 3. 启动服务
+
+```bash
+docker compose -f docker-compose.prod.yml --env-file .env.docker up -d
+```
+
+API 容器启动时会自动执行 `prisma migrate deploy`，一般无需手动迁移。
+
+### 4. 验证
+
+```bash
+docker compose -f docker-compose.prod.yml ps
+docker logs thebet365-api --tail 50
+```
+
+浏览器访问（端口以 `.env.docker` 为准）：
+
+- 玩家端：`http://服务器IP:8082`
+- 管理端：`http://服务器IP:8081`
+
+---
+
+## 六、与「服务器上直接 build」的区别
+
+| 方式 | 优点 | 缺点 |
+|------|------|------|
+| **本地 build + 导出 tar** | 不占用服务器 CPU/内存；可重复部署同一包 | 需上传较大 tar（约 200–300 MB） |
+| **服务器 `docker compose build`** | 无需传 tar | 首次/全量构建慢，小内存机器易失败 |
+
+发版推荐流程：**本地或构建机执行脚本 → 上传 tar → 服务器 `docker load` → `up -d`**。
+
+---
+
+## 七、常见问题
+
+### 1. 构建时提示 `CHUANGLAN_* variable is not set`
+
+仅为 **警告**，不影响镜像构建；运行时请在 `.env.docker` 中补全创蓝配置，否则短信验证码无法发送。
+
+### 2. player / admin 构建失败 `ENOENT ... public/球员`
+
+旧包残留中文目录。清理后重试：
+
+```bash
+find packages/shared/public -mindepth 1 -maxdepth 1 -type d \
+  ! -name flags ! -name players -exec rm -rf {} +
+```
+
+### 3. `docker load` 后 `up -d` 仍拉取或重建镜像
+
+确保 compose 中 `image` 与 load 的 tag 一致（`thebet365-api:latest` 等），且使用同一 `docker-compose.prod.yml`。
+
+### 4. API 启动后不断重启
+
+```bash
+docker logs thebet365-api
+```
+
+常见原因：数据库未就绪、`DATABASE_URL` 与 `POSTGRES_PASSWORD` 不一致、迁移失败。
+
+---
+
+## 八、相关文件
+
+```text
+thebet365/
+├── docker-compose.prod.yml
+├── .env.docker.example
+├── thebet365-images.tar             # 导出产物（默认，已 gitignore）
+├── docker/
+│   ├── api/Dockerfile
+│   ├── player/Dockerfile
+│   ├── admin/Dockerfile
+│   └── nginx/
+└── docs/
+    ├── Docker部署指南.md
+    └── docker/
+        ├── 镜像构建与导出.md        # 本文档
+        ├── build-and-export-images.ps1
+        └── build-and-export-images.sh
+```