Palgo 自部署操作手册

版本：1.0 部署方式：Docker Compose 应用服务栈

1. 部署说明

Palgo 使用一套 Docker Compose 部署应用服务。现场运维进入交付包中的 palgo 部署目录，维护以下两个文件：

text

.env
docker-compose.yml

所有启动、停止、更新、回滚、排障操作均在该部署目录执行。

2. 服务清单

服务名	容器名	镜像	端口	作用
`train-service`	`train-service`	`docker.medipath.com.cn/palgo/train-service`	`59999`	训练任务服务
`alg-service`	`palgo-alg`	`docker.medipath.com.cn/palgo/alg-service`	`58888`	Palgo 算法调度/业务算法服务
`search-service`	`search-service`	`docker.medipath.com.cn/palgo/search-service`	`48888`	检索服务，使用本地 `lucene` 目录
`backend-service`	`backend-service`	`docker.medipath.com.cn/palgo/backend-service`	`18888`	后端主业务服务
`tenant-service`	`tenant-service`	`docker.medipath.com.cn/palgo/tenant-service`	`28888`	租户服务
`project-service`	`project-service`	`docker.medipath.com.cn/palgo/project-service`	`38888`	项目服务、Socket JS 地址
`case-service`	`case-service`	`docker.medipath.com.cn/case-service`	`18082`	病例服务

所有服务使用 network_mode: host，因此端口直接占用宿主机端口。

3. 前置服务栈

Palgo 的 docker-compose.yml 只启动应用服务，不包含 Mongo、MinIO、RabbitMQ、Keycloak 和底层算法容器。前置服务由交付包中的 esb 部署目录提供。

部署顺序必须是：

先启动 esb 前置服务栈。
确认 MinIO、MongoDB、RabbitMQ、算法容器等前置服务正常。
再启动 palgo 应用服务栈。

esb/docker-compose.yml 服务清单：

服务名	容器名	端口	作用
`minio-1`	`minio-1`	`9000`, `9001`	对象存储和控制台
`mongo`	`mongo`	`27017`	MongoDB
`postgres`	`keycloak-postgres`	内部端口	Keycloak 数据库
`keycloak`	`keycloak`	`18080`	SSO/认证服务
`rabbitmq`	`rabbitmq`	host 网络	消息队列
`pma`	`pma`	host 网络	数据辅助服务
`alg-0`	`alg-0`	`8080`	Palgo 底层算法服务
`sam-0`	`sam-0`	`4040`	SAM 算法服务

esb/docker-compose.yml 示例：

yaml

x-alg-template: &alg-template
  image: docker.medipath.com.cn/alg:palgo
  restart: always
  network_mode: host
  runtime: nvidia
  mem_limit: 15G
  volumes:
    - /mnt:/mnt
    - ./cache:/root/.medipath
  healthcheck:
    test: [ "CMD", "bash", "-c", "curl -f http://127.0.0.1:$$API_PORT/health || exit 1", ]
    interval: 30s
    timeout: 10s
    retries: 6
    start_period: 10s

x-env-template: &env-template
  TZ: Asia/Shanghai
  MINIO_ENDPOINT: 127.0.0.1:9000
  NVIDIA_DRIVER_CAPABILITIES: all

services:
  minio-1:
    image: quay.io/minio/minio:RELEASE.2024-08-29T01-40-52Z
    hostname: minio-1
    container_name: minio-1
    restart: always
    command: server --console-address ":9001" http://minio-{1...1}/data{1...2}
    volumes:
      - /media/data1:/data1
      - /media/data2:/data2
    environment:
      MINIO_ROOT_USER: minio
      MINIO_ROOT_PASSWORD: ***
    expose:
      - 9000
      - 9001
    ports:
      - 9000:9000
      - 9001:9001
    healthcheck:
      test: [ "CMD", "curl", "-f", "http://localhost:9000/minio/health/live" ]
      interval: 30s
      timeout: 20s
      retries: 3

  mongo:
    image: docker.medipath.com.cn/mongo
    container_name: mongo
    restart: always
    command: --quiet
    environment:
      TZ: Asia/Shanghai
      MONGO_INITDB_ROOT_USERNAME: root
      MONGO_INITDB_ROOT_PASSWORD: ***
    expose:
      - 27017
    ports:
      - 27017:27017
    volumes:
      - ./mongo/db:/data/db

  postgres:
    image: docker.medipath.com.cn/postgres:16
    container_name: keycloak-postgres
    restart: always
    volumes:
      - ./postgres:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: password

  keycloak:
    image: docker.medipath.com.cn/keycloak
    container_name: keycloak
    restart: always
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: ***
      KC_DB: postgres
      KC_DB_URL: "jdbc:postgresql://postgres:5432/keycloak"
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: password
      KC_HTTP_ENABLED: true
      KC_HOSTNAME_STRICT: false
      KC_HOSTNAME: sso.local
    entrypoint: [ "/opt/keycloak/bin/kc.sh", "start" ]
    ports:
      - 18080:8080
    depends_on:
      - postgres

  rabbitmq:
    image: docker.medipath.com.cn/rabbitmq
    container_name: rabbitmq
    restart: always
    network_mode: host
    volumes:
      - ./mq:/var/lib/rabbitmq/mnesia
      - ./alg.mq:/etc/rabbitmq/conf.d/99-alg.conf
    environment:
      - RABBITMQ_DEFAULT_USER=admin
      - RABBITMQ_DEFAULT_PASS=***

  pma:
    image: docker.medipath.com.cn/pma
    container_name: pma
    restart: always
    network_mode: host
    environment:
      TZ: Asia/Shanghai
    volumes:
      - /mnt:/mnt

  alg-0:
    <<: *alg-template
    container_name: alg-0
    environment:
      <<: *env-template
      API_PORT: 8080
      NVIDIA_VISIBLE_DEVICES: "0"
    volumes:
      - /mnt:/mnt

  sam-0:
    <<: *alg-template
    image: docker.medipath.com.cn/alg:sam
    container_name: sam-0
    environment:
      <<: *env-template
      API_PORT: 4040
      NVIDIA_VISIBLE_DEVICES: "0"
    volumes:
      - /mnt:/mnt

前置服务启动：

bash

cd esb
docker compose up -d
docker compose ps

前置服务检查：

bash

curl -f http://127.0.0.1:9000/minio/health/live
curl -f http://127.0.0.1:8080/health
curl -f http://127.0.0.1:4040/health
docker ps
ss -lntp

如 alg-0 或 sam-0 健康检查失败，先检查 GPU 和 NVIDIA 容器运行时，再启动 Palgo 应用服务。

4. docker-compose.yml 示例

yaml

services:
  train-service:
    image: docker.medipath.com.cn/palgo/train-service
    container_name: train-service
    restart: always
    privileged: true
    pid: host
    network_mode: host
    env_file:
      - .env
    environment:
      TZ: Asia/Shanghai
      IXTF_API_PORT: 59999
      PALGO_TRAIN_DIR: /mnt/data/palgo/train
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./log:/log
      - /mnt:/mnt

  alg-service:
    image: docker.medipath.com.cn/palgo/alg-service
    container_name: palgo-alg
    restart: always
    network_mode: host
    env_file:
      - .env
    environment:
      TZ: Asia/Shanghai
      IXTF_API_PORT: 58888
    volumes:
      - ./log:/log
      - /mnt:/mnt

  search-service:
    image: docker.medipath.com.cn/palgo/search-service
    container_name: search-service
    restart: always
    network_mode: host
    env_file:
      - .env
    environment:
      TZ: Asia/Shanghai
      IXTF_API_PORT: 48888
    volumes:
      - ./log:/log
      - /mnt:/mnt
      - ./lucene:/lucene

  backend-service:
    image: docker.medipath.com.cn/palgo/backend-service
    container_name: backend-service
    restart: always
    network_mode: host
    env_file:
      - .env
    environment:
      TZ: Asia/Shanghai
      IXTF_API_PORT: 18888
    volumes:
      - ./log:/log
      - /mnt:/mnt

  tenant-service:
    image: docker.medipath.com.cn/palgo/tenant-service
    container_name: tenant-service
    restart: always
    network_mode: host
    env_file:
      - .env
    environment:
      TZ: Asia/Shanghai
      IXTF_API_PORT: 28888
    volumes:
      - ./log:/log
      - /mnt:/mnt

  project-service:
    image: docker.medipath.com.cn/palgo/project-service
    container_name: project-service
    restart: always
    network_mode: host
    env_file:
      - .env
    environment:
      TZ: Asia/Shanghai
      IXTF_API_PORT: 38888
    volumes:
      - ./log:/log
      - /mnt:/mnt

  case-service:
    image: docker.medipath.com.cn/case-service
    container_name: case-service
    restart: always
    network_mode: host
    env_file:
      - .env
    environment:
      TZ: Asia/Shanghai
      IXTF_API_PORT: 18082
    volumes:
      - ./log:/log
      - /mnt:/mnt

5. 服务器要求

项目	要求
操作系统	Ubuntu Server 22.04/24.04
CPU	8 核及以上
内存	32 GB 及以上，训练场景建议 64 GB 及以上
GPU	训练和算法场景需要 NVIDIA GPU
磁盘	数据盘建议 1 TB 及以上
时区	`Asia/Shanghai`

必须安装：

Docker
Docker Compose plugin
curl
pigz，离线导入导出镜像时使用
NVIDIA Driver 与 NVIDIA Container Toolkit，训练或算法服务需要 GPU 时必须安装

部署前检查：

bash

docker version
docker compose version
nvidia-smi
docker ps

6. 端口规划

端口	服务	说明
`18888`	`backend-service`	后端主业务服务
`28888`	`tenant-service`	租户服务
`38888`	`project-service`	项目服务、Socket JS endpoint
`48888`	`search-service`	检索服务
`58888`	`alg-service`	Palgo 算法业务服务
`59999`	`train-service`	训练服务
`18082`	`case-service`	病例服务
`9000`	MinIO	`esb` 前置服务
`9001`	MinIO Console	`esb` 前置服务
`27017`	MongoDB	`esb` 前置服务
`18080`	Keycloak	`esb` 前置服务
`8080`	底层算法服务 `alg-0`	`esb` 前置服务
`4040`	SAM 服务 `sam-0`	`esb` 前置服务

公网只开放统一代理端口或 HTTPS。Mongo、MinIO、RabbitMQ、训练服务、算法服务不建议直接暴露公网。

7. 目录规划

bash

mkdir -p log lucene

训练目录：

bash

sudo mkdir -p /mnt/data/palgo/train
sudo chown -R "$USER":"$USER" /mnt/data/palgo/train

挂载说明：

挂载	说明
`./log:/log`	所有 Palgo 应用服务日志目录
`/mnt:/mnt`	数据文件统一挂载目录
`./lucene:/lucene`	Search 服务索引目录
`/var/run/docker.sock:/var/run/docker.sock`	Train 服务调用宿主机 Docker

注意：train-service 使用 privileged: true、pid: host 并挂载 Docker socket，应只部署在可信服务器。

8. .env 配置

进入 Palgo 部署目录后编辑：

bash

vi .env

示例：

dotenv

MP_SDK_MARKET_BIND_TENANT_CODE=67d92caa22d9ed0dc78bd002

PALGO_OSS_ENDPOINT=http://127.0.0.1:9000
PALGO_OSS_ACCESS_KEY=minio
PALGO_OSS_SECRET_KEY=***

PALGO_MQ_HOST=127.0.0.1
PALGO_MQ_USER=admin
PALGO_MQ_PASSWORD=***

PALGO_MONGO_URI=mongodb://root:***@127.0.0.1

PALGO_ALG_ENDPOINTS=http://127.0.0.1:8080
PALGO_SOCKET_JS_ENDPOINT=http://127.0.0.1:38888
PALGO_SEARCH_ENDPOINT=http://127.0.0.1:48888
PALGO_TRAIN_ENDPOINT=http://127.0.0.1:59999
PALGO_TRAIN_GPUS_START_IDX=1

CASE_MQ_HOST=127.0.0.1
CASE_MQ_USER=admin
CASE_MQ_PASSWORD=***
CASE_MONGO_URI=mongodb://root:***@127.0.0.1

配置说明：

配置项	说明
`MP_SDK_MARKET_BIND_TENANT_CODE`	绑定租户编码
`PALGO_OSS_*`	MinIO/对象存储配置
`PALGO_MQ_*`	Palgo 消息队列配置
`PALGO_MONGO_URI`	Palgo MongoDB 地址
`PALGO_ALG_ENDPOINTS`	底层算法服务地址
`PALGO_SOCKET_JS_ENDPOINT`	项目服务 Socket 地址
`PALGO_SEARCH_ENDPOINT`	检索服务地址
`PALGO_TRAIN_ENDPOINT`	训练服务地址
`PALGO_TRAIN_GPUS_START_IDX`	训练任务起始 GPU 编号
`CASE_*`	病例服务依赖配置

生产环境应将密码替换为现场安全密码，不建议继续使用默认密码。

9. 镜像准备

在线环境：

bash

docker login docker.medipath.com.cn
docker compose pull

离线环境：

bash

pigz -dc palgo-update.tar.gz | docker load
docker images

镜像包名称以现场交付文件为准。

10. 启动与检查

启动前置服务：

bash

cd esb
docker compose up -d
docker compose ps

启动 Palgo 应用服务：

bash

cd ../palgo
docker compose up -d

查看 Palgo 容器：

bash

docker compose ps
docker ps

端口检查：

bash

ss -lntp

如当前版本提供 /health 接口，可执行：

bash

curl -f http://127.0.0.1:18888/health
curl -f http://127.0.0.1:28888/health
curl -f http://127.0.0.1:38888/health
curl -f http://127.0.0.1:48888/health
curl -f http://127.0.0.1:58888/health
curl -f http://127.0.0.1:59999/health
curl -f http://127.0.0.1:18082/health

如某服务无 /health 接口，以容器 running、端口监听、日志无持续错误为准。

11. 业务验收

打开 Palgo 系统访问地址或代理地址。
使用测试账号登录。
创建或打开租户、项目、病例相关数据。
上传或选择测试数据文件。
发起一次算法分析。
发起一次检索或查看检索结果。
如现场启用训练，提交一次训练任务并确认任务状态变化。
确认日志无持续错误。

12. 常用运维命令

bash

docker compose ps
docker compose logs -f --tail=200 backend-service
docker compose logs -f --tail=200 tenant-service
docker compose logs -f --tail=200 project-service
docker compose logs -f --tail=200 search-service
docker compose logs -f --tail=200 alg-service
docker compose logs -f --tail=200 train-service
docker compose logs -f --tail=200 case-service
docker compose restart backend-service tenant-service project-service
docker compose restart search-service alg-service train-service case-service
docker compose down
docker compose pull
docker compose up -d
docker stats
nvidia-smi

13. 日志与排障

文件日志目录：

bash

./log

容器日志：

bash

docker logs backend-service
docker logs tenant-service
docker logs project-service
docker logs search-service
docker logs palgo-alg
docker logs train-service
docker logs case-service

重点搜索：

text

ERROR
Exception
Connection refused
Mongo
RabbitMQ
MinIO
OSS
No such file
Permission denied
GPU
Docker socket

14. 更新与回滚

更新前备份：

bash

cp .env .env.bak.$(date +%F)
cp docker-compose.yml docker-compose.yml.bak.$(date +%F)
tar -czf palgo-log-lucene-$(date +%F).tgz log lucene

在线更新：

bash

docker compose pull
docker compose up -d

离线更新：

bash

pigz -dc palgo-update.tar.gz | docker load
docker compose up -d

回滚：

恢复上一版 .env 和 docker-compose.yml。
确认上一版镜像已存在。
执行：

bash

docker compose up -d
docker compose ps

15. 备份要求

内容	频率
`.env`	每次上线前
`docker-compose.yml`	每次上线前
`./lucene`	每日或重大升级前
`./log`	按需
`/mnt/data/palgo/train`	按训练数据重要性备份
MongoDB 数据	每日或重大升级前
MinIO 数据	每日或重大升级前
RabbitMQ 数据	按需

16. 常见故障处理

问题	常见原因	处理
服务启动后立即退出	`.env` 配置错误、依赖不可达	查看对应 `docker logs`，检查 `.env`
后端无法访问数据库	Mongo 未启动、账号密码错误、网络不通	检查 `PALGO_MONGO_URI` 和 Mongo 状态
任务无法投递	RabbitMQ 未启动或账号错误	检查 `PALGO_MQ_`、`CASE_MQ_`
文件上传或读取失败	MinIO 配置错误、`/mnt` 数据不存在	检查 `PALGO_OSS_*` 和 `/mnt` 挂载
算法无结果	`PALGO_ALG_ENDPOINTS` 不通、底层算法容器异常	检查 `8080` 算法服务和日志
检索异常	`search-service` 异常或 `./lucene` 权限问题	查看 `search-service` 日志，检查 `lucene` 权限
训练任务失败	GPU 不足、Docker socket 不可用、训练目录权限不足	检查 `nvidia-smi`、`/var/run/docker.sock`、`/mnt/data/palgo/train`
端口冲突	host 网络模式下端口已被占用	使用 `ss -lntp` 找到占用进程

17. 最终交付清单

[ ] Docker 正常。
[ ] .env 已按现场环境配置。
[ ] esb 前置服务栈已启动。
[ ] MongoDB、MinIO、RabbitMQ、Keycloak、底层算法服务已可用。
[ ] docker compose ps 服务正常。
[ ] 18888/28888/38888/48888/58888/59999/18082 端口监听正常。
[ ] 系统能登录。
[ ] 项目、病例、文件访问正常。
[ ] 算法分析能返回结果。
[ ] 检索服务正常。
[ ] 如启用训练，训练任务能提交并运行。
[ ] 日志无持续错误。
[ ] 配置和关键数据已备份。

Palgo 自部署操作手册 ​

1. 部署说明 ​

2. 服务清单 ​

3. 前置服务栈 ​

4. docker-compose.yml 示例 ​

5. 服务器要求 ​

6. 端口规划 ​

7. 目录规划 ​

8. .env 配置 ​

9. 镜像准备 ​

10. 启动与检查 ​

11. 业务验收 ​

12. 常用运维命令 ​

13. 日志与排障 ​

14. 更新与回滚 ​

15. 备份要求 ​

16. 常见故障处理 ​

17. 最终交付清单 ​

Palgo 自部署操作手册

1. 部署说明

2. 服务清单

3. 前置服务栈

4. docker-compose.yml 示例

5. 服务器要求

6. 端口规划

7. 目录规划

8. .env 配置

9. 镜像准备

10. 启动与检查

11. 业务验收

12. 常用运维命令

13. 日志与排障

14. 更新与回滚

15. 备份要求

16. 常见故障处理

17. 最终交付清单