fix(docker): start mediamtx-hls without shell on scratch image.

Seed shared HLS config via alpine init container and pass explicit config path for ephemeral docker run.

Co-authored-by: Cursor <cursoragent@cursor.com>

backend/app/services/hls_preview.py

@@ -299,6 +299,7 @@ class HlsPreviewManager:
             "-p",
             f"{publish_host}:{port}:{_MEDIAMTX_HLS_INTERNAL_PORT}",
             MEDIAMTX_IMAGE,
+            "/mediamtx.yml",
         ]
         r = subprocess.run(cmd, capture_output=True, text=True, timeout=120)
         if r.returncode != 0:

backend/docker-compose.yml

@@ -21,22 +21,32 @@ services:
       retries: 20
       start_period: 5s
 
-  mediamtx-hls:
-    image: ${MEDIAMTX_DOCKER_IMAGE:-m.daocloud.io/docker.io/bluenviron/mediamtx:latest}
-    container_name: orm-mediamtx-hls
-    restart: unless-stopped
+  # bluenviron/mediamtx 为 scratch 镜像，仅含 /mediamtx，无 /bin/sh；用 alpine init 种子配置。
+  hls-preview-init:
+    image: m.daocloud.io/docker.io/library/alpine:3.20
+    restart: "no"
+    volumes:
+      - hls_preview_config:/config
+      - ./resources/mediamtx_hls_preview.bootstrap.yml:/seed/mediamtx.yml:ro
     entrypoint: ["/bin/sh", "-c"]
     command:
       - |
         if [ ! -f /config/mediamtx.yml ]; then
-          cp /bootstrap/mediamtx.yml /config/mediamtx.yml
+          cp /seed/mediamtx.yml /config/mediamtx.yml
         fi
-        exec /mediamtx /config/mediamtx.yml
+
+  mediamtx-hls:
+    image: ${MEDIAMTX_DOCKER_IMAGE:-m.daocloud.io/docker.io/bluenviron/mediamtx:latest}
+    container_name: orm-mediamtx-hls
+    restart: unless-stopped
+    command: ["/config/mediamtx.yml"]
     ports:
       - "127.0.0.1:${DEMO_HLS_PREVIEW_PORT:-18888}:8888"
     volumes:
       - hls_preview_config:/config
-      - ./resources/mediamtx_hls_preview.bootstrap.yml:/bootstrap/mediamtx.yml:ro
+    depends_on:
+      hls-preview-init:
+        condition: service_completed_successfully
 
   minio:
     image: m.daocloud.io/docker.io/minio/minio:latest

docs/video-backends.md

@@ -63,7 +63,7 @@ SDK **不作为构建期依赖**：将厂商提供的 Linux x86_64 动态库挂
 
 | 部署方式 | 行为 |
 |----------|------|
-| **Docker Compose（推荐）** | 固定服务 `mediamtx-hls`（宿主机 `127.0.0.1:18888`）；`ensure` 写共享 `mediamtx.yml` 并 `docker restart orm-mediamtx-hls`；`DEMO_HLS_PREVIEW_UPSTREAM=http://127.0.0.1:18888` |
+| **Docker Compose（推荐）** | 固定服务 `mediamtx-hls`（宿主机 `127.0.0.1:18888`）；`hls-preview-init` 种子共享卷后 MediaMTX 直接读 `/config/mediamtx.yml`（官方镜像是 scratch，勿用 `/bin/sh` entrypoint）；`ensure` 写共享 `mediamtx.yml` 并 `docker restart orm-mediamtx-hls`；`DEMO_HLS_PREVIEW_UPSTREAM=http://127.0.0.1:18888` |
 | **本机 uvicorn** | 未设 upstream 时按需 `docker run` 临时 MediaMTX（端口默认 `127.0.0.1:18888`） |
 
 | 链路 | 行为 |