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`），并设置：