From 55a7043cbda88495ff03891eb6641212d5300ab3 Mon Sep 17 00:00:00 2001 From: Mars <3361409208a@gmail.com> Date: Mon, 8 Jun 2026 17:40:47 +0800 Subject: [PATCH] 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 --- docs/项目启动指南.md | 228 ++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 216 insertions(+), 12 deletions(-) diff --git a/docs/项目启动指南.md b/docs/项目启动指南.md index 14449a7..ea8adf1 100644 --- 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 '*'` + --- ## 十、推荐日常开发顺序