198 lines
5.3 KiB
Markdown
198 lines
5.3 KiB
Markdown
# Docker 镜像构建与导出
|
||
|
||
本文档说明如何在本地或 CI 机器上**构建** `api` / `player` / `admin` 三个生产镜像，并**导出**为 tar 包，便于上传到服务器离线加载部署。
|
||
|
||
> 全栈部署流程见上级文档：[Docker部署指南.md](../Docker部署指南.md)
|
||
|
||
---
|
||
|
||
## 一、脚本位置
|
||
|
||
脚本与本文档同目录 `docs/docker/`：
|
||
|
||
| 文件 | 适用环境 |
|
||
|------|----------|
|
||
| `docs/docker/build-and-export-images.ps1` | Windows（PowerShell） |
|
||
| `docs/docker/build-and-export-images.sh` | Linux / macOS / Git Bash |
|
||
|
||
两个脚本行为一致：在**项目根目录**执行 compose 构建 → 导出为根目录下的 `thebet365-images.tar`（默认）。
|
||
|
||
---
|
||
|
||
## 二、前置条件
|
||
|
||
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`
|
||
- `CHUANGLAN_ACCOUNT`、`CHUANGLAN_PASSWORD`（短信注册）
|
||
- `SEED_DATABASE=false`（生产建议保持 false，由部署脚本按需一次性 seed）
|
||
|
||
---
|
||
|
||
## 三、使用方法
|
||
|
||
### Windows
|
||
|
||
在项目根目录打开 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
|
||
```
|
||
|
||
### 可选参数
|
||
|
||
| PowerShell | Bash | 说明 |
|
||
|------------|------|------|
|
||
| （默认） | （默认） | `--no-cache` 全量构建，适合发版 |
|
||
| `-UseCache` | `--use-cache` | 使用 Docker 缓存，构建更快 |
|
||
| `-ExportOnly` | `--export-only` | 跳过构建，仅导出已有 `latest` 镜像 |
|
||
| `-Output my.tar` | `--output my.tar` | 自定义导出文件名 |
|
||
|
||
示例：仅重新导出已有镜像
|
||
|
||
```powershell
|
||
.\docs\docker\build-and-export-images.ps1 -ExportOnly
|
||
```
|
||
|
||
```bash
|
||
./docs/docker/build-and-export-images.sh --export-only
|
||
```
|
||
|
||
---
|
||
|
||
## 四、构建产物
|
||
|
||
| 镜像名 | 说明 |
|
||
|--------|------|
|
||
| `thebet365-api:latest` | NestJS API（含 Prisma 迁移入口） |
|
||
| `thebet365-player:latest` | 玩家前台（Nginx 静态资源） |
|
||
| `thebet365-admin:latest` | 管理后台（Nginx 静态资源） |
|
||
|
||
导出文件默认路径：
|
||
|
||
```text
|
||
<项目根目录>/thebet365-images.tar
|
||
```
|
||
|
||
该文件已加入 `.gitignore`，**请勿提交到 Git**。
|
||
|
||
---
|
||
|
||
## 五、上传到服务器并部署
|
||
|
||
### 1. 上传
|
||
|
||
将以下内容传到服务器同一目录（如 `/www/wwwroot/thebet365`）：
|
||
|
||
- `thebet365-images.tar`
|
||
- `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.tar
|
||
```
|
||
|
||
后续更新同一个服务器时：
|
||
|
||
```bash
|
||
./scripts/deploy-update.sh --images thebet365-images.tar
|
||
```
|
||
|
||
更新脚本会先备份数据库，再用新 API 镜像执行 `prisma migrate deploy`，最后替换运行中的容器。
|
||
|
||
### 3. 验证
|
||
|
||
```bash
|
||
docker compose -f docker-compose.prod.yml ps
|
||
docker logs thebet365-api --tail 50
|
||
```
|
||
|
||
浏览器访问（端口以 `.env.docker` 为准）：
|
||
|
||
- 玩家端：`http://服务器IP:8082`
|
||
- 管理端：`http://服务器IP:8081`
|
||
|
||
---
|
||
|
||
## 六、与「服务器上直接 build」的区别
|
||
|
||
| 方式 | 优点 | 缺点 |
|
||
|------|------|------|
|
||
| **本地 build + 导出 tar** | 不占用服务器 CPU/内存；可重复部署同一包 | 需上传较大 tar（约 200–300 MB） |
|
||
| **服务器 `docker compose build`** | 无需传 tar | 首次/全量构建慢，小内存机器易失败 |
|
||
|
||
发版推荐流程：**本地或构建机执行脚本 → 上传 tar → 服务器执行 `deploy-update.sh --images thebet365-images.tar`**。
|
||
|
||
---
|
||
|
||
## 七、常见问题
|
||
|
||
### 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` 后 `up -d` 仍拉取或重建镜像
|
||
|
||
确保 compose 中 `image` 与 load 的 tag 一致（`thebet365-api:latest` 等），且使用同一 `docker-compose.prod.yml`。
|
||
|
||
### 4. API 启动后不断重启
|
||
|
||
```bash
|
||
docker logs thebet365-api
|
||
```
|
||
|
||
常见原因：数据库未就绪、`DATABASE_URL` 与 `POSTGRES_PASSWORD` 不一致、迁移失败。
|
||
|
||
---
|
||
|
||
## 八、相关文件
|
||
|
||
```text
|
||
thebet365/
|
||
├── docker-compose.prod.yml
|
||
├── .env.docker.example
|
||
├── thebet365-images.tar # 导出产物（默认，已 gitignore）
|
||
├── docker/
|
||
│ ├── api/Dockerfile
|
||
│ ├── player/Dockerfile
|
||
│ ├── admin/Dockerfile
|
||
│ └── nginx/
|
||
└── docs/
|
||
├── Docker部署指南.md
|
||
└── docker/
|
||
├── 镜像构建与导出.md # 本文档
|
||
├── build-and-export-images.ps1
|
||
└── build-and-export-images.sh
|
||
```
|