Medipath-K 安装操作手册

版本：2.1 部署方式：Docker Compose 一体化部署

1. 部署说明

本系统按一套 Docker Compose 统一部署，不需要分别部署后端和算法项目。现场运维只需要进入交付包中的 expert-service 部署目录，维护以下两个文件：

text

.env
docker-compose.yml

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

脚本安装

在线环境可直接下载并执行安装脚本：

bash

curl -fsSL "https://deploy-1328549252.cos.ap-shanghai.myqcloud.com/expert-service/install.sh" -o install.sh
sudo bash install.sh

如需先确认脚本内容，可执行：

bash

less install.sh

2. Compose 服务清单

服务名	镜像	作用
`mongo`	`docker.medipath.com.cn/mongo`	数据库
`expert-service`	`docker.medipath.com.cn/expert-service:${version}`	主业务服务
`alg-0`	`docker.medipath.com.cn/alg:${algVersion}`	算法服务 1，端口 8080，GPU 0
`alg-1`	`docker.medipath.com.cn/alg:${algVersion}`	算法服务 2，端口 8081，GPU 1
`node-exporter`	`quay.io/prometheus/node-exporter`	主机监控
`dcgm-exporter`	`nvcr.io/nvidia/k8s/dcgm-exporter:4.4.1-4.6.0-ubuntu22.04`	GPU 监控
`pma`	`docker.medipath.com.cn/pma`	数据辅助服务

3. docker-compose.yml 示例

yaml

services:
  mongo:
    image: docker.medipath.com.cn/mongo
    container_name: mongo
    restart: always
    environment:
      TZ: Asia/Shanghai
      MONGO_INITDB_ROOT_USERNAME: root
      MONGO_INITDB_ROOT_PASSWORD: ***
    ports:
      - "27017:27017"
    volumes:
      - ${dataDir}/mongo:/data/db

  expert-service:
    image: docker.medipath.com.cn/expert-service:${version}
    container_name: expert-service
    restart: always
    network_mode: host
    depends_on:
      mongo:
        condition: service_started
      alg-0:
        condition: service_healthy
      alg-1:
        condition: service_healthy
    environment:
      TZ: Asia/Shanghai
      EXPERT_EXPIRE_DAY: 7
      EXPERT_ALG_ENDPOINTS: http://${localIp}:8080,http://${localIp}:8081
      NODE_EXPORT_ENDPOINT: http://${localIp}:9100/metrics
      NODE_EXPORT_METRICS_MOUNTPOINT: /home
    volumes:
      - ./log:/log
      - ${dataDir}:/data
    healthcheck:
      test: curl -f http://localhost:9090/health || exit 1
      interval: 15s
      timeout: 5s
      retries: 3
      start_period: 30s

  alg-0:
    image: docker.medipath.com.cn/alg:${algVersion}
    container_name: alg-0
    restart: always
    network_mode: host
    environment:
      TZ: Asia/Shanghai
      API_PORT: 8080
    volumes:
      - ${dataDir}:/data
      - ${algCache}:/root/.medipath
    deploy:
      resources:
        limits:
          memory: 40G
        reservations:
          devices:
            - driver: nvidia
              device_ids: [ "0" ]
              capabilities: [ gpu ]
    healthcheck:
      test: curl -f http://localhost:$$API_PORT/health || exit 1
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

  alg-1:
    image: docker.medipath.com.cn/alg:${algVersion}
    container_name: alg-1
    restart: always
    network_mode: host
    environment:
      TZ: Asia/Shanghai
      API_PORT: 8081
    volumes:
      - ${dataDir}:/data
      - ${algCache}:/root/.medipath
    deploy:
      resources:
        limits:
          memory: 40G
        reservations:
          devices:
            - driver: nvidia
              device_ids: [ "1" ]
              capabilities: [ gpu ]
    healthcheck:
      test: curl -f http://localhost:$$API_PORT/health || exit 1
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

  node-exporter:
    image: quay.io/prometheus/node-exporter
    container_name: node-exporter
    restart: always
    network_mode: host
    pid: host
    environment:
      TZ: Asia/Shanghai
    volumes:
      - '/:/host:ro,rslave'
    command:
      - '--path.rootfs=/host'

  dcgm-exporter:
    image: nvcr.io/nvidia/k8s/dcgm-exporter:4.4.1-4.6.0-ubuntu22.04
    container_name: dcgm-exporter
    restart: always
    network_mode: host
    cap_add:
      - SYS_ADMIN
    environment:
      - DCGM_EXPORTER_NO_HOSTNAME=1
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [ gpu ]

  pma:
    image: docker.medipath.com.cn/pma
    container_name: pma
    restart: always
    network_mode: host
    environment:
      TZ: Asia/Shanghai
    volumes:
      - ${dataDir}:/data

单 GPU 服务器处理方式：

删除或注释 alg-1 服务。
删除 expert-service.depends_on.alg-1。
将 EXPERT_ALG_ENDPOINTS 改成只保留 http://${localIp}:8080。

4. 服务器要求

项目	要求
操作系统	Ubuntu Server 22.04/24.04
CPU	8 核及以上
内存	64 GB 及以上，双算法容器建议 96 GB 及以上
GPU	NVIDIA GPU，推荐 2 张
磁盘	数据盘 1 TB 及以上，建议 SSD/NVMe
时区	`Asia/Shanghai`

必须安装 Docker、Docker Compose plugin、NVIDIA Driver、NVIDIA Container Toolkit、curl。离线环境建议安装 pigz。

部署前检查：

bash

nvidia-smi
docker version
docker compose version
docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi

5. 端口规划

端口	服务	说明
`9090`	`expert-service`	主业务服务
`8080`	`alg-0`	算法服务 1
`8081`	`alg-1`	算法服务 2
`27017`	`mongo`	MongoDB
`9100`	`node-exporter`	主机监控指标

公网只开放 HTTPS 或统一代理端口，不要将 27017、8080、8081、9100 直接开放公网。

6. 数据目录规划

生产环境建议使用固定绝对路径：

bash

/home/medipath/app/image/data/expert-service

创建目录：

bash

sudo mkdir -p /home/medipath/app/image/data/expert-service
sudo mkdir -p /home/medipath/app/image/data/expert-service/algCache
sudo chown -R "$USER":"$USER" /home/medipath/app/image/data/expert-service

目录	说明
`${dataDir}/mongo`	MongoDB 数据
`${dataDir}`	Expert 业务数据，挂载到容器 `/data`
`${algCache}`	算法缓存，挂载到容器 `/root/.medipath`
`./log`	Expert 日志，挂载到容器 `/log`

7. .env 配置

进入 expert-service 部署目录后编辑：

bash

vi .env

生产推荐配置：

dotenv

version=6.1.0
algVersion=all-in-one
localIp=127.0.0.1
limitMemory=8G
dataDir=/home/medipath/app/image/data/expert-service
algCache=/home/medipath/app/image/data/expert-service/algCache

配置项	说明
`version`	`expert-service` 镜像版本
`algVersion`	`alg` 算法镜像版本
`localIp`	单机部署用 `127.0.0.1`；跨机器部署用算法服务器内网 IP
`dataDir`	数据挂载目录，生产必须使用绝对路径
`algCache`	算法缓存目录，生产必须使用绝对路径
`limitMemory`	保留项，当前 compose 未实际使用

localIp 配错会导致算法调用失败。

8. 镜像准备

在线环境：

bash

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

离线环境：

bash

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

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

9. 启动与检查

启动：

bash

docker compose up -d

查看状态：

bash

docker compose ps

健康检查：

bash

curl -f http://127.0.0.1:9090/health
curl -f http://127.0.0.1:8080/health
curl -f http://127.0.0.1:8081/health

单 GPU 部署时只检查实际启用的算法端口。

10. 业务验收

打开系统访问地址或代理地址。
使用管理员或测试账号登录。
上传或打开一张测试切片/图片。
确认图片信息可以读取。
确认瓦片可以正常显示。
发起一次算法分析。
确认算法结果返回。
确认报告或结果页面可以正常查看。

11. 常用运维命令

bash

docker compose ps
docker compose logs -f --tail=200 expert-service
docker compose logs -f --tail=100 alg-0
docker compose logs -f --tail=100 alg-1
docker compose logs -f --tail=100 mongo
docker compose restart expert-service
docker compose restart alg-0 alg-1
docker compose down
docker compose pull
docker compose up -d
nvidia-smi
docker stats
curl -s http://127.0.0.1:9100/metrics | head

12. 日志与排障

Expert 文件日志目录：

bash

./log

容器日志：

bash

docker logs expert-service
docker logs alg-0
docker logs alg-1
docker logs mongo

重点搜索：

text

ERROR
GPU_NOT_AVAILABLE
GPU_CHECK_TIMEOUT
model
Mongo
Connection refused
No such file
Permission denied

13. 更新与回滚

更新：

bash

cp .env .env.bak.$(date +%F)
cp docker-compose.yml docker-compose.yml.bak.$(date +%F)
vi .env
docker compose pull
docker compose up -d

回滚：

bash

vi .env
docker compose pull
docker compose up -d
docker compose ps
curl -f http://127.0.0.1:9090/health
curl -f http://127.0.0.1:8080/health

回滚时将 version、algVersion 改回上一稳定版本。如涉及数据库恢复，先停止服务，再恢复 ${dataDir}/mongo。

14. 备份要求

内容	频率
`.env`	每次上线前
`docker-compose.yml`	每次上线前
`${dataDir}/mongo`	每日或重大升级前
`${dataDir}` 业务数据	每日
`${algCache}`	按需
证书、密钥	变更时

示例：

bash

tar -czf expert-config-$(date +%F).tgz .env docker-compose.yml
tar -czf expert-data-$(date +%F).tgz /home/medipath/app/image/data/expert-service

15. 常见故障处理

问题	常见原因	处理
`alg-0` 或 `alg-1` 不健康	GPU 不可用、显存不足、模型加载失败	查看 `nvidia-smi`、`docker logs alg-0`、`docker logs alg-1`
`expert-service` 不健康	Mongo 未启动、算法地址不通、配置错误	查看 `docker logs expert-service`，检查 `.env` 的 `localIp`
页面能打开但算法无结果	算法容器未就绪、端口不通、数据目录不一致	检查 `8080/8081/health` 和 `${dataDir}`
图片打不开	文件不存在、权限不足、数据目录未挂载	检查 `${dataDir}` 权限和容器 `/data`
镜像拉取失败	未登录仓库、网络不通、版本号错误	执行 `docker login`，检查 `version/algVersion`
宿主机有 GPU 但容器不可用	NVIDIA Container Toolkit 异常	重启 Docker，重新验证 `docker run --gpus all ... nvidia-smi`
Mongo 异常	数据目录权限问题或旧数据密码不一致	查看 `docker logs mongo`，检查 `${dataDir}/mongo`

16. 最终交付清单

[ ] Docker 正常。
[ ] NVIDIA 容器运行时正常。
[ ] .env 已按现场环境配置。
[ ] docker compose ps 服务正常。
[ ] 9090/health 正常。
[ ] 8080/health 正常。
[ ] 8081/health 正常，单 GPU 部署除外。
[ ] 系统能登录。
[ ] 图片能打开。
[ ] 算法能返回结果。
[ ] 日志无持续错误。
[ ] 配置和数据已备份。
[ ] 当前版本和回滚版本已记录。

Medipath-K 安装操作手册 ​

1. 部署说明 ​

脚本安装 ​

2. Compose 服务清单 ​

3. docker-compose.yml 示例 ​

4. 服务器要求 ​

5. 端口规划 ​

6. 数据目录规划 ​

7. .env 配置 ​

8. 镜像准备 ​

9. 启动与检查 ​

10. 业务验收 ​

11. 常用运维命令 ​

12. 日志与排障 ​

13. 更新与回滚 ​

14. 备份要求 ​

15. 常见故障处理 ​

16. 最终交付清单 ​

Medipath-K 安装操作手册

1. 部署说明

脚本安装

2. Compose 服务清单

3. docker-compose.yml 示例

4. 服务器要求

5. 端口规划

6. 数据目录规划

7. .env 配置

8. 镜像准备

9. 启动与检查

10. 业务验收

11. 常用运维命令

12. 日志与排障

13. 更新与回滚

14. 备份要求

15. 常见故障处理

16. 最终交付清单