# Seg_Server_Docker 部署说明

`Seg_Server_Docker` 是语义分割系统的自包含 Docker 部署包。目标不是“最小可运行”，而是尽量完整、可搬迁、能适应 CPU/GPU 与局域网访问等常见环境的可运行版本。

部署时只需要保留并移动这一整个文件夹。默认配置只引用本目录内的 `models/`、`demo/`、前端源码、后端源码和 Docker 配置，不依赖旁边的源码仓库，也不依赖固定宿主机路径。

## 目录内容

```text
Seg_Server_Docker/
├── docker-compose.yml          # 基础服务：前端、后端、worker、PostgreSQL、Redis、MinIO
├── docker-compose.gpu.yml      # GPU 覆盖配置：给 backend/worker 透传 NVIDIA GPU
├── Dockerfile.backend          # FastAPI + Celery + PyTorch + SAM2 后端镜像
├── Dockerfile.frontend         # React 前端构建 + Nginx 静态服务
├── .env                        # 当前部署环境变量
├── .env.example                # 环境变量模板
├── backend/                    # FastAPI 后端代码
├── src/                        # React 前端代码
├── public/                     # 前端静态资源
├── docker/                     # Nginx 配置等 Docker 辅助文件
├── demo/                       # 演示数据
│   ├── 演视LC视频序列.mp4
│   └── 演视DICOM序列/
└── models/                     # SAM 2.1 权重，容器内挂载为 /app/models
```

## 服务说明

| 服务 | 容器名 | 作用 | 默认端口 |
|---|---|---|---|
| frontend | `seg-frontend` | Web 前端页面 | `3000 -> 80` |
| backend | `seg-backend` | FastAPI API、登录、项目、模板、标注、单帧 AI 分割 | `8000 -> 8000` |
| worker | `seg-worker` | Celery 后台任务、视频拆帧、DICOM 解析、AI 自动推理/传播 | 内部访问 |
| postgres | `seg-postgres` | 元数据数据库 | 内部访问 |
| redis | `seg-redis` | Celery broker/result backend | 内部访问 |
| minio | `seg-minio` | 视频、DICOM、帧图、缩略图等对象存储 | `9000`、`9001` |

`backend` 构建并发布 `seg-server-backend:latest` 镜像，`worker` 直接复用这个镜像。更新后端依赖、PyTorch、SAM2 或系统包时，只需要重建 `backend` 镜像，再同时重启 `backend` 与 `worker`，避免 API 端显示模型可用但 worker 执行传播时缺依赖。

`worker` 配置了 `pull_policy: never`，只使用本地 `seg-server-backend:latest`，不会尝试从远端镜像仓库拉取这个内部镜像。首次部署请使用带 `--build` 的启动命令，让 `backend` 先构建出本地镜像。

## 部署前准备

1. 安装 Docker Engine 和 Docker Compose plugin。
2. 确认当前目录包含演示数据：

```bash
ls demo/演视LC视频序列.mp4
ls demo/演视DICOM序列
```

3. 确认当前目录包含 SAM 2.1 权重：

```bash
ls -lh models/
```

推荐至少包含：

```text
models/sam2_hiera_tiny.pt
models/sam2.1_hiera_small.pt
models/sam2.1_hiera_base_plus.pt
models/sam2.1_hiera_large.pt
```

如果只部署部分权重，系统仍可启动；缺失权重对应的模型变体会显示不可用。

### 下载 SAM 2.1 权重

部署分支不提交 `.pt` 权重文件。首次部署前在本目录执行：

```bash
mkdir -p models
wget -O models/sam2_hiera_tiny.pt https://dl.fbaipublicfiles.com/segment_anything_2/072824/sam2_hiera_tiny.pt
wget -O models/sam2.1_hiera_small.pt https://dl.fbaipublicfiles.com/segment_anything_2/092824/sam2.1_hiera_small.pt
wget -O models/sam2.1_hiera_base_plus.pt https://dl.fbaipublicfiles.com/segment_anything_2/092824/sam2.1_hiera_base_plus.pt
wget -O models/sam2.1_hiera_large.pt https://dl.fbaipublicfiles.com/segment_anything_2/092824/sam2.1_hiera_large.pt
```

也可以只下载 tiny/small 等需要的权重。`sam2_hiera_tiny.pt` 是兼容旧名，系统会把它作为 `sam2.1_hiera_tiny` 的 fallback 使用。

## 环境变量

部署前编辑 `.env`：

```ini
PUBLIC_HOST=localhost

VITE_API_BASE_URL=
VITE_WS_PROGRESS_URL=

FRONTEND_PORT=3000
BACKEND_PORT=8000
MINIO_PORT=9000
MINIO_CONSOLE_PORT=9001

POSTGRES_USER=seguser
POSTGRES_PASSWORD=segpass123
POSTGRES_DB=segserver

MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_PUBLIC_ENDPOINT=localhost:9000
MINIO_SECURE=false
# MINIO_PUBLIC_SECURE=true

SAM_MODELS_DIR=./models

CORS_ORIGINS=["http://localhost:3000","http://127.0.0.1:3000"]

JWT_SECRET_KEY=change-this-to-a-long-random-production-secret
ACCESS_TOKEN_EXPIRE_MINUTES=1440
DEFAULT_ADMIN_USERNAME=admin
DEFAULT_ADMIN_PASSWORD=123456
```

局域网访问时，把 `PUBLIC_HOST` 改成部署机器 IP，并把对应前端地址加入 `CORS_ORIGINS`。例如前端通过 `http://192.168.3.11:3000` 打开时：

```ini
PUBLIC_HOST=192.168.3.11
VITE_API_BASE_URL=
VITE_WS_PROGRESS_URL=
MINIO_PUBLIC_ENDPOINT=192.168.3.11:9000
MINIO_SECURE=false
CORS_ORIGINS=["http://192.168.3.11:3000","http://localhost:3000","http://127.0.0.1:3000"]
```

保持 `SAM_MODELS_DIR=./models` 可以让部署包自包含、可搬迁。只有在刻意共享外部模型缓存时，才把它改成其他路径。

`.env` 和 `.env.example` 中用 `# XXXX` 标出的配置项，是局域网部署或公网域名反代部署时最常需要修改的地方。

生产或长期演示环境请修改：

- `JWT_SECRET_KEY`
- `DEFAULT_ADMIN_PASSWORD`
- `POSTGRES_PASSWORD`
- `MINIO_ACCESS_KEY`
- `MINIO_SECRET_KEY`

## CPU 启动

适用于没有 NVIDIA GPU 或暂时不配置 GPU 透传的环境：

```bash
docker compose up -d --build
```

查看状态：

```bash
docker compose ps
curl http://localhost:8000/health
```

CPU 模式下，如果 PyTorch、SAM2 和 `.pt` 权重存在，模型可以加载，但推理速度明显慢于 GPU。

## GPU 启动

GPU 模式要求宿主机满足：

1. NVIDIA 驱动可用。
2. `nvidia-smi` 能看到 GPU。
3. Docker 已安装并配置 NVIDIA Container Toolkit。
4. `docker run --rm --gpus all ... nvidia-smi` 能在容器内看到 GPU。

先验证宿主机 GPU：

```bash
nvidia-smi
```

验证 Docker GPU 透传：

```bash
docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi
```

如果 Docker GPU 验证失败，需要先安装并配置 NVIDIA Container Toolkit：

```bash
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
  | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
  | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
  | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
```

启动 GPU 版：

```bash
docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d --build
```

验证 backend 和 worker 都能看到 GPU：

```bash
docker compose -f docker-compose.yml -f docker-compose.gpu.yml exec -T backend python - <<'PY'
import torch
print(torch.cuda.is_available())
print(torch.cuda.device_count())
print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else "NO CUDA")
PY

docker compose -f docker-compose.yml -f docker-compose.gpu.yml exec -T worker python - <<'PY'
import torch
print(torch.cuda.is_available())
print(torch.cuda.device_count())
print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else "NO CUDA")
PY
```

如果 backend 是 GPU 但 worker 不是 GPU，AI 自动推理/传播会失败。此时重建并重启二者：

```bash
docker compose -f docker-compose.yml -f docker-compose.gpu.yml build backend
docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d backend worker
```

## 公网域名 + frpc/frps + NPM

如果公网服务器绑定了域名，并通过 frpc/frps 把内网部署机器端口映射到公网服务器本机端口，再由 Nginx Proxy Manager 反向代理，推荐使用三个子域名：

```text
seg.example.com        -> 前端
seg-api.example.com    -> 后端 API + WebSocket
seg-minio.example.com  -> MinIO 图片/帧图/缩略图
```

推荐链路：

```text
浏览器
  -> 公网服务器 NPM
    -> 公网服务器本机 frps 映射端口
      -> frpc
        -> 内网部署机器的 3000 / 8000 / 9000
```

端口映射建议：

```text
内网部署机器 3000 -> 公网服务器本机 13000 -> NPM: seg.example.com
内网部署机器 8000 -> 公网服务器本机 18000 -> NPM: seg-api.example.com
内网部署机器 9000 -> 公网服务器本机 19000 -> NPM: seg-minio.example.com
```

### 可选：使用部署包内置 frpc

部署包已经包含可选 frpc 容器配置，默认不会启动。需要使用时，先编辑：

```text
docker/frpc/frpc.toml
```

文件中用 `# XXXX` 标出的地方需要按你的 frps 服务端配置修改：

```toml
# XXXX 公网 frps 服务器地址
serverAddr = "XX.XX.XX.XX"

# XXXX 公网 frps 服务端口，必须与 frps 的 bindPort 一致
serverPort = 7000

# XXXX 必须替换为 frps 服务端配置中的 token
auth.token = "XXXXX"
```

默认模板已经配置了三个 TCP 代理：

```text
seg-frontend: 内部 frontend:80  -> 远端 13000
seg-backend:  内部 backend:8000 -> 远端 18000
seg-minio:    内部 minio:9000   -> 远端 19000
```

frpc 容器和系统服务在同一个 Docker Compose 网络里，所以 `localIP` 推荐保持为 `frontend`、`backend`、`minio` 这些服务名；如果改成宿主机或其他内网 IP，也可以按你的实际网络调整。

启用内置 frpc 的 CPU 版启动命令：

```bash
docker compose --profile frpc up -d --build
```

启用内置 frpc 的 GPU 版启动命令：

```bash
docker compose --profile frpc -f docker-compose.yml -f docker-compose.gpu.yml up -d --build
```

只重启 frpc：

```bash
docker compose --profile frpc up -d frpc
```

查看 frpc 日志：

```bash
docker compose --profile frpc logs -f frpc
```

不带 `--profile frpc` 的普通启动命令不会启动 frpc：

```bash
docker compose up -d
docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d
```

NPM 中配置三个 Proxy Host：

```text
seg.example.com
  Scheme: http
  Forward Hostname / IP: 127.0.0.1
  Forward Port: 13000

seg-api.example.com
  Scheme: http
  Forward Hostname / IP: 127.0.0.1
  Forward Port: 18000
  Websocket Support: 开启

seg-minio.example.com
  Scheme: http
  Forward Hostname / IP: 127.0.0.1
  Forward Port: 19000
```

建议三个域名都在 NPM 里申请 HTTPS 证书，并开启 HTTPS。公网 HTTPS 场景下，内网 `Seg_Server_Docker/.env` 需要修改 `# XXXX` 标出的几项：

```ini
# XXXX Public-domain access through frpc/frps + NPM
PUBLIC_HOST=seg.example.com

# XXXX Frontend build-time API/WebSocket endpoints
VITE_API_BASE_URL=https://seg-api.example.com
VITE_WS_PROGRESS_URL=wss://seg-api.example.com/ws/progress

# XXXX Browser-facing MinIO endpoint
MINIO_PUBLIC_ENDPOINT=seg-minio.example.com
MINIO_SECURE=false
MINIO_PUBLIC_SECURE=true

# XXXX Browser origins
CORS_ORIGINS=["https://seg.example.com"]
```

修改 `VITE_API_BASE_URL` 或 `VITE_WS_PROGRESS_URL` 后必须重建前端，因为它们是前端构建期变量：

```bash
docker compose -f docker-compose.yml -f docker-compose.gpu.yml build frontend
docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d frontend backend worker
```

如果同时从零启动 GPU 版：

```bash
docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d --build
```

公网域名部署后，浏览器只需要访问：

```text
https://seg.example.com
```

不要只反代前端 `3000`。后端 `8000` 不通会导致登录、项目、任务和 AI 接口失败；MinIO `9000` 不通会导致帧图、缩略图、预览图等资源加载失败。

## 访问入口

默认地址：

```text
前端：http://localhost:3000
后端：http://localhost:8000
MinIO API：http://localhost:9000
MinIO 控制台：http://localhost:9001
```

局域网访问时，把 `localhost` 换成 `.env` 中的 `PUBLIC_HOST`。

默认账号：

```text
用户名：admin
密码：123456
```

## 演示数据和恢复出厂设置

演示数据固定从部署包本地读取：

```text
demo/演视LC视频序列.mp4
demo/演视DICOM序列/
```

系统启动和“恢复演示出厂设置”都会使用这两个路径。恢复后应出现：

- `演视LC视频序列`
- `演视DICOM序列`

DICOM 序列会按文件名自然顺序读取，避免切片顺序错位。

## 常用运维命令

启动：

```bash
docker compose up -d
```

GPU 启动：

```bash
docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d
```

停止：

```bash
docker compose down
```

查看容器：

```bash
docker compose ps
```

查看日志：

```bash
docker compose logs -f backend
docker compose logs -f worker
docker compose logs -f frontend
```

重建前后端：

```bash
docker compose build backend frontend
docker compose up -d backend worker frontend
```

重建 GPU 版后端和 worker：

```bash
docker compose -f docker-compose.yml -f docker-compose.gpu.yml build backend
docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d backend worker
```

清空当前部署数据：

```bash
docker compose down -v
docker compose up -d --build
```

注意：`down -v` 会删除数据库和 MinIO 对象存储卷，项目、帧、标注和上传文件都会清空。

## 模型状态验证

登录后前端左下角会显示 CPU/GPU 状态。也可以通过后端接口检查：

```bash
curl http://localhost:8000/health
```

模型状态接口需要登录 token。更简单的容器内检查方式：

```bash
docker compose exec -T backend python - <<'PY'
from services.sam_registry import sam_registry
print(sam_registry.runtime_status())
PY
```

GPU 版：

```bash
docker compose -f docker-compose.yml -f docker-compose.gpu.yml exec -T backend python - <<'PY'
from services.sam_registry import sam_registry
print(sam_registry.runtime_status())
PY
```

## 常见问题

### 前端能打开，但图片或缩略图打不开

检查 `.env`：

- `PUBLIC_HOST` 是否是浏览器可以访问到的主机名或 IP。
- `MINIO_PORT` 是否开放。
- `CORS_ORIGINS` 是否包含当前前端地址。

修改 `.env` 后重启：

```bash
docker compose up -d backend worker frontend
```

### 左下角显示 CPU

先确认是 CPU 部署还是 GPU 部署。GPU 部署必须使用：

```bash
docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d
```

再检查 Docker GPU 透传：

```bash
docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi
```

如果这条命令失败，问题在宿主机 Docker GPU runtime，不在应用代码。

### 单帧 AI 分割可用，但 AI 自动推理无结果

检查 `seg-worker` 是否和 `seg-backend` 使用同一个镜像，并且 worker 是否能看到 PyTorch、SAM2 和 GPU：

```bash
docker inspect seg-backend seg-worker --format '{{.Name}} {{.Image}} {{.Config.Image}}'

docker compose -f docker-compose.yml -f docker-compose.gpu.yml exec -T worker python - <<'PY'
import importlib.util, torch
print("torch", bool(importlib.util.find_spec("torch")))
print("sam2", bool(importlib.util.find_spec("sam2")))
print("cuda", torch.cuda.is_available())
PY
```

如果 worker 缺依赖，重建并重启：

```bash
docker compose -f docker-compose.yml -f docker-compose.gpu.yml build backend
docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d backend worker
```

### 恢复演示出厂设置后项目为空

检查 demo 文件是否仍在部署包本地：

```bash
ls demo/演视LC视频序列.mp4
ls demo/演视DICOM序列
```

如果目录被移动或删掉，恢复出厂设置无法重新生成演示项目。

### 模型不可用

检查 `models/`：

```bash
ls -lh models/
```

缺失的 `.pt` 权重对应模型会显示不可用。部署包默认从 `./models` 挂载到容器内 `/app/models`。