# Docker 部署说明

本文档对应 `docs/deployment-plan.md`，按应用服务器和算力服务器拆分 Dockerfile 与 Docker Compose 文件。所有业务代码均通过 volume 外挂到容器内，镜像只包含运行时环境和第三方依赖。

## 目录

```text
docker/
  app/
    Dockerfile.backend
    Dockerfile.frontend
    docker-compose.yml
    .env.example
  compute/
    Dockerfile.compute
    docker-compose.yml
    .env.example
```

项目根目录不再保留 `Dockerfile` 和 `docker-compose.yml`，避免与应用服务器、算力服务器拆分部署入口混淆。

## 应用服务器部署

应用服务器包含前端 Nginx、Backend API、PostgreSQL、Redis。

开发阶段默认由项目自带 PostgreSQL/Redis：

```env
USE_BUILTIN_POSTGRES=true
USE_BUILTIN_REDIS=true
DATABASE_URL=postgresql+asyncpg://yg_ft:change_me@postgres:5432/yg_ft
REDIS_URL=redis://redis:6379/0
```

后续切换企业统一基础设施时，保留应用配置方式，只需要：

- 修改 `DATABASE_URL` 指向企业 PostgreSQL。
- 修改 `REDIS_URL` 指向企业 Redis。
- 从 Compose 中移除或禁用 `postgres`、`redis` 服务。
- 保留 `docs/postgres-schema.sql` 作为数据库初始化或迁移参考。

首次部署前先构建前端产物：

```bash
cd docker/app
cp .env.example .env
docker compose --profile build run --rm frontend-builder
docker compose up -d --build
```

默认访问地址：

```text
http://<app-server-ip>:6801
```

应用侧代码外挂：

```text
../../backend -> /app
../../frontend/dist -> /usr/share/nginx/html
../../runtime/app/logs/backend -> /opt/yg-ft/logs/backend
../../runtime/app/data -> /data/yg-ft
```

如果算力服务独立部署，需要在 `docker/app/.env` 中修改：

```env
COMPUTE_API_BASE_URL=http://<compute-server-ip>:9100
FILE_GATEWAY_BASE_URL=http://<compute-server-ip>:9101
COMPUTE_SERVICE_TOKEN=change_me
COMPUTE_STATUS_SYNC_MODE=polling
COMPUTE_POLL_INTERVAL_SECONDS=10
COMPUTE_POLL_BATCH_SIZE=100
```

状态同步采用应用侧定时轮询 Compute API 为主，避免算力服务器需要访问应用服务器，从而减少双向网络策略开通。

## 应用服务与算力服务交互

应用服务与算力服务之间只要求应用服务器主动访问算力服务器：

```text
Frontend
  -> Backend API
    -> Compute API
      -> Compute Agent / LLaMA-Factory
      -> 本地数据盘 / 模型目录 / 训练产物
    <- Backend Worker 定时轮询 Compute API
```

默认交互流程：

- `Backend API` 读取 `COMPUTE_API_BASE_URL`，向 `Compute API` 提交训练、评测、合并、导出等任务。
- `Compute API` 在算力服务器上调度 `Compute Agent`。
- `Compute Agent` 通过宿主机挂载目录调用 LLaMA-Factory，并读写 `/data/yg-ft` 下的数据集、模型和训练产物。
- `Backend Worker` 按 `COMPUTE_POLL_INTERVAL_SECONDS` 定时轮询 Compute API，同步任务状态、训练指标、日志摘要和产物索引。
- 前端只访问应用服务；文件下载和产物访问由应用服务完成权限校验后，再通过 `FILE_GATEWAY_BASE_URL` 获取受控资源。

当前支持通过环境变量动态配置算力服务地址：

```env
COMPUTE_API_BASE_URL=http://<compute-server-ip>:9100
FILE_GATEWAY_BASE_URL=http://<compute-server-ip>:9101
COMPUTE_SERVICE_TOKEN=change_me
COMPUTE_STATUS_SYNC_MODE=polling
COMPUTE_POLL_INTERVAL_SECONDS=10
COMPUTE_POLL_BATCH_SIZE=100
```

后续多算力节点阶段建议升级为数据库配置：在 `compute_nodes` 表中维护节点地址、服务 token、启用状态、权重、标签和健康状态，并通过“算力节点管理”页面动态启停节点，避免每次调整地址都重启应用服务。

## 算力服务器部署

算力服务器包含 Compute API、后续 Compute Agent、后续 File Gateway、GPU runtime、本地训练数据目录和宿主机挂载的 LLaMA-Factory。

部署前需要安装：

- NVIDIA Driver。
- NVIDIA Container Toolkit。
- Docker Engine 和 Docker Compose Plugin。
- LLaMA-Factory 宿主机目录，默认 `/opt/LLaMA-Factory`。
- 本地训练数据盘，默认 `/data/yg-ft`。

算力服务器上的 LLaMA-Factory 使用宿主机挂载方式，不在当前 Compose 中重新构建 LLaMA-Factory 镜像：

```env
LLAMA_FACTORY_HOME=/opt/LLaMA-Factory
LLAMA_FACTORY_HOST_PATH=/opt/LLaMA-Factory
```

启动：

```bash
cd docker/compute
cp .env.example .env
docker compose up -d --build
```

健康检查：

```text
GET http://<compute-server-ip>:9100/health
GET http://<compute-server-ip>:9100/api/v1/compute/health
```

算力侧代码和数据外挂：

```text
../../compute -> /app/compute
${LLAMA_FACTORY_HOST_PATH} -> /opt/LLaMA-Factory
${YG_FT_DATA_ROOT_HOST} -> /data/yg-ft
../../runtime/compute/logs -> /opt/yg-ft/logs/compute
../../runtime/compute/training-logs -> /opt/yg-ft/logs/training
```

算力侧只需要允许应用服务器访问 Compute API/File Gateway，不要求访问应用服务器：

```env
ENABLE_APP_CALLBACK=false
COMPUTE_SERVICE_TOKEN=change_me
```

## 多算力节点部署

多算力节点仍按“单机多 GPU 节点”部署。每台 GPU 服务器都需要独立部署一套算力服务和宿主机挂载的 LLaMA-Factory：

```text
gpu-node-01: docker/compute + /opt/LLaMA-Factory + /data/yg-ft
gpu-node-02: docker/compute + /opt/LLaMA-Factory + /data/yg-ft
gpu-node-03: docker/compute + /opt/LLaMA-Factory + /data/yg-ft
```

节点之间默认不互相访问。应用服务器主动访问每个节点的 Compute API/File Gateway，并通过 `compute_nodes` 表或算力节点管理页面维护：

- `api_base_url`
- `file_gateway_url`
- `enabled`
- `scheduler_status`
- `scheduler_weight`
- `tags`
- `data_root`
- `model_root`
- `log_root`

长期使用每台算力服务器本地磁盘时，需要由应用平台维护资源副本关系。调度前先检查目标节点是否已有数据集和模型副本；如果没有，应用平台通过目标节点 File Gateway 创建资源同步任务，同步完成后再提交训练任务。

## 单机所有服务部署在算力服务器

在同一台 GPU 服务器上分别启动两套 Compose：

```bash
cd docker/app
docker compose --profile build run --rm frontend-builder
docker compose up -d --build

cd ../compute
docker compose up -d --build
```

应用侧 `.env` 中可使用：

```env
COMPUTE_API_BASE_URL=http://host.docker.internal:9100
FILE_GATEWAY_BASE_URL=http://host.docker.internal:9101
COMPUTE_STATUS_SYNC_MODE=polling
```

Linux 环境如需容器访问宿主机地址，可在应用侧 Compose 中按需增加 `extra_hosts: ["host.docker.internal:host-gateway"]`，或直接配置算力服务器内网 IP。

## 生产注意事项

- 当前 Compose 是工程部署骨架，后续 Backend Worker、Compute Agent、File Gateway 有可运行入口后，再拆分为独立服务。
- PostgreSQL 和 Redis 开发阶段采用项目自带部署，生产阶段保留切换企业统一基础设施的配置入口。
- 生产环境请把 `change_me` 替换为强密码或密钥管理系统注入。
- 当前镜像默认优先保证宿主机外挂日志和数据目录可写；生产环境如需非 root 运行，需要统一宿主机目录 UID/GID 后在 Compose 中增加 `user` 配置。
- Compute API 不应暴露公网，建议通过防火墙限制只允许应用服务器访问。
- GPU 容器需要 NVIDIA Container Toolkit，否则 `gpus: all` 无法生效。
- 前端 Nginx 默认挂载 `frontend/dist`，发布前需要先运行 `frontend-builder` 或由 CI 构建产物。