thebet365/docs/docker/镜像构建与导出.md

Docker 镜像构建与导出

本文档说明如何在本地或 CI 机器上构建 api / player / admin 三个生产镜像，并导出为 tar 包，便于上传到服务器离线加载部署。

全栈部署流程见上级文档：Docker部署指南.md

---

一、脚本位置

脚本与本文档同目录 docs/docker/：

文件	适用环境
docs/docker/build-and-export-images.bat	Windows（CMD，构建全部）
docs/docker/build-and-export-api.bat	Windows（仅 api，可双击）
docs/docker/build-and-export-player.bat	Windows（仅单分支 player，可双击）
docs/docker/build-and-export-player-main.bat	Windows（仅主站/暗金主题，自动切分支）
docs/docker/build-and-export-player-theme-2.bat	Windows（仅 theme-2 蓝白主题，自动切分支）
docs/docker/build-and-export-player-theme-3.bat	Windows（仅 theme-3 移动主题，自动切分支）
docs/docker/build-and-export-player-theme-4.bat	Windows（仅 theme-4 海军蓝极简，自动切分支）
docs/docker/build-and-export-admin.bat	Windows（仅 admin，可双击）
docs/docker/build-and-export-all-themes.bat	Windows（四套主题 player 一键打包，自动切分支）
docs/docker/build-and-export-images.ps1	Windows（PowerShell）
docs/docker/build-and-export-images.sh	Linux / macOS / Git Bash

两个脚本行为一致：在项目根目录执行 compose 构建 → 导出 tar（默认 tag 为 latest），并生成同名 .manifest.txt。

默认 tag 为 latest，服务器 docker load 后可直接 compose up，无需再 docker tag。版本追溯见 manifest 里的 git_commit。若需保留多版本 tag，可传 --tag v1.2.3。

---

二、前置条件

1. 已安装 Docker 与 Docker Compose v2（docker compose）
2. 项目根目录存在 docker-compose.prod.yml
3. 环境变量文件（二选一）：
   • 推荐：.env.docker（从 .env.docker.example 复制并修改）
   • 若无 .env.docker，脚本会回退使用 .env.docker.example 并给出警告

生产环境务必在 .env.docker 中配置：

• POSTGRES_PASSWORD、JWT_SECRET
• IMAGE_TAG、BIND_ADDR、RUN_MIGRATIONS_ON_START 保持 .env.docker.example 默认即可，部署脚本会按 --tag 写回真实版本
• CHUANGLAN_ACCOUNT、CHUANGLAN_PASSWORD（短信注册）
• SEED_DATABASE=false（生产建议保持 false，由部署脚本按需一次性 seed）

---

三、使用方法

Windows

推荐（CMD / 双击）： 在项目根目录打开命令提示符，或直接双击对应 bat：

docs\docker\build-and-export-images.bat
docs\docker\build-and-export-api.bat
docs\docker\build-and-export-player.bat
docs\docker\build-and-export-admin.bat

单服务 bat 等价于 build-and-export-images.bat --service <name>，其余参数（--use-cache、--export-only、--tag 等）照常追加即可，例如：

docs\docker\build-and-export-admin.bat --use-cache

PowerShell 也可用：

.\docs\docker\build-and-export-images.ps1

Linux / Git Bash

在项目根目录：

chmod +x docs/docker/build-and-export-images.sh
./docs/docker/build-and-export-images.sh

可选参数

BAT / PowerShell	Bash	说明
--service admin / -Service admin	--service admin	只构建/导出单个服务（api / player / admin / all）
--tag v1.2.3 / -Tag v1.2.3	--tag v1.2.3	指定镜像 tag；默认 latest
（默认）	（默认）	--no-cache 全量构建，适合发版
--use-cache / -UseCache	--use-cache	使用 Docker 缓存，构建更快
--export-only / -ExportOnly	--export-only	跳过构建，仅导出已有指定 tag 镜像
--output my.tar / -Output my.tar	--output my.tar	自定义导出文件名

默认导出文件名：

范围	默认 tar
全部	thebet365-images-latest.tar
仅 admin	thebet365-admin-latest.tar
仅 api	thebet365-api-latest.tar
仅 player	thebet365-player-latest.tar

示例：只打包 admin（含邀请链接 VITE_PLAYER_URL）

docs\docker\build-and-export-images.bat --service admin

示例：仅重新导出已有镜像

docs\docker\build-and-export-images.bat --export-only

.\docs\docker\build-and-export-images.ps1 -ExportOnly

./docs/docker/build-and-export-images.sh --export-only

---

三、四套主题玩家端打包

关联文档：四套主题Docker部署任务.md「阶段 C」

一键打包（推荐）

脚本会自动：切到各主题分支 → 构建 player 镜像 → 导出 tar → 切回原分支 → 构建 api/admin。

cd C:\path\to\thebet365
docs\docker\build-and-export-all-themes.bat

可选参数：

参数	说明
--use-cache	使用 Docker 层缓存，加快重复构建速度
--export-only	跳过构建，仅导出本地已有镜像
--skip-api-admin	只打四套 player，跳过 api/admin

产物

tar 文件	加载后镜像名
thebet365-player-main.tar	thebet365-player:main
thebet365-player-theme-2.tar	thebet365-player:theme-2
thebet365-player-theme-3.tar	thebet365-player:theme-3
thebet365-player-theme-4.tar	thebet365-player:theme-4
thebet365-images-latest.tar	thebet365-api:latest + thebet365-admin:latest

分支要求

• 执行前确保 main、theme-2、theme-3、theme-4 四个分支在本地均已拉取
• 工作区若有未提交变更，脚本会给出 WARN；建议先 git stash 后再运行
• 若某一分支切换失败，该分支会被跳过并标记失败，其余分支仍继续构建

手动逐一打包（有明确失败时）

git checkout main
docs\docker\build-and-export-images.bat --service player --tag main

git checkout theme-2
docs\docker\build-and-export-images.bat --service player --tag theme-2

git checkout theme-3
docs\docker\build-and-export-images.bat --service player --tag theme-3

git checkout theme-4
docs\docker\build-and-export-images.bat --service player --tag theme-4

REM 最后打 api + admin
git checkout main
docs\docker\build-and-export-images.bat --tag latest

---

四、构建产物

镜像名	说明
thebet365-api:<tag>	NestJS API（迁移由部署脚本执行）
thebet365-player:<tag>	玩家前台（Nginx 静态资源）
thebet365-admin:<tag>	管理后台（Nginx 静态资源）

导出文件默认路径：

<项目根目录>/thebet365-images-<tag>.tar
<项目根目录>/thebet365-images-<tag>.manifest.txt

这些文件已加入 .gitignore，请勿提交到 Git。manifest 会记录 tag、构建时间、Git commit、镜像 ID 和 tar 的 SHA-256，便于服务器核对发布包。

---

五、上传到服务器并部署

完整分步说明（本地打包 → 上传 → 终端执行 → 验证）见上级文档 Docker部署指南.md 第八节。

1. 上传

将以下内容传到服务器同一目录（如 /www/wwwroot/thebet365）：

• thebet365-images-<tag>.tar
• thebet365-images-<tag>.manifest.txt
• docker-compose.prod.yml
• .env.docker（或服务器上已有配置）
• docker/nginx/ 等 compose 依赖目录（若仅 load 镜像、不 rebuild，compose 文件仍需要）

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

2. 首次部署

cd /www/wwwroot/thebet365
chmod +x scripts/*.sh
./scripts/deploy-first.sh --images thebet365-images-v1.2.3.tar --tag v1.2.3

后续更新同一个服务器时：

./scripts/deploy-update.sh --images thebet365-images-v1.2.3.tar --tag v1.2.3

更新脚本会先备份数据库与 uploads，再用新 API 镜像执行 prisma migrate deploy，最后替换运行中的容器并等待健康检查通过。

3. 验证

docker compose -f docker-compose.prod.yml ps
docker logs thebet365-api --tail 50

浏览器访问（端口以 .env.docker 为准）：

• 玩家端：经宝塔反代访问，或服务器本机 http://127.0.0.1:8082
• 管理端：经宝塔反代访问，或服务器本机 http://127.0.0.1:8081

---

六、与「服务器上直接 build」的区别

方式	优点	缺点
本地 build + 导出 tar	不占用服务器 CPU/内存；有 tag 与 manifest，可重复部署同一包	需上传较大 tar（约 200–300 MB）
服务器 docker compose build	无需传 tar	首次/全量构建慢，小内存机器易失败

发版推荐流程：本地或构建机执行脚本 → 上传 tar + manifest → 服务器执行 deploy-update.sh --images thebet365-images-<tag>.tar --tag <tag>。

---

七、常见问题

1. 构建时提示 CHUANGLAN_* variable is not set

仅为 警告，不影响镜像构建；运行时请在 .env.docker 中补全创蓝配置，否则短信验证码无法发送。

2. player / admin 构建失败 ENOENT ... public/球员

旧包残留中文目录。清理后重试：

find packages/shared/public -mindepth 1 -maxdepth 1 -type d \
  ! -name flags ! -name players -exec rm -rf {} +

3. docker load 后部署仍找不到镜像

确保上传的 tar 中包含 thebet365-api:<tag>、thebet365-player:<tag>、thebet365-admin:<tag>，并且服务器执行部署时传入同一个 --tag <tag>。

4. API 启动后不断重启

docker logs thebet365-api

常见原因：数据库未就绪、DATABASE_URL 与 POSTGRES_PASSWORD 不一致、迁移失败。

---

八、相关文件

thebet365/
├── docker-compose.prod.yml
├── .env.docker.example
├── thebet365-images-<tag>.tar       # 导出产物（默认，已 gitignore）
├── thebet365-images-<tag>.manifest.txt
├── docker/
│   ├── api/Dockerfile
│   ├── player/Dockerfile
│   ├── admin/Dockerfile
│   └── nginx/
└── docs/
    ├── Docker部署指南.md
    └── docker/
        ├── 镜像构建与导出.md        # 本文档
        ├── build-and-export-images.bat
        ├── build-and-export-images.ps1
        └── build-and-export-images.sh