重组为 backend/clients/docs 三层结构，并清理 git 污染。
将后端迁入 backend/，完善根目录 .gitignore，删除误提交的 .mypy_cache 缓存文件。 Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Kevin
147
docs/Docker部署.md
147
docs/Docker部署.md
@@ -2,169 +2,76 @@
|
||||
|
||||
本文说明在 **NVIDIA GPU 服务器**上通过 Docker Compose 部署全套后端（FastAPI + PostgreSQL + MinIO），以及 Demo 客户端、语音确认页的**手动**启动方式。
|
||||
|
||||
## 仓库结构
|
||||
|
||||
```
|
||||
operation-room-monitor/
|
||||
backend/ # API + DB + MinIO（docker compose）
|
||||
clients/ # 独立前端（手动启动）
|
||||
docs/ # 文档
|
||||
```
|
||||
|
||||
## 架构
|
||||
|
||||
| 组件 | 部署方式 | 默认端口 |
|
||||
|------|----------|----------|
|
||||
| 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`。
|
||||
| API + PostgreSQL + MinIO | `cd backend && docker compose up -d --build` | 38080 / 35432 / 9000 |
|
||||
| Demo 客户端 | `clients/demo-client/start.sh` | 38081 |
|
||||
| 语音确认页 | `clients/voice-confirmation/start.sh` | 8080 |
|
||||
|
||||
---
|
||||
|
||||
## 一、前置条件
|
||||
|
||||
### 宿主机
|
||||
|
||||
- **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`。
|
||||
- Docker Compose V2、NVIDIA 驱动、NVIDIA Container Toolkit
|
||||
- 复制 `backend/.env.example` 为 `backend/.env` 并填写
|
||||
- ActionFormer 权重：`backend/app/resources/actionformer_epoch_045.pth.tar`
|
||||
|
||||
---
|
||||
|
||||
## 二、启动后端
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
首次构建或代码变更后加 `--build`；日常重启可用 `docker compose up -d`。
|
||||
|
||||
健康检查：
|
||||
|
||||
```bash
|
||||
curl -sf http://127.0.0.1:38080/health
|
||||
```
|
||||
|
||||
GPU 验证（可选）：
|
||||
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 down -v # 删除 PostgreSQL / MinIO 卷
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、手动启动客户端页面
|
||||
|
||||
后端 `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` 并启动静态服务，便于离线拷贝。
|
||||
浏览器 Base URL 填 `http://<GPU服务器IP>:38080`。
|
||||
|
||||
---
|
||||
|
||||
## 四、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
|
||||
- [部署版使用指南.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)
|
||||
|
||||
@@ -17,7 +17,7 @@
|
||||
## Docker 与 RTSP 地址
|
||||
|
||||
- **站点 JSON 中的局域网 IP**（如 `[or_site_config.sample.json](../app/resources/or_site_config.sample.json)` 的 `192.168.3.x`）：API 在默认 **bridge** 网络下出站流量经 **宿主机** 转发，只要**宿主机**能访问该网段，容器内一般可直接使用相同 URL，无需改成 `172.x` 等。
|
||||
- **`127.0.0.1` / `localhost`**：在容器内指向**容器自身**。若 RTSP 服务跑在宿主机（含 `fake_rtsp_from_file.py`、本机 MediaMTX），URL 应使用 **`rtsp://host.docker.internal:<端口>/<路径>`**。[`docker-compose.yml`](../docker-compose.yml) 已为 `api` 服务配置 `extra_hosts: host.docker.internal:host-gateway`（Linux 兼容；macOS/Windows Desktop 通常已内置该主机名）。
|
||||
- **`127.0.0.1` / `localhost`**：在容器内指向**容器自身**。若 RTSP 服务跑在宿主机（含 `fake_rtsp_from_file.py`、本机 MediaMTX），URL 应使用 **`rtsp://host.docker.internal:<端口>/<路径>`**。[`backend/docker-compose.yml`](../backend/docker-compose.yml) 已为 `api` 服务配置 `extra_hosts: host.docker.internal:host-gateway`（Linux 兼容；macOS/Windows Desktop 通常已内置该主机名）。
|
||||
- **传输协议**：compose 默认设置环境变量 **`OPENCV_FFMPEG_CAPTURE_OPTIONS=rtsp_transport;tcp`**，使 OpenCV 经 FFmpeg 以 **TCP** 拉 RTSP，降低容器/NAT 下 UDP 丢包导致的首帧超时；可通过环境变量覆盖。
|
||||
|
||||
## 海康官方 SDK 模式（可选）
|
||||
@@ -47,4 +47,4 @@ SDK **不作为构建期依赖**：将厂商提供的 Linux x86_64 动态库挂
|
||||
|
||||
## 相关环境变量
|
||||
|
||||
详见仓库根目录 `.env.example` 中「视频：RTSP + 可选海康 HCNetSDK」一节。
|
||||
详见 `backend/.env.example` 中「视频：RTSP + 可选海康 HCNetSDK」一节。
|
||||
@@ -36,7 +36,7 @@ RTSP 地址、账号、口令等由客户端对接工程师提供给服务端运
|
||||
| `or-cam-03` | `rtsp://admin:Aa183137@192.168.3.4:554/Streaming/Channels/101` | 同上 |
|
||||
| `or-cam-04` | `rtsp://admin:Aa183137@192.168.3.5:554/Streaming/Channels/101` | 同上 |
|
||||
|
||||
**Docker 部署**：API 在容器内拉流时，上表这类**术间摄像头局域网 IP**通常可继续使用（出站经宿主机路由，须宿主机已能访问该网段）。若 RTSP 实际跑在**宿主机本机**（假流等），URL 中的主机应使用 `host.docker.internal`，勿写 `127.0.0.1`；详见 `docs/video-backends.md` 与 `docker-compose.yml`。
|
||||
**Docker 部署**：API 在容器内拉流时，上表这类**术间摄像头局域网 IP**通常可继续使用（出站经宿主机路由，须宿主机已能访问该网段）。若 RTSP 实际跑在**宿主机本机**（假流等），URL 中的主机应使用 `host.docker.internal`，勿写 `127.0.0.1`；详见 `docs/video-backends.md` 与 `backend/docker-compose.yml`。
|
||||
|
||||
## 3. HTTP 路由一览
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
本文说明 **方式 B**：厂商在可联网环境构建并导出 API 镜像为 `tar`/`tar.gz`，客户在目标服务器 **不拉取 API 镜像构建上下文** 的情况下，通过 `docker load` 加载后启动完整后端（PostgreSQL + MinIO + API）。
|
||||
|
||||
> 说明：仓库默认的 `docker-compose.yml` 中 `api` 使用 `build:`。客户侧使用 tarball 时，必须使用下方 **「仅使用已加载镜像」** 的 Compose 片段（将 `build` 换成 `image`），否则仍会尝试本地构建。
|
||||
> 说明：仓库默认的 `backend/docker-compose.yml` 中 `api` 使用 `build:`。客户侧使用 tarball 时，必须使用下方 **「仅使用已加载镜像」** 的 Compose 片段（将 `build` 换成 `image`），否则仍会尝试本地构建。
|
||||
|
||||
---
|
||||
|
||||
@@ -13,7 +13,7 @@
|
||||
### 1. 构建并打标签
|
||||
|
||||
```bash
|
||||
cd /path/to/operation-room-monitor-server
|
||||
cd /path/to/operation-room-monitor/backend
|
||||
docker compose build api
|
||||
docker tag operation-room-monitor-server-api:latest <交付镜像名>:<版本号>
|
||||
# 示例：docker tag operation-room-monitor-server-api:latest acme/or-monitor-api:1.0.0
|
||||
@@ -51,8 +51,8 @@ docker save \
|
||||
|------|------|
|
||||
| `or-monitor-api_*.tar.gz`（或全栈 `*_offline.tar.gz`） | 镜像包 |
|
||||
| 本文档 | 客户部署步骤 |
|
||||
| `docker-compose.yml` **或** 下文「离线 Compose」全文 | `api` 使用 `image:` 而非 `build:` |
|
||||
| `.env.example`（按项目实际改名） | 环境变量模板，勿包含真实密钥 plaintext 于公共渠道 |
|
||||
| `docker-compose.yml` **或** 下文「离线 Compose」全文 | `api` 使用 `image:` 而非 `build:`（位于 `backend/`） |
|
||||
| `backend/.env.example`（按项目实际改名） | 环境变量模板，勿包含真实密钥 plaintext 于公共渠道 |
|
||||
|（可选）语音确认前端静态包、`OR_SITE_CONFIG` 样例 | 按需 |
|
||||
|
||||
---
|
||||
@@ -212,7 +212,7 @@ volumes:
|
||||
|
||||
## 五、环境变量与密钥
|
||||
|
||||
在同一目录放置 `.env`（可参考仓库内 `.env.example`）。至少建议关注：
|
||||
在同一目录（`backend/`）放置 `.env`（可参考 `backend/.env.example`）。至少建议关注：
|
||||
|
||||
- `POSTGRES_PASSWORD`：生产请务必改为强密码。
|
||||
- `API_PORT`：宿主机监听端口。
|
||||
|
||||
@@ -52,4 +52,4 @@
|
||||
|
||||
---
|
||||
|
||||
以上内容对应仓库里的语音确认页面（`clients/voice-confirmation`）。手术室主程序、摄像头等由别家软件或信息科配置，不在此页填写。
|
||||
以上内容对应 `clients/voice-confirmation/` 语音确认页面。手术室主程序、摄像头等由别家软件或信息科配置，不在此页填写。
|
||||
Reference in New Issue
Block a user