BigBlueButton 4.0.0 配置参数详解

目标：讲清 BigBlueButton 4.0.0 服务端的参数体系——配置文件布局与读取优先级、服务器标识/API 密钥/会议默认值等核心参数的逐项解说，并给出每个关键参数「修改 → 重启 → API 验证」的真实实测闭环；同时给出 Compose 编排形态（.env）参数与裸机属性文件的对应关系、录制产物目录与备份边界、TURN 配置要点。全部命令与回显均在真实服务器环境实测采集（BigBlueButton 4.0.0 (0)，2026-10-27），组件背景见《BigBlueButton 4.0.0 介绍与选型指南》。

一、环境信息

本文所有命令在以下环境实测：

服务器系统：Ubuntu 24.04.5 LTS（x86_64，内核 7.0.0-38-generic），专用内网服务器（IP 10.89.58.2，独立隔离网段 10.89.58.0/24）
软件版本：BigBlueButton Server 4.0.0（0）（bbb-conf --version 实测回显 BigBlueButton Server 4.0.0 (0)）
安装方式：官方 bbb-install-4.0.sh 一键脚本（-v noble-400，未带域名证书的实验形态）
Compose 形态对照：社区 Compose 编排形态（3.0.39）实测于同网段另一台服务器（IP 10.89.58.3），用于第五章 .env 参数对照，部署过程见《BigBlueButton 3.0.39 Docker Compose 部署指南》
测试会议：bm4-004 / bm4-005（moderatorPW q1w2e3r4Mod）

二、配置文件布局与读取优先级

BigBlueButton 的服务端参数集中在一个 Spring 属性体系里，分两层（实测路径与行数）：

层	文件	说明
出厂默认	`/usr/share/bbb-web/WEB-INF/classes/bigbluebutton.properties`	622 行（实测 `wc -l`），全部参数的默认值定义处，升级会被包管理覆盖，不要直接改
本地覆盖	`/etc/bigbluebutton/bbb-web.properties`	安装器实际写入的本地配置（实测仅 2-3 行），Spring 启动时覆盖同键默认值，管理员只改这里
编排形态	Compose 编排项目的 `.env`	见第五章，仅存在于 Compose 形态

读取优先级：本地覆盖文件 > 出厂默认文件。修改后需要重启 bbb-web 服务进程使新值生效（第四章实测验证）。

查看当前生效值的三个入口（均实测）：

# 1) 覆盖文件当前内容
cat /etc/bigbluebutton/bbb-web.properties
# 2) 任意键的出厂默认值
grep -n "^defaultMaxUsers=" /usr/share/bbb-web/WEB-INF/classes/bigbluebutton.properties
# 3) 服务器标识与密钥的官方视图
bbb-conf --secret

实测回显（1、2）：

bigbluebutton.web.serverURL=http://10.89.58.2
securitySalt=mUHYW5QT1zFfhRgN2HTesQ6jQQ970iiiPF2fuZa8ao
defaultMaxUsers=50

285:defaultMaxUsers=0

💡 注意：安装器在无域名实验形态下会把 bigbluebutton.web.serverURL 写成 https://10.89.58.2（协议跟随证书形态），而 80 端口并未提供 HTTPS——这正是本文 3.1 节实测修正的对象。

三、核心参数详解（逐项实测闭环）

3.1 bigbluebutton.web.serverURL——服务器对外基准 URL

默认值（本机实测）：安装器写入 https://10.89.58.2（有域名时为 https://域名）；
作用：join 等跳转链接、客户端加载路径的基准前缀，协议（http/https）直接决定入会跳转协议；
实测闭环：把覆盖文件中的值改为 http://10.89.58.2 并重启后，同一会议的 join 跳转从 https://10.89.58.2/html5client/... 变为 http://10.89.58.2/html5client/?sessionToken=...（HTTP 302）：

# 修改前跳转（实测）：HTTP 302 Location=https://10.89.58.2/html5client/?sessionToken=chpq1nzwcneonkqo
sed -i "s|bigbluebutton.web.serverURL=.*|bigbluebutton.web.serverURL=http://10.89.58.2|" /etc/bigbluebutton/bbb-web.properties
systemctl restart bbb-web && sleep 12
# create 新会议 bm4-004 后 join 实测（create 请求形态见 CLI 篇 7.3 节；checksum 口径见 3.2 节）
SECRET=$(grep -oP "(?<=^securitySalt=).*" /etc/bigbluebutton/bbb-web.properties)
Q="fullName=DocTester&meetingID=bm4-004&password=q1w2e3r4Mod&redirect=true"
C=$(printf %s "join${Q}${SECRET}" | sha256sum | cut -d" " -f1)
curl -s -o /dev/null -w "join -> HTTP %{http_code} Location=%{redirect_url}\n" \
  "http://10.89.58.2/bigbluebutton/join?${Q}&checksum=${C}"

实测回显：

join -> HTTP 302 Location=http://10.89.58.2/html5client/?sessionToken=chpq1nzwcneonkqo

进一步跟随该会话 URL，实测 http://10.89.58.2/html5client/?sessionToken=chpq1nzwcneonkqo 返回 HTTP 200 且页面标题为 BigBlueButton（端到端 Web 链路可用；真实音视频体验需浏览器设备权限，边界说明见《BigBlueButton 3.0.39 Docker Compose 部署指南》 5.2 节）。

3.2 securitySalt——API 共享密钥（checksum 签名键）

默认值：安装时随机生成（本机实测值 mUHYW5QT1zFfhRgN2HTesQ6jQQ970iiiPF2fuZa8ao），写入覆盖文件；
作用：全部 HTTP API 调用的 checksum 签名键。4.0/3.0 系列签名口径为 sha256(action + queryString + securitySalt)，queryString 为按发送顺序拼接、不含 checksum 参数本身的查询串；2.x 的 sha1(action + salt + query) 老口径在带参接口上会报 ChecksumError（实测排障过程见《BigBlueButton 3.0.39 Docker Compose 部署指南》 5.1 节）；
验证方式：bbb-conf --secret 输出 URL 与 Secret、API-Mate 调试链接；与覆盖文件中的 securitySalt 一致（实测一致）；
修改注意：更换 salt 后所有调用方（Greenlight、LMS 集成、脚本）必须同步更新，否则 API 全部 401 级失败。

3.3 defaultMaxUsers——单会议默认人数上限

出厂默认：0（第 285 行实测，0 表示不限制）；
作用：create 未显式传 maxUsers 参数时新建会议的人数上限；
实测闭环：在覆盖文件追加 defaultMaxUsers=50 → systemctl restart bbb-web → 新建会议 → getMeetingInfo 观察 maxUsers 从 0 变为 50：

echo "defaultMaxUsers=50" >> /etc/bigbluebutton/bbb-web.properties
systemctl restart bbb-web && sleep 15
# create bm4-005 后查询（checksum 口径见 3.2 节）
SECRET=$(grep -oP "(?<=^securitySalt=).*" /etc/bigbluebutton/bbb-web.properties)
C=$(printf %s "getMeetingInfomeetingID=bm4-005${SECRET}" | sha256sum | cut -d" " -f1)
curl -s "http://10.89.58.2/bigbluebutton/api/getMeetingInfo?meetingID=bm4-005&checksum=${C}" | grep -oP "(?<=<maxUsers>)[^<]+"

实测回显（修改前会议 bm4-004 / 修改后新建 bm4-005）：

0
50

3.4 defaultWelcomeMessage 与 defaultWelcomeMessageFooter——入会欢迎语

出厂默认（第 280/281 行实测原文）：

defaultWelcomeMessage=Welcome to <b>%%CONFNAME%%</b>!<br><br>For help on using BigBlueButton see these (short) <a href="https://bigbluebutton.org/teachers/tutorials/"><u>tutorial videos</u></a>.<br><br>To join the audio bridge click the speaker button.  Use a headset to avoid causing background noise for others.
defaultWelcomeMessageFooter=This server is running <a href="https://bigbluebutton.org/" target="_blank"><u>BigBlueButton</u></a>.

作用：会议聊天区的欢迎语与页脚，%%CONFNAME%% 为会议名占位符；create 参数传 welcome 可按会议覆盖（《BigBlueButton 3.0.39 Docker Compose 部署指南》 5.2 节实测过 welcome=Welcome+to+doc-test 的传参形态）；
修改方式：同 3.3，改覆盖文件后重启 bbb-web 生效。

3.5 会议行为类参数（出厂默认实测）

参数	默认值（实测行号）	作用
`defaultGuestPolicy`	`ALWAYS_ACCEPT`（第 254 行）	访客策略默认值（ALWAYS_ACCEPT / ASK_MODERATOR / ALWAYS_DENY）
`defaultMeetingLayout`	`UNIFIED_LAYOUT`（第 265 行）	会议默认布局（统一布局/自定义等）
`allowStartStopRecording`	`true`（第 327 行）	允许演示者在会中开始/暂停录制
`defaultKeepEvents`	`false`（第 382 行）	会议结束后是否保留事件流（事件回放/审计用途）
`maxNumPages`	`200`（第 59 行）	单会议白板页数上限

以上参数均存在于出厂默认文件，修改一律走本地覆盖文件 + 重启（机制见第四章）。

四、参数修改与生效机制

唯一推荐流程（全程实测验证）：

# 1) 改本地覆盖文件（不改出厂默认文件）
vim /etc/bigbluebutton/bbb-web.properties
# 2) 重启 bbb-web 使属性生效
systemctl restart bbb-web
# 3) 以 API 实测验证新值（本文 3.1/3.3 两个闭环即按此完成）

两种重启的对照实测：

systemctl restart bbb-web：仅重启应用服务，秒级到十几秒，本文两个闭环均用此方式（sleep 12/sleep 15 后即验证通过）；
bbb-conf --restart：全量重启全部 BBB 服务进程，适合修改 TURN/FreeSWITCH/nginx 层配置后使用；实测中 --restart 后务必用 bbb-conf --status 复查——本实测形态曾出现部分组件未随 restart 拉起的情况，定位与恢复实录见《BigBlueButton 4.0.0 常用 CLI 命令与工具详解》 4.5 节。

⚠️ 修改覆盖文件后若忘了重启，参数不生效且无报错——务必按「改文件 → 重启 → API 验证」三步闭环执行。

五、Compose 编排形态参数（.env）

Compose 编排形态（实测版本 3.0.39，部署全流程见《BigBlueButton 3.0.39 Docker Compose 部署指南》）把上述服务器级参数收敛为编排目录下的单个 .env 文件，核心变量与裸机参数的对应关系（均为实测值）：

.env 变量	实测值	对应裸机参数/说明
`SHARED_SECRET`	`dQlqhNULhRDTwaPdKi2hXet1bihGeLqH0RDEXPOfEI`	即 `securitySalt`，API checksum 密钥
`DOMAIN`	`bbb.example.com`	对应 `bigbluebutton.web.serverURL` 的主机部分与证书 CN
`EXTERNAL_IPv4`	`10.89.58.3`	服务器公网/路由可达 IPv4（媒体通告地址）
`EXTERNAL_IPv6`	留空	服务器 IPv6（无则留空）
`STUN_IP` / `STUN_PORT`	`216.93.246.18` / `3478`	默认 STUN 探测目标
`TURN_SECRET`	实测生成值	TURN 长期凭据密钥（配合 `ENABLE_COTURN=true`）
`ENABLE_COTURN`	`true`	启用内置 TURN 中继组件
`ENABLE_GREENLIGHT`	`true`	启用 Greenlight 前端
`ENABLE_RECORDING`	`false`	启用录制组件（见第六章边界）
`ENABLE_COLLABORA`	`false`	在线办公套件集成（按需）
`ENABLE_HTTPS_PROXY`	`true`	启用 TLS 入口（402/443 反代层）
`IGNORE_TLS_CERT_ERRORS`	`true`（自签实验形态）	自签证书形态开关；正式证书置 false 走 Let's Encrypt
`SOUNDS_LANGUAGE`	`en-us-callie`	语音提示音语言包
`DEFAULT_PRESENTATION`	`./mod/nginx/default.pdf`	新会议默认加载的演示文档

修改机制与裸机不同：改 .env 后需重新执行编排生成并全量应用（实测命令形态为 ./scripts/generate-compose 后全栈重建），.env 的值即 3.2/3.3 节同名参数在编排形态下的来源。

六、录制与备份边界

录制产物与状态目录实测（ls /var/bigbluebutton/，以 -<毫秒时间戳> 结尾的哈希目录即「每场会议一个」，输出按字母序）：

135a4ead32fecd39517ffb9a7bca3d790c5310c7-1793065200644
ad3c26864a836e0fa3f24550de9f35e6c28b517c-1793065248040
basic_stats
bf06e52707a95e5ab3470bbb8dc7617ec4677898-1793065288892
blank
c379741dbcd4249c8530fad1c3c34abd9587a365-1793065597381
captions
configs
deleted
diagnostics
e8dba677965ecdee9b1a562382d17008fb57403c-1793065170682
events
fe27b5a22241891ef0c20d46f1145c8f7a6c3c24-1793065213989
learning-dashboard
playback
published
recording
unpublished

目录语义（实测 + 官方流水线脚本印证）：会议哈希目录内为该场会议的事件/媒体素材；published/ 存放已发布回放、unpublished/ 存放未发布录制、events/ 存事件流、deleted/ 为已删除产物；
流水线脚本位置：/usr/local/bigbluebutton/core/scripts/（实测目录含 archive/、caption/、cleanup.rb、post_archive/、post_events/ 等），三段式「归档 → 处理 → 发布」的执行入口（命令实测见《BigBlueButton 4.0.0 常用 CLI 命令与工具详解》第五章）；
录制开关边界：本机实测环境未启用录制组件栈时，会议事件仍会归档（bbb-record --list 可见 archived 记录），但音视频回放产物依赖真实浏览器会话产生的媒体流——自动化验证无法生成，《BigBlueButton 4.0.0 常用 CLI 命令与工具详解》 5.2/5.4 节如实标注；
备份边界：需要备份的是 /var/bigbluebutton/（录制与回放产物）与 /etc/bigbluebutton/（本地覆盖配置）；Greenlight 元数据在裸机形态存于本机 PostgreSQL（数据库名 greenlight），Compose 形态则全部落在编排目录 data/ 子目录（实测 92 MB，含 postgres/redis/greenlight/haproxy 证书等八个子目录，栈重建数据保留已实测）；
磁盘规划：官方对启用录制的生产环境建议 500 GB 磁盘（选型指南第三章引用），结合本目录结构，录制增长主要发生在会议哈希目录与 published/。

七、TURN 配置与实测边界

服务端组件：TURN 由 coturn 组件承担，客户端侧的 TURN 目标/凭据在 /usr/share/bbb-web/WEB-INF/classes/spring/turn-stun-servers.xml（实测文件存在）；Compose 形态则由 ENABLE_COTURN/TURN_SECRET/STUN_IP 三个 .env 变量声明（第五章表格）；
实测边界（如实标注）：本文两套实测环境均为内网隔离网段部署，coturn 组件处于运行状态（裸机 bbb-conf --status 实测显示 coturn 进程相关服务 active；Compose 服务状态实测显示 coturn Up），但跨公网/对称 NAT 场景下的 TURN 中继连通性未实测——这需要公网安全组放行 3478/TCP-UDP 与中继端口段、以及对应证书，超出本文验证能力，请生产部署时按官方文档单独验证。

八、常见问题（FAQ）

Q1：改了 /usr/share/bbb-web/WEB-INF/classes/bigbluebutton.properties 为什么升级后失效？ 该文件属软件包管辖，升级会被覆盖；所有本地定制必须写入 /etc/bigbluebutton/bbb-web.properties 覆盖层（第二章优先级）。

Q2：API 全部返回 ChecksumError？ 4.0/3.0 系列 checksum 口径为 sha256(action + queryString + securitySalt)；核对 securitySalt 是否与 bbb-conf --secret 一致、拼接顺序是否正确（3.2 节）。

Q3：defaultMaxUsers 改了没生效？ 覆盖文件未保存、未重启 bbb-web、或 create 请求显式带了 maxUsers 参数（请求参数优先于服务器默认值），三步闭环逐项排查（3.3 节）。

Q4：serverURL 该写域名还是 IP？ 生产环境写与证书一致的域名（https://域名）；本文实验形态因无域名证书写 http://IP，效果已实测（3.1 节）。

Q5：录制文件在哪、能直接拷走吗？ 在 /var/bigbluebutton/（第六章），published/ 内为可直接以 HTTP 访问的回放产物；备份时连同目录结构整体拷贝即可。

九、参考链接

官方文档（安装与配置总览）：https://docs.bigbluebutton.org
属性文件上游模板：https://github.com/bigbluebutton/bigbluebutton/blob/v4.0.x-release/bigbluebutton-web/grails-app/conf/bigbluebutton.properties
本专栏配套篇目：《BigBlueButton 4.0.0 介绍与选型指南》、《BigBlueButton 3.0.39 Docker Compose 部署指南》、《BigBlueButton 4.0.0 常用 CLI 命令与工具详解》