running

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 路由一览
 
 | **序号** | **方法** | **路径**                                                                          | **说明**  |