Owncast 0.3.0 Docker Compose 部署指南

‍‍‌> 目标：用 Docker Compose 从零部署一套 Owncast v0.3.0 直播服务器，覆盖镜像选型、端口规划（Web 与 RTMP 双端口）、推流码与管理密码初始化、数据持久化、ffmpeg 推流冒烟验证与运维命令——全部步骤在 Ubuntu 22.04 x86_64 + Docker 29 环境实测通过（推流、HLS 播放、聊天与管理 API 均验证可用）。

一、环境信息

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

操作系统：Ubuntu 22.04（x86_64）
Docker：29.x（含 compose 插件，docker compose version 输出 Docker Compose version v5.6.1）
Owncast 镜像：owncast/owncast:0.3.0（官方镜像，digest sha256:0f35b568b1098d2badbde2dbf3c73a902009c95eb687c647edea04d6da079a78）
推流工具：FFmpeg 6.1.1
部署形态：单容器部署，容器内 /app/owncast 以 ENTRYPOINT 直跑官方二进制，数据目录 /app/data
本次实测宿主端口规划：Web 8150（容器默认 8080）、RTMP 8153（容器默认 1935）——本服务器 1935 已被其他直播服务占用，8128–8146/8149 已被占用，故宿主侧取 8150/8153；读者服务器上若 8080/1935 空闲，把宿主侧端口换回 8080:8080、1935:1935 即可，容器内端口不必动

Owncast 本身介绍与选型对比见《Owncast 0.3.0 介绍与选型指南》。

二、镜像选型说明

Owncast 官方在 Docker Hub 维护 owncast/owncast 镜像，tag 规则为 latest 与具体版本号（如 0.3.0）。选型要点：

事项	结论	依据
镜像仓库	`owncast/owncast`	官方 Release Notes 指定（v0.3.0 发布说明"available via Docker Hub at owncast/owncast"）
tag 策略	生产固定版本号（`0.3.0`），不要用 `latest`	版本升级可能变更默认行为，固定 tag 保证可复现
镜像基础	Alpine 3.24，自带 FFmpeg 与 CA 证书	官方 Dockerfile：`apk add ffmpeg ffmpeg-libs ca-certificates`
运行用户	非 root，专用用户 `owncast`（uid/gid 101）	Dockerfile `USER owncast`，挂载宿主目录时注意属主
内置依赖	FFmpeg 内置于镜像，无需额外安装转码器	镜像即开即用，`ffmpegPath` 默认 `/usr/bin/ffmpeg`
端口	8080（Web）+ 1935（RTMP）	Dockerfile `EXPOSE 8080 1935`

拉取镜像（实测回显）：

docker pull owncast/owncast:0.3.0

0.3.0: Pulling from owncast/owncast
Digest: sha256:0f35b568b1098d2badbde2dbf3c73a902009c95eb687c647edea04d6da079a78
Status: Downloaded newer image for owncast/owncast:0.3.0
docker.io/owncast/owncast:0.3.0

⚠️ 网络说明：实测宿主 Docker 守护进程可直连 Docker Hub 完成拉取；若你的网络拉取超时，为守护进程配置镜像加速器或代理后重试。

三、前置条件

服务器已安装 Docker 24+ 与 compose v2 插件（docker compose version 有输出）；
端口规划完成：Web 与 RTMP 两个端口在宿主侧未被占用（ss -ltn 核对；Owncast 仅需 TCP，无 UDP 端口）；
建立工作目录（本文以 /opt/owncast 为例，与后续挂载路径一致）；
创建容器专用网络（固定网段便于与推流端同网互通，按内网空闲槽位显式指定子网）：

mkdir -p /opt/owncast && cd /opt/owncast
ss -ltn | grep -E ':(8150|8153)\b'          # 核对端口占用
docker network create -d bridge --subnet 10.89.61.0/24 owncast-net

实测回显（端口空闲时 grep 无输出即代表可占用；网络创建返回完整 ID）：

（端口核对无输出 = 端口空闲可用）
d32721245c10f8fa662eaa2beefa2b7b0fbe69f03e359c4b2ce4c2bfbff68d0f

四、部署步骤

4.1 编写 docker-compose.yml

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

name: owncast-0.3.0-stack
services:
  app:
    image: owncast/owncast:0.3.0
    container_name: owncast-0.3.0-app
    restart: unless-stopped
    ports:
      - "8150:8080"   # Web：播放页/聊天/后台/API（容器默认 8080）
      - "8153:1935"   # RTMP 推流入口（容器默认 1935，宿主 1935 被占改用 8153）
    volumes:
      - ./data:/app/data   # 数据库/HLS/日志/表情全部在此目录
    networks:
      - owncast-net

networks:
  owncast-net:
    name: owncast-net
    external: true

配置项说明：

container_name 固定为 owncast-0.3.0-app，便于日志与排障定位；
restart: unless-stopped 让服务随宿主开机自启（手动 stop 后不自动拉起）；
./data:/app/data 是唯一的持久化挂载：Owncast 无配置文件，全部配置存于该目录下的 SQLite 数据库（见第五章）；
网络使用第三章创建的 owncast-net（external）。

4.2 启动并确认

cd /opt/owncast && docker compose up -d
docker compose ps
docker logs owncast-0.3.0-app

实测回显：

 Container owncast-0.3.0-app Creating
 Container owncast-0.3.0-app Created
 Container owncast-0.3.0-app Starting
 Container owncast-0.3.0-app Started
NAME                IMAGE                   COMMAND          SERVICE   CREATED         STATUS         PORTS
owncast-0.3.0-app   owncast/owncast:0.3.0   "/app/owncast"   app       7 seconds ago   Up 6 seconds   0.0.0.0:8153->1935/tcp, [::]:8153->1935/tcp, 0.0.0.0:8150->8080/tcp, [::]:8150->8080/tcp
time="2026-10-29T14:20:40Z" level=info msg="Owncast v0.3.0-linux-64bit (4b09a1b11693977400fb6f6cb06a7b9891bdca6d)"
time="2026-10-29T14:20:40Z" level=info msg="plugins: 0 discovered"
time="2026-10-29T14:20:40Z" level=info msg="Web server is listening on port 8080."
time="2026-10-29T14:20:40Z" level=info msg="Configure this server by visiting /admin."

日志出现 Web server is listening on port 8080. 与 Configure this server by visiting /admin. 即启动完成。首次启动会自动在 ./data 下初始化数据库与默认资源。确认 Web 可达：

curl -s http://127.0.0.1:8150/api/status

实测回显：

{"serverTime":"2026-10-29T14:20:53.958057793Z","lastConnectTime":null,"lastDisconnectTime":null,"versionNumber":"0.3.0","streamTitle":"","online":false}

versionNumber: "0.3.0" 且 online: false（尚未推流）即为健康状态。

4.3 推流冒烟验证（默认推流码）

Owncast 出厂默认推流码为 abc123、后台管理密码同为 abc123（用户名 admin）。先用默认推流码验证推流入口可用——在服务器（或任一能连通 8153 端口的机器）上用 FFmpeg 推测试流：

ffmpeg -re -stream_loop -1 \
  -f lavfi -i testsrc=size=1280x720:rate=30 \
  -f lavfi -i 'sine=frequency=1000' \
  -c:v libx264 -preset veryfast -tune zerolatency -pix_fmt yuv420p \
  -c:a aac -b:a 128k -ar 44100 \
  -f flv rtmp://127.0.0.1:8153/live/abc123

推流成功后服务端日志（实测）：

time="2026-10-29T14:21:36Z" level=info msg="Inbound stream connected from 10.89.61.1:35774"
time="2026-10-29T14:21:36Z" level=info msg="Processing video using codec x264 with 1 output qualities configured."

此时再查状态与 HLS 播放列表（输出节选，实测首尾）：

curl -s http://127.0.0.1:8150/api/status
curl -s http://127.0.0.1:8150/hls/0/stream.m3u8 | head -5

{"serverTime":"2026-10-29T14:21:56.630574293Z","lastConnectTime":"2026-10-29T14:21:36Z","lastDisconnectTime":null,"versionNumber":"0.3.0","streamTitle":"","online":true}

#EXTM3U
#EXT-X-VERSION:6
#EXT-X-TARGETDURATION:3
#EXT-X-INDEPENDENT-SEGMENTS
#EXTINF:3.000000,

online: true 且 m3u8 正常输出 3 秒分片，说明「RTMP 收流 → 转码 → HLS 分发」链路全通。浏览器打开 http://<服务器IP>:8150 即是观众页面，http://<服务器IP>:8150/admin 是管理后台（账号 admin，密码即当前推流码）。

4.4 首次安全配置：改管理密码与推流码

默认凭据必须立即更换。两种方式等价：后台页面 /admin 修改，或直接调 Admin API（本文实测后者）。把管理密码改为 q1w2e3r4、推流码改为 q1w2e3r4：

curl -s -X POST -u admin:abc123 -H 'Content-Type: application/json' \
  -d '{"value":"q1w2e3r4"}' http://127.0.0.1:8150/api/admin/config/adminpass
curl -s -X POST -u admin:q1w2e3r4 -H 'Content-Type: application/json' \
  -d '{"value":[{"comment":"demo","key":"q1w2e3r4"}]}' http://127.0.0.1:8150/api/admin/config/streamkeys

实测回显：

{"message":"changed","success":true}
{"message":"changed","success":true}

验证新旧凭据（旧密码应 401、新密码应 200，实测）：

curl -s -o /dev/null -w "%{http_code}\n" -u admin:abc123   http://127.0.0.1:8150/api/admin/status
curl -s -o /dev/null -w "%{http_code}\n" -u admin:q1w2e3r4 http://127.0.0.1:8150/api/admin/status

401
200

⚠️ 注意：推流码更换后旧推流码立即失效，正在推的流会被保留到断开为止，但重连必须用新码。用旧码重推会收到如下失败（实测，见第十章常见问题 2）：
[out#0/flv @ 0x5ab790b6ae40] Error opening output rtmp://127.0.0.1:8153/live/abc123: Input/output error
Error opening output file rtmp://127.0.0.1:8153/live/abc123.
Error opening output files: Input/output error
服务端对应日志：level=error msg="invalid streaming key; rejecting incoming stream from 10.89.61.1:51028"。

用新码重推验证（实测后 online: true，lastConnectTime 刷新）：

ffmpeg -re -stream_loop -1 \
  -f lavfi -i testsrc=size=1280x720:rate=30 \
  -f lavfi -i 'sine=frequency=1000' \
  -c:v libx264 -preset veryfast -tune zerolatency -pix_fmt yuv420p \
  -c:a aac -b:a 128k -ar 44100 \
  -f flv rtmp://127.0.0.1:8153/live/q1w2e3r4

五、数据持久化说明

Owncast 的全部状态都落在 /app/data 一个目录里，宿主机 ./data 绑定挂载后，删除/重建容器不丢数据。首次启动后实测目录内容：

ls -la /opt/owncast/data/

drwxr-xr-x 9 root root   4096 Oct 29 22:20 .
drwxr-xr-x 3 root root   4096 Oct 29 22:20 ..
drwxr-x--- 8 root root   4096 Oct 29 22:20 emoji
drwxr-x--- 3 root root   4096 Oct 29 22:20 hls
-rw------- 1 root root 124167 Oct 29 22:20 logo.png
drwx------ 2 root root   4096 Oct 29 22:20 logs
drwxr-xr-x 3 root root   4096 Oct 29 22:20 metrics
-rw-r--r-- 1 root root   4096 Oct 29 22:20 owncast.db
-rw-r--r-- 1 root root  32768 Oct 29 22:20 owncast.db-shm
-rw-r--r-- 1 root root 543872 Oct 29 22:20 owncast.db-wal
drwx------ 2 root root   4096 Oct 29 22:20 plugins
drwx------ 2 root root   4096 Oct 29 22:20 plugin-storage
drwx------ 2 root root   4096 Oct 29 22:20 tmp

各条目含义：

owncast.db（含 -shm/-wal）：SQLite 数据库，配置、用户、聊天记录、Webhook 全在这里——备份它等于备份整台服务器的业务状态；
hls/：转码输出的 HLS 分片缓存，重启后重建，无需备份；
logs/：运行日志；emoji/：自定义表情；metrics/：统计指标；
plugins/、plugin-storage/：0.3.0 插件宿主目录；
logo.png：首次初始化生成的默认 logo。

升级方法：改 compose 中镜像 tag 为新版本号，docker compose pull && docker compose up -d，数据目录原样保留即可完成升级。备份方法：停写后整目录打包，或用二进制自带的备份参数（见第六章 -backupdir）。

⚠️ 注意：容器内以 uid 101（owncast 用户）运行，若宿主目录由 root 创建，Docker 会以 root 属主挂载，Owncast 可正常读写（实测通过）；但把目录迁移到别的机器时注意保持属主可写。

六、环境变量表

与多数镜像不同，owncast/owncast 不通过环境变量配置。运行期配置全部经后台页面/Admin API 持久化到数据库（详见《Owncast 0.3.0 配置参数详解》）；仅启动瞬间可通过命令行参数做一次性覆盖。二进制支持的完整参数（owncast --help 实测）：

参数	作用	实测说明
`-streamkey string`	设置临时推流码	仅本次启动生效，注释为 "Set a temporary stream key for this session"
`-adminpassword string`	设置管理密码	忘记后台密码时的救援入口
`-webserverport string`	强制 Web 监听端口	覆盖数据库中的 `webServerPort`
`-webserverip string`	强制 Web 监听 IP	默认 `0.0.0.0`
`-rtmpport int`	强制 RTMP 监听端口	覆盖数据库中的 `rtmpServerPort`
`-database string`	指定数据库文件路径	默认 `data/owncast.db`
`-logdir string`	指定日志目录	默认 `data/logs`
`-backupdir string`	指定备份输出目录	配合备份功能使用
`-restoreDatabase string`	从备份恢复数据库	恢复场景使用
`-followervalidationinterval int`	关注者校验间隔（秒）	联邦关注校验频率
`-enableVerboseLogging`	开启详细日志	排障时使用
`-enableDebugFeatures`	开启调试特性	开发排障使用

在 compose 中可通过 command: 追加参数（ENTRYPOINT 为 /app/owncast，command 的内容会作为其参数），例如临时改推流码启动：command: ["-streamkey", "q1w2e3r4"]。

七、配置参数说明与配置文件挂载

Owncast 没有 owncast.yml 之类的配置文件——这一点与常见中间件不同：

首次启动时程序把默认配置写入 SQLite 数据库 data/owncast.db；
之后所有配置变更（页面外观、推流码、转码档位、聊天开关、联邦、S3 存储等）都在后台页面或 Admin API 完成，写入数据库；
重启后配置从数据库加载（实测：改端口/推流码/标题后 docker compose down && up -d，配置全部保留）。

因此本文唯一挂载就是第五章的数据目录，不存在配置文件挂载项。若需要把配置纳入版本管理，用 Admin API 的 GET /api/admin/serverconfig 导出完整配置 JSON 做快照、用 POST /api/admin/config/<key> 批量回灌——各参数含义、默认值与实测修改方法见《Owncast 0.3.0 配置参数详解》。

八、等价 docker run

不用 compose 时，以下单条 docker run 与第四章配置等价（实测参数来源一致）：

docker run -d \
  --name owncast-0.3.0-app \
  --restart unless-stopped \
  -p 8150:8080 \
  -p 8153:1935 \
  -v /opt/owncast/data:/app/data \
  --network owncast-net \
  owncast/owncast:0.3.0

需要临时参数时直接追加，例如指定临时推流码：

docker run -d --name owncast-0.3.0-app -p 8150:8080 -p 8153:1935 \
  -v /opt/owncast/data:/app/data \
  owncast/owncast:0.3.0 -streamkey q1w2e3r4

九、常用运维命令

cd /opt/owncast
docker compose ps                     # 查看运行状态
docker logs -f owncast-0.3.0-app      # 跟踪日志（推流接入/断开/错误都在这）
docker compose restart                # 重启服务（配置保留在数据库）
docker compose down                   # 停止并删除容器（数据目录保留）
docker compose pull && docker compose up -d   # 升级到 compose 中指定的新版本
tar czf owncast-data-$(date +%F).tar.gz data/ # 冷备：停写期间整目录打包

查看推流者实时信息（编码器/分辨率/帧率，实测）：

curl -s -u admin:q1w2e3r4 http://127.0.0.1:8150/api/admin/status

{
    "broadcaster": {
        "time": "2026-10-29T14:21:36.624986595Z",
        "remoteAddr": "10.89.61.3:32944",
        "streamDetails": {
            "videoCodec": "H.264",
            "audioCodec": "AAC",
            "encoder": "Lavf63.1.102",
            "width": 1280,
            "height": 720,
            "videoBitrate": 0,
            "audioBitrate": 125,
            "framerate": 30
        }
    },

（输出节选，实测首段；currentBroadcast 字段包含当前生效的转码档位。）

十、常见问题

Q1：宿主机 1935 被其他服务占用，RTMP 起不来？

两种处理：① 推荐——只改宿主侧映射（如本文 "8153:1935"），容器内保持默认；② 若希望应用层也换端口，调 Admin API 后重启容器（实测有效）：

curl -s -X POST -u admin:q1w2e3r4 -H 'Content-Type: application/json' \
  -d '{"value":8153}' http://127.0.0.1:8150/api/admin/config/rtmpserverport

{"message":"rtmp port set","success":true}

重启后日志变为 RTMP is accepting inbound streams on port 8153.，此时 compose 映射需同步改为 "8153:8153"（推流地址相应变成 rtmp://<host>:8153/live/<key>）。

Q2：推流报 Error opening output ... Input/output error？

按以下顺序排查（均为实测结论）：推流码错误（服务端日志出现 invalid streaming key; rejecting incoming stream from ...，去后台/Admin API 核对推流码）；推流地址路径错误（必须是 /live/<推流码> 形式）；端口不通（ss -ltn | grep 8153 确认监听、防火墙放行）。

Q3：后台管理页面打不开或 401？

/admin 页面与 Admin API 共用同一套凭据：用户名固定 admin，密码为管理密码（出厂等于默认推流码 abc123，本文已改为 q1w2e3r4）。忘记密码时用第六章 -adminpassword 参数重启一次容器即可重置。

Q4：直播有画面没声音/声音异常？

检查推流端是否包含音频轨（本文示例的 sine 音源即为此准备）；Owncast 默认输出档位对音频做直通（audioPassthrough: true），推流侧音频编码需为 AAC。转码档位与 CPU 占用档位说明见《Owncast 0.3.0 配置参数详解》第五章。

Q5：观众页面 HLS 加载慢或卡顿？

降低转码档位码率（/api/admin/config/video/streamoutputvariants）或降低 CPU 档位（cpuUsageLevel，0 最快画质最低）；弱网场景把延迟级别调高（streamlatencylevel，0–4，数值越大越抗抖动，默认 2 ≈ 10 秒延迟）。

十一、参考链接

Owncast 官方文档 Quickstart（查询日期 2026-10-29）
官方镜像 owncast/owncast（查询日期 2026-10-29）
Release Notes v0.3.0（查询日期 2026-10-29）
GitHub 仓库 owncast/owncast（含官方 Dockerfile）（查询日期 2026-10-29）
本专栏姊妹篇：《Owncast 0.3.0 介绍与选型指南》、《Owncast 0.3.0 配置参数详解》、《Owncast 0.3.0 API 使用详解》