Jitsi Meet 保姆级部署教程：Docker Compose 一键私有化部署加密视频会议

本文所有命令与配置均照搬 Jitsi 官方仓库 jitsi/docker-jitsi-meet 的 env.example、docker-compose.yml、gen-passwords.sh 与官方 Handbook《Docker Guide》（jitsi.github.io/handbook），未作任何改动与发挥。信息核验日期：2026-11-01。

一、项目介绍

Jitsi 是一套开源项目集合，官方 README 对其定位是"让你轻松构建和部署安全的视频会议解决方案"。其中 Jitsi Meet 是一个完全加密、100% 开源的视频会议方案，官方强调它可以"全天、每天、免费使用，无需账号"。

jitsi/docker-jitsi-meet 这个仓库则提供了在 Docker 与 Docker Compose 上跑起一整套 Jitsi Meet 栈所需的全部工具。官方 README 明确：所有镜像发布在 GitHub Container Registry（GHCR，github.com/orgs/jitsi/packages），镜像标签分为 stable（最新稳定版）、stable-NNNN-X（某个稳定发行版）、unstable（最新开发版）、unstable-YYYY-MM-DD（每日构建）。项目持续活跃维护（核验日期 2026-11-01）。

二、功能拆解

按官方 README 与 Handbook，这套 Docker 栈由多个组件组成，核心能力如下：

组件 / 功能	说明
Web（jitsi/web）	基于 nginx 的前端 Web 界面，提供会议网页
Prosody（jitsi/prosody）	XMPP 服务器，负责信令与用户/房间管理
Jicofo（jitsi/jicofo）	会议焦点组件，控制会议创建、邀请与房间配置
JVB（jitsi/jvb，VideoBridge）	视频桥接，转发各参会者之间的媒体流
全加密	官方宣称 fully encrypted，端到端加密可选
无需账号	默认即可匿名入会，也可开启登录鉴权
Let's Encrypt	内置 ACME 自动申请 HTTPS 证书
Etherpad / Whiteboard	可选集成在线文档与白板协作
Kubernetes	官方另有 jitsi-contrib/jitsi-kubernetes 项目

三、官方/GitHub 链接

GitHub 仓库：https://github.com/jitsi/docker-jitsi-meet
官方 Handbook（Docker 部署手册）：https://jitsi.github.io/handbook/docs/devops-guide/devops-guide-docker
Jitsi 官网：https://jitsi.org/
GHCR 镜像：https://github.com/orgs/jitsi/packages
Kubernetes 部署：https://github.com/jitsi-contrib/jitsi-kubernetes

四、环境要求

官方 Handbook 明确本部署基于 Docker 与 Docker Compose，因此前置要求是已安装 Docker Engine 与 Docker Compose 插件（docker compose 命令可用）。

端口：默认 HTTP_PORT=8000（会跳转到 HTTPS）、HTTPS_PORT=8443；JVB 媒体端口默认 UDP 10000。
配置目录：官方 CONFIG=~/.jitsi-meet-cfg，所有配置与密钥都写在这里。
公网域名：PUBLIC_URL 为必填项（在 .env 中配置），且若使用非标准 HTTPS 端口，该端口必须出现在 PUBLIC_URL 中（env.example 注释原文）。
硬件：官方 env.example 提供 JICOFO_MAX_MEMORY=3072m、VIDEOBRIDGE_MAX_MEMORY=3072m 等 Java 组件内存上限配置；实际占用取决于并发路数与视频分辨率。

五、部署步骤

步骤 1：克隆官方仓库并进入

git clone https://github.com/jitsi/docker-jitsi-meet && cd docker-jitsi-meet

逐段解释：git clone 拉取仓库，里面带有官方维护的 docker-compose.yml、env.example、gen-passwords.sh；cd 进入目录，后续所有命令都在此执行。

预期输出参考： 正常克隆日志，最后回到命令行提示符。

步骤 2：复制环境变量模板

cp env.example .env

逐段解释：env.example 是官方给出的样例配置（仓库内共 270 余行注释），复制为 .env 后由 Compose 自动加载。

预期输出参考： 无输出，当前目录生成 .env 文件。

步骤 3：编辑 .env，设置必填项

nano .env

按官方 env.example 注释，至少需要设置/确认以下几项：

CONFIG=~/.jitsi-meet-cfg
HTTP_PORT=8000
HTTPS_PORT=8443
TZ=UTC
# 公网访问地址（必填）。用域名替换，非标准端口要写进 URL：
PUBLIC_URL=https://meet.example.com:8443

逐段解释：CONFIG 指定配置落盘目录；HTTP_PORT/HTTPS_PORT 是宿主暴露端口；TZ 时区；PUBLIC_URL 是浏览器访问会议时使用的对外地址，Jitsi 会据此生成邀请链接。env.example 明确提示："if you use a non-standard HTTPS port, it has to appear in the public URL"。

步骤 4：一键生成随机密钥（官方 gen-passwords.sh）

./gen-passwords.sh

逐段解释：官方脚本会用 openssl rand -hex 16 生成 6 组随机密码，并用 sed -i.bak 就地写回 .env 中的 JICOFO_AUTH_PASSWORD、JVB_AUTH_PASSWORD、JIGASI_XMPP_PASSWORD、JIBRI_RECORDER_PASSWORD、JIBRI_XMPP_PASSWORD、JIGASI_TRANSCRIBER_PASSWORD 六个占位项。执行前需确保系统有 openssl 与 sed。

预期输出参考： 命令成功、无标准输出；.env 中上述六项被替换为随机串，并生成 .env.bak 备份。

步骤 5：启动整套栈

docker compose up -d

逐段解释：docker compose up 依据 docker-compose.yml 创建并启动 web、prosody、jicofo、jvb 等服务；-d 后台运行。官方 compose 中镜像形如 ${JITSI_IMAGE_REPO:-ghcr.io/jitsi}/web:${JITSI_IMAGE_VERSION:-unstable}，默认拉取 ghcr.io/jitsi/*:unstable，可在 .env 用 JITSI_IMAGE_VERSION=stable 切到稳定版。

预期输出参考： 拉取镜像与创建容器的日志，形如 ✔ Container prosody ... Started、✔ Container web ... Started，最终回到提示符。

步骤 6：确认运行状态

docker compose ps

逐段解释：列出本 compose 项目所有容器状态，Up 即运行中。

六、配置参数详解

官方 env.example 中常用变量（默认值取自 env.example 注释）：

变量	默认 / 示例	说明
`CONFIG`	`~/.jitsi-meet-cfg`	所有配置落盘目录
`HTTP_PORT`	`8000`	暴露的 HTTP 端口（会重定向到 HTTPS）
`HTTPS_PORT`	`8443`	暴露的 HTTPS 端口
`TZ`	`UTC`	系统时区
`PUBLIC_URL`	（需填写）	Web 服务对外公网 URL，必填
`JVB_ADVERTISE_IPS`	（注释掉）	JVB 对外宣告的媒体 IP 列表，NAT/内网环境用
`JICOFO_MAX_MEMORY`	`3072m`	Jicofo 组件 JVM 内存上限
`VIDEOBRIDGE_MAX_MEMORY`	`3072m`	JVB 组件 JVM 内存上限
`ENABLE_LETSENCRYPT`	`1`（注释示例）	是否启用 Let's Encrypt 自动证书
`LETSENCRYPT_DOMAIN`	`meet.example.com`	申请证书的域名
`LETSENCRYPT_EMAIL`	`alice@atlanta.net`	ACME 账号邮箱（启用时必填）
`ETHERPAD_URL_BASE`	（注释掉）	集成 Etherpad 的内网地址
`WHITEBOARD_COLLAB_SERVER_PUBLIC_URL`	（注释掉）	白板后端对外地址
`ENABLE_TRACING`	（注释掉）	是否启用 OTLP 链路追踪

完整变量参考见 Handbook「Docker Guide」一节。启用公网 HTTPS 时，需将 ENABLE_LETSENCRYPT=1、LETSENCRYPT_DOMAIN、LETSENCRYPT_EMAIL 一并配置，并把域名 DNS 指向本服务器；测试时可用 LETSENCRYPT_USE_STAGING=1 避免触发正式限额。

七、启动与运维

启动 / 停止： docker compose up -d 启动；docker compose down 停止并移除容器。
查看日志： docker compose logs -f web、docker compose logs -f jvb 分别跟踪前端与媒体桥日志，Ctrl+C 退出跟踪。
切到稳定版： 在 .env 设置 JITSI_IMAGE_VERSION=stable 后 docker compose up -d（官方标签表：stable 指向最新稳定版）。
开机自启： 官方 compose 未专门声明 restart 策略；如需容器随 Docker 守护进程自启，可在 compose 服务中加 restart: unless-stopped（Docker 平台通用机制，非 Jitsi 官方文档内容）。
NAT / 内网部署： Handbook 专门有「Running behind NAT or on a LAN environment」一节，通过 JVB_ADVERTISE_IPS 配置 JVB 对外宣告的 IP:端口列表。
数据持久化： 官方 CONFIG 目录（默认 ~/.jitsi-meet-cfg）挂载进容器，配置、证书、密钥都持久化在宿主该目录。

八、实操验证

确保 PUBLIC_URL 域名解析到本机，且 HTTPS_PORT（默认 8443）已在防火墙放行，JVB 的 UDP 10000 端口也必须放行（否则媒体流不通、只能看到自己）。
浏览器访问 https://你的域名:8443，应看到 Jitsi Meet 的欢迎界面，标题栏显示房间名输入框。
直接输入一个房间名进入会议，首次使用浏览器会请求摄像头与麦克风权限，允许后即可看到本地画面。
在另一台设备（或手机）访问同一 URL、进入同一房间名，验证双方音视频互通；邀请链接形如 https://你的域名:8443/房间名#config.prejoinPageEnabled=false。

登录与安全（重要）

官方默认登录状态：默认匿名、无账号。 Jitsi Meet 设计上"无需账号"即可入会；.env 中默认不开启访客登录鉴权。
是否需要密码： 默认房间无密码。如需开启登录鉴权或房间密码，按 Handbook 的安全章节在 .env 中配置（官方未在 env.example 中给出默认管理员账号）。
密钥： gen-passwords.sh 生成的各组件 XMPP 认证密码保存在 .env 与 CONFIG 目录中，请勿提交到 Git；公网部署时务必重新运行 ./gen-passwords.sh 或自行改强。
安全提醒： 公网部署必须配置真实域名并启用 HTTPS（Let's Encrypt 或反向代理），放行 UDP 10000，并关注官方安全公告。

九、故障排查

案例 1：能进会议页面，但看不到/听不到对方（媒体不通）

报错现象：页面正常、信令连接成功，但视频画面卡 loading，对方看不到你。
报错原因：JVB 的 UDP 10000 端口未在防火墙/安全组放行，或服务器在 NAT 后未配置 JVB_ADVERTISE_IPS。
分步解决：① 放行宿主 UDP 10000；② 在 .env 设置 JVB_ADVERTISE_IPS=你的公网IP（env.example 注释原文支持逗号分隔多个 IP，格式 IP#端口）；③ docker compose up -d 重建 jvb 容器后重试。

案例 2：PUBLIC_URL 与访问端口不一致，邀请链接错误

报错现象：生成的邀请链接端口/域名与实际不符，他人打不开。
报错原因：env.example 明确提示"if you use a non-standard HTTPS port, it has to appear in the public URL"，即改了 HTTPS_PORT 却没同步改 PUBLIC_URL。
分步解决：① 编辑 .env，把 PUBLIC_URL 改为 https://你的域名:实际端口；② docker compose up -d 重启 web/jicofo。

案例 3：Let's Encrypt 证书申请失败

报错现象：docker compose up 后 web 容器日志出现 ACME 错误，页面证书不受信任。
报错原因：LETSENCRYPT_DOMAIN 的 DNS 未解析到本机，或 80/443 被占用，或未填 LETSENCRYPT_EMAIL。
分步解决：① 确认域名 A 记录指向本机公网 IP；② 确认 80/443 未被其他服务占用（ACME http-01 校验需要）；③ 填写 LETSENCRYPT_EMAIL；④ 测试阶段先设 LETSENCRYPT_USE_STAGING=1 用 staging 环境避免正式限额，成功后再去掉。

案例 4：gen-passwords.sh 报 sed/openssl 错误

报错原文（常见形式）：sed: command not found 或 openssl: command not found
报错原因：官方脚本依赖 openssl rand -hex 16 与 sed -i.bak，精简容器或最小化系统未安装。
分步解决：① 宿主安装 openssl 与 sed（如 sudo apt install openssl）；② 重新执行 ./gen-passwords.sh；③ 检查 .env 中六项密码是否已被替换为非占位值。

十、升级、回滚与卸载

升级： 官方 README 标签机制下，拉取新镜像并重建即可：

git pull
docker compose pull
docker compose up -d

逐段解释：git pull 取最新 compose 与 env 模板；docker compose pull 拉取 GHCR 新镜像；up -d 用新镜像重建容器。配置目录 CONFIG=~/.jitsi-meet-cfg 在容器外，升级不丢配置。如需固定版本，在 .env 设置 JITSI_IMAGE_VERSION=stable-NNNN-X。

回滚： 官方未提供一键回滚命令；可在 .env 将 JITSI_IMAGE_VERSION 改为上一个稳定标签（如 stable-8862），再 docker compose pull && docker compose up -d（基于官方镜像标签机制）。

卸载： docker compose down 停止并移除容器；彻底清理则删除配置目录 ~/.jitsi-meet-cfg 与 .env（此操作删除全部证书与密钥，先备份），并删除镜像 docker rmi ghcr.io/jitsi/web ghcr.io/jitsi/prosody ghcr.io/jitsi/jicofo ghcr.io/jitsi/jvb。

十一、商用许可合规说明

许可证：Apache License 2.0（仓库 LICENSE 文件首行确认："Apache License Version 2.0"）。
Apache-2.0 允许自由使用、修改、分发与商用；分发时须保留版权声明与许可文本，修改过的文件须标注变更。
Jitsi Meet 由 8x8 与开源社区维护；私有化商用部署无需付费授权。官方同时提供托管服务 8x8 Meet（JaaS）作为可选商业渠道，自托管 OSS 版本免费。