统一 Docker Compose 部署，并将客户端拆分为独立子项目。
移除宿主机/conda 启动脚本与 dev 联调工具，后端仅通过 docker compose 部署并默认启用 GPU。模拟客户端与语音确认页迁入 clients/ 下自包含目录，切断对后端源码路径的依赖。 Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Kevin
170
docs/Docker部署.md
Normal file
170
docs/Docker部署.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user