operating-room-monitor-server/docs/Docker部署.md

# Docker Compose 部署（NVIDIA GPU）

本文说明在 **NVIDIA GPU 服务器**上通过 Docker Compose 部署全套后端（FastAPI + PostgreSQL + MinIO），以及 Demo 客户端、语音确认页的**手动**启动方式。

## 仓库结构

```
operation-room-monitor/
  backend/          # API + DB + MinIO（docker compose）
  clients/          # 独立前端（手动启动）
  docs/             # 文档
```

## 架构

| 组件 | 部署方式 | 默认端口 |
|------|----------|----------|
| API + PostgreSQL + MinIO | `cd backend && docker compose up -d --build` | 38080 / 45432 / 19000 |
| Demo 客户端 | `clients/demo-client/start.sh` | 38081 |
| 语音确认页 | `clients/voice-confirmation/start.sh` | 8080 |

---

## 一、前置条件

- Docker Compose V2、NVIDIA 驱动、NVIDIA Container Toolkit
- 复制 `backend/.env.example` 为 `backend/.env` 并填写
- 算法子进程包：`backend/algorithm_subprocesses/5.15/`（含 `main.py` 与 `weights/`；镜像构建时会 `COPY` 进容器，勿在 `.dockerignore` 中整目录排除）
- 标注视频中文字体：镜像内已安装 `fonts-noto-cjk`、`fonts-wqy-microhei`（供 `visualize_result_video.py` 绘制耗材标签）
- 医生识别（MediaPipe Pose）：镜像内已安装 `libgles2`、`libegl1`、`libegl-mesa0`、`libglx-mesa0`、`libgl1-mesa-dri` 等 Mesa/GLVND 库；构建阶段会 `import mediapipe` 校验 `libGLESv2.so.2` 可用。子进程强制 CPU delegate。若仍见该错误，请 **`docker compose build --no-cache api`** 后重启（勿沿用旧 tarball 镜像）
- 可选备用权重：`backend/app/resources/actionformer_epoch_045.pth.tar`

---

## 二、启动后端

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

健康检查：

```bash
curl -sf http://127.0.0.1:38080/health
```

GPU 验证：

```bash
docker compose exec api python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"
```

停止 / 重置：

```bash
docker compose down
docker compose down -v   # 删除 PostgreSQL / MinIO 卷
```

---

## 三、手动启动客户端

```bash
cd clients/demo-client && ./start.sh
cd clients/voice-confirmation && ./start.sh
```

浏览器 Base URL 填 `http://<GPU服务器IP>:38080`。

---

## 四、相关文档

- [部署版使用指南.md](部署版使用指南.md)
- [客户端手术通信接口说明.md](客户端手术通信接口说明.md)
- [clients/demo-client/README.md](../clients/demo-client/README.md)
- [clients/voice-confirmation/README.md](../clients/voice-confirmation/README.md)
- [离线镜像tarball部署.md](离线镜像tarball部署.md)