YG_FT/docker

Docker 部署说明

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

目录

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：

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 作为数据库初始化或迁移参考。

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

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

默认访问地址：

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

应用侧代码外挂：

../../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 中修改：

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 为主，避免算力服务器需要访问应用服务器，从而减少双向网络策略开通。

应用服务与算力服务交互

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

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 获取受控资源。

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

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 镜像：

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

启动：

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

健康检查：

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

算力侧代码和数据外挂：

../../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，不要求访问应用服务器：

ENABLE_APP_CALLBACK=false
COMPUTE_SERVICE_TOKEN=change_me

多算力节点部署

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

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：

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

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

应用侧 .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 构建产物。