thebet365/docs/项目启动指南.md

TheBet365 项目启动指南

本文档汇总本地开发、首次部署与日常启动所需的全部步骤与配置说明。

---

一、环境要求

工具	版本要求	说明
Node.js	≥ 20	见根目录 package.json → engines
pnpm	8+（推荐最新）	Monorepo 包管理，需先 corepack enable 或全局安装
Docker	最新稳定版（可选）	推荐：一键起 PostgreSQL；也可用本机安装的 Postgres
PostgreSQL	14+（推荐 16）	必需（API / Prisma）
Git	任意	拉取代码

当前 API 仅依赖 PostgreSQL；docker-compose 里的 Redis 为预留，未安装 Redis 一般不影响本地开发。

可选：

• Docker Compose v2（docker compose，非旧版 docker-compose）
• Windows 用户建议使用 PowerShell 或 Windows Terminal

---

二、仓库结构速览

thebet365/
├── apps/
│   ├── api/          NestJS 后端（Prisma + PostgreSQL）
│   ├── admin/        管理后台（平台管理员 + 代理，:5174）
│   └── player/       玩家 H5 前台（:5173）
├── packages/
│   └── shared/       共享类型与静态资源（public）
├── uploads/          上传文件目录（Banner 等，API 静态托管）
├── docker-compose.yml
├── .env.example      环境变量模板
└── package.json      根脚本（dev / db:*）

---

三、首次启动（完整流程）

按顺序执行，只需做一次（或换机器 / 清空数据库后重做）。

1. 克隆并进入项目

cd thebet365

2. 启动数据库（二选一）

方案 A：Docker（已安装 Docker Desktop 时）

docker compose up -d
docker compose ps

服务	容器名	端口	默认账号
PostgreSQL 16	thebet365-postgres	5432	用户/密码/库：thebet365
Redis 7	thebet365-redis	6379	无密码（可选）

apps/api/.env 使用：

DATABASE_URL=postgresql://thebet365:thebet365@localhost:5432/thebet365

停止：docker compose down · 清空数据卷（慎用）：docker compose down -v

Windows 未识别 docker 命令时：安装 Docker Desktop for Windows，安装后重启 PowerShell，并确保设置里已勾选 Use WSL 2（推荐）。也可用 winget：

winget install Docker.DockerDesktop

方案 B：本机 PostgreSQL（无 Docker）

1. 安装 PostgreSQL 16（任选其一）：
   • https://www.postgresql.org/download/windows/
   • 或 winget install PostgreSQL.PostgreSQL.16
2. 安装时记住 超级用户密码（默认用户常为 postgres）。
3. 用 pgAdmin 或 psql 创建与项目一致的数据库（也可改用你自己的账号，同步改 DATABASE_URL）：

CREATE USER thebet365 WITH PASSWORD 'thebet365';
CREATE DATABASE thebet365 OWNER thebet365;
GRANT ALL PRIVILEGES ON DATABASE thebet365 TO thebet365;

4. 编辑 apps/api/.env：

DATABASE_URL=postgresql://thebet365:thebet365@localhost:5432/thebet365

若只用默认 postgres 用户：

DATABASE_URL=postgresql://postgres:你的密码@localhost:5432/thebet365

（需已 CREATE DATABASE thebet365;）

5. 确认本机 5432 端口 Postgres 服务已启动（Windows「服务」里 postgresql-x64-16 为「正在运行」）。

3. 安装依赖

在仓库根目录执行：

pnpm install

4. 配置环境变量

将根目录模板复制到 API 目录（Nest 从 apps/api 工作目录读取 .env）：

cp .env.example apps/api/.env

apps/api/.env 主要项说明：

变量	示例值	说明
DATABASE_URL	postgresql://thebet365:thebet365@localhost:5432/thebet365	须与 docker-compose 一致
REDIS_URL	redis://localhost:6379	预留，与 compose 中 Redis 对应
JWT_SECRET	长随机字符串	生产环境务必修改
JWT_PLAYER_EXPIRES	24h	玩家 Token 有效期
JWT_ADMIN_EXPIRES	2h	管理员 Token
JWT_AGENT_EXPIRES	8h	代理 Token
PORT	3000	API 监听端口
NODE_ENV	development	开发环境
UPLOAD_DIR	留空	默认使用 apps/api/uploads；可填绝对路径

5. 数据库迁移与种子数据

仍在仓库根目录：

pnpm db:generate   # 生成 Prisma Client（改 schema 后需要）
pnpm db:migrate    # 执行迁移（开发环境，可交互命名）
pnpm db:seed       # 演示账号、赛事、世界杯 48 强夺冠盘等

生产环境部署迁移使用：

pnpm --filter @thebet365/api db:migrate:deploy

可视化查看数据（可选）：

pnpm db:studio

6. 启动开发服务

方式 A：一键启动全部（API + admin + player + shared 编译监听）

pnpm dev

方式 B：分终端启动（推荐调试时）

# 终端 1 — 必须先起 API
pnpm dev:api

# 终端 2 — 管理后台
pnpm dev:admin

# 终端 3 — 玩家前台
pnpm dev:player

dev:manage 与 dev:admin 相同，均为管理后台。

---

四、访问地址

应用	地址	说明
API	http://localhost:3000/api	全局前缀 api
Swagger	http://localhost:3000/api/docs	接口文档
玩家前台	http://localhost:5173	Vite 代理 /api → :3000
管理后台	http://localhost:5174	Vite 代理 /api → :3000
静态上传	http://localhost:3000/uploads/...	玩家端也可经 :5173/uploads 代理

前端开发时无需单独配置 CORS，Vite 已将 /api（玩家端含 /uploads）反向代理到 API。

---

五、演示账号与默认数据

pnpm db:seed 写入账号、赛事、48 强夺冠、Banner 等。完整清单见 默认数据说明.md。

角色	用户名	密码	登录入口
平台管理员	admin	Admin@123	管理后台 http://localhost:5174
一级代理	agent1	Agent@123	同上（菜单为代理端）
二级代理	agent2	Agent@123	同上
玩家	player1	Player@123	玩家前台 http://localhost:5173

管理端：POST /api/manage/auth/login · 玩家端：POST /api/player/auth/login

---

六、根目录常用命令

命令	作用
pnpm dev	并行启动各 app 的 dev 脚本
pnpm dev:api	仅 API（watch）
pnpm dev:admin	仅管理后台
pnpm dev:player	仅玩家前台
pnpm build	构建所有 workspace 包
pnpm test	运行各包测试
pnpm db:generate	Prisma Client 生成
pnpm db:migrate	开发迁移
pnpm db:seed	种子数据（含 WC2026 48 强夺冠）
pnpm db:studio	Prisma Studio

---

七、业务数据与上传目录

详见 默认数据说明.md（赛事、盘口、48 强夺冠、player1 余额与注单、Banner 等）。

• 上传目录默认：apps/api/uploads/（可由 UPLOAD_DIR 覆盖）

---

八、生产构建（简述）

pnpm install
pnpm build
# API
pnpm --filter @thebet365/api start
# 前端产物在各自 apps/*/dist，由 Nginx 等托管，并反向代理 /api 到后端

生产务必：

1. 修改 JWT_SECRET 与数据库密码
2. 使用 db:migrate:deploy 而非 migrate dev
3. 配置 NODE_ENV=production 与真实 DATABASE_URL

---

九、常见问题

1. PowerShell 提示「无法将 docker 识别为 cmdlet」

• 未安装 Docker，或未加入 PATH → 用上文 方案 B 本机 PostgreSQL，或安装 Docker Desktop 后重启终端。

2. P3015 / Could not find the migration file at migration.sql

• 原因：apps/api/prisma/migrations/ 下某个迁移目录缺少 migration.sql（例如空的 20260602120000_user_preference_contact）。
• 处理：拉取最新代码后重试 pnpm db:migrate；若本地曾误删该文件，需从仓库恢复或删除空目录后重新 prisma migrate dev。
• 说明：若 pnpm db:seed 已成功，说明表结构多半已可用，可先 pnpm dev:api 开发；仍建议修好 migrate 以便团队协作。

若修复文件后提示 Drift detected（库里有字段但迁移历史未记录），在 apps/api 下将已存在的迁移标记为已应用（不删数据）：

cd apps/api
pnpm exec prisma migrate resolve --applied 20260602120000_user_preference_contact
pnpm exec prisma migrate resolve --applied 20260603102323_zhibo_match_fields
pnpm db:migrate

仍无法收敛且可接受清空库时：pnpm exec prisma migrate reset（会删库），再 pnpm db:seed。

3. pnpm db:migrate 连接数据库失败

• Docker 方案：确认 docker compose up -d 且 Postgres 健康
• 本机方案：确认 PostgreSQL 服务已启动、库 thebet365 已创建
• 检查 apps/api/.env 中 DATABASE_URL 主机/端口/账号/密码

4. 管理后台文案显示为 key（如 user.field.xxx）

• 勿在 apps/admin/src 下保留误生成的 *.js（会抢先于 .ts 被 Vite 加载）
• 清理缓存后重启：apps/admin/node_modules/.vite
• 硬刷新浏览器（Ctrl+Shift+R）

5. 前端接口 502 / 代理错误

• 必须先启动 pnpm dev:api，再开 admin/player

6. agent-form 等模块导出报错

• 同上，删除 apps/admin/src 内过期 .js，重启 dev server

7. 夺冠盘不足 48 队

pnpm db:seed

或在管理后台 世界杯夺冠 → 应用表格基准数据。

8. Windows 下 Prisma / ts-node 权限问题

• 以管理员运行终端，或关闭占用 5432 端口的其他 Postgres 实例

---

十、推荐日常开发顺序

1. docker compose up -d
2. pnpm dev:api          # 等 API 打印 running
3. pnpm dev:admin      # 或 pnpm dev:player
4. 浏览器打开对应端口

改 Prisma schema 后：

pnpm db:generate && pnpm db:migrate

---

十一、相关文档

• README.md — 项目概览与技术栈
• 默认数据说明.md — seed 后的账号、赛事、夺冠盘、运营内容
• apps/admin/README.md — 管理后台结构
• 足球投注平台产品需求与MVP实施计划_PRD_v1.2.md — 产品需求（若存在）

---

文档随仓库脚本与端口变更时请同步更新。