Restreamer 2.12.0 Docker Compose 部署指南

‍‍​​‌​> 目标：用 Docker Compose 从零部署一套 Restreamer 2.12.0 流媒体服务器，覆盖版本选型、端口规划、数据持久化、环境变量、配置挂载、推拉流冒烟验证与运维命令——全部步骤在 Ubuntu 24.04 x86_64 + Docker 29.9.2 环境实测通过。

一、环境信息

本文所有命令与回显均在以下真实环境实测通过（实测日期 2026-10-30）：

• 操作系统：Ubuntu 24.04.5 LTS（x86_64）
• Docker：29.9.2（含 compose v2 插件，docker compose version 回显 Docker Compose version v5.6.1）
• Restreamer：datarhei/restreamer:2.12.0（官方发行版，amd64 架构，digest sha256:813acc9d41d2953b1e7fbb5b281f9a1f68d07fef4e1b30e34472b12d3db9426a，docker inspect 实测）
• 内核组件：datarhei-core 16.16.0（服务启动日志实测回显 version="16.16.0" build="2024-06-07T10:01:49Z" license="Apache License Version 2.0"）
• 部署形态：单服务部署，服务内 Restreamer 以 /core/bin/run.sh 为入口常驻（docker compose ps 实测 COMMAND 列回显）
• 本次实测宿主端口规划：宿主机 1935 已被既有服务占用，按「宿主空闲端口 → 服务标准端口」重映射（8156→8080、8157→8181、19355→1935、19356→1936、16000→6000/udp）；生产环境宿主侧空闲时可保持同号映射
• 选型依据与软件定位见[《Restreamer 介绍与选型指南》](https://www.quzuo.net/document/T9V4T9qaPrlq)

二、镜像选型说明

Restreamer 官方只在 Docker Hub 以 datarhei/restreamer 发行（无裸机二进制），tag 规则与变体如下（查询日期 2026-10-30，实查自官方 GitHub Releases 发布说明）：

选型要点：固定版本号 tag（如 2.12.0）而不是 latest，保证重建服务时版本可追溯；硬件转码需求才选对应变体（变体体积更大）；版本与官方 Releases 对应，2.12.0 为当前最新稳定版（2024-09-13 发布）。拉取命令（⚠️ 网络说明：实测宿主 Docker 守护进程可直连 Docker Hub 完成拉取；若你的网络超时，为守护进程配置镜像加速器或代理后重试）：

docker pull datarhei/restreamer:2.12.0

2.12.0: Pulling from datarhei/restreamer
Digest: sha256:813acc9d41d2953b1e7fbb5b281f9a1f68d07fef4e1b30e34472b12d3db9426a
Status: Downloaded newer image for datarhei/restreamer:2.12.0

💡 技术拓展：服务端直播转码有「CPU 软编（libx264）」与「GPU 硬编（NVENC/QSV/OMX）」两条路线，对应官方发行变体——标准版用 libx264（兼容性最好、CPU 占用高），cuda-/vaapi-/rpi- 变体启用硬件编码器（占用低、画质调优空间小）。本文因是通用验证环境，实测采用标准版软编。

三、前置条件

1. 服务器已安装 Docker 24+ 与 compose v2 插件，docker compose version 有输出；
2. 端口规划完成：HTTP 8080（Web 界面 + API + HLS 分发）、HTTPS 8181（可选，TLS 默认未启用）、RTMP 1935、RTMPS 1936、SRT 6000/UDP。宿主端口冲突时只改映射左侧（宿主侧），服务内标准端口不要改；
3. 规划两个持久化目录（本文用 /opt/restreamer/config 与 /opt/restreamer/data）：前者放配置与数据库（升级不丢），后者放磁盘存储产物；
4. 防火墙放行上述端口（对外提供播放时 8080 必放，仅内网可收紧）。

四、部署步骤

4.1 编写 docker-compose.yml

在 /opt/restreamer/docker-compose.yml 写入（以下即本次实测配置，宿主侧端口为实测重映射值）：

name: restreamer-2-12-0-stack
services:
  restreamer:
    image: datarhei/restreamer:2.12.0
    container_name: restreamer-2-12-0-main
    restart: unless-stopped
    ports:
      - "8156:8080"      # HTTP Web UI / HLS / API
      - "8157:8181"      # HTTPS Web UI（默认未启用 TLS）
      - "19355:1935"     # RTMP 入口
      - "19356:1936"     # RTMPS 入口
      - "16000:6000/udp" # SRT 入口
    volumes:
      - ./config:/core/config
      - ./data:/core/data
    environment:
      - RS_USERNAME=admin
      - RS_PASSWORD=q1w2e3r4
      - CORE_RTMP_ENABLE=true
      - CORE_SRT_ENABLE=true
      - CORE_STORAGE_MEMORY_AUTH_USERNAME=admin
      - CORE_STORAGE_MEMORY_AUTH_PASSWORD=q1w2e3r4
    networks:
      restreamer-net:
        ipv4_address: 10.89.66.2
networks:
  restreamer-net:
    name: restreamer-2-12-0-net
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.66.0/24

逐项解读：

• name: compose 项目名，docker compose 系列命令按它分组管理；
• ports: 左侧是宿主端口、右侧是 Restreamer 固定监听端口；UDP 映射必须带 /udp 后缀，漏写会导致 SRT 不通；
• volumes: ./config 挂到 /core/config（配置文件 config.json 与内置数据库都在这里，必须持久化，否则重建后管理员账号与流水线全丢）；./data 挂到 /core/data（磁盘存储目录，HLS 归档/快照同步落点）；
• environment: RS_USERNAME/RS_PASSWORD 是 Web 界面管理员凭据（首次启动自动创建）；CORE_* 是透传给内核的环境变量覆盖（完整机制见第五章与《Restreamer 2.12.0 配置参数详解》）；
• restart: unless-stopped 开机自启与异常拉起。

4.2 启动并确认

cd /opt/restreamer && docker compose up -d && docker compose ps

实测回显：

NAME                     IMAGE                        COMMAND              SERVICE      CREATED       STATUS     PORTS
restreamer-2-12-0-main   datarhei/restreamer:2.12.0   "/core/bin/run.sh"   restreamer   7 hours ago   Up 7 hours   0.0.0.0:19355->1935/tcp, 0.0.0.0:19356->1936/tcp, 0.0.0.0:16000->6000/udp, 0.0.0.0:8156->8080/tcp, 0.0.0.0:8157->8181/tcp

启动日志中三个「Server started」是服务就绪的权威判据（docker logs restreamer-2-12-0-main 2>&1 | grep "Server started" 实测回显）：

ts=2026-10-29T17:38:53Z level=INFO component="HTTP" msg="Server started" address=":8080"
ts=2026-10-29T17:38:53Z level=INFO component="RTMP" msg="Server started" address=":1935"
ts=2026-10-29T17:38:53Z level=INFO component="SRT" msg="Server started" address=":6000"

再用 HTTP 探针确认 API 可用（实测回显）：

curl http://127.0.0.1:8156/ping

pong

4.3 推流、拉流两项冒烟验证

推一路测试流（testsrc 彩条 + 440Hz 正弦音）到 RTMP 入口（实测完整回显见 ffmpeg_push.log，此处节选关键行）：

ffmpeg -re -f lavfi -i testsrc=size=640x360:rate=25 -f lavfi -i sine=frequency=440:sample_rate=44100 \
  -c:v libx264 -preset ultrafast -tune zerolatency -pix_fmt yuv420p -g 50 \
  -c:a aac -b:a 64k -f flv rtmp://127.0.0.1:19355/live/test.stream

Output #0, flv, to 'rtmp://127.0.0.1:19355/live/test.stream':
frame=  105 fps= 29 q=16.0 size=     162kB time=00:00:04.16 bitrate= 319.1kbits/s speed=1.14x

服务端日志同步确认入站会话（docker logs restreamer-2-12-0-main 2>&1 | grep PUBLISH | head -3 实测回显）：

ts=2026-10-29T17:39:04Z level=INFO component="RTMP" action="START" address=":1935" client="10.89.66.1:47830" path="/live/test.stream" who="PUBLISH"
ts=2026-10-29T17:39:04Z level=INFO component="RTMP" msg="H264" action="STREAM" address=":1935" client="10.89.66.1:47830" path="/live/test.stream" who="PUBLISH"
ts=2026-10-29T17:39:04Z level=INFO component="RTMP" msg="AAC" action="STREAM" address=":1935" client="10.89.66.1:47830" path="/live/test.stream" who="PUBLISH"

拉 HLS 分发地址取证（实测回显节选）：

curl http://127.0.0.1:8156/memfs/live.m3u8

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-STREAM-INF:BANDWIDTH=1024
live.m3u8?session=bufEgDZ8VX7VXfWU8MoZhZ

推流建立后 core 自动创建 live 流水线（日志实测回显 ts=… level=INFO component="Process" msg="Started" id="live"）。浏览器打开 http://<宿主IP>:8156 即可在 Web 界面看到直播流在线并预览播放。

五、数据持久化说明

Restreamer 的落盘数据只有两处，重建服务前先分清：

1. 配置与数据库（/core/config）：config.json（服务主配置）+ v1.json（内置数据库，存管理员账号、流水线、播放器页面等）。首次启动日志实测回显 Database doesn't exist and nothing will be imported database="/core/config/v1.json"，之后每次变更都写入该文件。不挂载此目录 = 重建后回到初始向导。
2. 磁盘存储（/core/data）：HLS 分片等 memfs 产物按需同步的落点（CORE_STORAGE_DISK_DIR 指定，默认 ./data 即容器内 /core/data）。直播切片以内存分发为主，此目录主要承接录像/快照类产物，按需持久化。

升级版本时：改 compose 中的 image tag → docker compose up -d（原地重建），配置目录原样保留即完成迁移；跨大版本升级先看官方 Releases 的 breaking changes 说明再动。

六、环境变量表

Restreamer 的环境变量分两类：RS_*（发行层：界面管理员凭据等）与 CORE_*（透传内核的配置覆盖，对应 config.json 的同名路径，下表均为本次实测使用过的键，完整清单以官方文档与《Restreamer 2.12.0 配置参数详解》为准）：

解读：CORE_* 的生效规则是「同名路径覆盖 config.json 对应字段」，因此环境变量适合部署期固定项（开关、目录、凭据），细粒度参数（端口、日志、限流）建议直接改 config.json 后热加载，两种方式的分工见配置篇。修改环境变量必须 docker compose up -d 重建服务才生效。

七、配置参数说明

服务启动后会在挂载目录生成主配置 /opt/restreamer/config/config.json，本次实测生成的文件关键段（节选自实测文件）：

{
    "name": "quiet-lake-3440",
    "address": ":8080",
    "log": { "level": "info", "max_lines": 1000 },
    "db": { "dir": "./config" },
    "api": { "auth": { "enable": false } },
    "tls": { "address": ":8181", "enable": false },
    "storage": { "disk": { "dir": "./data" } }
}

逐项解读：address 是 HTTP 总入口监听地址（8080 一个端口承载界面/API/HLS）；log.level 默认 info（排障时改 debug）；api.auth.enable=false 表示 REST API 本机内不鉴权（对外暴露前必须启用，启用后走 JWT，见 API 篇实测）；tls.enable=false 表示 8181 未启 TLS（生产启用后可用 Let's Encrypt 自动签发）。全部参数的逐项拆解见《Restreamer 2.12.0 配置参数详解》。

修改配置后热加载（实测回显）：

curl http://127.0.0.1:8156/api/v3/config/reload

"OK"

⚠️ 注意：/api/v3/config/reload 会触发内核重启（Swagger 描述原文 "This will trigger a restart of the Core."），进行中的推流水线会短暂中断并按 reconnect 策略恢复。

八、等价 docker run 命令

不用 compose 的等价单命令（参数与第四章 compose 完全对应，可直接使用；来源为官方 README 快速启动命令并按本文端口规划改写）：

docker run -d --restart=always --name restreamer-2-12-0-main \
   -v /opt/restreamer/config:/core/config \
   -v /opt/restreamer/data:/core/data \
   -p 8156:8080 -p 8157:8181 \
   -p 19355:1935 -p 19356:1936 \
   -p 16000:6000/udp \
   -e RS_USERNAME=admin -e RS_PASSWORD=q1w2e3r4 \
   -e CORE_RTMP_ENABLE=true -e CORE_SRT_ENABLE=true \
   -e CORE_STORAGE_MEMORY_AUTH_USERNAME=admin \
   -e CORE_STORAGE_MEMORY_AUTH_PASSWORD=q1w2e3r4 \
   datarhei/restreamer:2.12.0

参数解读与 compose 一致；差异仅有 --restart=always（compose 用 unless-stopped，两者语义差在手动停止后是否仍自启）与网络（run 默认 bridge，无固定 IP；需要固定内网 IP 时用 compose）。官方原版最小命令（仅挂载与端口，凭据走向导，查询日期 2026-10-30 实查自官方 README）：

docker run -d --restart=always --name restreamer \
   -v /opt/restreamer/config:/core/config -v /opt/restreamer/data:/core/data \
   -p 8080:8080 -p 8181:8181 \
   -p 1935:1935 -p 1936:1936 \
   -p 6000:6000/udp \
   datarhei/restreamer:latest

九、常用运维命令

以下命令均在本文实测环境验证过（compose 项目目录 /opt/restreamer 下执行）：

docker compose ps                          # 查看服务状态与端口映射（实测回显见 4.2）
docker compose logs -f --tail=100          # 跟踪服务日志（内核日志含推拉流会话明细）
docker compose restart                     # 重启服务（进行中的流水线会按 reconnect 恢复）
docker compose down                        # 停止并移除服务（挂载目录保留，数据不丢）
docker compose up -d                       # 启动/重建（改 yml 或版本后执行）

日志中巡检要点（实测样例）：

ts=2026-10-30T02:39:04Z level=INFO component="Session" msg="Active" id="/live/test.stream" location="publish:/live/test.stream" type="rtmp"
ts=2026-10-30T02:43:22Z level=INFO component="Process" msg="Started" id="live"

逐行解读：Session msg="Active" 是入站推流会话建立（who="PUBLISH"）；Process msg="Started" id="live" 是流水线拉起。二选一消失即流断，配合 API 巡检（/api/v3/process/live/state 的 exec 字段）最直观，见《Restreamer 2.12.0 API 使用详解》。

十、常见问题（FAQ）

Q1：宿主 1935 端口已被占用，服务起不来怎么办？

实测现象与解法：本机 1935 已有其他服务监听，compose 直接映射会报端口冲突。改映射左侧为空闲高位端口（如 19355:1935），推流端改推 rtmp://<宿主>:19355/live/... 即可（本文全部实测即用 19355）。服务内 1935 不要改——内核进程间通过 rtmp://localhost:1935 互访。

Q2：重建服务后，推流端显示已连接但直播页一直「无流」？

实测排障实录：内核因配置 reload/重建重启后，旧的推流端 FFmpeg 连接被断开，部分推流端不会自动重连，服务端流水线进入 failed 并循环重试（实测 /api/v3/process/live/state 回显 exec: failed，last_logline 显示 FFmpeg 打开输入流失败的 I/O error 类报错）。解法：在推流端重启推流命令（本文实测重推后流水线即刻恢复 exec: running）。推流端侧建议加 --retry 类参数或用系统守护托管推流命令。

Q3：config.json 改了却不生效？

两种原因：改的是环境变量已覆盖的键（CORE_* 覆盖优先，改文件无效，需改 compose 后重建）；或改完没执行热加载。先 curl http://127.0.0.1:8156/api/v3/config/reload（回显 "OK"），仍无效再查 CORE_* 覆盖清单。

Q4：拉流地址 404？

分片地址是 /memfs/<流水线输出名>.m3u8（本文实测 /memfs/live.m3u8）。404 常见于：推流还没建立成功（先看 docker compose logs 里有无 PUBLISH 会话）；或输出的 m3u8 文件名与请求名不一致（看流水线配置的 {memfs} 输出文件名）。

十一、参考链接

• 官方镜像页：https://hub.docker.com/r/datarhei/restreamer
• 官方安装文档（最低要求与 Docker 部署）：https://docs.datarhei.com/restreamer/getting-started/quick-start
• 2.12.0 发布说明（发行变体清单，查询日期 2026-10-30）：https://github.com/datarhei/restreamer/releases/tag/v2.12.0
• 本平台系列：[《Restreamer 介绍与选型指南》](https://www.quzuo.net/document/T9V4T9qaPrlq)、[《Restreamer 2.12.0 配置参数详解》](https://www.quzuo.net/document/u6Yi2xGp3c4T)、[《Restreamer 2.12.0 API 使用详解》](https://www.quzuo.net/document/DAWPhSW0QKsb)