# Docker Compose 部署（NVIDIA GPU）

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

## 架构

| 组件 | 部署方式 | 默认端口 |
|------|----------|----------|
| API + PostgreSQL + MinIO | `docker compose up -d --build` | 38080 / 35432 / 9000 |
| Demo 客户端 | `clients/demo-client/start.sh`（宿主机 Python） | 38081 |
| 语音确认页 | `clients/voice-confirmation/start.sh`（宿主机 Python） | 8080 |

Demo 页与语音页通过 HTTP/WebSocket 访问 API；浏览器 Base URL 填 `http://<GPU服务器局域网IP>:38080`。

---

## 一、前置条件

### 宿主机

- **Docker** 与 **Docker Compose V2**（`docker compose`）
- **NVIDIA 驱动**，`nvidia-smi` 正常
- **[NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)**，且 `docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi` 可用
- 磁盘：PostgreSQL / MinIO 使用命名卷，建议预留数十 GB

### 仓库与配置

1. 复制环境变量模板：

```bash
cp .env.example .env
```

2. 编辑 `.env`：至少修改 `POSTGRES_PASSWORD`；配置 `BAIDU_*`（语音）、`OR_SITE_CONFIG_JSON_FILE`（站点 JSON）等。

3. 确保 ActionFormer 权重存在：`app/resources/actionformer_epoch_045.pth.tar`（~110MB，离线下发，未入 git）。

4. VideoSwin 预训练权重首次运行可能需联网下载；容器内默认缓存目录 `TORCH_HOME=/root/.cache/torch`。

---

## 二、启动后端

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

首次构建或代码变更后加 `--build`；日常重启可用 `docker compose up -d`。

健康检查：

```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))"
```

常用环境变量（写在 `.env` 中）：

| 变量 | 说明 |
|------|------|
| `API_PORT` | API 宿主机映射端口，默认 38080 |
| `DOCKER_POSTGRES_PUBLISH_PORT` | PostgreSQL 宿主机映射端口，默认 35432（仅调试） |

查看日志：

```bash
docker compose logs -f api
```

停止服务：

```bash
docker compose down
```

**重置所有数据**（PostgreSQL + MinIO 卷会被删除）：

```bash
docker compose down -v
```

---

## 三、手动启动客户端页面

后端 `docker compose up -d` 成功后，在**同一台或局域网内其他机器**上：

```bash
# Demo 联调页（默认 0.0.0.0:38081）
cd clients/demo-client && ./start.sh

# 语音确认页（默认 0.0.0.0:8080）
cd clients/voice-confirmation && ./start.sh
```

浏览器访问：

- Demo：`http://<主机IP>:38081/`
- 语音确认：`http://<主机IP>:8080/`

两页内的 **服务端 Base URL** 均指向监控 API：`http://<GPU服务器IP>:38080`。

### CORS

独立部署的前端跨域访问 API 时，`.env` 中需 `DEMO_CORS_ENABLED=true`。生产环境建议将 `DEMO_CORS_ORIGINS` 收窄为具体来源，例如：

```bash
DEMO_CORS_ORIGINS=http://192.168.1.100:8080,http://192.168.1.100:38081
```

### 语音确认单 HTML 分发

```bash
cd clients/voice-confirmation && ./start.sh --single 8080
```

会生成 `clients/voice-confirmation/dist/index.html` 并启动静态服务，便于离线拷贝。

---

## 四、RTSP 与站点配置

- 站点 JSON（`OR_SITE_CONFIG_JSON_FILE`）维护术间、摄像头 RTSP、语音终端绑定；样例见 `app/resources/or_site_config.sample.json`。
- API 在 Docker 内访问**宿主机**上的 RTSP 假流时，URL 应使用 `host.docker.internal`（compose 已为 `api` 配置 `extra_hosts`）。
- 详见 [video-backends.md](video-backends.md)。

无真摄像头联调时，可在宿主机运行 `clients/demo-client/fake_rtsp_from_file.py`，详见 [clients/demo-client/README.md](../clients/demo-client/README.md)。

---

## 五、常见问题

**Q：容器内 GPU 不可用？**

确认宿主机已安装 NVIDIA Container Toolkit，且 `docker-compose.yml` 中 `api` 服务含 `gpus: all`。验证：

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

**Q：语音页麦克风不可用？**

勿用 `file://` 打开；须通过 HTTP(S) 访问。非 localhost 场景通常需要 HTTPS。

**Q：如何升级 API？**

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

容器启动时会执行 `alembic upgrade head`。

**Q：离线 tarball 交付？**

见 [离线镜像tarball部署.md](离线镜像tarball部署.md)。

---

## 六、相关文档

- [部署版使用指南.md](部署版使用指南.md) — 语音确认页填写说明（面向现场人员）
- [客户端手术通信接口说明.md](客户端手术通信接口说明.md) — API 协议
- [clients/voice-confirmation/README.md](../clients/voice-confirmation/README.md) — 语音页独立分发
- [clients/demo-client/README.md](../clients/demo-client/README.md) — Demo 页与假 RTSP