BigBlueButton 4.0.0 常用 CLI 命令与工具详解
BigBlueButton 4.0.0 常用命令与 REST API 实测：bbb-conf 版本/状态/体检/密钥/启停（含 --restart 后服务未拉起的定位与恢复实录）、bbb-record 录制管理、systemd 单元管理、API curl 全矩阵与错误分支、日志查看（2026-10-27 实测）。
BigBlueButton 4.0.0 常用 CLI 命令与工具详解
目标：梳理 BigBlueButton 4.0.0 服务端日常管理与排障所需的命令与工具——服务器级管理工具
bbb-conf（版本/状态/体检/密钥/启停，含--restart后服务未拉起的完整排障实录）、录制管理工具bbb-record、systemd 单元管理、REST API 的 curl 全矩阵实测（getMeetings/create/join/getMeetingInfo/end 与错误分支），以及日志目录结构。全部命令与回显均在真实服务器环境实测采集（BigBlueButton Server 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（
bbb-conf --version实测回显BigBlueButton Server 4.0.0 (0)） - 安装方式：官方 bbb-install-4.0.sh 一键脚本（
-v noble-400，未带域名证书的实验形态） - 测试会议：d1-cli-001（moderatorPW
q1w2e3r4Mod、attendeePWq1w2e3r4Att，第七章 API 实测创建） - 密钥读取：API 共享密钥不直接落文，统一用「从本机配置文件运行时读取」的方式（见 7.1 节）
二、工具概览
BigBlueButton 4.0.0 服务端的日常管理围绕以下四类入口展开，本章先给出全景，后续章节逐一实测：
| 工具/入口 | 提供方 | 用途 |
|---|---|---|
bbb-conf | bbb-config 软件包（/usr/bin/bbb-conf，shell 脚本） | 服务器级：版本、组件状态、配置体检、API 密钥查看、全栈启停 |
bbb-record | bbb-record-core 软件包 | 录制域：录制列表、工作流、配置体检、重建/删除 |
systemctl | systemd | 单个服务的状态查询、启动/停止/重启、单元定义查看 |
curl + HTTP API | bbb-web（8080 端口，经 nginx 反代 /bigbluebutton/api） | 会议生命周期：getMeetings/create/join/getMeetingInfo/end 等 |
💡 说明：
bbb-conf官方定位即「BigBlueButton 配置工具」——修改部分配置、管理系统启停、排障三合一；无参数执行会打印全部可用选项（官方文档见参考链接 1）。
三、前置条件
- 已按官方一键脚本完成 BigBlueButton 4.0.0 安装（本文实测形态见第一章）；
- 具备 root 权限 shell（
bbb-conf部分动作与systemctl管理 需要 root）； - 服务器处于运行状态——先用
bbb-conf --status确认全部组件 active（实测回显见 4.2 节）； - API 实测需要本机
securitySalt（从/etc/bigbluebutton/bbb-web.properties读取，见 7.1 节）与可达的http://10.89.58.2/bigbluebutton/api端点。
四、bbb-conf 服务器管理工具
bbb-conf 是服务器级管理的第一入口。本节按「看版本 → 看状态 → 做体检 → 看密钥 → 启停与排障」的顺序逐项实测。
4.1 bbb-conf --version：查看版本与组件清单
bbb-conf --version
实测回显（输出节选，实测首部；完整输出为全部 BBB 软件包的 dpkg 清单）：
BigBlueButton Server 4.0.0 (0)
ii bbb-apps-akka 2:4.0.0+20261014T162352-git.local-build-7d27e7e206 all BigBlueButton Apps (Akka)
ii bbb-config 2:4.0.0+20261014T162352-git.local-build-7d27e7e206 amd64 BigBlueButton configuration utilities
ii bbb-coturn 2:4.0.0+20261014T162352-git.local-build-7d27e7e206 amd64 coturn 4.16.0 TURN/STUN server packaged for BigBlueButton
首行为服务器版本号 BigBlueButton Server 4.0.0 (0)，随后列出各组件包的版本（实测各包版本号均带 4.0.0+20261014T162352 构建标识，可据此核对组件是否同一批构建）。
4.2 bbb-conf --status：查看组件运行状态
bbb-conf --status
实测回显（19 个组件，全部 active）：
nginx ————————————————————————► [✔ - active]
freeswitch ———————————————————► [✔ - active]
redis-server —————————————————► [✔ - active]
bbb-apps-akka ————————————————► [✔ - active]
bbb-fsesl-akka ———————————————► [✔ - active]
postgresql ———————————————————► [✔ - active]
bbb-graphql-actions ——————————► [✔ - active]
bbb-graphql-middleware ———————► [✔ - active]
bbb-graphql-server ———————————► [✔ - active]
bbb-webrtc-sfu ———————————————► [✔ - active]
bbb-webrtc-recorder ——————————► [✔ - active]
bbb-web ——————————————————————► [✔ - active]
bbb-export-annotations ———————► [✔ - active]
bbb-rap-caption-inbox ————————► [✔ - active]
bbb-rap-resque-worker ————————► [✔ - active]
bbb-rap-starter ——————————————► [✔ - active]
livekit-server ———————————————► [✔ - active]
livekit-sip ——————————————————► [✔ - active]
bbb-shared-notes-server ——————► [✔ - active]
19 个组件涵盖 Web 入口（nginx）、API（bbb-web）、语音（freeswitch）、媒体转发（bbb-webrtc-sfu / livekit-server / livekit-sip）、录制流水线（bbb-rap-*）与数据层（redis-server / postgresql）。4.0 已将 LiveKit 纳入媒体栈（livekit-server / livekit-sip 两个组件），状态排查时应一并确认。
4.3 bbb-conf --check：配置体检
bbb-conf --check
实测回显（输出节选，实测首部与尾部）：
BigBlueButton Server 4.0.0 (0)
Kernel version: 7.0.0-38-generic
Distribution: Ubuntu 24.04.5 LTS (64-bit)
Memory: 20428 MB
CPU cores: 128
/etc/bigbluebutton/bbb-web.properties (override for bbb-web)
/usr/share/bbb-web/WEB-INF/classes/bigbluebutton.properties (bbb-web)
bigbluebutton.web.serverURL: http://10.89.58.2
defaultGuestPolicy: ALWAYS_ACCEPT
defaultMeetingLayout: UNIFIED_LAYOUT
/etc/nginx/sites-available/bigbluebutton (nginx)
server_name: 10.89.58.2
port: 80, [::]:80
UDP port ranges
FreeSWITCH: 16384-24576
bbb-webrtc-sfu: 24577-32768
bbb-webrtc-recorder: 24577-32768
livekit.rtc.port_range_start: 16384
livekit.rtc.port_range_end: 32768
# Potential problems described below
# Warning: No firewall detected. Recommend using setting up a firewall for your server
#
# https://docs.bigbluebutton.org/administration/firewall-configuration
#
--check 会把关键配置文件的生效值汇总输出（含覆盖层文件来源标注），末尾给出「Potential problems」清单。本次实测唯一警告为未检测到防火墙——体检结论是无配置错误，仅提示安全加固项。端口段信息（FreeSWITCH 16384-24576、bbb-webrtc-sfu 24577-32768、LiveKit 16384-32768）可直接用于防火墙放行清单。
4.4 bbb-conf --secret：查看 API 端点与共享密钥
bbb-conf --secret
实测回显（Secret 与 API-Mate 链接中的密钥参数以 ***MASKED*** 代替展示，实际值即本机 securitySalt）：
URL: http://10.89.58.2/bigbluebutton/
Secret: ***MASKED***
Link to the API-Mate:
https://mconf.github.io/api-mate/#server=http://10.89.58.2/bigbluebutton/&sharedSecret=***MASKED***
URL即 API 端点前缀（第七章全部 curl 实测都用它）；Secret与本地覆盖文件中的securitySalt为同一值，需要读取实际值时用：
grep -oP "(?<=^securitySalt=).*" /etc/bigbluebutton/bbb-web.properties
Link to the API-Mate指向官方在线调试页 API-Mate，打开后可直接以浏览器发起带签名的 API 调试请求；- 官方文档另提供
--setsecret <new_secret>更换共享密钥（本节未实测更换动作；更换后所有调用方需同步更新）。
4.5 bbb-conf --restart / --start：启停与服务恢复实录
--restart 为「全量停止再拉起」，--start 为「拉起」。本节含一次真实排障实录：实测中 --restart 停止阶段正常，但拉起阶段后部分组件未随之启动，定位与恢复过程如下（每一步回显均为实测）。
第一步，执行 --restart：
bbb-conf --restart
实测回显（输出节选，实测尾部——停止阶段各组件显示 inactive）：
# bbb-graphql-actions ——————————► [✘ - inactive]
bbb-graphql-middleware ———————► [✘ - inactive]
bbb-webrtc-sfu ———————————————► [✘ - inactive]
bbb-web ——————————————————————► [✘ - inactive]
bbb-export-annotations ———————► [✘ - inactive]
livekit-sip ——————————————————► [✘ - inactive]
bbb-shared-notes-server ——————► [✘ - inactive]
#
第二步，等待 25 秒后复查状态（7 个组件仍为 inactive）：
sleep 25
bbb-conf --status
实测回显：
nginx ————————————————————————► [✔ - active]
freeswitch ———————————————————► [✔ - active]
redis-server —————————————————► [✔ - active]
bbb-apps-akka ————————————————► [✔ - active]
bbb-fsesl-akka ———————————————► [✔ - active]
postgresql ———————————————————► [✔ - active]
bbb-graphql-actions ——————————► [✘ - inactive]
bbb-graphql-middleware ———————► [✘ - inactive]
bbb-graphql-server ———————————► [✔ - active]
bbb-webrtc-sfu ———————————————► [✘ - inactive]
bbb-webrtc-recorder ——————————► [✔ - active]
bbb-web ——————————————————————► [✘ - inactive]
bbb-export-annotations ———————► [✘ - inactive]
bbb-rap-caption-inbox ————————► [✔ - active]
bbb-rap-resque-worker ————————► [✔ - active]
bbb-rap-starter ——————————————► [✔ - active]
livekit-server ———————————————► [✔ - active]
livekit-sip ——————————————————► [✘ - inactive]
bbb-shared-notes-server ——————► [✘ - inactive]
此时 API 已不可用（nginx 正常但后端 bbb-web 未起，返回 502）：
SECRET=$(grep -oP "(?<=^securitySalt=).*" /etc/bigbluebutton/bbb-web.properties)
C=$(printf %s "getMeetings${SECRET}" | sha256sum | cut -d" " -f1)
curl -s "http://10.89.58.2/bigbluebutton/api/getMeetings?checksum=${C}"
实测回显：
<html>
<head><title>502 Bad Gateway</title></head>
<body>
<center><h1>502 Bad Gateway</h1></center>
<hr><center>nginx/1.24.0 (Ubuntu)</center>
</body>
</html>
第三步，先按常规路径执行 --start，再复查：
bbb-conf --start
实测回显（完整输出仅两行）：
Reloading NginX configuration, restarting if needed
Starting BigBlueButton
复查 bbb-conf --status 后上述 7 个组件仍为 inactive——--start 未把它们拉起来。
第四步，定位 --start 实际做了什么（bbb-conf 是 shell 脚本，可用 bash -x 观察其内部执行）：
bash -x /usr/bin/bbb-conf --start 2>&1 | grep -E "^\+ .*systemctl"
实测回显（输出节选）：
+ systemctl reload-or-restart nginx
+ systemctl restart bigbluebutton.target
可见 --start 的核心动作是重启 bigbluebutton.target 这个聚合单元。查看该单元定义：
systemctl cat bigbluebutton.target --no-pager
实测回显（完整）：
# /usr/lib/systemd/system/bigbluebutton.target
[Unit]
Description=BigBlueButton System
Requires=
After=syslog.target network.target
[Install]
WantedBy=multi-user.target
关键点：Requires= 后面的依赖列表为空——重启该 target 只是「到达」target 本身，不会拉起任何服务单元。再用 dpkg -V 校验该文件与软件包内建内容是否一致：
dpkg -V bbb-config
实测无任何输出（即文件与包内一致、未被改动），说明「target 不挂服务依赖」是该安装形态下的原始状态。各服务单元自身的归属关系可从单元定义印证（如 bbb-web 通过 PartOf=bigbluebutton.target 挂在 target 之下，见 6.4 节），但 target 的 Requires 列表为空时，PartOf 只保证「停止 target 时跟随停止」，不提供「启动 target 时跟随启动」的语义。
第五步，恢复：对 7 个 inactive 组件逐个执行 systemctl start 并立即用 is-active 验证（每个单元单独执行）：
systemctl start bbb-web
systemctl is-active bbb-web
active
systemctl start bbb-graphql-actions
systemctl is-active bbb-graphql-actions
active
systemctl start bbb-graphql-middleware
systemctl is-active bbb-graphql-middleware
active
systemctl start bbb-webrtc-sfu
systemctl is-active bbb-webrtc-sfu
active
systemctl start bbb-export-annotations
systemctl is-active bbb-export-annotations
active
systemctl start livekit-sip
systemctl is-active livekit-sip
active
systemctl start bbb-shared-notes-server
systemctl is-active bbb-shared-notes-server
active
第六步，终态复查（全部 19 个组件 active，回显见 4.2 节，实测一致）并再次 API 探活：
bbb-conf --status
SECRET=$(grep -oP "(?<=^securitySalt=).*" /etc/bigbluebutton/bbb-web.properties)
C=$(printf %s "getMeetings${SECRET}" | sha256sum | cut -d" " -f1)
curl -s "http://10.89.58.2/bigbluebutton/api/getMeetings?checksum=${C}"
实测回显（API 探活）：
<response>
<returncode>SUCCESS</returncode>
<meetings/>
<messageKey>noMeetings</messageKey>
<message>no meetings were found on this server</message>
</response>
⚠️ 结论沉淀：在本实测形态（bbb-install-4.0.sh 装出的 4.0.0）中，
bbb-conf --restart/--start后必须用bbb-conf --status复查；若发现 inactive 组件，按上节逐个systemctl start恢复，并以 API 探活作为最终验收。
五、bbb-record 录制管理工具
bbb-record 面向录制域：查看录制列表与处理状态、列出处理工作流、体检录制配置，以及重建/删除录制。本节逐项实测其只读类核心命令。
5.1 bbb-record --help：命令清单
bbb-record --help
实测回显（完整）：
BigBlueButton Recording Diagnostic Utility (BigBlueButton Version 4.0.0)
bbb-record [options]
Reporting:
--list List all recordings
--list-recent List recent recordings
--list-recent --withDesc List recent recordings and show their description
--list-workflows List available recording workflows
Monitoring:
--watch Watch processing of recordings
--watch --withDesc Watch processing of recordings and show their description
Administration:
--rebuild <internal meetingID> rebuild the output for the given internal meetingID
--rebuildall rebuild every recording
--delete <internal meetingID> delete one meeting and recording
--deleteall delete all meetings and recordings
--debug check for recording errors
--check check for configuration errors
--enable <workflow> enable a recording workflow
--disable <workflow> disable a recording workflow
--tointernal <external meetingId> get the internal meeting ids for the given external meetingId
--toexternal <internal meetingId> get the external meeting id for the given internal meetingId
--republish <internal meetingID> republish the recording for meetingID. (Only for Matterhorn Integration)
命令分三组：Reporting（报表）、Monitoring（监控）、Administration（管理）。注意 --rebuild/--delete 等管理类命令的参数是内部会议 ID（形如 <40位哈希>-<毫秒时间戳>，可与 --tointernal 互转）。
5.2 bbb-record --list：录制列表
bbb-record --list
实测回显（输出节选，实测首部）：
Internal MeetingID Time APVD APVDE RAS Slides Processed Published External MeetingID
------------------------------------------------------ ---------------------------- ---- ----- --- ------ -------------------- ------------------ -------------------
c379741dbcd4249c8530fad1c3c34abd9587a365-1793065597381 Tue Oct 27 01:46:37 UTC 2026 .P.. ..... ... 0
bf06e52707a95e5ab3470bbb8dc7617ec4677898-1793065288892 Tue Oct 27 01:41:28 UTC 2026 .P.. ..... ... 0
ad3c26864a836e0fa3f24550de9f35e6c28b517c-1793065248040 Tue Oct 27 01:40:48 UTC 2026 .P.. ..... ... 0
fe27b5a22241891ef0c20d46f1145c8f7a6c3c24-1793065213989 Tue Oct 27 01:40:13 UTC 2026 .P.. ..... ... 0
135a4ead32fecd39517ffb9a7bca3d790c5310c7-1793065200644 Tue Oct 27 01:40:00 UTC 2026 .P.. ..... ... 0
e8dba677965ecdee9b1a562382d17008fb57403c-1793065170682 Tue Oct 27 01:39:30 UTC 2026 .P.. ..... ... 0
实测中此前每场已结束的会议各占一行（内部会议 ID 与时间）。Processed / Published 两列均为 0 / 空——本实测环境无真实浏览器媒体流（见注意事项），会议事件仅归档、无回放产物发布，与 bbb-record --list 的观测一致。
5.3 bbb-record --list-workflows：列出处理工作流
bbb-record --list-workflows
实测回显（完整）：
# Enabled recording processing steps:
#
# archive
# sanity
# captions
# process:presentation
# publish:presentation
#
# Available processing scripts:
#
# presentation
当前启用的处理步骤为归档（archive）→ 校验（sanity）→ 字幕（captions）→ 处理（process:presentation）→ 发布（publish:presentation），可用脚本为 presentation——即「演示文稿回放」这一种工作流形态。
5.4 bbb-record --check：录制配置体检
bbb-record --check
实测回显（完整）：
** Potential problems described below **
#
# Warning: /var/log/bigbluebutton/bbb-rap-worker.log is missing.
#
#
# Warning: /var/log/bigbluebutton/sanity.log is missing.
#
#
# Warning: /var/log/bigbluebutton/post_process.log is missing.
#
#
# Warning: /var/log/bigbluebutton/post_publish.log is missing.
#
#
# Warning: /var/log/bigbluebutton/bbb-recording-cleanup.log is missing.
#
5 条警告全部是「某日志文件不存在」。结合本环境从未跑过录制处理流水线（无媒体流、无 process/publish 动作），这些日志尚未生成属预期现象；执行过真实录制处理后再次体检，相应警告应消失。
5.5 其余子命令
--watch（跟踪录制处理）、--rebuild/--rebuildall（重建产物）、--delete/--deleteall（删除会议与录制）、--enable/--disable（启停工作流）、--debug（扫描录制错误）等子命令见 5.1 节帮助清单。此类命令会改动录制数据，操作前建议先 --list 留存内部会议 ID 清单。
六、systemd 服务管理
bbb-conf 管的是「全栈」，systemctl 管「单个服务」。修改某一组件配置后，最常见的动作就是重启对应单个服务并验证。
6.1 查看运行中的 BBB 服务单元
systemctl list-units "bbb-*" --type=service --no-pager
实测回显（完整）：
UNIT LOAD ACTIVE SUB DESCRIPTION
bbb-apps-akka.service loaded active running BigBlueButton Apps (Akka)
bbb-fsesl-akka.service loaded active running BigBlueButton FS-ESL (Akka)
bbb-graphql-server.service loaded active exited BigBlueButton GraphQL Server start unit
bbb-graphql-server@8085.service loaded active running BigBlueButton GraphQL Server
bbb-rap-caption-inbox.service loaded active running BigBlueButton recording caption upload handler
bbb-rap-resque-worker.service loaded active running BigBlueButton resque worker for recordings
bbb-rap-starter.service loaded active running BigBlueButton recording processing starter
bbb-webrtc-recorder.service loaded active running BigBlueButton WebRTC Recorder
Legend: LOAD → Reflects whether the unit definition was properly loaded.
ACTIVE → The high-level unit activation state, i.e. generalization of SUB.
SUB → The low-level unit activation state, values depend on unit type.
8 loaded units listed. Pass --all to see loaded but inactive units, too.
To show all installed unit files use 'systemctl list-unit-files'.
list-units 默认只列出「已加载且 active」的单元，故只显示 8 个 bbb-* 前缀单元；nginx、redis-server、postgresql、bbb-web、bbb-webrtc-sfu、livekit-server 等组件要么不带 bbb- 前缀、要么其单元在 4.5 节的异常场景下处于 inactive 而不出现在此列表中——排查服务状态请以 bbb-conf --status（覆盖全部 19 个组件）为准。
6.2 查看单个服务状态
systemctl status bbb-web --no-pager
实测回显（输出节选，实测首部）：
● bbb-web.service - BigBlueButton Web Application
Loaded: loaded (/usr/lib/systemd/system/bbb-web.service; disabled; preset: enabled)
Drop-In: /etc/systemd/system/bbb-web.service.d
└─10-user-session.conf, override.conf
Active: active (running) since Tue 2026-10-27 02:21:37 UTC; 4min 0s ago
Main PID: 22066 (java)
Tasks: 79 (limit: 21153)
Memory: 757.6M (peak: 759.0M)
CPU: 20.255s
CGroup: /system.slice/bbb-web.service
实测 bbb-web 为 Java 进程（Main PID 22066），常驻内存约 758 MB；Drop-In 行显示该单元叠加了两个本地覆盖片段——排查服务参数时应把 drop-in 一并查看（见 6.4 节）。
6.3 重启单个服务并验证
以重启 bbb-web（修改 /etc/bigbluebutton/bbb-web.properties 后的标准动作）为例：
systemctl restart bbb-web
sleep 12
systemctl is-active bbb-web
实测回显：
active
重启后除 is-active 外，建议再用 API 探活确认应用层可用（Java 服务进程 active 不等于应用就绪，实测中重启后约 10 余秒内 API 才恢复响应）。
6.4 查看单元定义
systemctl cat bbb-web --no-pager
实测回显（输出节选，实测首部）：
# /usr/lib/systemd/system/bbb-web.service
[Unit]
Description=BigBlueButton Web Application
Requires=network.target
Wants=redis-server.service
After=redis-server.service
PartOf=bigbluebutton.target
[Service]
Type=simple
User=bigbluebutton
Group=bigbluebutton
PartOf=bigbluebutton.target 印证了 4.5 节的行为：target 停止/重启时 bbb-web 跟随停止；但 PartOf 不含「跟随启动」语义，且 target 的 Requires 列表为空（4.5 节实测），因此全栈拉起需依赖逐单元 systemctl start。
七、REST API 与 curl 实测矩阵
BBB 的全部管理动作都可通过 HTTP API 完成，返回 XML。本节用 curl 完成会议生命周期全矩阵实测：getMeetings → create → join → getMeetingInfo → end，外加两个错误分支。
7.1 端点与鉴权（checksum）
- 端点：
http://10.89.58.2/bigbluebutton/api（与bbb-conf --secret输出的 URL 一致）； - 鉴权：每个请求都必须携带
checksum参数，4.0/3.0 系列的计算口径为sha256(action + queryString + securitySalt)——action为接口名（如create），queryString为按发送顺序拼接、不含checksum本身的查询串，无参接口（如getMeetings）的 queryString 为空串，结果取十六进制小写； - 密钥读取（运行时从本机配置文件读取，避免在命令历史/脚本中写死）：
SECRET=$(grep -oP "(?<=^securitySalt=).*" /etc/bigbluebutton/bbb-web.properties)
BASE=http://10.89.58.2/bigbluebutton/api
以下各节命令均在这两个变量已就位的前提下执行，与实测执行方式一致。
7.2 getMeetings：列出当前会议（无参接口）
C=$(printf %s "getMeetings${SECRET}" | sha256sum | cut -d" " -f1)
curl -s "${BASE}/getMeetings?checksum=${C}"
实测回显（空会议时）：
<response>
<returncode>SUCCESS</returncode>
<meetings/>
<messageKey>noMeetings</messageKey>
<message>no meetings were found on this server</message>
</response>
7.3 create：创建会议
Q="name=D1+CLI+Demo&meetingID=d1-cli-001&moderatorPW=q1w2e3r4Mod&attendeePW=q1w2e3r4Att"
C=$(printf %s "create${Q}${SECRET}" | sha256sum | cut -d" " -f1)
curl -s "${BASE}/create?${Q}&checksum=${C}"
实测回显（完整）：
<response>
<returncode>SUCCESS</returncode>
<meetingID>d1-cli-001</meetingID>
<internalMeetingID>c374f296a21397107c0ba64db6665e3217824891-1793067386352</internalMeetingID>
<parentMeetingID>bbb-none</parentMeetingID>
<attendeePW>q1w2e3r4Att</attendeePW>
<moderatorPW>q1w2e3r4Mod</moderatorPW>
<createTime>1793067386352</createTime>
<voiceBridge>20603</voiceBridge>
<dialNumber>613-555-1234</dialNumber>
<createDate>Tue Oct 27 02:16:26 UTC 2026</createDate>
<hasUserJoined>false</hasUserJoined>
<duration>0</duration>
<hasBeenForciblyEnded>false</hasBeenForciblyEnded>
<messageKey></messageKey>
<message></message>
</response>
要点：internalMeetingID 即 5.1 节所述「40 位哈希-毫秒时间戳」形态，是录制类命令的操作对象；meetingID 重复 create 同名会议时返回 duplicateWarning 而不会重建（幂等保护）。实测中未传 maxUsers，随后 7.5 节 getMeetingInfo 显示该会议人数上限取服务器默认值 50（来自本机覆盖配置的 defaultMaxUsers=50）。
7.4 join：获取入会跳转
Q="fullName=D1+Tester&meetingID=d1-cli-001&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" "${BASE}/join?${Q}&checksum=${C}"
实测回显：
join -> HTTP 302 Location=http://10.89.58.2/html5client/?sessionToken=ppmqso1cdrydtd5k
join 不返回 XML，而是 302 跳转到客户端页面（redirect=true 时）；跳转协议与 bigbluebutton.web.serverURL 的协议一致。该 URL 即浏览器入会地址，真实音视频体验需浏览器授权设备，自动化验证以「HTTP 302 + 客户端页面可访问」为边界。
7.5 getMeetingInfo：查询会议详情
Q="meetingID=d1-cli-001"
C=$(printf %s "getMeetingInfo${Q}${SECRET}" | sha256sum | cut -d" " -f1)
curl -s "${BASE}/getMeetingInfo?${Q}&checksum=${C}"
实测回显（完整）：
<response>
<returncode>SUCCESS</returncode>
<meetingName>D1 CLI Demo</meetingName>
<meetingID>d1-cli-001</meetingID>
<internalMeetingID>c374f296a21397107c0ba64db6665e3217824891-1793067386352</internalMeetingID>
<createTime>1793067386352</createTime>
<createDate>Tue Oct 27 02:16:26 UTC 2026</createDate>
<voiceBridge>20603</voiceBridge>
<dialNumber>613-555-1234</dialNumber>
<attendeePW>q1w2e3r4Att</attendeePW>
<moderatorPW>q1w2e3r4Mod</moderatorPW>
<running>false</running>
<duration>0</duration>
<hasUserJoined>false</hasUserJoined>
<recording>false</recording>
<hasBeenForciblyEnded>false</hasBeenForciblyEnded>
<startTime>1793067386371</startTime>
<endTime>0</endTime>
<participantCount>0</participantCount>
<listenerCount>0</listenerCount>
<voiceParticipantCount>0</voiceParticipantCount>
<videoCount>0</videoCount>
<maxUsers>50</maxUsers>
<moderatorCount>0</moderatorCount>
<attendees>
</attendees>
<metadata>
</metadata>
<isBreakout>false</isBreakout>
</response>
maxUsers=50 即 7.3 节所述服务器默认值；participantCount / attendees 是确认入会人数的观测点。
7.6 end：结束会议
Q="meetingID=d1-cli-001&password=q1w2e3r4Mod"
C=$(printf %s "end${Q}${SECRET}" | sha256sum | cut -d" " -f1)
curl -s "${BASE}/end?${Q}&checksum=${C}"
实测回显（完整）：
<response>
<returncode>SUCCESS</returncode>
<messageKey>sentEndMeetingRequest</messageKey>
<message>A request to end the meeting was sent. Please wait a few seconds, and then use the getMeetingInfo or isMeetingRunning API calls to verify that it was ended.</message>
</response>
end 是「异步请求」语义——回显明确提示等几秒后再用 getMeetingInfo 验证。实测在结束数分钟后复查 getMeetings，会议已从列表消失（回到 7.2 节的 noMeetings 形态）。
7.7 错误分支实测
分支一：checksum 错误。 故意传错误签名：
curl -s "${BASE}/getMeetings?checksum=0000000000000000000000000000000000000000000000000000000000000000"
实测回显：
<response>
<returncode>FAILED</returncode>
<messageKey>checksumError</messageKey>
<message>Checksums do not match</message>
</response>
分支二：会议不存在。 查询一个未创建的 meetingID：
Q="meetingID=no-such-meeting"
C=$(printf %s "getMeetingInfo${Q}${SECRET}" | sha256sum | cut -d" " -f1)
curl -s "${BASE}/getMeetingInfo?${Q}&checksum=${C}"
实测回显：
<response>
<returncode>FAILED</returncode>
<messageKey>notFound</messageKey>
<message>A meeting with that ID does not exist</message>
</response>
两个分支的 messageKey（checksumError / notFound）是脚本化调用时判别失败原因的稳定依据。
八、日志查看
8.1 日志目录结构
ls /var/log/bigbluebutton/
实测回显：
bbb-web.log
html5
presentation
顶层为 bbb-web（API 层）日志与两个子目录（html5/ 客户端侧、presentation/ 录制处理侧）。5.4 节 bbb-record --check 警告缺失的 bbb-rap-worker.log、sanity.log 等都归属 presentation/ 处理流水线——本环境未跑过录制处理，故尚未生成。
8.2 bbb-web 日志
ls -lh /var/log/bigbluebutton/bbb-web.log
实测回显：
-rw-r--r-- 1 bigbluebutton bigbluebutton 101K Oct 27 01:53 /var/log/bigbluebutton/bbb-web.log
tail -n 3 /var/log/bigbluebutton/bbb-web.log
实测回显（输出节选）：
2026-10-27T01:51:42.414Z INFO o.bigbluebutton.api.MeetingService - --analytics-- data={"logCode":"update_activity_json","name":"D1 命令演示会议","description":"Updating activities json.","meetingId":"c379741dbcd4249c8530fad1c3c34abd9587a365-1793065597381","externalMeetingId":"d1-demo-001"}
2026-10-27T01:51:42.414Z DEBUG o.b.api.LearningDashboardService - Learning Dashboard (/var/bigbluebutton/learning-dashboard/c379741dbcd4249c8530fad1c3c34abd9587a365-1793065597381/khydan5ioygq/learning_dashboard_data.json) updated for meeting c379741dbcd4249c8530fad1c3c34abd9587a365-1793065597381.
2026-10-27T01:53:42.413Z INFO o.b.api.LearningDashboardService - Learning Dashboard files removed for meeting c379741dbcd4249c8530fad1c3c34abd9587a365-1793065597381.
bbb-web 日志含 API 请求处理与会议事件（含外部会议 ID、学习面板数据更新/清理等），排障时可按时间戳与 logCode 定位。官方还提供 bbb-conf --debug（扫描日志中的错误）与 bbb-conf --zip（打包日志用于报告问题），见参考链接 1。
九、注意事项
--restart/--start后必须复查：4.5 节实测表明拉起阶段可能只到达 target 而未拉起服务单元，标准动作序列是「restart →bbb-conf --status→ 逐个systemctl start补齐 → API 探活」；- 单服务重启 ≠ 应用就绪：Java 类服务（bbb-web 等）进程 active 后需数秒到十余秒才完成应用初始化，验证以
systemctl is-active+ API 探活双重确认； - API 调用顺序：先 create 后 join；end 为异步请求，需延时后复查；
meetingID由调用方保证唯一（重复 create 返回duplicateWarning）； - checksum 口径：统一
sha256(action + queryString + securitySalt)， queryString 按发送顺序拼接且不含 checksum 自身；换接口/换参数顺序都要重算； - 共享密钥保管：
--secret的输出含完整密钥与 API-Mate 链接，不要截图/粘贴到公开渠道；更换密钥（官方--setsecret）后所有调用方同步更新； - 录制边界：无真实浏览器媒体流时只有事件归档、无回放产物（5.2/5.4 节实测佐证），验收录制功能需真实入会并开启录制。
十、常见问题（FAQ）
Q1：bbb-conf --restart（或 --start）后部分服务一直是 inactive？
先 bbb-conf --status 确认缺失组件清单，再按 4.5 节定位（bash -x 观察 --start 实际执行的是 systemctl restart bigbluebutton.target；systemctl cat bigbluebutton.target 查看其 Requires 列表），然后对 inactive 组件逐个 systemctl start 并用 is-active 验证，最后 API 探活收尾。
Q2：API 调用返回 502 Bad Gateway（HTML 而非 XML）？
nginx 正常但后端 bbb-web 未运行（4.5 节实测同款现象）。systemctl is-active bbb-web 确认后执行 systemctl start bbb-web，等十余秒再探活。
Q3：API 返回 checksumError，密钥明明没改过？
核对三点：密钥是否与 bbb-conf --secret 输出一致（以覆盖文件 securitySalt 为准）；拼接顺序是否为 action + queryString + salt（不是 salt 在中间）；queryString 是否按发送顺序拼接且未把 checksum 自身算进去（7.1/7.7 节）。
Q4：bbb-record --check 报一堆日志文件缺失，要紧吗？ 若服务器从未跑过录制处理（无真实入会与录制动作），这些流水线日志尚未生成，属预期（5.4 节实测）。执行过真实录制后复查，相应警告会消失；若仍缺失再排查流水线服务状态。
Q5：bbb-record 的命令该用哪个会议 ID？
录制类子命令（--rebuild/--delete 等）用内部会议 ID（--list 第一列，40 位哈希-毫秒时间戳形态）；只有 API 层的 create/join/end 用调用方自定义的 meetingID。两者可用 --tointernal / --toexternal 互查。
十一、参考链接
- 官方文档 bbb-conf 工具页（含 --setip/--setsecret/--debug/--zip 等选项说明）：https://docs.bigbluebutton.org/administration/bbb-conf/
- 官方文档 API Reference（各接口参数与 checksum 约定）：https://docs.bigbluebutton.org/development/api/
- 官方文档总览：https://docs.bigbluebutton.org
- 本专栏配套篇目：《BigBlueButton 4.0.0 介绍与选型指南》、《BigBlueButton 3.0.39 Docker Compose 部署指南》