跳到主要内容

OpenIMServer 与 ChatServer 生产环境源码部署(单机)

一、环境及组件要求

OpenIMServer 与外部组件部署在同一台机器上,部分组件可按需使用云服务。

二、获取 OpenIMServer 并部署依赖组件

建议通过仓库拉取并切到 GitHub Releases 页面绿色 Latest 对应的最新正式发布 tag

git clone https://github.com/openimsdk/open-im-server && cd open-im-server
git fetch --tags
LATEST_STABLE_TAG=$(basename "$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/openimsdk/open-im-server/releases/latest)")
git checkout "$LATEST_STABLE_TAG"
echo "using open-im-server stable release tag: $LATEST_STABLE_TAG"

这里的 latest 指 GitHub Releases 页面绿色 Latest 的正式发布版,不包含 alpha/beta/rc 等预发布版本。main 为开发版分支,生产环境不要直接使用 main

注意:后续所有命令都在 OpenIMServer 项目根目录执行。

2.1 部署外部组件(Docker Compose)

确保 dockerdocker compose 已可用。

  1. 如果本机已部署 mongodb/redis/kafka/minio/etcd 中一个或多个组件,或计划改用云服务(etcd 不支持云服务),可在 docker-compose.yml 注释对应组件。
  2. 强烈建议修改 docker-compose.yml 里的默认账号和密码。
组件docker-compose.yml 中的位置
MongoDBMONGO_INITDB_ROOT_USERNAME MONGO_INITDB_ROOT_PASSWORD MONGO_OPENIM_USERNAME MONGO_OPENIM_PASSWORD
Redisredis-server --requirepass ...
MinIOMINIO_ROOT_USER MINIO_ROOT_PASSWORD
EtcdETCD_ROOT_USER ETCD_ROOT_PASSWORD(启用鉴权时)
KafkaKAFKA_USERNAME KAFKA_PASSWORD(启用鉴权时)
  1. 修改 .env 中的 DATA_DIR,指向大磁盘目录用于外部组件数据存储。
  2. 执行以下命令部署外部组件:
docker compose up -d

当前 open-im-server/docker-compose.yml 除外部组件外,还会一并拉起 openim-web-frontopenim-admin-front。如果你当前只想部署依赖组件,可以按需调整 compose 文件后再启动。

2.2 自行部署组件或使用云服务时的初始化要求

存储组件初始化要求
MongoDB预先创建数据库:openim_v3
Kafka预先创建 4 个 topic:toRedis toMongo toPush toOfflinePush,每个 topic 设置 8 个分区

三、部署 OpenIMServer

确保 Go 已正确安装。

bootstrap.sh 会尝试自动安装 mage,但前提是系统里已经有可用的 go 命令。因此如果 go version 不通过,后续 bash bootstrap.shmage 都无法执行。

3.1 中国境内建议设置 Go 代理

go env -w GO111MODULE=on
go env -w GOPROXY=https://goproxy.cn,direct

3.2 初始化(仅执行一次)

bash bootstrap.sh

3.3 编译

mage

首次编译耗时较长,请耐心等待。

3.4 基础配置修改

描述所在文件
Kafka 用户名、密码、地址config/kafka.yml
Redis 密码、地址config/redis.yml
MinIO 用户名、密码、地址;externalAddress 必须改为外网 IP 或域名路径config/minio.yml
S3 云存储密钥(使用 S3 时)config/openim-rpc-third.yml
Etcd 用户名、密码、地址config/discovery.yml
MongoDB 用户名、密码、地址config/mongodb.yml
OpenIMServer secretconfig/share.yml

minio.ymlexternalAddress 必须改为外网 IP 或域名路径,否则 IM 无法正常发送图片和文件。

3.5 启动/停止/检测

任务命令说明
后台启动nohup mage start >> _output/logs/openim.log 2>&1 &生产环境建议使用
停止mage stop-
检测mage check-

首次启动后建议等待 20-30s 再执行 mage check 或接口验证,避免把启动过程中的短暂连接失败误判为最终异常。

四、获取 ChatServer

如果已有自有账号体系,可不部署 ChatServer。

同样建议拉取后切到 GitHub Releases 页面绿色 Latest 对应的最新正式发布 tag

git clone https://github.com/openimsdk/chat && cd chat
git fetch --tags
LATEST_STABLE_TAG=$(basename "$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/openimsdk/chat/releases/latest)")
git checkout "$LATEST_STABLE_TAG"
echo "using chat stable release tag: $LATEST_STABLE_TAG"

如需复现指定版本,按实际发布说明改为固定 tag;若服务端联调需要固定到 v3.8.3-patch.12 对应版本,也请同时固定 ChatServer 的对应正式版 tag。

五、部署 ChatServer

注意:以下命令都在 ChatServer 项目根目录执行。

5.1 编译

mage

5.2 基础配置修改

描述所在文件
Redis 用户名、密码、地址config/redis.yml
Etcd 用户名、密码、地址config/discovery.yml
MongoDB 用户名、密码、地址config/mongodb.yml
OpenIMServer secretconfig/share.yml
ChatServer secretconfig/chat-rpc-admin.yml

5.3 启动/停止/检测

任务命令说明
后台启动nohup mage start >> _output/logs/chat.log 2>&1 &生产环境建议使用
停止mage stop-
检测mage check-

ChatServer 启动时依赖 OpenIMServer 先可用,建议在 OpenIMServer mage check 正常后,再启动 ChatServer,并等待 20-30s 再验证 10008/10009 接口。

六、配置文件说明

  • OpenIMServer 配置说明请以当前检出代码的 config/README_zh_CN.md 为准。
  • ChatServer 配置说明请以当前检出代码的 config/README_zh_CN.md 为准。

七、关于离线推送

  • 个推:支持个推离线推送,按个推官方申请 AppIDAppKeyMasterSecret 后接入即可。
  • Firebase:修改 config/openim-push.ymlfcm.filepath

八、服务实例个数修改(可选)

start-config.ymlserviceBinaries 中,除 openim-msggatewayopenim-api 外,其他服务可直接调整实例数。

openim-msggatewayopenim-api

  • 服务实例数要和对应配置文件里的端口数量保持一致。
  • 修改后重启服务生效。

九、监控告警(可选)

待补充

十、重要指引

10.1 secret 修改

强烈建议修改默认 secret

  • 至少 8 位
  • 数字 + 字母组合
  • 妥善保密

10.2 端口开放与客户端地址

不使用域名/SSL 时,端口开放与 SDK 地址请参考:端口和防火墙

  • apiAddr: http://your_server_ip:10002
  • wsAddr: ws://your_server_ip:10001

使用域名/SSL 时,配置请参考:域名及 SSL 证书配置

  • 按部署要求修改域名解析,绑定 IP 与域名
  • 域名模式一般仅对外开放 443
  • apiAddr: https://your_domain.com/api
  • wsAddr: wss://your_domain.com/msg_gateway

10.3 单机生产环境数据备份及恢复

请参考:单机生产环境数据备份及恢复