plugNmeet 2.5.3 配置参数详解

逐节讲清 plugNmeet 2.5.3 主配置 config.yaml：client 鉴权、LiveKit/NATS/Redis/MariaDB 对接、上传录制与 AI insights 全参数表，并实测验证修改配置重启生效链路。

plugNmeetWebRTC视频会议2026/10/26

plugNmeet 2.5.3 配置参数详解

目标：逐节讲清 plugNmeet 2.5.3 主配置文件 config.yaml 的每个配置节——参数含义、默认值、取值约束与生产建议，并实测验证「修改配置 → 重启服务 → 参数生效」的完整链路。

一、环境信息

  • plugNmeet 服务端 v2.5.3（官方镜像与源码双查证），配置文件以官方样例 config.yaml（tag v2.5.3）为基准
  • 依赖组件：LiveKit 1.13.x、NATS 2.15、Redis 8、MariaDB 12.3
  • 实测部署形态：Linux 宿主机上的 systemd 服务与编排部署各一套，参数行为一致（配置解析在服务端二进制内，与部署形态无关）
  • 实测时间：2026-10-26

🔗 配置文件的获取与放置位置见 《Ubuntu 24.04 安装 plugNmeet 2.5.3 指南》（裸机）与 《plugNmeet 2.5.3 Docker Compose 部署指南》（编排）；组件背景见 《plugNmeet 2.5.3 介绍与选型指南》。

二、加载方式与生效规则

  • 启动时用 --config 指定：plugnmeet-server --config /opt/plugNmeet/config.yaml，容器部署则挂载进 /app/config.yaml。
  • YAML 解析失败或必填项缺失时服务直接拒绝启动，日志给出首个错误位置；不会「带病降级运行」。
  • 修改配置后必须重启服务进程才生效（无热加载）。实测验证：
$ grep -A2 'prometheus:' config.yaml | head -3   # enable: true 时
  prometheus:
    enable: true
    metrics_path: "/metrics"
$ curl -s -o /dev/null -w 'metrics HTTP %{http_code}\n' http://127.0.0.1:8145/metrics
metrics HTTP 200
# 把 enable 改为 false 并重启服务
$ curl -s -o /dev/null -w 'metrics after disable: HTTP %{http_code}\n' http://127.0.0.1:8145/metrics
metrics after disable: HTTP 404
# 恢复 enable: true 并重启
$ curl -s -o /dev/null -w 'metrics restored: HTTP %{http_code}\n' http://127.0.0.1:8145/metrics
metrics restored: HTTP 200
  • 配置中的路径全部相对「服务进程工作目录」（systemd 看 WorkingDirectory，容器默认 /app）；本文示例统一用绝对路径或容器内约定路径，避免歧义。

三、配置节总览

节作用关键参数
clientWeb/API 监听与鉴权、Webhook、Prometheus、代理、版权port、api_key、secret
room_default_settings新建房间的默认限制max_duration、max_participants
log_settings日志文件与轮转log_file、log_level
livekit_info对接 LiveKit SFUhost、api_key、secret
livekit_sip_info电话语音网关（SIP）enabled、trunk_name
redis_infoRedis 连接与键 TTLhost、default_ttl
database_infoMySQL/MariaDB 连接host、db、prefix
nats_infoNATS 总线、WebSocket、KV、频道nkey、nats_ws_urls、subjects
upload_file_settings上传文件限制max_size、allowed_types
recorder_info录制文件与回收站recording_files_path、ping_timeout
analytics_settings会后分析文件enabled
artifacts_settingsAI 摘要等产物存储storage_path、备份保留
insightsAI 转写/摘要/语音合成供应商providers
hooks文件外部存储钩子（可选）upload_hook、delete_hook

四、client 节

client:
  port: 8080
  debug: false
  path: "./client/dist"
  api_key: PLUG_N_MEET_API_KEY
  secret: PLUG_N_MEET_SECRET
  token_validity: 10m
  webhook_conf:
    enable: true
    url: ""
    enable_for_per_meeting: true
  prometheus:
    enable: false
    metrics_path: "/metrics"
    username: ""
    password: ""
  proxy_conf:
    enabled: false
    proxy_header: "X-Forwarded-For"
    trusted_proxy_ips: [ "127.0.0.0/8", "10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", "::1/128" ]
  copyright_conf:
    allow_override: false
    text: 'Powered by <a href="https://www.plugnmeet.org" target="_blank">plugNmeet</a>'
  bbb_join_host: "https://PLUG_N_MEET_SERVER_DOMAIN"
参数类型/默认说明与建议
portint，8080Web 与 API 共用监听端口；生产经反代 443 转发到这里
debugbool，false排障期临时打开；会输出更多请求日志
pathstring，./client/dist客户端静态资源目录；官方镜像已内置，自备客户端时指向含 index.html 的目录
api_keystring，必填管理凭证之一：登录页输入、REST API API-KEY 头；建议 openssl rand -hex 32 生成
secretstring，必填管理凭证之二：REST API HMAC-SHA256 签名密钥；泄露=任何人可建房/拉会
token_validityduration，10m客户端 JWT 有效期；到前自动续期，无需调大
webhook_conf.enable/urlbool/string全局事件回调地址；enable_for_per_meeting: true 允许建房间时单 rooms 指定
prometheus.*—enable: true 后 metrics_path 开放 Prometheus 指标（实测 /metrics 200 返回 Go 运行时+业务指标）；username/password 非空则启用 Basic Auth
proxy_conf.enabledbool，false反代后置 true；proxy_header 常用 X-Forwarded-For，trusted_proxy_ips 只填真实反代地址段（防伪造头）
copyright_conf—底部版权；allow_override: false 时 API 不可改文案；text 仅支持 b/i/em/strong/a 五种标签
bbb_join_hoststringBBB 兼容模式下拼 join URL 的对外域名；反代/负载均衡后填公网地址

五、room_default_settings 节

room_default_settings:
  max_duration: 0
  max_participants: 0
  max_num_breakout_rooms: 6
  max_preloaded_wb_file_size: 5mb
参数默认说明
max_duration0新房间默认时长（分钟），0=不限；房间元数据可单独覆盖
max_participants0单房间人数上限，0=不限（受 SFU 带宽约束，实际几十路小会议单机即可）
max_num_breakout_rooms6分组讨论数上限；最大 16，API 请求超出会被拒
max_preloaded_wb_file_size5mb白板预载文件大小上限（支持 kb/mb 单位写法）

六、log_settings 节

log_settings:
  log_file: "./log/plugNmeet.log"
  maxsize: 20
  maxbackups: 4
  maxage: 2
  log_level: "warn"
参数默认说明
log_file./log/plugNmeet.log日志路径，目录需存在且进程可写
maxsize / maxbackups / maxage20 / 4 / 2lumberjack 轮转：单文件 MB、保留份数、保留天数
log_levelwarndebug/info/warn/error/fatal/panic；生产建议 info（本文实测用 info），排障开 debug

七、livekit_info 与 livekit_sip_info 节

livekit_info:
  host: "https://PLUG_N_MEET_SERVER_DOMAIN/livekit"
  api_key: LIVEKIT_API_KEY
  secret: LIVEKIT_SECRET
livekit_sip_info:
  enabled: false
  trunk_name: "pnm-inbound-trunk"
  phone_numbers: ["+12674777275","+441883778715"]
  • host：plugNmeet 调 LiveKit HTTP API 的地址。同机部署填 http://127.0.0.1:7880（LiveKit 默认端口；本文实验改 8146）；反代部署填对外域名路径。
  • api_key/secret：必须与 LiveKit 配置 keys: 里的键值完全一致（实测口径：两边一致才能建房/发 token）。
  • livekit_sip_info：电话进会（SIP 网关）功能，默认关闭；需要额外部署 livekit-sip 组件并配置 phone_numbers 入局白名单与可选 media_encryption（0 不加密/1 协商/2 强制）。

八、redis_info 节

redis_info:
  host: localhost:6379
  username: ""
  password: ""
  db: 0
  default_ttl: 24h
  • 存房间实时状态（成员、聊天游标等），键带 TTL 自动过期——default_ttl 即键的默认存活期，24h 适配常规会议时长；超长会议调大。
  • 支持 Sentinel：去掉 host，改配 sentinel_master_name + sentinel_addresses（凭据不同再加 sentinel_username/password）；use_tls: true 走 TLS。

九、database_info 节

database_info:
  driver_name: mysql
  host: localhost
  port: 3306
  username: plugnmeet
  password: DB_PLUGNMEET_PASSWORD
  db: plugnmeet
  prefix: pnm_
  charset: "utf8mb4"
  loc: "UTC"
  conn_max_lifetime: 4m
  max_open_conns: 10
参数说明
driver_name目前仅 mysql（MariaDB 同协议兼容，官方脚本装的就是 MariaDB 12.3）
prefix表名前缀，默认 pnm_；实测四张表：pnm_room_info、pnm_recordings、pnm_room_analytics、pnm_room_artifacts
charset / locutf8mb4 + UTC 基本不用动（go-sql-driver 约定）
conn_max_lifetime / max_open_conns连接池参数；并发大时调高 max_open_conns（如 50）
replicas可选只读副本列表，读多写少场景分流

首次建库用源码仓 sql_dump/install.sql 导入，业务账号最小权限：plugnmeet.* 全权即可。

十、nats_info 节（v2.x 核心改动）

nats_info:
  nats_urls:
    - "nats://localhost:4222"
  nats_ws_urls:
    - "https://PLUG_N_MEET_SERVER_DOMAIN/ws"
  account: NATS_ACCOUNT
  nkey: NATS_NKEY_PRIVATE_KEY
  auth_callout_issuer_private: NATS_CALLOUT_PRIVATE_KEY
  auth_callout_xkey_private: NATS_CALLOUT_XKEY_PRIVATE_KEY
  num_replicas: 1
  room_stream_name: "pnm-room-stream"
  default_ttl: 24h
  subjects:
    system_api_worker: "sysApiWorker"
    system_js_worker: "sysJsWorker"
    system_core_worker: "sysCoreWorker"
    system_public: "sysPublic"
    system_private: "sysPrivate"
    chat: "chat"
    whiteboard: "whiteboard"
    data_channel: "dataChannel"
  recorder:
    recorder_channel: "recorderChannel"
    recorder_info_kv: "pnm-recorderInfo"
    transcoding_jobs_subject: "pnm-RecorderTranscoderJobs"
  • v2.x 起客户端与会务事件全走 NATS：nats_urls 是服务端连总线，nats_ws_urls 是浏览器直连的 WebSocket 入口（生产必须 wss 反代，客户端连不上则无法入会）。
  • account：NATS 侧账号名（如 PNM），需与 nats-server.conf 一致。
  • 三个私钥参数：nkey（SU 种子）、auth_callout_issuer_private（SA 种子）、auth_callout_xkey_private（SX 种子）——私钥种子只出现在这里；对应 U/A/X 公钥写进 nats-server.conf（实测填反直接重启循环，见部署指南篇）。
  • num_replicas：JetStream 副本数，单机 1；集群 3/5。
  • subjects：各业务频道名；改动牵连多端，保持默认即可。recorder.* 是录制组件的频道与 KV。

十一、upload_file_settings 节

upload_file_settings:
  path: "./upload"
  max_size: 50
  max_size_whiteboard_file: 30
  keep_forever: false
  allowed_types: ["jpg","png","jpeg","svg","pdf","docx","txt","xlsx","pptx","zip","mp4","webm","mp3"]
  • max_size（聊天上传，MB）/ max_size_whiteboard_file（白板上传，MB）分别限流；allowed_types 按扩展名白名单。
  • keep_forever: false 时会后清理上传文件；需要文件留存（如教学课件）改 true。
  • 多副本部署 path 必须是共享存储（NFS 等），否则 A 节点上传 B 节点取不到。

十二、recorder_info 节

recorder_info:
  recording_files_path: "./recording_files"
  token_validity: 30m
  ping_timeout: 8s
  enable_del_recording_backup: true
  del_recording_backup_path: "./recording_files/del_backup"
  del_recording_backup_duration: 72h
  • recording_files_path 必须与录制组件的 copy_to_dir 一致（录制器生成后落到这里，服务端负责索引与下载）。
  • ping_timeout（8s）内收不到录制器心跳即判离线；token_validity 是下载链接的有效期。
  • 删除保护：enable_del_recording_backup: true 时删除动作只移到 del_recording_backup_path 回收站，保留 del_recording_backup_duration（默认 72h），误删可捞回。

十三、analytics_settings 与 artifacts_settings 节

analytics_settings:
  enabled: true
artifacts_settings:
  storage_path: "./artifacts"
  token_validity: 10m
  enable_del_artifacts_backup: true
  del_artifacts_backup_path: "./artifacts/trash"
  del_artifacts_backup_duration: 72h
  • analytics_settings.enabled: true 后每次会议结束生成分析文件（入会/离会时间、功能使用、发言时长），落 pnm_room_analytics 与文件系统。
  • artifacts_settings 管 AI 产物（摘要、转写文本）：目录结构 {storage_path}/{service_type}/{room_id}/；回收站机制与录制一致。

十四、insights 节（AI 能力）

insights:
  enabled: true
  providers:
    azure:
      - id: "eastus_standard"
        credentials:
          api_key: "YOUR_AZURE_KEY_1"
          region: "eastus"
    google:
      - id: "default-gemini-creds"
        credentials:
          api_key: "YOUR_GOOGLE_KEY"
  features:
    speech-synthesis:
      provider: "azure"
      id: "eastus_standard"
      options:
        voice-en: "en-US-JennyNeural"
    ai_text_chat:
      provider: "google"
      id: "default-gemini-creds"
      options:
        chat_model: "gemini-2.5-pro"
        summarize_model: "gemini-2.0-flash"
        context_window: 5
    meeting_summarizing:
      provider: "google"
      id: "default-gemini-creds"
      options:
        summarize_model: "gemini-2.0-flash"
  • 结构分两层：providers 定义供应商账号池（azure 语音转写/合成、google Gemini 文本），features 把各能力绑定到具体账号与模型。
  • 每个 feature 可配 pricing（每百万字符/令牌单价）用于用量统计。
  • 不用 AI 功能时置 enabled: false 即可（本文实验即 false）；注意编译产物链接了 Azure Speech SDK 动态库，运行时库文件仍需在位（裸机编译见安装指南篇 5.2 节）。

十五、hooks 节（外部存储，可选）

hooks 允许用自定义脚本接管文件生命周期，接入 S3/GCS 等外部存储，默认整节注释：

钩子触发点
upload_hook会议文件上传后
download_hook文件下载前（可做签名/鉴权中转）
delete_hook文件删除时
resumable_upload_hook断点续传场景
room_end_hook会议结束

每个钩子支持脚本列表、pool_size 并发、hook_timeout、is_one_shot（执行一次）。省略本节=全部本地盘存储（recorder_info/artifacts_settings 的路径）。

十六、安全基线建议

  1. client.api_key/secret、database_info.password、LiveKit/NATS 全套密钥一律 openssl rand -hex 32 类强随机，禁止示例值上生产。
  2. config.yaml 含全部明文密钥：属主 600，备份与日志不落明文。
  3. MariaDB/Redis/NATS 仅监听回环或内网，不对公网暴露（编排部署端口绑 127.0.0.1，裸机用监听地址控制）。
  4. 生产公网部署前置反代终结 TLS：Web 443→8145、NATS wss /ws→8222、LiveKit 走官方 TURN/ICE 拓扑。

十七、常见问题

  1. 改了配置不生效：必须重启进程（systemd restart 或编排 restart）；实测 /metrics 开关即开即关（200↔404），可用作生效性探针。
  2. 启动即退，日志 invalid seed/Cannot unmarshal：YAML 语法或密钥对位错误；nkey 三参数须 SU/SA/SX 种子（公钥写 NATS 配置），缩进用空格不用 Tab。
  3. 客户端进不了会议：nats_ws_urls 不可达（浏览器侧 WebSocket）；反代需支持并放行该路径的 Upgrade。
  4. 文件传不上去：max_size 超限、扩展名不在 allowed_types、或 path 目录不可写。
  5. 录制文件没出现：recorder_info.recording_files_path 与录制组件 copy_to_dir 不一致，或录制器未连上（ping_timeout 心跳超时日志可见）。

十八、参考链接