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

# Docker 镜像构建与导出

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

> 全栈部署流程见上级文档：[Docker部署指南.md](../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.ps1` | Windows（**四套主题 player 一键打包**，自动切分支，推荐） |
| `docs/docker/build-and-export-all-themes.bat` | Windows（同上，薄包装启动器，双击可用） |
| `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：

```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` 等）照常追加即可，例如：

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

PowerShell 也可用：

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

### Linux / Git Bash

在项目根目录：

```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`）

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

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

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

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

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

---

## 三、四套主题玩家端打包

> 关联文档：[四套主题Docker部署任务.md](../四套主题Docker部署任务.md)「阶段 C」

### 一键打包（推荐）

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

> **为何用 PowerShell？** 本脚本仅存在于 `main` 分支；执行过程中会 `git checkout theme-*`，CMD 批处理会从磁盘逐行读取，切分支后脚本文件消失会导致中断。PowerShell 启动时已将整份脚本载入内存，可安全跨分支执行。`.bat` 仅为薄包装，内部转调 `.ps1`。

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

或双击 / CMD：

```bat
docs\docker\build-and-export-all-themes.bat
```

可选参数（PowerShell 与 bat 均支持）：

| 参数 | 说明 |
|------|------|
| `-UseCache` / `--use-cache` | 使用 Docker 层缓存，加快重复构建速度 |
| `-ExportOnly` / `--export-only` | 跳过构建，仅导出本地已有镜像 |
| `-SkipApiAdmin` / `--skip-api-admin` | 只打四套 player，跳过 api/admin |
| `-SkipBundle` / `--skip-bundle` | 跳过六合一包，仅保留分散 tar |

### 产物

| 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` |
| **`thebet365-full-themes-latest.tar`** | **上面全部 6 个镜像（上传这一个即可）** |

也可单独导出六合一包（本地镜像已齐时）：

```bat
docs\docker\build-and-export-images.bat --service full-themes --export-only --tag latest
```

### 分支要求

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

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

```bat
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 静态资源） |

导出文件默认路径：

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

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

---

## 五、上传到服务器并部署

完整分步说明（本地打包 → 上传 → 终端执行 → 验证）见上级文档 **[Docker部署指南.md 第八节](../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. 首次部署

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

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

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

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

### 3. 验证

```bash
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/球员`

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

```bash
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 启动后不断重启

```bash
docker logs thebet365-api
```

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

---

## 八、相关文件

```text
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
```