Owncast 0.3.0 配置参数详解

‍‍​​‌​> 目标：把 Owncast v0.3.0 的全部可配置项一次讲透——参数怎么查看（无配置文件，全在数据库）、怎么修改（Admin API 实测）、每类参数的默认值与影响，并给出一套 2C4G 小型服务器可直接落地的生产配置模板。全部命令与回显已在 Ubuntu 22.04（x86_64）+ Owncast 0.3.0 实测通过（实测日期 2026-10-29）。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64）
• Owncast 版本：0.3.0（/api/status 返回 versionNumber: "0.3.0" 实测）
• 服务端口：Web 8150（默认 8080）、RTMP 8153（默认 1935，本服务器因端口冲突调整，修改过程见第六章实测）
• 管理凭据：admin / q1w2e3r4（出厂默认为 admin / abc123，本文已实测改密）
• 配置存储：SQLite 数据库 data/owncast.db（0.3.0 无 owncast.yml 配置文件）
• 部署方式：官方发行形态部署（Docker 或单二进制均可，本文命令与部署形态无关），部署过程见《Owncast 0.3.0 Docker Compose 部署指南》

二、前置条件

1. Owncast 0.3.0 已部署并启动（curl -s http://127.0.0.1:8150/api/status 返回 JSON）；
2. 已掌握管理凭据（用户名固定 admin，密码为管理密码；本文全部示例使用 admin:q1w2e3r4）；
3. 本机可访问 Web 端口（示例统一用 http://127.0.0.1:8150，远程服务器替换为 http://<服务器IP>:<Web端口>）。

三、参数查看与修改方式

这是理解 Owncast 配置的第一件事：0.3.0 没有配置文件，配置只有三种入口，全部落到同一个 SQLite 数据库（data/owncast.db），重启不丢。

查看当前全量配置（一条命令拿回所有生效值，实测）：

curl -s -u admin:q1w2e3r4 http://127.0.0.1:8150/api/admin/serverconfig | python3 -m json.tool | head -20

{
    "instanceDetails": {
        "appearanceVariables": {},
        "version": "",
        "welcomeMessage": "",
        "offlineMessage": "",
        "logo": "logo.png",
        "name": "New Owncast Server",
        "extraPageContent": "\n# Welcome to Owncast!\n\n- This is a live stream powered by [Owncast](https://owncast.online), a free and open source live streaming server.\n\n- To discover more examples of streams, visit [Owncast's directory](https://owncast.directory).\n\n- If you're the owner of this server you should visit the admin and customize the content on this page.\n\n<hr/>\n\n<video id=\"video\" controls preload=\"metadata\" style=\"width: 60vw; max-width: 600px; min-width: 200px;\" poster=\"https://videos.owncast.online/t/xaJ3xNn9Y6pWTdB25m9ai3\">\n  <source src=\"https://assets.owncast.tv/video/owncast-embed.mp4\" type=\"video/mp4\" />\n</video>\n\t",

（输出节选，实测首段；完整 JSON 约 106 行，后续各章按类拆解。）

修改单个参数：统一格式 POST /api/admin/config/<key>，请求体 {"value": <新值>}，类型随参数而定（字符串/数字/布尔/数组/对象）。实测改实例名：

curl -s -X POST -u admin:q1w2e3r4 -H 'Content-Type: application/json' \
  -d '{"value":"quzuo 直播实验台"}' http://127.0.0.1:8150/api/admin/config/name

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

改完立即读公开接口验证（无需管理凭据，实测回显）：

curl -s http://127.0.0.1:8150/api/config | python3 -c "import json,sys;print(json.load(sys.stdin)['name'])"

quzuo 直播实验台

💡 说明：绝大多数配置修改即时生效、无需重启；少数与监听行为相关的参数（webserverport/rtmpserverport 等）修改成功后需重启服务才重新绑定端口（实测见第六章）。

四、参数总览

按 /api/admin/serverconfig 实测返回结构，0.3.0 的可配置项分 9 类：

五、核心参数分类详解

5.1 实例信息（instanceDetails.*）

控制观众页面「是谁在播」。实测关键字段与默认值：

实测改名称并回读验证（改回原值）：

curl -s -X POST -u admin:q1w2e3r4 -H 'Content-Type: application/json' \
  -d '{"value":"quzuo 直播实验台"}' http://127.0.0.1:8150/api/admin/config/name
curl -s -X POST -u admin:q1w2e3r4 -H 'Content-Type: application/json' \
  -d '{"value":"New Owncast Server"}' http://127.0.0.1:8150/api/admin/config/name

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

5.2 推流密钥（streamKeys）

0.3.0 支持多推流码（数组结构，每项含 key 与 comment），适合「主码自用 + 临时码给嘉宾」。默认只有一条 {"comment":"Default stream key","key":"abc123"}（实测 serverconfig 返回）。整体替换写入（实测）：

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}

推流地址格式固定为 rtmp://<服务器>:<RTMP端口>/live/<推流码>（源码 services/rtmp 与实测一致）。换码后旧码立即失效：实测用旧码 abc123 重推报 Input/output error，服务端日志 invalid streaming key; rejecting incoming stream from ...（完整排障过程见《Owncast 0.3.0 Docker Compose 部署指南》第十章）。

streamKeyOverridden：当启动参数 -streamkey 覆盖过推流码时为 true，方便判断当前码来自数据库还是命令行。

💡 技术拓展：直播推流的「鉴权载体」不止推流码一种——

方案	原理	适用场景
静态推流码	服务端预存密钥串，URL 携带	最通用，Owncast/多数平台采用
时间戳签名	码中带过期时间与签名	防泄露，大型平台常用
IP 白名单	仅允许指定来源 IP 推流	固定推流机内网场景
登录态推流	推流前先调 API 换一次性码	嘉宾频繁变动的活动场景

Owncast 采用静态推流码（多码可轮换），安全性依赖「码的私密性 + 端口防火墙」，生产上建议定期换码并对 RTMP 端口限源。

5.3 网络端口（webServerPort / rtmpServerPort / rtmpServerAddress）

本服务器实测：1935 被占用，通过 Admin API 把应用内端口改为 8153、Web 改为 8150（实时生效的返回如下），重启后端口重新绑定并持久化：

curl -s -X POST -u admin:q1w2e3r4 -H 'Content-Type: application/json' \
  -d '{"value":8150}' http://127.0.0.1:8150/api/admin/config/webserverport
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":"HTTP port set","success":true}
{"message":"rtmp port set","success":true}

重启后服务端日志（实测）：

time="2026-10-29T14:29:03Z" level=info msg="RTMP is accepting inbound streams on port 8153."
time="2026-10-29T14:29:03Z" level=info msg="Web server is listening on port 8150."

再次读配置确认持久化（实测）：

curl -s -u admin:q1w2e3r4 http://127.0.0.1:8150/api/admin/serverconfig \
  | python3 -c "import json,sys;d=json.load(sys.stdin);print(d['webServerPort'],d['rtmpServerPort'])"

8150 8153

⚠️ 注意：改端口会改变连接入口，若以 Docker 部署则宿主侧端口映射要同步调整（见《Owncast 0.3.0 Docker Compose 部署指南》第十章常见问题 1），否则改完端口 Web 反而不通——这是端口类参数唯一的「坑」，其余参数均即时生效。

5.4 转码与视频（videoSettings / videoCodec / ffmpegPath）

这是影响画质、延迟与 CPU 的核心类。

延迟档位 latencyLevel（实测 videoSettings.latencyLevel 默认 2）。0–4 档与分片参数的对应关系（源码 models/latencyLevels.go 注释即官方口径，实测默认档 m3u8 为 3 秒分片 × 10 片）：

实测切换档位（改到 1 再改回 2，均即时返回成功）：

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

{"message":"set stream latency","success":true}
{"message":"set stream latency","success":true}

输出档位 videoQualityVariants[]：默认单档 1.2Mbps@24fps（videoBitrate: 1200、framerate: 24、audioPassthrough: true、cpuUsageLevel: 2，实测 serverconfig 返回）。可配多档实现自适应，观众端按带宽选择（/api/video/variants 实测返回 [{"name":"1.2Mbps@24fps","index":0}]）。

CPU 档位 cpuUsageLevel（0–4）映射 FFmpeg x264 编码 preset（源码 services/transcoder/codecs.go 的 GetPresetForLevel，0 最快画质最低）：

编码器 videoCodec：默认 libx264（软件编码）；supportedCodecs 实测为 libx264、h264_qsv、h264_v4l2m2m、h264_vaapi——硬件加速取决于宿主 FFmpeg 编译与硬件（Intel QSV/AMD VAAPI/嵌入式 V4L2M2M）。

转码器路径 ffmpegPath：默认 /usr/bin/ffmpeg（实测 serverconfig 返回值），自编译 FFmpeg 时指向新路径即可。

5.5 聊天互动（chat.*）

实测开关一轮（关闭→确认→恢复开启，均即时生效）：

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

{"message":"chat disabled status updated","success":true}

curl -s -u admin:q1w2e3r4 http://127.0.0.1:8150/api/admin/serverconfig \
  | python3 -c "import json,sys;print(json.load(sys.stdin)['chatDisabled'])"

True

恢复：同端点 {"value":false}，回读 False（实测）。

5.6 联邦社交（federation.*）

ActivityPub 联邦是 Owncast 的差异化能力：开启后实例成为 Fediverse 上的一个「直播账号」，Mastodon 等平台用户可直接关注、收到开播动态，0.3.0 更新增 Featured Streams 实例互推。

⚠️ 注意：联邦开启前先把「对外可访问的域名」配好（反向代理 + HTTPS），ActivityPub 要求实例有公网可达的稳定 URL。

5.7 对象存储（s3.*）

默认关闭（实测 {"enabled":false,"forcePathStyle":false}）。开启后 HLS 分片与视频转存到 S3 兼容对象存储，源站只做转码上送，观众流量走对象存储/CDN——小水管大观看量的标配。可用字段：endpoint、servingEndpoint（对外 CDN 域名）、accessKey、secret、bucket、region、acl、forcePathStyle（MinIO 等自建 S3 需置 true）。实测写入关闭态配置：

curl -s -X POST -u admin:q1w2e3r4 -H 'Content-Type: application/json' \
  -d '{"value":{"enabled":false,"endpoint":"","accessKey":"","secret":"","bucket":"","region":"","forcePathStyle":false}}' \
  http://127.0.0.1:8150/api/admin/config/s3

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

5.8 目录与通知（yp.* / notifications.*）

• yp（Yellowscale Public 目录，实测默认 {"instanceUrl":"","enabled":false}）：开启后实例登记到官方公开目录 owncast.directory，带来陌生观众；instanceUrl 填对外完整域名。
• notifications：开播通知渠道。browser（浏览器推送，实测默认 enabled: true，goLiveMessage: "I've gone live!"）与 discord（Webhook，默认关闭）。观众在页面上订阅后，开播时收到提醒。

5.9 安全与杂项

六、生产配置模板

适用场景：2 核 4GB 内存、50GB SSD 云主机，个人/小团队直播，单输出档位，观众 ≤ 200 并发，未启用对象存储。逐条给出落库命令（改完即生效，端口两项需重启）：

# 1. 实例身份（name/summary 按需替换）
curl -s -X POST -u admin:q1w2e3r4 -H 'Content-Type: application/json' \
  -d '{"value":"My Live"}' http://127.0.0.1:8150/api/admin/config/name
curl -s -X POST -u admin:q1w2e3r4 -H 'Content-Type: application/json' \
  -d '{"value":"每周三晚 8 点，聊开源与自托管"}' http://127.0.0.1:8150/api/admin/config/serversummary

# 2. 推流码与管理密码（强度口令）
curl -s -X POST -u admin:q1w2e3r4 -H 'Content-Type: application/json' \
  -d '{"value":[{"comment":"primary","key":"q1w2e3r4"}]}' http://127.0.0.1:8150/api/admin/config/streamkeys

# 3. 延迟与画质（默认档已适配 2C4G：单档 1200kbps + cpuUsageLevel 2，无需再降）
curl -s -X POST -u admin:q1w2e3r4 -H 'Content-Type: application/json' \
  -d '{"value":2}' http://127.0.0.1:8150/api/admin/config/video/streamlatencylevel

# 4. 聊天防刷（默认即开限流；小台子建议再开 established user mode）
curl -s -X POST -u admin:q1w2e3r4 -H 'Content-Type: application/json' \
  -d '{"value":true}' http://127.0.0.1:8150/api/admin/config/chat/spamprotectionenabled
curl -s -X POST -u admin:q1w2e3r4 -H 'Content-Type: application/json' \
  -d '{"value":true}' http://127.0.0.1:8150/api/admin/config/chat/establishedusermode

# 5. 隐私：默认不收录目录、不允许自动播放（yp.enabled=false 为出厂默认，无需改动）

模板要点解读：

• 2C4G 的安全余量：libx264 在 cpuUsageLevel 2（veryfast）下转码单档 1200kbps@24fps 约占用 1 核出头，剩余算力留给系统与聊天；
• 延迟选择：默认 2 档（≈10 秒）是「延迟-抗抖动」平衡点；互动问答场景降到 1 档（≈8 秒）足够，0 档（≈5 秒）对网络抖动敏感，弱网观众多时不建议；
• 多档位取舍：观众端带宽差异大时加一档 400kbps@480p（streamoutputvariants 端点整体替换数组），但每加一档转码 CPU 几乎翻倍，2C 机器不建议超过两档；
• 磁盘：HLS 分片是环形缓存（10 片 × 3 秒 × 1.2Mbps ≈ 每观众会话兆级），磁盘压力主要来自 data/logs，长期运行定期清理或外移。

七、常见问题

Q1：改了配置为什么不生效？

先分清两类：即时生效类（页面/聊天/推流码/延迟档位等，改完 /api/admin/serverconfig 立即可见）与重启生效类（webserverport/rtmpserverport 等监听参数，需重启服务重新绑定，见 5.3 实测）。另外改端口后检查客户端连接的是不是新端口。

Q2：没有配置文件，怎么把一台服务器的配置复制到另一台？

源机 GET /api/admin/serverconfig 导出完整 JSON，按目标机逐项 POST /api/admin/config/<key> 回灌（adminPassword 哈希不可直接回灌，需在目标机单独设密码）；或直接拷贝 data/owncast.db（停服冷拷贝）到新机数据目录，两机的配置即完全一致。

Q3：管理密码忘了怎么办？

用启动参数救援：以 -adminpassword 新密码 启动一次（Docker 部署可在 compose 的 command: 字段追加该参数，见《Owncast 0.3.0 Docker Compose 部署指南》第六章环境变量表），进入后台后再按常规改密并移除临时参数。

Q4：/api/config 与 /api/admin/serverconfig 有什么区别？

/api/config 是公开接口（无认证，只暴露页面展示所需的非敏感字段，实测不含推流码与密码哈希）；/api/admin/serverconfig 是管理接口（Basic 认证，返回全部配置含 bcrypt 密码哈希）。写自动化脚本时注意不要把后者输出透到公开渠道。

Q5：如何确认我的配置改动已持久化？

重启服务后再查一次：curl -s -u admin:q1w2e3r4 http://127.0.0.1:8150/api/admin/serverconfig 与改动期望一致即落库（本文 5.3/5.5 均以此法验证）。SQLite 的 -wal 文件存在属正常，它也是持久化的一部分。

八、参考链接

• Owncast 官方文档：配置（查询日期 2026-10-29）
• Owncast 官方文档：视频质量（查询日期 2026-10-29）
• Owncast 官方文档：外部存储（查询日期 2026-10-29）
• v0.3.0 Release Notes（查询日期 2026-10-29）
• 源码参数口径：models/latencyLevels.go（延迟档位）、services/transcoder/codecs.go（CPU 档位映射）、config/defaults.go（默认值），v0.3.0 源码包实测核对
• 本专栏姊妹篇：《Owncast 0.3.0 介绍与选型指南》、《Owncast 0.3.0 Docker Compose 部署指南》、《Owncast 0.3.0 API 使用详解》