docs: 从 main 同步 AGENTS、文档与部署脚本

2026-06-18 14:59:17 +08:00
parent 58f0876017
commit 533d748605
7 changed files with 649 additions and 763 deletions
--- a/docs/Docker部署指南.md
+++ b/docs/Docker部署指南.md
@@ -226,55 +226,226 @@ pnpm docker:ps

 ---

-## 八、后续更新部署
+## 八、推荐发版流程：本地打包 → 上传 → 线上更新

-**推荐：先删旧代码再解压新 zip**（避免 `packages/shared/public/球员` 等中文目录残留导致 Vite 构建失败）。
+**日常更新推荐走这条链路**，不在服务器上编译，省 CPU/内存，发版包可重复部署。

-推荐主流程是：本地或构建机生成版本化镜像包 → 上传 tar 与 manifest → 服务器执行 `deploy-update.sh --images ... --tag ...`。详细步骤见：[docker/镜像构建与导出.md](./docker/镜像构建与导出.md)（脚本位于 `docs/docker/build-and-export-images.ps1` / `build-and-export-images.sh`）。
+```text
+本地 Windows/Mac          宝塔/SCP 上传              服务器终端
+─────────────────        ───────────────           ─────────────────
+checkout 目标分支    →    只传 tar + manifest   →   deploy-update.sh
+build 三端镜像            到 /www/wwwroot/thebet365    自动备份+迁移+重启
+导出 .tar + .manifest     不要覆盖 .env.docker
+```

-### 方式 A：服务器直接拉代码并构建
+镜像构建细节见：[docker/镜像构建与导出.md](./docker/镜像构建与导出.md)。
+
+---
+
+### 步骤 1：本地打包镜像
+
+#### 1.1 前置条件
+
+- 已安装 **Docker Desktop**（Windows/Mac）或 Linux Docker
+- 在项目根目录，且已 `git checkout` 到要发布的分支（如 `main`、`theme-4`）
+
+#### 1.2 确认环境文件
+
+本地需有 `.env.docker`（可从 `.env.docker.example` 复制）。构建 **admin** 镜像时会读取其中的 `VITE_PLAYER_URL`（玩家站公网地址，用于邀请链接）。若玩家域名有变，**改 `.env.docker` 后需重新打包 admin**。
+
+#### 1.3 执行构建脚本
+
+**Windows（推荐 CMD）：**
+
+```bat
+cd C:\path\to\thebet365
+docs\docker\build-and-export-images.bat --tag latest
+```
+
+带版本号（便于回滚追溯）：
+
+```bat
+docs\docker\build-and-export-images.bat --tag v20260618
+```
+
+**Linux / macOS / Git Bash：**
+
+```bash
+cd /path/to/thebet365
+chmod +x docs/docker/build-and-export-images.sh
+./docs/docker/build-and-export-images.sh --tag latest
+```
+
+首次或发版建议不加 `--use-cache`（默认全量构建）。仅重新导出已有镜像时：
+
+```bat
+docs\docker\build-and-export-images.bat --export-only --tag latest
+```
+
+#### 1.4 构建产物（在项目根目录）
+
+| 文件 | 说明 |
+|------|------|
+| `thebet365-images-<tag>.tar` | 含 `api` / `player` / `admin` 三个镜像，约 200–300 MB |
+| `thebet365-images-<tag>.manifest.txt` | 记录 tag、构建时间、`git_commit`、镜像 ID、tar SHA-256 |
+
+示例：`thebet365-images-latest.tar`、`thebet365-images-latest.manifest.txt`
+
+> 这两个文件已在 `.gitignore` 中，**不要提交到 Git**。
+
+---
+
+### 步骤 2：上传到服务器
+
+#### 2.1 上传目标目录
+
+服务器项目目录，例如：
+
+```text
+/www/wwwroot/thebet365
+```
+
+#### 2.2 本次更新需要上传的文件
+
+| 文件 | 是否必传 |
+|------|----------|
+| `thebet365-images-<tag>.tar` | **必传** |
+| `thebet365-images-<tag>.manifest.txt` | 建议传（便于核对版本） |
+
+可用 **宝塔 → 文件 → 上传**，或 SCP：
+
+```bash
+scp thebet365-images-latest.tar thebet365-images-latest.manifest.txt \
+  root@你的服务器IP:/www/wwwroot/thebet365/
+```
+
+#### 2.3 不要覆盖的文件
+
+| 文件/目录 | 说明 |
+|-----------|------|
+| **`.env.docker`** | 生产密钥、端口、域名配置；**保留服务器上原有文件** |
+| `postgres_data` 等 Docker 卷 | 数据库与上传文件，不在文件管理里替换 |
+
+服务器目录里应**早已存在**（首次部署时上传过）：`docker-compose.prod.yml`、`scripts/`、`docker/` 等。仅换镜像时**不必**重传整份代码。
+
+若部署脚本有更新（如 `scripts/deploy-lib.sh`），可单独上传覆盖 `scripts/` 目录。
+
+---
+
+### 步骤 3：服务器执行更新脚本
+
+SSH 或 **宝塔 → 终端**，进入项目目录：

 ```bash
 cd /www/wwwroot/thebet365
-./scripts/deploy-update.sh --pull
+chmod +x scripts/*.sh
+./scripts/deploy-update.sh --images thebet365-images-latest.tar --tag latest
 ```

-### 方式 B：上传 zip 后在服务器构建
+`--tag` 必须与打包时一致（上例为 `latest`；若本地用了 `--tag v20260618`，这里也要写 `v20260618`）。

-保留原来的 `.env.docker`，替换代码后执行：
+#### 脚本会自动完成（按顺序）
+
+1. 检查 `.env.docker`（缺少密钥会报错；示例密码仅**警告**，不阻断）
+2. 启动并等待 PostgreSQL / Redis 就绪
+3. **更新前备份** → `./backups/thebet365-db-pre-update-<时间>.sql.gz` 与 `thebet365-uploads-pre-update-<时间>.tar.gz`
+4. `docker load -i` 导入镜像包
+5. 用新 API 镜像执行 `prisma migrate deploy`（数据库结构变更）
+6. 重启/替换 `api`、`player`、`admin` 容器
+7. 等待健康检查通过，执行 `prisma migrate status`
+8. 将本次发布写入 `.deploy/current-release.env`（含备份路径）
+
+#### `.env.docker` 会被改什么？
+
+- **不会**整文件覆盖，**不会**改 `JWT_SECRET`、`POSTGRES_PASSWORD` 等
+- 部署结束时可能只更新一行：`IMAGE_TAG=<本次 tag>`
+
+#### 首次用镜像包部署（新机器）
+
+若服务器从未部署过，用首次脚本：

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

-### 方式 C：上传已构建镜像包
+---
+
+### 步骤 4：验证是否成功

 ```bash
-cd /www/wwwroot/thebet365
-./scripts/deploy-update.sh --images thebet365-images-v1.2.3.tar --tag v1.2.3
+# 容器状态（api / player / admin 应为 healthy）
+docker compose -f docker-compose.prod.yml --env-file .env.docker ps
+
+# 迁移是否全部应用
+docker compose -f docker-compose.prod.yml --env-file .env.docker exec api \
+  sh -c 'cd /app/apps/api && npx prisma migrate status'
+
+# 本次发布记录与备份路径
+cat .deploy/current-release.env
+
+# 今天是否生成了新备份
+ls -lh backups/ | tail -5
+
+# API 日志（无报错即可）
+docker compose -f docker-compose.prod.yml --env-file .env.docker logs --tail=50 api
 ```

-更新脚本默认会：
+浏览器：玩家站、管理站各访问一次；必要时强刷或清 CDN 缓存。

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

-除非已经手工确认有其他备份，否则不要使用 `--no-backup`。
+### 步骤 5：部署后管理端配置（镜像不会自动开启）
+
+若本次更新含站内邮箱、员工菜单等新功能，需在**管理后台**手动配置：
+
+1. **员工管理** → 给员工勾选可见菜单（`visibleMenus`）
+2. **内容管理** → 开启 Inbox（站内邮箱）及充值/Banner/公告通知开关
+3. 验证：充值审核后玩家收到站内信、侧栏充值待审角标、在线人数等
+
+---
+
+### 备份说明
+
+| 项目 | 说明 |
+|------|------|
+| **何时备份** | 执行 `deploy-update.sh` 时，在**加载新镜像、跑迁移之前** |
+| **备份内容** | 更新前一刻的 PostgreSQL 全库 + `uploads` 用户上传文件 |
+| **存放位置** | `/www/wwwroot/thebet365/backups/` |
+| **文件命名** | `thebet365-db-pre-update-YYYYMMDD-HHMMSS.sql.gz`、`thebet365-uploads-pre-update-....tar.gz` |
+| **记录位置** | `.deploy/current-release.env` 中的 `db_backup=`、`uploads_backup=` |
+
+手动备份（不更新时也可执行）：
+
+```bash
+./scripts/backup-db.sh
+./scripts/backup-prod.sh --prefix manual
+```
+
+**恢复数据库**（仅出问题时）：先 `stop api`，再将 `.sql.gz` 导入 postgres，最后 `start api`。项目无一键恢复脚本，需手工操作；详见下方回滚说明。
+
+---
+
+### 其他更新方式（备选）
+
+| 方式 | 适用场景 | 命令 |
+|------|----------|------|
+| **A：服务器拉代码构建** | 服务器性能足够、不用传 tar | `./scripts/deploy-update.sh --pull` |
+| **B：上传 zip 后服务器构建** | 无 Git、在服务器编译 | 替换代码后 `./scripts/deploy-update.sh` |
+
+方式 B 上传代码时**保留** `.env.docker`；若用 zip 覆盖，注意清理旧的中文目录 `packages/shared/public/球员`（见第九节故障排查）。
+
+---

 ### 回滚应用镜像

 ```bash
 cd /www/wwwroot/thebet365
-./scripts/rollback.sh --to v1.2.2
+./scripts/rollback.sh --to <旧tag>
 ```

-回滚脚本只切换 `api` / `player` / `admin` 镜像 tag，不自动恢复数据库。若新版本包含不可逆迁移或已写入不兼容数据，需要先按 `backups/` 中的 `.sql.gz` 备份手工恢复 PostgreSQL，再执行镜像回滚。
+`rollback.sh` **只切换** `api` / `player` / `admin` 镜像 tag，**不自动恢复数据库**。若新版本已执行不可逆迁移，需先从 `backups/` 中选取 `pre-update` 的 `.sql.gz` 手工恢复 PostgreSQL，再回滚镜像。
+
+除非已确认另有备份，否则不要使用 `--no-backup` 跳过自动备份。

 ---

@@ -329,10 +500,10 @@ docker compose -f docker-compose.prod.yml --env-file .env.docker build --no-cach

 ## 十、与本地开发的区别

-| 场景 | 命令 |
+| 场景 | 命令 / 文档 |
 |------|------|
 | 本地开发（仅 DB 用 Docker） | `docker compose up -d` + `pnpm dev` |
 | 生产首次部署 | `./scripts/deploy-first.sh` |
-| 生产后续更新 | `./scripts/deploy-update.sh` |
+| 生产后续更新（推荐） | 本地打包 → 上传 tar → `./scripts/deploy-update.sh --images ... --tag ...`（见第八节） |

 相关文档：[项目启动指南.md](./项目启动指南.md)