Janus 1.4.3 配置参数详解
逐段详解 Janus 1.4.3 配置体系:janus.jcfg 四大段、HTTP/WebSockets transport、核心插件与事件处理器参数,附 debug_level/api_secret/证书/json 格式四项重启生效验证实录。
Janus 1.4.3 配置参数详解
目标:逐段讲清 Janus 1.4.3(全称 janus-gateway)的配置体系:主配置
janus.jcfg的 general/certificates/media/nat 四段、HTTP 与 WebSockets 两个 transport 配置、核心插件配置与事件处理器配置,并对关键参数给出重启前后的生效验证实录(日志/接口双证据)。安装与启动见《Debian 12 安装 Janus 1.4.3 指南》,容器化部署见《Janus 1.4.3 Docker Compose 部署指南》。
一、配置体系与文件布局
Janus 1.x 的配置文件全部是 .jcfg 格式(libconfig 语法:段名: { 参数 = 值 },值可以是字符串/整数/布尔,# 为行注释)。make configs 在 /opt/janus/etc/janus/ 下生成 17 个生效的 .jcfg + 同名 .sample 备份:
| 类别 | 文件 | 职责 |
|---|---|---|
| 主配置 | janus.jcfg | 目录、日志、鉴权、DTLS 证书、媒体、NAT/ICE |
| 接入层 | janus.transport.http.jcfg | REST (HTTP/HTTPS) transport 与 Admin API |
| 接入层 | janus.transport.websockets.jcfg | WebSockets (WS/WSS) transport |
| 接入层 | janus.transport.pfunix.jcfg | Unix Socket transport(默认关闭) |
| 插件 | janus.plugin.{echotest,streaming,videoroom,audiobridge,videocall,sip,nosip,textroom,recordplay,lua}.jcfg | 各业务插件的默认值 |
| 事件 | janus.eventhandler.{sampleevh,wsevh,gelfevh}.jcfg | 事件处理器(默认关闭) |
| 日志 | janus.eventhandler.gelfevh.jcfg 等同目录 | — |
三条硬规则:
- 修改后必须重启进程才生效(
systemctl restart janus或 compose restart)——Janus 启动时一次性读取全部配置,没有运行时热加载;个别运行时可调项走 Admin API 动态改,不在配置文件层面。 - 改前先备份:
.sample是 make configs 时的出厂备份,永远不要直接编辑.sample后指望生效——Janus 只读.jcfg。 - 语法自检:改完先用自带的
janus-cfgconv离线解析一遍,能在启动前抓出 libconfig 语法错:
/opt/janus/bin/janus-cfgconv /opt/janus/etc/janus/janus.jcfg
二、janus.jcfg:主配置四大段
2.1 general 段:目录、日志与鉴权
general: {
configs_folder = "/opt/janus/etc/janus" # Configuration files folder
plugins_folder = "/opt/janus/lib/janus/plugins" # Plugins folder
transports_folder = "/opt/janus/lib/janus/transports" # Transports folder
events_folder = "/opt/janus/lib/janus/events" # Event handlers folder
loggers_folder = "/opt/janus/lib/janus/loggers" # External loggers folder
debug_level = 4 # Debug/logging level, valid values are 0-7
#debug_timestamps = true # Whether to show a timestamp for each log line
#debug_colors = false # Whether colors should be disabled in the log
#log_to_file = "/path/to/janus.log" # Whether to use a log file or not
#daemonize = true # Whether Janus should run as a daemon
# or not (default=run in foreground)
#pid_file = "/path/to/janus.pid" # PID file to create when Janus has been started
#interface = "eth0" # Interface to use [if none, will be autodetected]
#ip = "192.168.0.1" # Ip to use [if none, will be autodetected]
#api_secret = "janusrocks" # String that all Janus requests must contain
#token_auth = true # Enable a token based authentication
#token_auth_secret = "janus" # Use HMAC signed tokens (with token_auth)
}
关键参数:
| 参数 | 默认 | 说明 |
|---|---|---|
debug_level | 4 | 0–7,排障时提到 6/7 可看到 ICE/DTLS 细节 |
interface / ip | 自动探测 | 多网卡服务器必配,否则 Janus 自动选第一块网卡(启动日志 Using x.x.x.x as local IP 可确认选了谁) |
api_secret | 未启用 | 所有 API 请求需携带 apisecret 字段,简单有效的全局口令 |
token_auth | false | 一次性/带签名 token 鉴权,配合 Admin API 发 token,适合多租户 |
daemonize | 前台运行 | systemd 托管时保持前台(Type=simple),不要开 |
生效验证 1:debug_level。把 4 改成 6 并重启,日志第一手证据(实测回显):
Oct 26 06:39:59 janus-host janus[4299]: Debug/log level is 6
生效验证 2:api_secret。设置 api_secret = "q1w2e3r4" 并重启后,无密请求被拒、带密请求放行(实测回显):
$ curl -s -X POST http://127.0.0.1:8088/janus -H "Content-Type: application/json" \
-d '{"janus":"create","transaction":"c1nosec00001"}'
{"janus":"error","transaction":"c1nosec00001","error":{"code":403,"reason":"Unauthorized request (wrong or missing secret/token)"}}
$ curl -s -X POST http://127.0.0.1:8088/janus -H "Content-Type: application/json" \
-d '{"janus":"create","transaction":"c1withsec001","apisecret":"q1w2e3r4"}'
{"janus":"success","transaction":"c1withsec001","data":{"id":6708051054784432}}
2.2 certificates 段:DTLS 证书
certificates: {
cert_pem = "/opt/janus/share/janus/certs/my.pem"
cert_key = "/opt/janus/share/janus/certs/my.key"
#cert_pwd = "secretpassphrase"
#dtls_accept_selfsigned = false
#dtls_ciphers = "your-desired-openssl-ciphers"
#rsa_private_key = false
}
不配置时 Janus 每次启动自动生成自签证书(日志出现 No cert/key specified, autogenerating some...),DTLS 媒体加密本身能工作,但浏览器会对 WSS/HTTPS 侧报证书无效,指纹也会随重启变化。测试机生成一副十年自签证书:
mkdir -p /opt/janus/share/janus/certs
openssl req -x509 -newkey rsa:2048 -nodes \
-keyout /opt/janus/share/janus/certs/my.key \
-out /opt/janus/share/janus/certs/my.pem \
-days 3650 -subj "/CN=janus.example.internal"
生效验证 3:cert_pem/cert_key。填入路径重启后,日志中 autogenerating 一行消失、出现明确的 Using certificates: 与新指纹——对比两次启动的指纹(实测回显):
# 配置前(自动生成):
Oct 26 06:39:59 janus-host janus[4299]: No cert/key specified, autogenerating some...
Oct 26 06:39:59 janus-host janus[4299]: Fingerprint of our certificate: 98:3B:F3:64:CD:3E:5B:6F:31:A8:39:83:41:E7:22:3B:95:75:26:07:A9:B1:86:D5:17:65:11:5C:9F:E6:C7:DD
# 配置后(使用 my.pem):
Oct 26 06:40:23 janus-host janus[4350]: Using certificates:
Oct 26 06:40:23 janus-host janus[4350]: Crypto: OpenSSL >= 1.1.0
Oct 26 06:40:23 janus-host janus[4350]: Fingerprint of our certificate: 2D:32:74:83:A5:7B:68:BB:89:D9:97:CD:85:C2:CB:7D:27:47:A8:13:12:D4:7B:C4:20:8D:A4:0D:4D:43:AB:07
2.3 media 段:媒体与 DTLS 行为
默认全部注释(即出厂默认值),核心项:
| 参数 | 默认 | 说明 |
|---|---|---|
rtp_port_range | "20000-40000" | RTP/RTCP UDP 端口段,防火墙放行对象;收窄时同步调整映射/安全组 |
min_nack_queue | 500 | NACK 重传队列长度(ms 级) |
no_media_timer | 1 | 秒级无媒体多久后通知应用 |
slowlink_threshold | 4 | 每秒丢包超阈值向应用发 slowlink 事件 |
twcc_period | 100 | TWCC(传输层拥塞控制反馈)周期 ms |
dtls_timeout | 500 | DTLS 握手重试间隔 ms |
dscp | 46 | RTP 包 DSCP 标记(EF,语音级优先) |
2.4 nat 段:ICE/STUN/TURN
内网测试可整段不动;公网部署必须读这节:
| 参数 | 说明 |
|---|---|
stun_server / stun_port | 部署在 NAT 后时打洞用(默认 stun.voip.eutelia.it 示例,建议换公共 STUN) |
turn_server / turn_port / turn_user / turn_pwd | TURN 中继(打洞失败兜底) |
nat_1_1_mapping | 一对一公网映射,宿主有公网 IP 时的首选:Janus 把该地址作为对外候选(如 nat_1_1_mapping = "1.2.3.4") |
full_trickle | 完全 trickle ICE(默认 half-trickle,候选随 answer 一次带出) |
ice_nomination | regular / aggressive |
ice_lite / ice_tcp | ICE-Lite 与 ICE-TCP(受限网络兜底) |
ice_consent_freshness | consent freshness 保活校验 |
hangup_on_failed | ICE failed 即挂断 |
ignore_mdns / keep_private_host | mDNS 候选处理 |
ice_ignore_list | 忽略指定网卡/网段的候选收集,如 ice_ignore_list = "vmnet,192.168." |
三、transport 配置
3.1 janus.transport.http.jcfg(REST API)
general: {
json = "compact" # indented / plain / compact
base_path = "/janus" # Base path to bind to in the web server (plain HTTP only)
http = true # Whether to enable the plain HTTP interface
port = 8088 # Web server HTTP port
#interface = "eth0" # Whether we should bind this server to a specific interface only
#ip = "192.168.0.1" # Whether we should bind this server to a specific IP address (v4 or v6) only
https = false # Whether to enable HTTPS (default=false)
#secure_port = 8089 # Web server HTTPS port, if enabled
#acl = "127.,192.168.0." # Only allow requests coming from this comma separated list of addresses
#mhd_connection_limit = 1020 # Open connections limit in libmicrohttpd (default=1020)
}
admin: {
admin_base_path = "/admin" # Base path to bind to in the admin/monitor web server (plain HTTP only)
admin_http = false # Whether to enable the plain HTTP interface
admin_port = 7088 # Admin/monitor web server HTTP port
}
| 参数 | 默认 | 说明 |
|---|---|---|
json | "compact" | 响应格式:compact(无空格)/ plain(无缩进)/ indented(缩进美化)。调试期用 indented,生产用 compact 省带宽 |
base_path / port | /janus、8088 | API 路径与端口;改 port 后 ss -ltn 与 curl 路径同步验证 |
https / secure_port | false | WSS 之外的 HTTPS API 入口,需 certificates 段证书 |
acl | 不限 | 源地址白名单,API 只对内网开放时必配 |
admin_http | false | Admin/monitor API 总开关(7088),能力大于普通 API(可查全部 session/handle 句柄、动态调级别),仅内网排障时打开 |
生效验证 4:json = "indented"。改成 indented 并重启,同一 create 请求的响应变为缩进格式(实测回显):
$ curl -s -X POST http://127.0.0.1:8088/janus -H "Content-Type: application/json" \
-d '{"janus":"create","transaction":"c1indent0001","apisecret":"q1w2e3r4"}'
{
"janus": "success",
"transaction": "c1indent0001",
"data": {
"id": 395708700708733
}
}
3.2 janus.transport.websockets.jcfg(WebSockets API)
general: {
json = "compact"
ws = true # Whether to enable the WebSockets API
port = 8188 # WebSockets server port
wss = false # Whether to enable secure WebSockets
#secure_port = 8989 # WebSockets server secure port, if enabled
}
浏览器端首选 WS:连接即长连接,Janus 的事件推送不再依赖 HTTP 长轮询。wss 同样依赖 certificates 段的证书。heartbeat 相关参数保持默认即可。
四、插件配置
各插件配置的骨架一致,general 段管插件全局,room-1234/rtp-sample 这类具名段预置房间/挂载点。全局通用的三件套:
| 参数 | 说明 |
|---|---|
admin_key | 设置后「创建房间/挂载点」必须携带该 key——防止 API 使用方随意建房(videoroom/streaming/audiobridge 均有) |
events | 是否向事件处理器发本插件事件(默认 true) |
string_ids | 房间/挂载点/参与者 ID 用字符串(如 UUID)替代默认整数 |
逐插件要点:
videoroom(SFU 房间):general 段 admin_key/string_ids;room-1234 示例段演示预置房间(desc、publishers 上限、bitrate、record 等),生产一般不预置、全部走 API 动态建房(配 admin_key)。
streaming(流媒体挂载点):比主配置多一个自己的 rtp_port_range(挂载点端口填 0 时在此段内随机分配,默认 10000-60000,注意与全局段的关系);rtp-sample 示例段演示 RTP 转发挂载点。
audiobridge(混音房间):额外有 lock_play_file(播放 .opus 文件也要求 admin_key)与 record_tmp_ext(录制中临时扩展名,防半成品文件被读到)。
videocall:最简,仅 events 一项——一对一通话无需房间概念。
sip(SIP 网关):网络三元组最关键——local_ip(SIP 信令绑定地址)、local_media_ip(媒体绑定,缺省跟随 local_ip)、sdp_ip(SDP 里对外通告的地址,NAT 后配公网 IP);以及 OPTIONS 保活间隔等注册保持参数。
lua:
general: {
path = "/opt/janus/share/janus/lua"
script = "/opt/janus/share/janus/lua/echotest.lua"
#script = "/opt/janus/share/janus/lua/videoroom.lua"
#config = "/path/to/configfile"
}
Janus 一个 Lua 插件实例只跑一个脚本;要同时跑多个 Lua 应用,编译期没提供多实例机制时通常按脚本分文件或用 videoroom.lua 单脚本承载多房间。
五、事件处理器
三个内置 event handler 默认全部 enabled = false,按需开启一个即可把 Janus 内部事件外送:
| 文件 | 后端 | 关键参数 |
|---|---|---|
| janus.eventhandler.sampleevh.jcfg | 示例(stdout/文件演示) | events = "all" |
| janus.eventhandler.wsevh.jcfg | 向 WebSocket 后端推送 | 后端 URL、events 掩码 |
| janus.eventhandler.gelfevh.jcfg | Graylog(GELF) | backend = "your.graylog.server"、端口 |
events 掩码可用值:none, sessions, handles, jsep, webrtc, media, plugins, transports, core, external, all——生产建议不要 all(量大),按需订阅 sessions,webrtc,media 起步。启用方式:enabled = true + 重启。
六、参数生效验证矩阵
本文四项实测的汇总(均为改配置 → systemctl restart janus → 双证据):
| 参数 | 修改 | 生效证据 1 | 生效证据 2 |
|---|---|---|---|
| general.debug_level | 4 → 6 | 日志 Debug/log level is 6 | 日志条目明显变多 |
| general.api_secret | 未启用 → q1w2e3r4 | 无密 create 返回 403 | 带密 create 返回 success |
| certificates.cert_pem/cert_key | 自动生成 → my.pem | 日志 autogenerating 消失 | 指纹由 98:3B:… 变为 2D:32:… |
| http.jcfg json | compact → indented | create 响应缩进格式 | — |
七、公网上线 checklist 与 FAQ
Q1:api_secret 和 token_auth 怎么选?
单一可信后端(自家应用服务器代客转发)用 api_secret 最简单;多客户端直连、需要按连接授权/吊销时用 token_auth(Admin API 发 token,支持 HMAC 签名与过期时间)。两者都启用时 token 优先。
Q2:改了配置重启后没生效?
三步排查:确认改的是 .jcfg 而不是 .sample;janus-cfgconv 过一遍语法(libconfig 对引号/分号敏感);确认重启的是目标实例(systemctl status janus 看启动时间与 PID)。
Q3:启动日志 Janus is deployed on a private address ... didn't specify any STUN server?
内网部署可忽略;公网服务按 nat 段配置 nat_1_1_mapping(有公网 IP)或 STUN/TURN(NAT 后),否则远端拿到的候选不可达。
Q4:防火墙要开哪些端口?
TCP:8088(HTTP API)/8188(WS)/7088(Admin,仅内网);UDP:rtp_port_range(默认 20000-40000)。HTTPS/WSS 再加 8089/8989(若启用)。
Q5:多网卡服务器候选地址乱了?
general 段 interface/ip 钉住业务网卡,nat 段 ice_ignore_list 排除虚拟网卡段(vmnet、docker0 网段等)。
本文参数均摘自 Janus 1.4.3(v1.4.3 源码 conf/ 目录)默认配置文件,四项生效验证在 Debian 12 实测环境完成(2026-10-26),回显为真实输出照录。