MiroTalk SFU 2.6.88 Docker Compose 部署指南

MiroTalk SFU 2.6.88 官方镜像 Docker Compose 部署：三文件配置、端口映射、项目名实测坑、升级运维与防火墙放行，全部命令带真实回显。

MiroTalk SFUWebRTC视频会议MiroTalk2026/10/26

MiroTalk SFU 2.6.88 Docker Compose 部署指南

本文演示用官方标准镜像 mirotalk/sfu 通过 Docker Compose 部署 MiroTalk SFU 2.6.88 系：镜像内已包含编译好的 mediasoup worker 与全部依赖，无需本地编译，全程约 5 分钟。所有命令与回显均在实际环境（Debian 12 内核、x86_64、6 核 18G）执行实测。

版本提示（实测发现）：master 源码 package.json 当前为 2.6.88（2026-10-26 实查），而 Docker Hub latest 镜像启动日志自报 2.6.87——官方镜像构建跟随 master 有滞后，两者仅相差一个补丁号。追新功能用源码部署（见上篇），追稳定复现用镜像并锁定 tag。

一、前置条件

安装 Docker Engine 与 Compose 插件（Debian 12 官方仓库源）：

curl -fsSL https://get.docker.com | sh
docker compose version

实测回显：

Docker Compose version v2.39.4

规划三个要素：

要素本文取值说明
部署目录/opt/mirotalksfu-deploy存放三个配置文件
服务端口8146（映射容器 3010）宿主机 HTTPS 入口
媒体端口段40000-40100 TCP+UDP与默认 SFU_MIN_PORT/SFU_MAX_PORT 一致

二、准备三个配置文件

mkdir -p /opt/mirotalksfu-deploy && cd /opt/mirotalksfu-deploy
curl -fsSL https://raw.githubusercontent.com/miroslavpejic85/mirotalksfu/master/app/src/config.template.js -o config.js
curl -fsSL https://raw.githubusercontent.com/miroslavpejic85/mirotalksfu/master/.env.template -o .env

.env 改三处（生产必做）：

sed -i "s|^JWT_SECRET=.*|JWT_SECRET=$(openssl rand -hex 32)|" .env
sed -i "s|^API_KEY_SECRET=.*|API_KEY_SECRET=$(openssl rand -hex 24)|" .env
sed -i "s|^NODE_ENV=development|NODE_ENV=production|" .env
  • JWT_SECRET：入会令牌签名密钥，为空服务器拒绝启动
  • API_KEY_SECRET：REST API 鉴权密钥，默认值会触发启动警告
  • NODE_ENV=production：切换生产日志格式

config.js 首次部署保持模板原样即可，所有敏感项都在 .env 覆盖。

三、docker-compose.yml

官方模板（docker-compose.template.yml）可直接改造，实测生效版本如下：

services:
    mirotalksfu:
        image: mirotalk/sfu:latest
        container_name: mirotalksfu
        hostname: mirotalksfu
        user: '1000:1000'
        restart: unless-stopped
        ports:
            - '8146:3010/tcp'
            - '40000-40100:40000-40100/tcp'
            - '40000-40100:40000-40100/udp'
        volumes:
            - ./config.js:/src/app/src/config.js:ro
            - ./.env:/src/.env:ro
        networks:
            - mirotalksfu-net

networks:
    mirotalksfu-net:
        external: true

关键点逐条说明：

  • user: '1000:1000'：官方镜像默认以非 root 的 node 用户运行，挂载进来的 config.js 与 .env 需对该 uid 可读（默认 644 即可）
  • ports 三行缺一不可：3010/tcp 承载信令与网页；40000-40100 的 tcp+udp 都要映射，mediasoup 的 ICE/媒体流走 UDP，但部分回退路径走 TCP
  • volumes 两个 :ro 挂载：配置与代码分离，升级镜像时配置零改动；如需启用服务端录制，追加 - ./app/rec:/src/app/rec（同时 .env 中 RECORDING_ENABLED=true）
  • networks 外部网络：先创建专属网络再启动（下节演示），便于与其他服务同网互通

创建外部网络（指定网段便于主机防火墙按网段放行）：

docker network create --subnet=10.89.60.0/24 mirotalksfu-net

实测回显：

26f0ef1e538023c4f25221c2fa5e757dd2c7c8e4284a2366b4a232c7c631433f

四、启动与验证

项目名坑（实测踩中）：Compose 项目名不允许出现点号。docker compose -p mirotalksfu-2.6.88-stack up -d 会直接报错：

invalid project name "mirotalksfu-2.6.88-stack": must consist only of lowercase alphanumeric characters, hyphens, and underscores as well as start with a letter or number

版本号里的 . 要改写成连字符，即 -p mirotalksfu-2-6-88-stack：

docker compose -p mirotalksfu-2-6-88-stack up -d

实测回显：

 Container mirotalksfu Created
 Container mirotalksfu Starting
 Container mirotalksfu Started

查看状态与启动日志：

docker compose -p mirotalksfu-2-6-88-stack ps --format '{{.Name}} {{.Status}}'

mirotalksfu Up 16 seconds

docker logs mirotalksfu 2>&1 | grep -aE 'WORKERS'

[10/26/2026, 07:40:40:121] [Server] WORKERS: 6

日志中 versions 段自报版本（注意镜像滞后现象）：

  versions: {
    app: '2.6.87',
    node: '24.22.1',
    server_version: '3.31.0',
    client_version: '3.25.3'
  }

HTTP 验证与网络归属确认：

curl -sk https://127.0.0.1:8146/ -o /dev/null -w "HTTP %{http_code}\n"
docker inspect mirotalksfu --format '{{range .NetworkSettings.Networks}}{{.IPAddress}} {{end}}'

实测回显：

HTTP 200
10.89.60.2

浏览器访问 https://<宿主机IP>:8146 即为入会首页。

五、防火墙放行

ufw allow 8146/tcp
ufw allow 40000:40100/udp
ufw allow 40000:40100/tcp

云服务器还需在安全组同步放行。NAT/公网 IP 场景记得设置 .env 的 SFU_ANNOUNCED_IP=服务器公网IP 后重启容器，否则远端用户无法建立媒体连接。

六、日常运维

查看实时日志：

docker logs -f mirotalksfu

升级版本（配置文件外挂，升级零迁移）：

docker compose -p mirotalksfu-2-6-88-stack pull
docker compose -p mirotalksfu-2-6-88-stack up -d

修改配置后生效：

# 编辑 .env 或 config.js 后
docker compose -p mirotalksfu-2-6-88-stack restart

彻底移除：

docker compose -p mirotalksfu-2-6-88-stack down   # 不加 -v，本服务无数据卷

七、常见问题速查

现象原因与处置
invalid project name ...Compose 项目名禁用点号，版本号 2.6.88 写成 2-6-88
容器反复重启，日志报 JWT_SECRET.env 未生成 JWT_SECRET，openssl rand -hex 32 后 restart
页面可开但媒体不通40000-40100/udp 未放行，或 NAT 后未设 SFU_ANNOUNCED_IP
挂载文件权限错误镜像以 uid 1000 运行，chmod 644 config.js .env 确保可读
镜像版本号与官方仓不一致latest 镜像构建滞后 master 一个小版本（实测 2.6.87 vs 2.6.88），属正常现象
端口段映射失败 port is already allocated宿主机 40000-40100 被其他服务占用，收窄 .env 的 SFU_MIN_PORT/SFU_MAX_PORT 并同步改 compose

至此镜像化部署完成。下一篇《MiroTalk SFU 2.6.88 配置参数详解》拆解 .env 全部 12 组配置与 config.template.js 的默认值逻辑。