docs: add server Git sync and Docker deploy guide

Document Gitea SSH/HTTPS auth, daily git pull workflow, and common server deployment troubleshooting in the project startup guide. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-08 17:40:47 +08:00
parent d5913b6301
commit 55a7043cbd
1 changed files with 216 additions and 12 deletions
--- a/docs/项目启动指南.md
+++ b/docs/项目启动指南.md
@@ -48,9 +48,12 @@ thebet365/
 ### 1. 克隆并进入项目

 ```bash
+git clone https://gitea.dengshikj.com/ysc/thebet365.git
 cd thebet365
 ```

+私有库 SSH 与服务器认证见 **第八节 8.3**。
+
 ### 2. 启动数据库（二选一）

 #### 方案 A：Docker（已安装 Docker Desktop 时）
@@ -229,6 +232,7 @@ pnpm dev:player
 | `pnpm db:migrate` | 开发迁移 |
 | `pnpm db:seed` | 种子数据（含 WC2026 48 强夺冠） |
 | `pnpm db:studio` | Prisma Studio |
+| `pnpm pack:deploy` | 生成 zip 部署包（无 Git 时备用，见 `pack.mjs`） |

 ---

@@ -240,32 +244,208 @@ pnpm dev:player

 ---

-## 八、生产构建（简述）
+## 八、服务器生产部署（Docker + Git）

-### 方式 A：Docker 全栈一键部署（推荐）
+生产环境推荐：**服务器用 Git 拉代码 + Docker Compose 全栈部署**，不必每次本地打 zip 上传。
+
+完整架构与端口说明见 **[Docker部署指南.md](./Docker部署指南.md)**。
+
+### 8.1 服务器要求
+
+| 项目 | 要求 |
+|------|------|
+| 系统 | Linux（阿里云 ECS + 宝塔面板常见） |
+| Docker | 24+，Compose v2（`docker compose`） |
+| 内存 | 建议 ≥ 2 GB（首次构建较耗内存） |
+| 代码目录 | 例如 `/www/wwwroot/thebet365` |
+
+### 8.2 首次部署（Git 克隆）
+
+在服务器 **宝塔 → 终端** 或 SSH 中执行：

 ```bash
-cp .env.docker.example .env.docker   # 修改 POSTGRES_PASSWORD、JWT_SECRET
+cd /www/wwwroot
+
+# 1. 若已有 zip 解压的旧目录，先备份配置并改名
+cp thebet365/.env.docker /root/thebet365.env.docker.bak 2>/dev/null || true
+mv thebet365 thebet365.bak 2>/dev/null || true
+
+# 2. 从 Gitea 克隆（地址按你的仓库为准）
+git clone https://gitea.dengshikj.com/ysc/thebet365.git thebet365
+
+cd thebet365
+
+# 3. 恢复或创建生产环境配置
+cp /root/thebet365.env.docker.bak .env.docker 2>/dev/null || cp .env.docker.example .env.docker
+```
+
+编辑 `.env.docker`，**生产务必修改**：
+
+| 变量 | 说明 |
+|------|------|
+| `POSTGRES_PASSWORD` | 数据库密码 |
+| `JWT_SECRET` | 足够长的随机字符串 |
+| `SEED_DATABASE` | 首次部署可 `true`，种子跑完后改 `false` 并重启 api |
+
+构建并启动（首次约 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
+```
+
+查看状态（须带 `--env-file .env.docker`）：
+
+```bash
+docker compose -f docker-compose.prod.yml --env-file .env.docker ps
+```
+
+成功时应看到 5 个容器均为 `Up`：
+
+- `thebet365-postgres`、`thebet365-redis`、`thebet365-api`、`thebet365-player`、`thebet365-admin`
+
+访问（将 `你的IP` 换成服务器公网 IP，并在安全组/防火墙放行端口）：
+
+| 应用 | 地址 |
+|------|------|
+| 玩家前台 | `http://你的IP:8080` |
+| 管理后台 | `http://你的IP:8081` |
+| API / Swagger | `http://你的IP:3000/api/docs` |
+
+### 8.3 Gitea 私有仓库认证
+
+私有库克隆/拉取前需配置认证。**推荐 SSH**（配一次，以后 `git pull` 无需密码）。
+
+#### 方式 A：SSH 密钥（推荐）
+
+在**服务器**执行：
+
+```bash
+# 1. 生成密钥（无 passphrase，便于自动拉代码）
+ssh-keygen -t ed25519 -C "aliyun-thebet365" -f ~/.ssh/id_ed25519 -N ""
+
+# 2. 查看公钥（整行复制）
+cat ~/.ssh/id_ed25519.pub
+
+# 3. 测试连接（首次输入 yes）
+ssh -T git@gitea.dengshikj.com
+```
+
+在 **Gitea 网页**：头像 → **设置** → **SSH / GPG 密钥** → **添加密钥**，粘贴公钥。
+
+使用 SSH 地址克隆：
+
+```bash
+git clone git@gitea.dengshikj.com:ysc/thebet365.git thebet365
+```
+
+已用 HTTPS 克隆时可改远程地址：
+
+```bash
+cd /www/wwwroot/thebet365
+git remote set-url origin git@gitea.dengshikj.com:ysc/thebet365.git
+```
+
+#### 方式 B：HTTPS + Access Token
+
+1. Gitea → **设置** → **应用 / Access Tokens** → 生成令牌（勾选 `read:repository`）
+2. 克隆时 **Password 填 Token**，不是登录密码：
+
+```bash
+git clone https://gitea.dengshikj.com/ysc/thebet365.git thebet365
+```
+
+记住凭据（避免每次 `git pull` 输入）：
+
+```bash
+git config --global credential.helper store
+cd /www/wwwroot/thebet365
+git pull   # 再输一次用户名 + Token
+```
+
+| 对比 | SSH | HTTPS + Token |
+|------|-----|----------------|
+| 推荐场景 | 服务器长期部署 | 临时测试 |
+| 体验 | 配好后免密 | 需 credential.helper |
+
+### 8.4 日常更新（不用打 zip）
+
+**本地开发机：**
+
+```bash
+git add .
+git commit -m "你的修改说明"
+git push
+```
+
+**服务器（宝塔终端）：**
+
+```bash
+cd /www/wwwroot/thebet365
+git pull
 docker compose -f docker-compose.prod.yml --env-file .env.docker up -d --build
 ```

-玩家 `:8080` · 管理 `:8081` · API `:3000`。完整说明见 **[Docker部署指南.md](./Docker部署指南.md)**。
+- 仅改文档、未改代码/依赖时，可省略 `--build`：`up -d` 即可
+- **不要**把 `.env.docker` 提交到 Git；服务器上单独保留
+- `release/*.zip` 为旧打包方式，Git 同步后不必再生成上传

-### 方式 B：宿主机 + Nginx
+若 `git pull` 冲突且可接受覆盖为远程版本：
+
+```bash
+git fetch origin
+git reset --hard origin/main
+# 再确认 .env.docker 仍在
+```
+
+### 8.5 部署状态检查
+
+```bash
+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:8080
+curl -I http://127.0.0.1:3000/api/docs
+```
+
+**`ps` 为空**：说明从未成功 `up`，或构建被中断 — 重新执行 8.2 中的 `build` + `up`。
+
+**终端被关掉**：构建可能仍在后台跑，也可能已失败；用上面命令查 `ps` 和 `/tmp/thebet365-build.log`。
+
+### 8.6 从 zip 迁移到 Git（一次性）
+
+若目录原是 zip 解压、没有 `.git`：
+
+```bash
+cd /www/wwwroot
+cp thebet365/.env.docker /root/thebet365.env.docker.bak
+mv thebet365 thebet365.bak
+git clone git@gitea.dengshikj.com:ysc/thebet365.git thebet365   # 或 HTTPS
+cd thebet365 && cp /root/thebet365.env.docker.bak .env.docker
+```
+
+### 8.7 宿主机 + Nginx（可选）
+
+不用 Docker 全栈时：

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

-生产务必：
-
-1. 修改 `JWT_SECRET` 与数据库密码  
-2. 使用 `db:migrate:deploy` 而非 `migrate dev`  
-3. 配置 `NODE_ENV=production` 与真实 `DATABASE_URL`
+生产务必：`JWT_SECRET`、数据库密码、`db:migrate:deploy`、`NODE_ENV=production`。

 ---

@@ -324,6 +504,30 @@ pnpm db:seed

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

+### 9. 服务器 `docker compose ps` 为空
+
+- 未加 `--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`
+
+### 10. 服务器 player 构建报 `ENOENT ... public/球员`
+
+- 原因：旧版中文目录 `packages/shared/public/球员/` 在 Linux 编码异常；或 zip 覆盖解压后残留旧目录
+- 处理：确保 `git pull` 到最新（含 `packages/shared/public/players/`），并清理：
+
+```bash
+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
+```
+
+### 11. 宝塔 Redis 里看到 `lottery-database-*` 等 key
+
+- 那是**宿主机上其他项目**（彩票系统）的数据，与 thebet365 Docker 内 `thebet365-redis` **不是同一个实例**
+- 查看本项目 Redis：`docker exec -it thebet365-redis redis-cli KEYS '*'`
+
 ---

 ## 十、推荐日常开发顺序