MiroTalk SFU 2.6.88 配置参数详解

MiroTalk SFU 2.6.88 的配置由两个文件承载：app/src/config.template.js（复制为 config.js，承担全部默认值与复杂逻辑，可提交版本库）与 .env（仅存敏感项与环境差异项，键值对格式）。本文基于官方 .env.template（2.6.88，共 353 个注入变量）逐组拆解，并附实测验证结论。

一、配置体系与优先级

config.template.js 第一行就引入 dotenv：

const dotenv = require('dotenv').config();

此后所有取值遵循统一模式 process.env.XXX || 默认值——.env 中出现过的键永远覆盖 config.js 的默认值。实测启动日志印证注入规模：

◇ injected env (353) from .env

两层分工的官方注释原话：config.js 放"全部默认值、复杂逻辑与校验"，.env 放"密钥与敏感数据（绝不提交）、环境差异项"。

一个实测发现的显示陷阱：启动日志 server config 中的 server_listen: 'https://localhost:3010' 是 config.js 拼装的展示字段，实际监听端口以 .env 的 SERVER_LISTEN_PORT 为准（实测 .env 改为 8145 后，该展示字段仍显示 3010，但 ss -ltn 实际监听 8145）。排查端口问题时以 ss -ltn 为准。

config.template.js 导出对象分十大区块（行号为 2.6.88 实查）：

日常运维只动 .env；config.js 仅在需要改逻辑（如自定义校验）时修改。

二、核心与服务器配置（组 1-3）

实测验证（6 核机器）：

• SFU_NUM_WORKERS=2 写入 .env 后重启，日志输出 [Server] WORKERS: 2（config.js 取值逻辑为 Math.min(设置值, CPU核数)，设置超过核数会被钳制）
• SERVER_LISTEN_PORT=8145 生效后 ss -ltn 出现 LISTEN 0 511 *:8145 *:*，curl -sk https://127.0.0.1:8145/ 返回 HTTP 200

三、媒体配置：录制与 RTMP（组 4）

录制（默认全关）：

RTMP 推流（默认关，子能力默认开）：

开启录制/RTMP 的前提是服务器装有 FFmpeg（RTMP_FFMPEG_PATH 留空自动探测）。

四、安全与认证（组 5，重点）

JWT（必配）：

• JWT_SECRET：为空服务器拒绝启动，实测报错原文：

  [Server] Invalid JWT configuration 'JWT_SECRET is not set. Set a strong secret (e.g. "openssl rand -hex 32") in JWT_SECRET.'
  

• JWT_EXPIRATION：默认 1h，入会令牌有效期

Host 保护（内置静态账号）：

• HOST_PROTECTED：开启后普通用户进房前需等待主持人
• HOST_USER_AUTH：开启登录页
• HOST_USERS：账号表，格式 username:password:displayName:allowedRooms，多账号用 | 分隔，也接受 JSON 数组（密码含 :/|/, 时必须用 JSON）
• HOST_MAX_LOGIN_ATTEMPTS / HOST_MIN_LOGIN_BLOCK_TIME：5 次 / 15 分钟，防爆破

模板注释明确声明：服务器拒绝启动使用公开已知弱口令（admin/admin、guest/guest、username/password 之类"用户名=密码"组合）。实测确认 HOST_USERS="admin:q1w2e3r4:Administrator:*" 可正常通过校验，启动日志解析出：

username: 'admin',
displayname: 'Administrator',

密码 q1w2e3r4 是键盘序列型弱口令，仅建议用于内网测试环境；生产环境请换长随机串。

OIDC 单点登录：OIDC_ENABLED 总开关，配 OIDC_ISSUER/OIDC_CLIENT_ID/OIDC_CLIENT_SECRET；OIDC_BASE_URL_DYNAMIC=true 时按请求 Host 动态生成回调，但必须配 OIDC_ALLOWED_DYNAMIC_BASE_URLS 白名单（否则有 Host 头注入风险）。

展示型限流：HOST_USERS_FROM_DB=false 时以下四项无效——USERS_API_ENDPOINT（默认 http://localhost:9000/api/v1/user/isAuth）等对接外部 MiroTalk Web 用户系统的端点。

主持人规则：PRESENTERS 匹配的是登录用户名或 OIDC 邮箱，未开认证时不生效；PRESENTER_JOIN_FIRST=true 时第一个进房者成为主持人。

五、REST API 配置（组 6）

注意不对称设计：/meetings（列出全部房间）默认关，/meeting（创建/删除单会）默认开——最小暴露面原则，按需开启。

六、第三方集成（组 7）

全部默认关闭，启用时逐项配置：

• AI 助手：CHATGPT_*（模型默认 gpt-6-luna，支持 reasoning 参数）、DEEP_SEEK_*（默认 deepseek-v4-flash）、WHISPER_*（转写，WHISPER_BASE_PATH 可指向自托管 OpenAI 兼容服务）
• 数字人：VIDEOAI_*（LiveAvatar/Anam 双供应商）
• 消息平台机器人：SLACK_*、MATTERMOST_*、DISCORD_*（斜杠命令默认名 /sfu）
• 邮件：EMAIL_ALERTS_ENABLED/EMAIL_NOTIFICATIONS + EMAIL_HOST/PORT/USERNAME/PASSWORD/FROM/SEND_TO
• 隧道：NGROK_ENABLED（本地调试穿透）
• 监控：SENTRY_ENABLED（错误上报）、STATS_ENABLED（使用统计，注意默认上报到官方 stats.mirotalk.com，数据敏感环境关闭）
• Webhook：WEBHOOK_ENABLED + WEBHOOK_URL（会议事件外推）
• 对象存储：S3_ENABLED + S3_ACCESS_KEY_ID/S3_SECRET_ACCESS_KEY/S3_BUCKET/S3_ENDPOINT/S3_FORCE_PATH_STYLE（MinIO 等 path-style 服务需设 true）

七、UI 与功能开关（组 8-10，速查）

组 8（UI 定制）与组 9（约 120 个 SHOW_*/ENABLE_* 按钮/面板开关）是体量最大的两块，命名即语义，三个高频项：

• APP_NAME/APP_TITLE：白标改名的第一入口
• SHOW_ACTIVE_ROOMS + ACTIVE_ROOMS_RATE_LIMIT_*：首页公开房间列表（默认关，开启时限流默认 60 次/分钟）
• CREATE_ROOM_RATE_LIMIT_WINDOW_MINUTES/CREATE_ROOM_RATE_LIMIT_MAX（1 分钟/10 次）：防房间号枚举

组 10（功能特性）：

• ROOM_MAX_PARTICIPANTS（默认 1000）/ROOM_LOBBY（大厅，默认关）：全局仲裁
• SURVEY_*/REDIRECT_*：会后问卷/跳转
• REMOTE_CONTROL_*：RustDesk 远控握手，自托管 RustDesk 时配 REMOTE_CONTROL_SERVER_HOST
• CUSTOM_NOISE_SUPPRESSION_*：降噪默认态

八、mediasoup 配置（组 12）

仅三项，一般不动：

MEDIASOUP_ROUTER_AUDIO_LEVEL_OBSERVER_ENABLED=true
MEDIASOUP_ROUTER_ACTIVE_SPEAKER_OBSERVER_ENABLED=true
MEDIASOUP_LOG_LEVEL=error

SFU_MIN_PORT/SFU_MAX_PORT 是唯一需要与防火墙联动的媒体层参数：端口段收窄时（如 40000-40020），放行规则与端口段必须同步修改。

九、最小生产 .env 模板

在模板基础上，最小化生产改动的参考（其余保持默认）：

NODE_ENV=production
SERVER_LISTEN_PORT=3010
SFU_ANNOUNCED_IP=203.0.113.10        # 换成你的公网 IP；纯内网可留空
JWT_SECRET=<openssl rand -hex 32 生成>
API_KEY_SECRET=<openssl rand -hex 24 生成>
HOST_PROTECTED=true
HOST_USER_AUTH=true
HOST_USERS="alice:<强密码>:Alice:*"
TRUST_PROXY=false                     # 仅在 nginx/CDN 之后设 true
STATS_ENABLED=false                   # 数据敏感环境关闭官方统计上报
SHOW_SPONSORS=false                   # 白标时可一并关闭 SHOW_POWERED_BY 等

十、常见配置错误速查

下一篇《MiroTalk SFU 2.6.88 REST API 实战指南》对 6 个 API 端点逐一带真实请求与响应实测。