YG_FT/docker

Docker 部署说明

本目录按应用服务器和算力服务器拆分 Dockerfile 与 Docker Compose 文件。Compose 文件不包含 build:，不会在 docker compose up 时自动构建业务镜像。所有业务镜像需要先通过手动 docker build 构建，再由 Compose 启动。

基础镜像

镜像	用途
python:3.12-slim	应用后端基础镜像，后端运行环境要求 Python 3.12 及以上
nginx:1.27-alpine	前端静态资源与 /api 反向代理运行镜像
hiyouga/llamafactory:latest	算力服务基础镜像，基于 LLaMA-Factory 官方镜像扩展 Compute API
postgres:16-alpine	开发阶段内置 PostgreSQL
redis:7-alpine	开发阶段内置 Redis

一键拉取基础镜像：

docker pull python:3.12-slim && \
docker pull nginx:1.27-alpine && \
docker pull hiyouga/llamafactory:latest && \
docker pull postgres:16-alpine && \
docker pull redis:7-alpine

Windows PowerShell：

$images = @(
  "python:3.12-slim",
  "nginx:1.27-alpine",
  "hiyouga/llamafactory:latest",
  "postgres:16-alpine",
  "redis:7-alpine"
)
$images | ForEach-Object { docker pull $_ }

如果部署环境不能访问外网，需要提前在可联网环境执行上述拉取命令，再用 docker save / docker load 导出导入。

业务镜像

镜像	Dockerfile	构建命令
yg-ft-backend-api:latest	docker/app/Dockerfile.backend	docker build -f docker/app/Dockerfile.backend -t yg-ft-backend-api:latest .
yg-ft-frontend-runtime:latest	docker/app/Dockerfile.frontend	docker build -f docker/app/Dockerfile.frontend -t yg-ft-frontend-runtime:latest .
yg-ft-compute-api:latest	docker/compute/Dockerfile.compute	docker build -f docker/compute/Dockerfile.compute -t yg-ft-compute-api:latest .

对外端口

所有宿主机对外端口统一使用 5 位端口。容器内部端口保持镜像默认端口，便于容器内服务和健康检查稳定。

服务	宿主机对外端口	容器内部端口	说明
前端 Nginx	16801	80	前端页面入口
后端 API	17861	8000	FastAPI 服务
PostgreSQL	15432	5432	开发阶段内置数据库
Redis	16379	6379	开发阶段内置缓存
Compute API	19100	9100	算力服务器 API
File Gateway	19101	后续服务端口	当前预留，后续拆出文件网关服务时使用

对应配置文件：

• docker/app/.env.example
  • FRONTEND_PORT=16801
  • BACKEND_API_PORT=17861
  • POSTGRES_PORT=15432
  • REDIS_PORT=16379
• docker/compute/.env.example
  • COMPUTE_API_PORT=19100
  • FILE_GATEWAY_PORT=19101

应用服务器部署

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

首次部署：

cd <repo-root>

# 1. 使用当前 Windows/宿主机 npm 构建前端静态产物
cd frontend
npm ci
npm run build
cd ..

# 2. 手动构建业务镜像
docker build -f docker/app/Dockerfile.backend -t yg-ft-backend-api:latest .
docker build -f docker/app/Dockerfile.frontend -t yg-ft-frontend-runtime:latest .

# 3. 启动应用服务
cd docker/app
cp .env.example .env
docker compose up -d

默认访问地址：

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

应用侧代码和数据外挂：

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

如果使用企业统一 PostgreSQL/Redis，修改 docker/app/.env：

DATABASE_URL=postgresql+asyncpg://<user>:<password>@<postgres-host>:15432/<db>
REDIS_URL=redis://<redis-host>:16379/0
USE_BUILTIN_POSTGRES=false
USE_BUILTIN_REDIS=false

生产环境如完全使用外部基础设施，可以删除或注释 Compose 中的 postgres、redis 服务及 backend-api.depends_on 中对应依赖。

算力服务器部署

算力服务器包含 Compute API、后续 Compute Agent、File Gateway、GPU runtime、本地训练数据目录和 LLaMA-Factory。Dockerfile.compute 基于 LLaMA-Factory 官方镜像：

FROM hiyouga/llamafactory:latest

部署前需要安装：

• NVIDIA Driver
• NVIDIA Container Toolkit
• Docker Engine 和 Docker Compose Plugin
• 本地训练数据目录，默认 /data/yg-ft

首次部署：

cd <repo-root>

# 手动构建算力业务镜像
docker build -f docker/compute/Dockerfile.compute -t yg-ft-compute-api:latest .

# 启动算力服务
cd docker/compute
cp .env.example .env
docker compose up -d

健康检查：

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

算力侧代码和数据外挂：

../../compute -> /app/compute
${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

应用与算力分离部署

应用服务器只需要主动访问算力服务器，不要求算力服务器回调应用服务器。

在 docker/app/.env 中配置：

COMPUTE_API_BASE_URL=http://<compute-server-ip>:19100
FILE_GATEWAY_BASE_URL=http://<compute-server-ip>:19101
COMPUTE_SERVICE_TOKEN=change_me
COMPUTE_STATUS_SYNC_MODE=polling
COMPUTE_POLL_INTERVAL_SECONDS=10
COMPUTE_POLL_BATCH_SIZE=100

交互链路：

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

多算力节点部署

多算力节点仍按“单机多 GPU 节点”部署。每台 GPU 服务器都独立部署一套 docker/compute：

gpu-node-01: docker/compute + /data/yg-ft + 19100/19101
gpu-node-02: docker/compute + /data/yg-ft + 19100/19101
gpu-node-03: docker/compute + /data/yg-ft + 19100/19101

节点之间默认不互访。应用平台主动访问每个节点的 Compute API/File Gateway，并通过 compute_nodes、resource_replicas、resource_sync_jobs 统一调度和同步。

常用命令

重新构建应用镜像：

docker build -f docker/app/Dockerfile.backend -t yg-ft-backend-api:latest .
docker build -f docker/app/Dockerfile.frontend -t yg-ft-frontend-runtime:latest .

重新构建算力镜像：

docker build -f docker/compute/Dockerfile.compute -t yg-ft-compute-api:latest .

启动服务：

cd docker/app
docker compose up -d

cd ../compute
docker compose up -d

查看服务：

docker compose ps
docker compose logs -f