Janus 1.4.3 配置参数详解

逐段详解 Janus 1.4.3 配置体系:janus.jcfg 四大段、HTTP/WebSockets transport、核心插件与事件处理器参数,附 debug_level/api_secret/证书/json 格式四项重启生效验证实录。

JanusJanusWebRTC流媒体2026/10/26

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.jcfgREST (HTTP/HTTPS) transport 与 Admin API
接入层janus.transport.websockets.jcfgWebSockets (WS/WSS) transport
接入层janus.transport.pfunix.jcfgUnix 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 等同目录—

三条硬规则:

  1. 修改后必须重启进程才生效(systemctl restart janus 或 compose restart)——Janus 启动时一次性读取全部配置,没有运行时热加载;个别运行时可调项走 Admin API 动态改,不在配置文件层面。
  2. 改前先备份:.sample 是 make configs 时的出厂备份,永远不要直接编辑 .sample 后指望生效——Janus 只读 .jcfg。
  3. 语法自检:改完先用自带的 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_level40–7,排障时提到 6/7 可看到 ICE/DTLS 细节
interface / ip自动探测多网卡服务器必配,否则 Janus 自动选第一块网卡(启动日志 Using x.x.x.x as local IP 可确认选了谁)
api_secret未启用所有 API 请求需携带 apisecret 字段,简单有效的全局口令
token_authfalse一次性/带签名 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_queue500NACK 重传队列长度(ms 级)
no_media_timer1秒级无媒体多久后通知应用
slowlink_threshold4每秒丢包超阈值向应用发 slowlink 事件
twcc_period100TWCC(传输层拥塞控制反馈)周期 ms
dtls_timeout500DTLS 握手重试间隔 ms
dscp46RTP 包 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_pwdTURN 中继(打洞失败兜底)
nat_1_1_mapping一对一公网映射,宿主有公网 IP 时的首选:Janus 把该地址作为对外候选(如 nat_1_1_mapping = "1.2.3.4")
full_trickle完全 trickle ICE(默认 half-trickle,候选随 answer 一次带出)
ice_nominationregular / aggressive
ice_lite / ice_tcpICE-Lite 与 ICE-TCP(受限网络兜底)
ice_consent_freshnessconsent freshness 保活校验
hangup_on_failedICE failed 即挂断
ignore_mdns / keep_private_hostmDNS 候选处理
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、8088API 路径与端口;改 port 后 ss -ltn 与 curl 路径同步验证
https / secure_portfalseWSS 之外的 HTTPS API 入口,需 certificates 段证书
acl不限源地址白名单,API 只对内网开放时必配
admin_httpfalseAdmin/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.jcfgGraylog(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_level4 → 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 jsoncompact → indentedcreate 响应缩进格式—

七、公网上线 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),回显为真实输出照录。