running

.env.example

@@ -27,6 +27,11 @@ POSTGRES_PORT=35432
 # VIDEO_RTSP_URL_TEMPLATE=rtsp://user:pass@host:554/path/{camera_id}
 #
 # 语音终端 ID 在站点 JSON 的 voice_or_room_bindings 中配置；浏览器语音确认页（web/voice-confirmation）在页面内填写本机终端 ID。
+#
+# Docker 跑 API（docker-compose.prod.yml）：站点 JSON 中可与 sample 相同使用术间摄像头局域网 IP（容器出站经宿主机路由，须宿主机可达该网段）。
+# 若 RTSP 由「宿主机」上的假流/服务提供，URL 须用 host.docker.internal 而非 127.0.0.1；compose 已为 api 注入 extra_hosts。
+# 容器内拉流默认使用 TCP（docker-compose.prod.yml）；仅当必须让 FFmpeg 自选传输时在 .env 中设空覆盖：
+# OPENCV_FFMPEG_CAPTURE_OPTIONS=
 
 # --- 海康 SDK（Linux x86_64；二进制勿提交仓库）---
 # HIKVISION_LIB_DIR=/opt/hikvision/lib

.env.prod

@@ -1,36 +0,0 @@
-# 本地/联调。部署项以外默认值见 `app/baked/algorithm.py`、`app/baked/pipeline.py`。
-# 启动前执行 `alembic upgrade head`（`./start.sh` 已跑）。
-
-# --- PostgreSQL ---
-POSTGRES_USER=postgres
-POSTGRES_PASSWORD=postgres
-POSTGRES_DB=operation_room
-POSTGRES_HOST=localhost
-POSTGRES_PORT=35432
-# DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:35432/operation_room
-
-# --- 手术室站点配置（严格 JSON：仅含 video_rtsp_urls + voice_or_room_bindings）---
-# 示例：app/resources/or_site_config.sample.json。一键联调会向该文件合并更新 video_rtsp_urls，须可写。
-OR_SITE_CONFIG_JSON_FILE=app/resources/or_site_config.sample.json
-
-# --- 百度 ---
-BAIDU_APP_ID=31461922
-BAIDU_API_KEY=8NjVDPUl64fg7InpxOka69TE
-BAIDU_SECRET_KEY=DzIO6BTdABb0jFu80jWGDfmpxFfwlvA0
-BAIDU_ASR_DEV_PID=1537
-# 人脸脚本 `scripts/baidu_face_1n_search.py`
-BAIDU_FACE_GROUP_ID_LIST=2_1
-
-# --- MinIO ---
-MINIO_ENDPOINT=127.0.0.1:9000
-MINIO_ACCESS_KEY=minioadmin
-MINIO_SECRET_KEY=minioadmin
-MINIO_BUCKET=operation-room-voice
-MINIO_SECURE=false
-
-# --- Demo 客户端联调 ---
-DEMO_CORS_ENABLED=true
-DEMO_CORS_ORIGINS=*
-DEMO_ORCHESTRATOR_ENABLED=true
-DEMO_ORCHESTRATOR_RTSP_PORT=18554
-DEMO_ORCHESTRATOR_RTSP_JSON_HOST=127.0.0.1

docker-compose.prod.yml

@@ -36,6 +36,10 @@ services:
     build:
       context: .
       dockerfile: Dockerfile
+    # 容器内访问「宿主机上监听的 RTSP」（假流 / MediaMTX 等）需要解析 host.docker.internal。
+    # Linux 默认无该主机名；host-gateway 解析为宿主机在容器网桥上的地址（Docker 20.10+）。
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
     environment:
       POSTGRES_USER: ${POSTGRES_USER:-postgres}
       POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD}
@@ -61,6 +65,21 @@ services:
       HIKVISION_USER: ${HIKVISION_USER:-}
       HIKVISION_PASSWORD: ${HIKVISION_PASSWORD:-}
       HIKVISION_PREVIEW_RTSP_TEMPLATE: ${HIKVISION_PREVIEW_RTSP_TEMPLATE:-}
+      # OpenCV/FFmpeg 拉 RTSP：TCP 在容器 NAT/防火墙场景下比 UDP 更可靠；可用 .env 覆盖为空禁用
+      OPENCV_FFMPEG_CAPTURE_OPTIONS: ${OPENCV_FFMPEG_CAPTURE_OPTIONS:-rtsp_transport;tcp}
+      # 语音待确认：TTS/ASR 需百度；resolve 上传 WAV 还需 MinIO（见 .env.example）
+      BAIDU_APP_ID: ${BAIDU_APP_ID:-}
+      BAIDU_API_KEY: ${BAIDU_API_KEY:-}
+      BAIDU_SECRET_KEY: ${BAIDU_SECRET_KEY:-}
+      BAIDU_ASR_DEV_PID: ${BAIDU_ASR_DEV_PID:-1537}
+      MINIO_ENDPOINT: ${MINIO_ENDPOINT:-}
+      MINIO_ACCESS_KEY: ${MINIO_ACCESS_KEY:-}
+      MINIO_SECRET_KEY: ${MINIO_SECRET_KEY:-}
+      MINIO_BUCKET: ${MINIO_BUCKET:-operation-room-voice}
+      MINIO_SECURE: ${MINIO_SECURE:-false}
+      MINIO_REGION: ${MINIO_REGION:-}
+      DEMO_CORS_ENABLED: ${DEMO_CORS_ENABLED:-false}
+      DEMO_CORS_ORIGINS: ${DEMO_CORS_ORIGINS:-*}
     ports:
       - "${API_PORT:-38080}:8000"
     depends_on:

docs/video-backends.md

@@ -14,6 +14,12 @@
 2. 调用 `POST /client/surgeries/start` 时，`camera_ids` 必须能在上述配置中解析出 RTSP 地址。
 3. **开录确认**：每路摄像头在超时内成功打开并读到**首帧**后，才认为该路已开录。
 
+## 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.prod.yml`](../docker-compose.prod.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 模式（可选）
 
 SDK **不作为构建期依赖**：将厂商提供的 Linux x86_64 动态库挂载到容器内（例如 `/opt/hikvision/lib/libhcnetsdk.so`），并设置：

docs/客户端手术通信接口说明.md

@@ -34,6 +34,8 @@ 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.prod.yml`。
+
 ## 3. HTTP 路由一览
 
 | **序号** | **方法** | **路径**                                                                          | **说明**  |