重构

2026-06-13 17:38:25 +08:00
parent e7e938f261
commit 7b33d9f9fa
190 changed files with 23222 additions and 4336 deletions
--- a/docs/Docker部署指南.md
+++ b/docs/Docker部署指南.md
@@ -41,7 +41,7 @@ api ──► postgres:5432

 ---

-## 三、一键部署（命令行）
+## 三、首次部署（命令行）

 ### 1. 上传代码

@@ -58,19 +58,39 @@ cp .env.docker.example .env.docker

 - `POSTGRES_PASSWORD` — 数据库密码
 - `JWT_SECRET` — 足够长的随机字符串
- 首次部署可保持 `SEED_DATABASE=true`，写入演示账号与默认数据；**种子跑完后改回 `false` 并重启 api**
+- `SEED_DATABASE=false` — 保持默认即可；首次部署脚本会在没有 `admin` 时一次性执行生产 seed

-### 3. 构建并启动
+### 3. 首次部署

 ```bash
-docker compose -f docker-compose.prod.yml --env-file .env.docker up -d --build
+chmod +x scripts/*.sh
+./scripts/deploy-first.sh
 ```

-或使用脚本：
+脚本会执行：
+
+- 启动 PostgreSQL / Redis
+- 构建 API、玩家端、管理端镜像
+- 执行 `prisma migrate deploy`
+- 启动全栈容器
+- 如果数据库中没有 `admin`，执行一次生产 seed
+
+如果服务器已经提前 `docker load` 了镜像，不想在服务器构建：

 ```bash
-chmod +x scripts/docker-up.sh
-./scripts/docker-up.sh
+./scripts/deploy-first.sh --no-build
+```
+
+如果上传的是 `thebet365-images.tar`，可让脚本自动加载镜像：
+
+```bash
+./scripts/deploy-first.sh --images thebet365-images.tar
+```
+
+如需全量初始化生产数据（会清空业务表，仅限全新库或明确重置）：
+
+```bash
+./scripts/deploy-first.sh --init-db
 ```

 ### 4. 查看状态
@@ -86,7 +106,8 @@ docker compose -f docker-compose.prod.yml --env-file .env.docker logs -f api
 |------|------|
 | 玩家前台 | http://服务器IP:8082 |
 | 管理后台 | http://服务器IP:8081 |
-| API 文档 | http://服务器IP:3000/api/docs |
+
+API 只在 Docker 网络内暴露，前端容器通过 `/api` 代理到 API。外层域名反代由宝塔网站配置处理。

 ---

@@ -101,7 +122,7 @@ docker compose -f docker-compose.prod.yml --env-file .env.docker logs -f api
   - 环境文件：选择 `.env.docker`（若面板支持）
 4. **构建并启动**

-若面板不支持指定 env 文件，在 **终端** 中执行第三节第 3 步命令即可。
+若面板不支持指定 env 文件，在 **终端** 中执行第三节第 3 步脚本即可。

 ### 方式 B：绑定域名（Nginx 反代）

@@ -121,19 +142,17 @@ location / {

 **管理站** — 将 `8082` 改为 `8081`。

-API 端口 3000 建议**不要**直接公网暴露；Swagger 仅供内网或通过 VPN 访问。
+API 端口 3000 不在生产 compose 中公网映射；Swagger 如需临时查看，建议只在内网或通过 VPN 暴露。

 ---

-## 五、演示账号
+## 五、默认账号

-`SEED_DATABASE=true` 首次启动后可用（生产环境**仅创建 admin**，不含代理/玩家；详见 [默认数据说明.md](./默认数据说明.md)）：
+生产 seed 仅创建平台管理员与基础赛事/内容数据，不创建代理/玩家演示账号；详见 [默认数据说明.md](./默认数据说明.md)。

 | 角色 | 用户名 | 密码 | 入口 |
 |------|--------|------|------|
 | 平台管理员 | admin | Admin@123 | 管理后台 :8081 |
-| 一级代理 | agent1 | Agent@123 | 管理后台 :8081 |
-| 玩家 | player1 | Player@123 | 玩家前台 :8082 |

 ---

@@ -149,8 +168,8 @@ docker compose -f docker-compose.prod.yml --env-file .env.docker down -v
 # 仅重建 API
 docker compose -f docker-compose.prod.yml --env-file .env.docker up -d --build api

-# 手动种子（容器已运行时，仅增量写入，不会删除已有数据）
-docker compose -f docker-compose.prod.yml --env-file .env.docker exec api npx prisma db seed
+# 手动备份数据库
+./scripts/backup-db.sh

 # 全量初始化（生产上线：仅 admin + WC2026 赛事，会先备份到 ./backups/）
 CONFIRM=YES ./scripts/prod-init-db.sh
@@ -183,36 +202,49 @@ pnpm docker:ps
 备份 PostgreSQL 示例：

 ```bash
-docker exec thebet365-postgres pg_dump -U thebet365 thebet365 > backup.sql
+./scripts/backup-db.sh
 ```

 ---

-## 八、更新部署
+## 八、后续更新部署

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

 本地构建并导出镜像的详细步骤见：[docker/镜像构建与导出.md](./docker/镜像构建与导出.md)（脚本位于 `docs/docker/build-and-export-images.ps1` / `build-and-export-images.sh`）。

-```bash
-cd /www/wwwroot
-mv thebet365 thebet365.bak.$(date +%Y%m%d)   # 备份旧目录（保留 .env.docker）
-mkdir thebet365 && cd thebet365
-# 上传并解压新 zip 到当前目录
-cp ../thebet365.bak.*/.env.docker . 2>/dev/null || cp .env.docker.example .env.docker
-
-docker compose -f docker-compose.prod.yml --env-file .env.docker build --no-cache
-docker compose -f docker-compose.prod.yml --env-file .env.docker up -d
-```
-
-若仍覆盖解压，构建前可手动清理：
+### 方式 A：服务器直接拉代码并构建

 ```bash
-find packages/shared/public -mindepth 1 -maxdepth 1 -type d \
-  ! -name flags ! -name players -exec rm -rf {} +
+cd /www/wwwroot/thebet365
+./scripts/deploy-update.sh --pull
 ```

-API 容器启动时会自动执行 `prisma migrate deploy`，无需手动迁移。
+### 方式 B：上传 zip 后在服务器构建
+
+保留原来的 `.env.docker`，替换代码后执行：
+
+```bash
+cd /www/wwwroot/thebet365
+./scripts/deploy-update.sh
+```
+
+### 方式 C：上传已构建镜像包
+
+```bash
+cd /www/wwwroot/thebet365
+./scripts/deploy-update.sh --images thebet365-images.tar
+```
+
+更新脚本默认会：
+
+- 先备份 PostgreSQL 到 `./backups/`
+- 构建或加载新镜像
+- 使用新 API 镜像执行 `prisma migrate deploy`
+- 启动/替换 API、玩家端、管理端容器
+- 执行 `prisma migrate status` 检查数据库迁移状态
+
+除非已经手工确认有其他备份，否则不要使用 `--no-backup`。

 ---

@@ -236,7 +268,7 @@ docker logs thebet365-api

 ### 4. 端口被占用

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

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

@@ -255,6 +287,7 @@ docker compose -f docker-compose.prod.yml --env-file .env.docker build --no-cach
 | 场景 | 命令 |
 |------|------|
 | 本地开发（仅 DB 用 Docker） | `docker compose up -d` + `pnpm dev` |
-| 生产全栈 Docker | `docker compose -f docker-compose.prod.yml --env-file .env.docker up -d --build` |
+| 生产首次部署 | `./scripts/deploy-first.sh` |
+| 生产后续更新 | `./scripts/deploy-update.sh` |

 相关文档：[项目启动指南.md](./项目启动指南.md)
--- a/docs/docker/build-and-export-images.ps1
+++ b/docs/docker/build-and-export-images.ps1
@@ -59,7 +59,9 @@ 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
+服务器首次部署:
+  ./scripts/deploy-first.sh --images thebet365-images.tar
+
+服务器后续更新:
+  ./scripts/deploy-update.sh --images thebet365-images.tar
 "@
--- a/docs/docker/build-and-export-images.sh
+++ b/docs/docker/build-and-export-images.sh
@@ -89,7 +89,9 @@ fi

 cat <<'EOF'

-服务器加载:
-  docker load -i thebet365-images.tar
-  docker compose -f docker-compose.prod.yml --env-file .env.docker up -d
+服务器首次部署:
+  ./scripts/deploy-first.sh --images thebet365-images.tar
+
+服务器后续更新:
+  ./scripts/deploy-update.sh --images thebet365-images.tar
 EOF
--- a/docs/docker/镜像构建与导出.md
+++ b/docs/docker/镜像构建与导出.md
@@ -31,7 +31,7 @@

 - `POSTGRES_PASSWORD`、`JWT_SECRET`
 - `CHUANGLAN_ACCOUNT`、`CHUANGLAN_PASSWORD`（短信注册）
- `SEED_DATABASE`（首次 `true`，灌完数据后改 `false`）
+- `SEED_DATABASE=false`（生产建议保持 false，由部署脚本按需一次性 seed）

 ---

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

 ---

-## 五、上传到服务器并加载
+## 五、上传到服务器并部署

 ### 1. 上传

@@ -106,28 +106,23 @@ chmod +x docs/docker/build-and-export-images.sh

 可用 SCP、宝塔文件管理、rsync 等。

-### 2. 加载镜像
+### 2. 首次部署

 ```bash
 cd /www/wwwroot/thebet365
-docker load -i thebet365-images.tar
+chmod +x scripts/*.sh
+./scripts/deploy-first.sh --images thebet365-images.tar
 ```

-确认镜像：
+后续更新同一个服务器时：

 ```bash
-docker images | grep thebet365
+./scripts/deploy-update.sh --images thebet365-images.tar
 ```

-### 3. 启动服务
+更新脚本会先备份数据库，再用新 API 镜像执行 `prisma migrate deploy`，最后替换运行中的容器。

-```bash
-docker compose -f docker-compose.prod.yml --env-file .env.docker up -d
-```
-
-API 容器启动时会自动执行 `prisma migrate deploy`，一般无需手动迁移。
-
-### 4. 验证
+### 3. 验证

 ```bash
 docker compose -f docker-compose.prod.yml ps
@@ -148,7 +143,7 @@ docker logs thebet365-api --tail 50
 | **本地 build + 导出 tar** | 不占用服务器 CPU/内存；可重复部署同一包 | 需上传较大 tar（约 200–300 MB） |
 | **服务器 `docker compose build`** | 无需传 tar | 首次/全量构建慢，小内存机器易失败 |

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

 ---

--- a/docs/项目启动指南.md
+++ b/docs/项目启动指南.md
@@ -285,15 +285,14 @@ cp /root/thebet365.env.docker.bak .env.docker 2>/dev/null || cp .env.docker.exam
 |------|------|
 | `POSTGRES_PASSWORD` | 数据库密码 |
 | `JWT_SECRET` | 足够长的随机字符串 |
-| `SEED_DATABASE` | 首次部署可 `true`，种子跑完后改 `false` 并重启 api |
+| `SEED_DATABASE` | 生产建议保持 `false`，首次部署脚本会按需一次性 seed |

 构建并启动（首次约 10～20 分钟，**勿提前关终端**）：

 ```bash
 cd /www/wwwroot/thebet365
-
-docker compose -f docker-compose.prod.yml --env-file .env.docker build --no-cache 2>&1 | tee /tmp/thebet365-build.log
-docker compose -f docker-compose.prod.yml --env-file .env.docker up -d
+chmod +x scripts/*.sh
+./scripts/deploy-first.sh
 ```

 查看状态（须带 `--env-file .env.docker`）：
@@ -312,7 +311,8 @@ docker compose -f docker-compose.prod.yml --env-file .env.docker ps
 |------|------|
 | 玩家前台 | `http://你的IP:8082` |
 | 管理后台 | `http://你的IP:8081` |
-| API / Swagger | `http://你的IP:3000/api/docs` |
+
+生产 compose 不公网映射 API 端口，玩家端/管理端容器会通过内部 Docker 网络访问 API。

 ### 8.3 Gitea 私有仓库认证

@@ -384,11 +384,10 @@ git push

 ```bash
 cd /www/wwwroot/thebet365
-git pull
-docker compose -f docker-compose.prod.yml --env-file .env.docker up -d --build
+./scripts/deploy-update.sh --pull
 ```

- 仅改文档、未改代码/依赖时，可省略 `--build`：`up -d` 即可
+- 更新脚本会先备份数据库，再构建新镜像、执行 Prisma 迁移并替换容器
 - **不要**把 `.env.docker` 提交到 Git；服务器上单独保留
 - `release/*.zip` 为旧打包方式，Git 同步后不必再生成上传

@@ -408,19 +407,17 @@ cd /www/wwwroot/thebet365
 # 容器是否在跑
 docker compose -f docker-compose.prod.yml --env-file .env.docker ps

-# 构建失败时看日志
-tail -50 /tmp/thebet365-build.log
+# 容器启动失败时看日志
 docker compose -f docker-compose.prod.yml --env-file .env.docker logs --tail=30 player
 docker compose -f docker-compose.prod.yml --env-file .env.docker logs --tail=30 api

 # 本机探测（在服务器上）
 curl -I http://127.0.0.1:8082
-curl -I http://127.0.0.1:3000/api/docs
 ```

-**`ps` 为空**：说明从未成功 `up`，或构建被中断 — 重新执行 8.2 中的 `build` + `up`。
+**`ps` 为空**：说明从未成功部署，或构建被中断 — 重新执行 8.2 中的 `./scripts/deploy-first.sh`。

-**终端被关掉**：构建可能仍在后台跑，也可能已失败；用上面命令查 `ps` 和 `/tmp/thebet365-build.log`。
+**终端被关掉**：构建可能仍在后台跑，也可能已失败；用上面命令查 `ps` 和容器日志。

 ### 8.6 从 zip 迁移到 Git（一次性）

@@ -508,8 +505,8 @@ pnpm db:seed

 - 未加 `--env-file .env.docker` 时可能看不到本项目容器，请用：  
  `docker compose -f docker-compose.prod.yml --env-file .env.docker ps`
- 若仍为空：构建未完成或失败，重新 `build --no-cache` 再 `up -d`，见 **第八节 8.5**
- 构建日志：`tail -50 /tmp/thebet365-build.log`
+- 若仍为空：构建未完成或失败，重新执行 `./scripts/deploy-first.sh`，见 **第八节 8.5**
+- 构建失败原因以部署脚本当前终端输出为准；容器启动失败再看 `docker compose logs`

 ### 10. 服务器 player 构建报 `ENOENT ... public/球员`

@@ -520,7 +517,7 @@ pnpm db:seed
 find packages/shared/public -mindepth 1 -maxdepth 1 -type d \
  ! -name flags ! -name players -exec rm -rf {} +
 docker compose -f docker-compose.prod.yml --env-file .env.docker build --no-cache player admin
-docker compose -f docker-compose.prod.yml --env-file .env.docker up -d
+./scripts/deploy-update.sh --no-build
 ```

 ### 11. 宝塔 Redis 里看到 `lottery-database-*` 等 key
--- a/docs/默认数据说明.md
+++ b/docs/默认数据说明.md
@@ -1,9 +1,9 @@
 # 默认数据说明

-执行 `pnpm db:migrate` 后数据库仅有**表结构**；执行 **`pnpm db:seed`** 后会写入下文演示数据。  
+执行 `pnpm db:migrate` 后数据库仅有**表结构**；执行 **`pnpm db:seed`** 后会写入下文默认数据。
 种子脚本位置：`apps/api/prisma/seed.ts`。

-> **注意**：以下为开发演示用途。生产环境务必修改密码、`JWT_SECRET`，勿直接使用默认账号。
+> **注意**：生产环境务必修改密码、`JWT_SECRET`，勿长期使用默认管理员密码。

 ---

@@ -24,9 +24,11 @@
 | 用户名 | 密码 | 角色 | 说明 |
 |--------|------|------|------|
 | `admin` | `Admin@123` | 平台管理员 | 绑定 `SUPER_ADMIN` 角色 |
-| `agent1` | `Agent@123` | 一级代理 | 授信额度 **100,000** |
-| `agent2` | `Agent@123` | 二级代理 | 上级为 agent1，授信 **30,000** |
-| `player1` | `Player@123` | 玩家 | 挂靠 agent1 |
+| `agent1` | `Agent@123` | 一级代理 | 仅 dev seed 写入，授信额度 **100,000** |
+| `agent2` | `Agent@123` | 二级代理 | 仅 dev seed 写入，上级为 agent1，授信 **30,000** |
+| `player1` | `Player@123` | 玩家 | 仅 dev seed 写入，挂靠 agent1 |
+
+生产模式 seed 只写入 `admin` 和赛事目录数据，不写入代理、玩家、充值流水或注单。

 | 入口 | 地址 |
 |------|------|
@@ -71,18 +73,20 @@

 | 代码 | 名称 |
 |------|------|
-| `EPL` | 英超 / Premier League |
 | `WC2026` | 2026 世界杯（加拿大、墨西哥、美国） |

-### 已发布场次（约 9 场）
+### 已发布场次

- **英超 2 场**：如曼联 vs 切尔西（开球时间为相对当前的演示时间）
- **世界杯 7 场**：如墨西哥-南非、美国-巴拉圭、法国-阿根廷等（2026-06 固定日期）
+- **世界杯小组赛 72 场**：含 2026-06 固定日期、场馆、分组、球队中英文名。
+- 球队图片使用公开 FlagCDN 国旗 URL，例如 `https://flagcdn.com/fr.svg`；不再使用旧的赛事图片源。
+- 默认赛事全部为非热门赛事，玩家首页不会因为 seed 数据自动出现热门赛事。

 每场在尚无盘口时会自动创建演示玩法，包括但不限于：

 - 全场 / 半场：独赢、让球、大小、单双  
- 全场 / 半场 / 下半场：波胆（多档比分选项）  
+- 全场：波胆（多档比分选项）
+
+默认足球盘口模板与赛事 seed **不创建** `HT_CORRECT_SCORE`（上半场波胆）和 `SH_CORRECT_SCORE`（下半场波胆）。这两个盘口类型仍保留在系统识别能力中，便于兼容历史数据或后续手动扩展。

 赔率均为种子脚本中的**示例数值**，可在管理后台赛事相关流程中调整（非冠军盘）。

@@ -108,7 +112,7 @@
 | 可用余额 | **88,888.88** |
 | 账变流水 | 2 笔演示充值（`DEMO-DEP-001` / `DEMO-DEP-002`） |
 | 语言偏好 | `zh-CN` |
-| 示例注单 | `DEMO-BET-001`：待结算单关；`DEMO-BET-002`：已赢且已结算单关 |
+| 示例注单 | 默认不写入演示注单 |

 ---

@@ -182,6 +186,14 @@ pnpm db:migrate
 pnpm db:seed
 ```

+生产服务器如需清空业务数据并写入正规默认数据，优先使用脚本：
+
+```bash
+CONFIRM=YES ./scripts/prod-init-db.sh
+```
+
+该脚本会先备份 PostgreSQL，再执行 Prisma 迁移，然后以 production 模式清空业务表并写入 `admin`、WC2026 小组赛 72 场和 48 强优胜盘。
+
 ---

 ## 十、相关文档