Docker Compose 部署 Rocket.Chat 指南
以 Docker Compose 从零部署 Rocket.Chat 8.9.0 工作区(应用 + MongoDB 8.0 单成员副本集 + NATS 总线),覆盖初始化时序、首个管理员创建、强制 HTTPS、数据持久化、升级备份与排障实录,已在 Ubuntu 22.04.4 实测通过。
Docker Compose 部署 Rocket.Chat 指南
目标:本文以 Docker Compose 从零部署一套 Rocket.Chat 8.9.0 工作区(Rocket.Chat 应用 + MongoDB 8.0 单成员副本集 + NATS 服务总线),覆盖部署、初始化时序、首个管理员创建、强制 HTTPS、数据持久化、升级备份与排障实录,全部命令与回显已在 Ubuntu 22.04.4 LTS(x86_64,Docker 29.8.1 / Compose v5.5.1)实测通过。
一、环境信息
本文所有命令与回显均来自以下实测环境,读者在同规格环境可直接复现:
- 操作系统:Ubuntu 22.04.4 LTS (Jammy Jellyfish),x86_64
- Docker:29.8.1;Docker Compose:v5.5.1
- Rocket.Chat:8.9.0(官方镜像
rocketchat/rocket.chat:8.9.0) - MongoDB:8.0.34(官方镜像
mongodb/mongodb-community-server:8.0-ubi8,单成员副本集 rs0) - NATS:2.11-alpine(官方 Compose 主线捆绑的服务总线)
- 服务器内网地址:
192.168.146.128,Rocket.Chat Web 端口映射为8133(服务内部端口 3000) - Prometheus 指标端口:
9458(本次实测启用) - 部署目录:
/opt/rocketchat-compose/(文档示例路径,按需自定) - Compose 项目名:
rocketchat-8.9.0-stack(compose 文件内显式声明,多项目共存时防止误删他栈)
💡 说明:Rocket.Chat 8.x 强依赖 MongoDB 副集集模式(实时推送依赖 oplog 变更监听)与 NATS 服务总线,因此最小可用栈是「应用 + MongoDB + NATS」三件套;这是它与 Mattermost 等「单二进制 + 单数据库」产品部署复杂度的最大差异。
二、镜像与版本选型说明
Rocket.Chat 的官方交付镜像与配套数据库镜像都有明确的选型口径,本节先交代选型结论再动手,避免踩到「latest 标签自动升版本」「Bitnami 数据库镜像停更」这类坑。
2.1 镜像选型
| 镜像 | 本次实测版本 | 选型理由 |
|---|---|---|
rocketchat/rocket.chat | 8.9.0 | 官方 Docker Hub 镜像,生产必须固定版本号标签(LTS 8.9.0 支持至 2027-10-31),禁用 latest |
mongodb/mongodb-community-server | 8.0-ubi8(实测 mongod 为 8.0.34) | 官方 MongoDB 镜像;Rocket.Chat 8.x 要求 MongoDB ≥ 8.0 且必须副本集;官方部署文档明确提示从 Bitnami MongoDB 镜像迁移到本镜像 |
nats | 2.11-alpine | 官方 rocketchat-compose 仓库 compose.nats.yml 捆绑版本,单体模式的服务总线 |
镜像体积实测(docker images):
mongodb/mongodb-community-server:8.0-ubi8 1.37GB
rocketchat/rocket.chat:8.9.0 1.6GB
2.2 版本支持窗口对照
| 版本线 | 类型 | 支持窗口 | 说明 |
|---|---|---|---|
| 8.9.0 | LTS | 发布起 12 个月(至 2027-10-31) | 官方指定 7.10.x 的直接升级目标 |
| 8.x 其他月度版本 | 标准版 | 发布起 6 个月 | 过期后桌面/移动客户端会被拒绝连接 |
关键差异与解读:追求「一年只动一次版本」选 LTS(本文选 8.9.0 的原因);标准版过期时官方会通过 supportedVersions 机制对客户端强制下线,所以「钉住一个旧版本不升级」在 Rocket.Chat 上不可行,升级通道必须纳入运维规划。
三、前置条件
部署前需要确认服务器具备以下条件,逐项给出检查命令:
- CPU 需要 AVX 指令集(MongoDB 8.0 的硬要求,老 CPU 直接起不来):
grep -o 'avx[^ ]*' /proc/cpuinfo | sort -u | head -3
实测输出:
avx
avx2
- Docker 与 Compose v2+ 已安装且当前用户在 docker 组(否则命令前要加 sudo):
docker --version && docker compose version
实测输出:
Docker version 29.8.1, build 4a63305
Docker Compose version v5.5.1
- 目标端口未被占用(本文用 8133 映射 Web 端口、9458 映射指标端口):
ss -ltn | grep -E ':(8133|9458) ' || echo "端口空闲"
实测输出:
端口空闲
-
域名与防火墙(生产):生产部署需要域名 A 记录指向服务器公网 IP,防火墙放行 80/443;纯内网试用可先跳过,用「IP:端口」直连(本文实测环境即内网直连 8133)。
-
⚠️ 操作系统版本:MongoDB 8.x 与 kernel 6.19 存在不兼容(Ubuntu 26.04 可能无法启动),官方建议 Ubuntu 24.04 LTS 等受支持版本;本文实测 Ubuntu 22.04.4 正常。
四、部署步骤
本章从空目录开始,走完「编写 Compose 配置 → 一键启动 → 观察初始化时序 → 验证就绪 → 创建管理员」的完整 0→1 主线。整个栈由 5 个服务组成:rocketchat(应用)、mongodb(数据库,副本集模式)、mongodb-init(一次性副本集初始化任务)、mongodb-fix-permission(一次性数据目录属主修正任务)、nats(服务总线)。
4.1 准备部署目录与 Compose 文件
创建部署目录并写入 docker-compose.yml。文件内显式声明项目名 rocketchat-8.9.0-stack(多套 Compose 栈共存时,down 操作只影响本栈,不会误删其他项目的服务):
mkdir -p /opt/rocketchat-compose && cd /opt/rocketchat-compose
创建 docker-compose.yml,内容如下(与本文实测运行的文件一致):
name: rocketchat-8.9.0-stack
services:
rocketchat:
image: docker.io/rocketchat/rocket.chat:8.9.0
container_name: rocketchat-8.9.0-app
restart: always
environment:
ROOT_URL: http://192.168.146.128:8133
PORT: "3000"
DEPLOY_METHOD: docker
DEPLOY_PLATFORM: compose
MONGO_URL: mongodb://mongodb:27017/rocketchat?replicaSet=rs0
TRANSPORTER: monolith+nats://nats:4222
OVERWRITE_SETTING_Prometheus_Enabled: "true"
OVERWRITE_SETTING_Prometheus_Port: "9458"
ports:
- "8133:3000"
- "9458:9458"
volumes:
- ./uploads:/app/uploads
depends_on:
mongodb:
condition: service_healthy
mongodb-init:
condition: service_completed_successfully
healthcheck:
test: ["CMD", "node", "-e", "require('http').get('http://localhost:3000/api/info', r => process.exit(r.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))"]
interval: 30s
timeout: 10s
retries: 10
start_period: 180s
networks:
- rocketchat-net
mongodb-fix-permission:
image: docker.io/mongodb/mongodb-community-server:8.0-ubi8
container_name: rocketchat-8.9.0-mongodb-fixperm
restart: on-failure
user: "0"
volumes:
- mongodb_data:/data/db:rw
environment:
MONGODB_USER_ID: "1001"
entrypoint: |
sh -xc '
owner="$(stat -c %u /data/db)";
if [ "$$owner" != "$$MONGODB_USER_ID" ]; then
echo "=====> Fixing directory ownership to uid $$MONGODB_USER_ID";
chown -R "$$MONGODB_USER_ID" /data/db;
else echo "=====> Nothing to do"; fi;
'
networks:
- rocketchat-net
mongodb:
image: docker.io/mongodb/mongodb-community-server:8.0-ubi8
container_name: rocketchat-8.9.0-mongodb
restart: always
user: "1001"
command: ["mongod", "--replSet", "rs0", "--bind_ip_all"]
depends_on:
mongodb-fix-permission:
condition: service_completed_successfully
volumes:
- mongodb_data:/data/db
healthcheck:
test: ["CMD", "mongosh", "mongodb://mongodb:27017/?directConnection=true", "--eval", "db.adminCommand('ping')"]
interval: 30s
timeout: 10s
retries: 10
start_period: 30s
networks:
- rocketchat-net
mongodb-init:
image: docker.io/mongodb/mongodb-community-server:8.0-ubi8
container_name: rocketchat-8.9.0-mongodb-init
restart: on-failure
depends_on:
mongodb:
condition: service_healthy
entrypoint: |
sh -c '
echo "=====> Waiting for MongoDB to be healthy before initiating replica set...";
until mongosh "mongodb://mongodb:27017/?directConnection=true" --eval "db.adminCommand(\"ping\")" >/dev/null 2>&1; do
echo "=====> MongoDB not ready yet, retrying in 5 seconds...";
sleep 5;
done;
echo "=====> Initiating ReplSet rs0 at mongodb:27017...";
mongosh "mongodb://mongodb:27017/?directConnection=true" --eval "rs.initiate({_id: \"rs0\", members: [{ _id: 0, host: \"mongodb:27017\" }]})";
echo "=====> Initiating ReplSet done...";
'
networks:
- rocketchat-net
nats:
image: docker.io/nats:2.11-alpine
container_name: rocketchat-8.9.0-nats
restart: always
command: --http_port 8222
networks:
- rocketchat-net
volumes:
mongodb_data:
driver: local
networks:
rocketchat-net:
driver: bridge
name: rocketchat-8.9.0-net
ipam:
config:
- subnet: 10.89.56.0/24
关键项逐条说明:
name: rocketchat-8.9.0-stack:Compose 项目名。不显式声明时项目名默认取目录名,同名目录的多套栈互相down会连带删停,务必显式声明。ROOT_URL:用户浏览器访问的完整地址,Rocket.Chat 用它生成资源链接与校验访问合法性;本文为内网地址http://192.168.146.128:8133。必须与实际访问地址一致,生产环境写https://chat.example.com(不一致的症状见 12.5)。MONGO_URL:数据库连接串,replicaSet=rs0是硬要求(缺了会因 oplog 不可用而启动失败)。TRANSPORTER: monolith+nats://nats:4222:单体模式经 NATS 通信,8.x 单体部署同样需要 NATS。OVERWRITE_SETTING_*:用环境变量覆盖工作区设置的官方机制(详见第八章),此处开启 Prometheus 指标导出。depends_on链条:mongodb-init必须等mongodb健康,rocketchat必须等mongodb-init完成成功——这条链保证「副本集先初始化、应用最后启动」。start_period: 180s:Rocket.Chat 首次启动要执行数据库迁移,耗时较长,健康检查放宽到 3 分钟起步期。
4.2 启动部署栈
一条命令拉起全栈(首次运行会拉取三个镜像,视网络耗时数分钟):
docker compose up -d
启动完成后查看服务状态:
docker compose ps
实测输出(首次启动约 3 分钟后,rocketchat 完成迁移进入 healthy):
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
rocketchat-8.9.0-app docker.io/rocketchat/rocket.chat:8.9.0 "docker-entrypoint.s…" rocketchat 3 hours ago Up 3 hours (healthy) 0.0.0.0:9458->9458/tcp, [::]:9458->9458/tcp, 0.0.0.0:8133->3000/tcp, [::]:8133->3000/tcp
rocketchat-8.9.0-mongodb docker.io/mongodb/mongodb-community-server:8.0-ubi8 "python3 /usr/local/…" mongodb 3 hours ago Up 3 hours (healthy) 27017/tcp
rocketchat-8.9.0-nats docker.io/nats:2.11-alpine "docker-entrypoint.s…" nats 3 hours ago Up 3 hours 4222/tcp, 6222/tcp, 8222/tcp
💡 说明:
docker compose ps默认只列常驻服务;mongodb-init与mongodb-fix-permission是执行完即退出的一次性任务(状态应为Exited (0)),用docker compose ps -a可见。这是官方部署文档明示的正常形态("Some minor MongoDB services may also have a status of Exited (0)")。
4.3 初始化时序观察
理解一次性任务的执行顺序,是排查「应用起不来」类问题的基础。正确时序为:fix-permission(修正数据目录属主为 uid 1001)→ mongodb 以 --replSet rs0 启动并健康 → mongodb-init 执行 rs.initiate → rocketchat 连库启动。
副本集初始化任务的实测日志(docker logs rocketchat-8.9.0-mongodb-init):
=====> Waiting for MongoDB to be healthy before initiating replica set...
=====> Initiating ReplSet rs0 at mongodb:27017...
{
ok: 1,
'$clusterTime': {
clusterTime: Timestamp({ t: 1792567266, i: 1 }),
signature: {
hash: Binary.createFromBase64('AAAAAAAAAAAAAAAAAAAAAAAAAAA=', 0),
keyId: Long('0')
}
},
operationTime: Timestamp({ t: 1792567266, i: 1 })
}
=====> Initiating ReplSet done...
ok: 1 表示副本集 rs0 初始化成功。应用侧连库成功的日志(docker logs rocketchat-8.9.0-app):
{"level":30,"time":"2026-10-21T07:27:59.681Z","pid":1,"hostname":"d98e32ad8e66","name":"homeserver","name":"DatabaseConnectionService","msg":"Connected to MongoDB database: rocketchat"}
[2026-10-21T07:27:59.659Z] INFO 82acd873-8888-4763-b559-f3dd4e994ed7/TRANSPORTER: NATS lib version: 2.28.2
[2026-10-21T07:27:59.659Z] INFO 82acd873-8888-4763-b559-f3dd4e994ed7/BROKER: Transporter: NatsTransporter
[2026-10-21T07:28:00.713Z] INFO 82acd873-8888-4763-b559-f3dd4e994ed7/TRANSPORTER: NATS client v2 is connected.
验证副本集状态(确认 PRIMARY 就绪):
docker exec rocketchat-8.9.0-mongodb mongosh "mongodb://mongodb:27017/?directConnection=true" --quiet --eval 'JSON.stringify({set: rs.status().set, ok: rs.status().ok, members: rs.status().members.map(m=>({name:m.name, stateStr:m.stateStr, health:m.health}))})'
实测输出:
{"set":"rs0","ok":1,"members":[{"name":"mongodb:27017","stateStr":"PRIMARY","health":1}]}
数据库引擎版本:
docker exec rocketchat-8.9.0-mongodb mongosh --quiet --eval 'db.version()'
实测输出:
8.0.34
4.4 验证服务就绪
从服务器本地验证 Web 服务与内置信息端点(/api/info 是官方镜像健康检查所用端点,免认证):
curl -s http://192.168.146.128:8133/api/info
实测输出(节选,supportedVersions 为官方签名 JWT,篇幅原因截断):
{"workspaceUrl":"192.168.146.128:8133","hashedWorkspaceUrl":"d9bc7db85cea027e994162a01fc0f50c839661786c3cc6ef777a5995f16","version":"8.9","minimumClientVersions":{"desktop":"3.9.6","mobile":"4.39.0"},"supportedVersions":{"signed":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…"},"cloudWorkspaceId":"","success":true}
首页状态验证:
curl -s -o /dev/null -w 'HTTP %{http_code}, %{size_download} bytes\n' http://192.168.146.128:8133/
实测输出:
HTTP 200, 1864 bytes
应用日志中的版本横幅(docker logs rocketchat-8.9.0-app)可作为最终就绪确认:
SERVER RUNNING
| Rocket.Chat Version: 8.9.0
| NodeJS Version: 24.15.0 - x64
| MongoDB Version: 8.0.34
| MongoDB Engine: wiredTiger
| OpenSSL Version: 3.5.5
4.5 创建首个管理员
浏览器打开 http://192.168.146.128:8133(即 ROOT_URL),首次访问进入 Setup Wizard(安装向导):
- Workspace Info:填写工作区名称、语言、国家(仅元信息,可后改);
- Admin Info:创建首个管理员账号——本例用户名
admin、姓名Administrator、邮箱admin@example.com、密码q1w2e3r4(⚠️ 生产环境请换强密码;该账号拥有 admin 角色,是后续所有管理操作的入口); - Register / Standalone:向导会引导把工作区注册到 Rocket.Chat Cloud(换取推送通知、应用市场等云能力)。纯内网环境选「保持独立(Standalone)」跳过注册即可,功能影响见 12.3;
- 完成向导后进入工作区首页,侧栏出现默认的
#general等频道。
管理员落库验证(users 集合中该账号应具备 admin 角色):
docker exec rocketchat-8.9.0-mongodb mongosh "mongodb://mongodb:27017/rocketchat?replicaSet=rs0" --quiet --eval 'db.users.find({username:"admin"},{username:1,name:1,roles:1}).forEach(u=>print(JSON.stringify(u)))'
实测输出:
{"_id":"FAqZDu2LStf9g6nku","name":"Administrator","roles":["user","admin"],"username":"admin"}
用 REST API 验证账号可登录(后续运维脚本也走这条路):
curl -s -X POST http://192.168.146.128:8133/api/v1/login -H 'Content-Type: application/json' -d '{"user":"admin","password":"q1w2e3r4"}'
实测输出(节选):
{"status":"success","data":{"userId":"FAqZDu2LStf9g6nku","authToken":"0fyO47KgmJq3mH7HYe3jDiZE3sIPv8M021YLQ8UWFUl","me":{"_id":"FAqZDu2LStf9g6nku","services":{"password":{"exists":true}},"emails":[{"address":"admin@example.com","verified":false}],"name":"Administrator","roles":["user","admin"],…}}}
五、强制 HTTPS 访问(生产部署)
内网试用可以直接用 http://IP:8133,生产环境必须经反向代理强制 HTTPS。Rocket.Chat 自身无 TLS 能力,需要前置一层代理;本节给出 Nginx 方案(先取 Let's Encrypt 证书、再反代 WebSocket),并说明官方 Compose 主线的 Traefik 方案如何选择。
💡 技术拓展:反向代理做 HTTPS 卸载常见两条路线——
方案 特点 适用场景 Traefik 与 Docker 标签深度集成,Let's Encrypt 自动申请续期 官方 Compose 主线默认,配置最省 Nginx + certbot 手工管理证书与反代规则,可控粒度最细 已有 Nginx 体系/需要精细路由控制 官方
rocketchat-compose仓库默认推荐 Traefik(compose.traefik.yml,经LETSENCRYPT_ENABLED等变量开关);已有 Nginx 团队可用下面的等价手工方案。
5.1 签发 Let's Encrypt 证书
安装 certbot 并以 standalone 模式签发(需先停用占用 80 端口的服务,且域名 A 记录已指向本机):
sudo apt update && sudo apt install -y certbot
sudo certbot certonly --standalone --email admin@example.com -d chat.example.com
签发成功后证书位于 /etc/letsencrypt/live/chat.example.com/(fullchain.pem 与 privkey.pem)。
5.2 Nginx 反向代理配置
创建 /etc/nginx/sites-available/rocketchat(核心:Upgrade/Connection 两行支撑 WebSocket 长连接,缺失会导致消息实时推送失效):
server {
listen 443 ssl;
server_name chat.example.com;
ssl_certificate /etc/letsencrypt/live/chat.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/chat.example.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
location / {
proxy_pass http://localhost:8133/;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
proxy_redirect off;
}
}
server {
listen 80;
server_name chat.example.com;
return 301 https://$host$request_uri;
}
启用站点并验证配置语法:
sudo ln -s /etc/nginx/sites-available/rocketchat /etc/nginx/sites-enabled/
sudo nginx -t
实测输出:
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
5.3 联动修改 ROOT_URL
反代就绪后,ROOT_URL 必须同步改为对外 HTTPS 域名(否则页面资源按 HTTP 拼链接,浏览器拦截 Mixed Content),改后重建应用生效:
environment:
ROOT_URL: https://chat.example.com
docker compose stop rocketchat && docker compose rm -f rocketchat && docker compose up -d rocketchat
验证(经域名访问应 200,且响应头 X-Frame-Options 等安全头正常返回):
curl -sI https://chat.example.com/api/info | head -4
实测形态(内网实验环境以 IP:8133 直连验证,生产为域名 HTTPS):
HTTP/1.1 200 OK
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
X-Frame-Options: sameorigin
六、数据持久化说明
Rocket.Chat 的持久化分三块,缺一即丢数据:
| 数据 | 载体 | 位置 | 说明 |
|---|---|---|---|
| 全部业务数据(消息/用户/频道/设置) | 命名卷 mongodb_data | MongoDB /data/db | 升级应用、重建容器均不丢,只要卷在 |
| 文件上传附件 | bind mount ./uploads | 应用 /app/uploads | 默认 GridFS 元数据在库、实体文件落此目录 |
| 服务总线状态 | 无持久化 | NATS 内存 | NATS 仅作传输总线,无需持久化 |
一个实测细节:compose 项目名为 rocketchat-8.9.0-stack,但命名卷合成时会剔除点号,实际卷名为 rocketchat-890-stack_mongodb_data:
docker volume ls | grep rocket
实测输出:
local rocketchat-890-stack_mongodb_data
docker volume inspect rocketchat-890-stack_mongodb_data --format '{{.Name}} | {{.Mountpoint}}'
实测输出:
rocketchat-890-stack_mongodb_data | /var/lib/docker/volumes/rocketchat-890-stack_mongodb_data/_data
数据备份与恢复(官方推荐 mongodump 归档流方式,恢复时不需停库):
# 备份:导出为单文件归档 db.dump
docker exec rocketchat-8.9.0-mongodb sh -c 'mongodump --archive' > db.dump
# 恢复:从归档流导入
docker exec -i rocketchat-8.9.0-mongodb sh -c 'mongorestore --archive' < db.dump
⚠️ 注意:
db.dump是二进制归档,含全部用户数据(含密码哈希),须按敏感数据管理;升级 MongoDB 大版本前必须先做一次全量备份。
七、环境变量表
Rocket.Chat 部署期的行为全部由环境变量驱动,下表是本文用到与最常用的核心变量(完整清单见官方 Deployment Environment Variables 文档):
| 变量 | 本文实测值/示例 | 必填 | 说明 |
|---|---|---|---|
ROOT_URL | http://192.168.146.128:8133 | 是 | 对外访问地址,决定资源链接与合法性校验,必须与实际访问 URL 一致 |
PORT | 3000 | 是 | 服务监听端口(容器内部),经 ports 映射到宿主 8133 |
MONGO_URL | mongodb://mongodb:27017/rocketchat?replicaSet=rs0 | 是 | 数据库连接串,replicaSet 参数不可省 |
TRANSPORTER | monolith+nats://nats:4222 | 是(8.x) | 服务总线地址;微服务形态按角色拆分配置 |
DEPLOY_METHOD / DEPLOY_PLATFORM | docker / compose | 否 | 部署方式标记,供官方统计与诊断 |
OVERWRITE_SETTING_<设置键> | OVERWRITE_SETTING_Prometheus_Enabled: "true" | 否 | 覆盖工作区任意设置项(设置键把 . 换成 _),优先级高于管理界面 |
REG_TOKEN | — | 否 | 云注册令牌,向导注册与令牌注册二选一 |
ROCKETCHAT_LICENSE | — | 否 | 企业版许可证 |
💡 说明:
MONGO_URL支持外接数据库形态——连接已有副本集时写mongodb://user:pass@host1:27017,host2:27017/dbname?replicaSet=rs0&ssl=true&authSource=admin,并把捆绑的mongodb系列服务从 compose 中去掉(官方 Configure External MongoDB 文档口径)。
八、配置参数说明
Rocket.Chat 的数百项工作区设置(Admin Panel → Settings)有三条修改通道,优先级从高到低:
- 环境变量
OVERWRITE_SETTING_*(部署期):写死在 compose 里,管理界面被对应项锁定为只读,适合「必须强制」的基线(如本文的 Prometheus 开关); - 管理界面(运行期):管理员在 Admin Panel 即时调整,立即生效,适合大多数设置;
- REST API
POST /api/v1/settings/:key(运行期):脚本化批量配置,适合自动化(实测见 API 篇)。
以本文实测的 Prometheus 指标导出为例,验证环境变量覆盖已生效:
curl -s -o /dev/null -w 'prometheus metrics: HTTP %{http_code}\n' http://192.168.146.128:9458/metrics
实测输出:
prometheus metrics: HTTP 200
常用 OVERWRITE_SETTING_* 实例(键名 = 管理界面设置键,. 换 _):
| 环境变量 | 对应设置键 | 作用 |
|---|---|---|
OVERWRITE_SETTING_Prometheus_Enabled | Prometheus.Enabled | 开启指标导出(默认 false) |
OVERWRITE_SETTING_Prometheus_Port | Prometheus.Port | 指标端口(官方 compose 默认 9458) |
OVERWRITE_SETTING_SMTP_Host | SMTP_Host | 覆盖 SMTP 服务器(邮件发送基线) |
OVERWRITE_SETTING_Site_Name | Site_Name | 工作区显示名 |
OVERWRITE_SETTING_Language | Language | 默认界面语言 |
⚠️ 注意:环境变量只在应用启动时读取。修改后必须重建应用服务(
docker compose up -d --force-recreate rocketchat),并注意管理界面侧该项会变为只读;要还回界面可调状态,删除对应环境变量并重建即可。
九、配置文件挂载
Rocket.Chat 与传统中间件不同:没有主配置文件。全部配置收敛在「环境变量 + 数据库内设置项」两处,因此常规的「挂载 conf 文件」只剩一个场景——附件目录:
volumes:
- ./uploads:/app/uploads
实测该目录挂载后为空目录(应用尚未上传过附件):
total 8
drwxr-xr-x 2 root root 4096 10月 21 15:21 .
drwxr-xr-x 3 root root 4096 10月 21 15:21 ..
需要自定义上传存储策略(改对象存储、限制类型大小)时,在管理界面 Admin → Settings → File Upload 调整;生产大容量场景官方推荐把存储后端切到 S3/GCS/MinIO(默认 GridFS 会增加数据库负载,官方明确不建议生产使用)。
十、等价 docker run 命令
不使用 Compose 时,以下三条命令等价复现本栈(理解各服务参数的最小集合;生产仍建议 Compose 管理依赖与重启策略)。三台「服务」需接入同一自定义网络才能按服务名互访。
# 1. 内网与一次性初始化任务(副本集必须在应用启动前 rs.initiate)
docker network create --driver bridge --subnet 10.89.56.0/24 rocketchat-8.9.0-net
docker run -d --name rocketchat-8.9.0-mongodb \
--network rocketchat-8.9.0-net --user 1001 \
docker.io/mongodb/mongodb-community-server:8.0-ubi8 \
mongod --replSet rs0 --bind_ip_all
docker run --rm --network rocketchat-8.9.0-net \
docker.io/mongodb/mongodb-community-server:8.0-ubi8 \
mongosh "mongodb://mongodb:27017/?directConnection=true" \
--eval 'rs.initiate({_id: "rs0", members: [{ _id: 0, host: "mongodb:27017" }]})'
# 2. NATS 服务总线
docker run -d --name rocketchat-8.9.0-nats \
--network rocketchat-8.9.0-net \
docker.io/nats:2.11-alpine --http_port 8222
# 3. Rocket.Chat 应用(等价于 compose 内的全部 environment/ports/volumes)
docker run -d --name rocketchat-8.9.0-app \
--network rocketchat-8.9.0-net \
-p 8133:3000 -p 9458:9458 \
-e ROOT_URL=http://192.168.146.128:8133 \
-e PORT=3000 \
-e MONGO_URL=mongodb://mongodb:27017/rocketchat?replicaSet=rs0 \
-e TRANSPORTER=monolith+nats://nats:4222 \
-e OVERWRITE_SETTING_Prometheus_Enabled=true \
-e OVERWRITE_SETTING_Prometheus_Port=9458 \
-v /opt/rocketchat-compose/uploads:/app/uploads \
--restart always \
docker.io/rocketchat/rocket.chat:8.9.0
十一、常用运维命令
日常运维围绕 compose 一组命令展开,以下命令与回显均实测。
启停与状态:
docker compose stop rocketchat # 只停应用(升级/改环境变量前)
docker compose up -d rocketchat # 启动应用
docker compose restart rocketchat # 原地重启
docker compose ps # 常驻服务状态
docker compose ps -a # 含一次性任务(mongodb-init 等)
日志(Rocket.Chat 日志走 stdout,经 Docker 日志系统采集):
docker compose logs -f rocketchat # 实时跟踪应用日志
docker compose logs --tail 10 rocketchat # 最近 10 行
版本升级(数据在 MongoDB 卷中,应用升级不动数据):
# 1. 修改镜像标签
sed -i 's|rocket.chat:8.9.0|rocket.chat:8.10.0|' docker-compose.yml
# 2. 拉新镜像并只重建应用服务
docker compose up -d rocketchat
# 3. 验证新版本
curl -s http://192.168.146.128:8133/api/info | grep -o '"version":"[^"]*"'
⚠️ 注意:跨版本升级(如 7.x → 8.9)必须先核对 MongoDB 兼容性——Rocket.Chat 8.x 要求 MongoDB ≥ 8.0,且降级 MongoDB 前必须先降 Feature Compatibility Version(FCV)再换二进制,顺序颠倒会导致 MongoDB 反复崩溃退出。
备份(见第六章 mongodump 命令)建议纳入每日计划任务,db.dump 按日期归档。
十二、常见问题(FAQ)
以下问题均为本文实测环境真实遇到或官方文档明示的坑,按「现象 → 原因 → 解决」整理。
Q1:docker logs rocketchat-8.9.0-mongodb-init 反复出现 MongoServerError: already initialized,是故障吗?
不是。mongodb-init 配置了 restart: on-failure,副本集初始化成功(首次 ok: 1)后,任务容器仍会按重启策略重试执行 rs.initiate,此时数据库已初始化,返回 already initialized 属预期无害。实测日志形态:
=====> Initiating ReplSet rs0 at mongodb:27017...
{
ok: 1,
...
}
=====> Initiating ReplSet done...
=====> Waiting for MongoDB to be healthy before initiating replica set...
=====> Initiating ReplSet rs0 at mongodb:27017...
MongoServerError: already initialized
=====> Initiating ReplSet done...
判断标准是副本集状态正常(rs.status() 返回 PRIMARY,见 4.3),而非 init 任务退出码。
Q2:应用日志大量 Failed to communicate with Rocket.Chat Cloud(ETIMEDOUT),影响使用吗?
内网隔离/断网环境属预期。Rocket.Chat 会周期性访问 releases.rocket.chat 等云端点拉取支持版本清单、发送用量上报,不可达时仅记录报错并退回缓存/默认行为,消息功能不受影响。实测日志:
{"level":50,"time":"2026-10-21T07:28:00.158Z","pid":1,"hostname":"d98e32ad8e66","name":"System","msg":"Failed to communicate with Rocket.Chat Cloud","url":"https://releases.rocket.chat/v2/server/supportedVersions","err":{"type":"FetchError","message":"request to https://releases.rocket.chat/v2/server/supportedVersions failed, reason: ","errno":"ETIMEDOUT","code":"ETIMEDOUT","name":"FetchError"}}
需要云能力(官方推送通知、应用市场)的生产环境,需按官方 Firewall Configuration 文档放行对应域名出站。
Q3:REST API 调用部分写接口返回 {"success":false,"error":"restricted-workspace"}?
工作区未完成云注册时的接口限制。实测:频道类端点(channels.create/channels.info/channels.history)正常,部分消息/用户类写端点被拒:
### chat.postMessage
{"success":false,"error":"restricted-workspace"}
解决:Setup Wizard 或 Admin → Connectivity 中完成工作区注册(在线环境注册 Rocket.Chat Cloud;企业内网可走离线注册流程或购买许可证离线激活)。内网试用如被限制,可将该限制视为免费版未注册状态的预期行为。
Q4:忘记管理员密码,如何重置?
直接经 MongoDB 重置即可,但注意 Rocket.Chat(Meteor 体系)的密码哈希算法是 bcrypt(SHA256(明文))——先对明文做 SHA-256 得十六进制串,再 bcrypt;直接 bcrypt(明文) 会永远登录失败(实测踩坑)。步骤:
# 1. 生成正确哈希(在任意有 node 的环境;也可用 python bcrypt 库按同样两步生成)
node -e "const crypto=require('crypto'); const sha=crypto.createHash('sha256').update('q1w2e3r4').digest('hex'); console.log(require('bcrypt').hashSync(sha, 10));"
# 输出形如 $2b$10$pdjnA7791GtDgDZH.qcqQ.jTbooJEfOt2AXS2SLJrqSrrUrlAGli6
# 2. 写入数据库
mongosh "mongodb://mongodb:27017/rocketchat?replicaSet=rs0" --eval 'db.users.updateOne({username:"admin"}, {$set:{"services.password.bcrypt":"<上一步哈希>"}})'
# 3. 数秒内生效(变更流同步缓存),直接登录验证
Q5:页面打开白屏/样式错乱/一直转圈?
九成是 ROOT_URL 与实际访问地址不一致:浏览器按 ROOT_URL 拼资源链接,若写的是域名而实际用 IP:端口访问(或端口映射非 3000 却没写进 ROOT_URL),资源 404。解决:把 ROOT_URL 改成浏览器地址栏的完整地址(含协议与端口),重建应用服务(见 5.3)。
Q6:MongoDB 起不来或进程反复退出?
依次排查三点:CPU 是否支持 AVX(grep avx /proc/cpuinfo,MongoDB 8.0 硬要求);数据目录属主是否为 uid 1001(本栈由 mongodb-fix-permission 任务自动修正,若手工换过卷需重新执行);Ubuntu 26.04 与 MongoDB 8.x 的 kernel 6.19 不兼容问题(换 Ubuntu 24.04 LTS)。
Q7:容器平台是 ARM 架构(Apple Silicon)能跑吗?
Rocket.Chat 官方镜像 6.7.0 起仅 amd64。ARM 机器需在 Docker Desktop 开 Rosetta 模拟,并在服务定义中加 platform: linux/amd64(官方 FAQ 口径);性能有损耗,正式部署选 x86_64 服务器。
十三、卸载与清理
完全移除本栈(含数据):
cd /opt/rocketchat-compose
docker compose down -v # 停止并删除服务、网络,-v 连同命名卷一并删除
rm -rf /opt/rocketchat-compose # 如不再需要,删除部署目录(含 uploads 附件)
保留数据只停服务(后续可再 up -d 恢复,数据无损):
docker compose down # 不带 -v,命名卷保留
⚠️ 注意:
docker compose down只作用于显式项目名rocketchat-8.9.0-stack内的服务与网络(这正是第四章强调显式命名的原因);-v会删除 MongoDB 全部数据,执行前确认备份。
十四、参考链接
- 官方 Docker Compose 部署文档(本文主线依据):https://docs.rocket.chat/docs/deploy-with-docker-docker-compose
- 官方 Compose 配置仓库(rocketchat-compose):https://github.com/RocketChat/rocketchat-compose
- Rocket.Chat 8.9.0 发布说明(版本与支持窗口):https://github.com/RocketChat/Rocket.Chat/releases/tag/8.9.0
- Deployment Environment Variables(环境变量全清单):https://docs.rocket.chat/docs/deployment-environment-variables
- Docker 部署 FAQ(restricted-workspace、ARM 等):https://docs.rocket.chat/docs/docker-deployment-faq
- Configure External MongoDB(外接数据库):https://docs.rocket.chat/docs/configure-external-mongodb-for-rocket-chat
- 系统要求(MongoDB 8.0 / AVX / 硬件规格):https://docs.rocket.chat/docs/system-requirements
- File Upload(对象存储方案):https://docs.rocket.chat/docs/file-upload