Skip to content

docs: update readme of config file. #3356

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
icey-yu merged 1 commit into from
Jul 28, 2025
Merged

docs: update readme of config file. #3356

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 70 additions & 46 deletions config/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,48 +1,66 @@
---
title: 'OpenIM Configuration Files and Common Configuration Item Modifications Guide'

## Configuration Files Explanation

| Configuration File | Description |
| ------------------------------- | ------------------------------------------------------------ |
| **kafka.yml** | Configurations for Kafka username, password, address, etc. |
| **redis.yml** | Configurations for Redis password, address, etc. |
| **minio.yml** | Configurations for MinIO username, password, address, and external IP/domain; failing to modify external IP or domain may cause image file sending failures |
| **zookeeper.yml** | Configurations for ZooKeeper user, password, address, etc. |
| **mongodb.yml** | Configurations for MongoDB username, password, address, etc. |
| **log.yml** | Configurations for log level and storage directory. |
| **notification.yml** | Configurations for events like adding friends, creating groups, etc. |
| **share.yml** | Common configurations needed by various OpenIM services, such as secret. |
| **webhooks.yml** | Configurations for URLs in Webhook. |
| **local-cache.yml** | Local cache configurations. |
| **openim-rpc-third.yml** | Configurations for listening IP, port, and storage settings for images and videos in openim-rpc-third service. |
| **openim-rpc-user.yml** | Configurations for listening IP and port in openim-rpc-user service. |
| **openim-api.yml** | Configurations for listening IP, port, etc., in openim-api service. |
| **openim-crontask.yml** | Configurations for openim-crontask service. |
| **openim-msggateway.yml** | Configurations for listening IP, port, etc., in openim-msggateway service. |
| **openim-msgtransfer.yml** | Configurations for openim-msgtransfer service. |
| **openim-push.yml** | Configurations for listening IP, port, and offline push settings in openim-push service. |
| **openim-rpc-auth.yml** | Configurations for listening IP, port, and token expiration settings in openim-rpc-auth service. |
| **openim-rpc-conversation.yml** | Configurations for listening IP, port, etc., in openim-rpc-conversation service. |
| **openim-rpc-friend.yml** | Configurations for listening IP, port, etc., in openim-rpc-friend service. |
| **openim-rpc-group.yml** | Configurations for listening IP, port, etc., in openim-rpc-group service. |
| **openim-rpc-msg.yml** | Configurations for listening IP, port, and whether to verify friendship before sending messages in openim-rpc-msg service. |

## Common Configuration Item Modifications

| Configuration Item Modification | Configuration File |
| ----------------------------------------------------- | ----------------------- |
| Using MinIO for image and video file object storage | `minio.yml` |
| Adjusting production environment logs | `log.yml` |
| Verifying friendship before sending messages | `openim-rpc-msg.yml` |
| Modifying secret | `share.yml` |
| Using OSS, COS, AWS, Kodo for image and video storage | `openim-rpc-third.yml` |
| Setting multiple login policy | `openim-msggateway.yml` |
| Setting up offline push | `openim-push.yml` |

## Starting Multiple Instances of an OpenIM Service

To start multiple instances of an OpenIM service, simply increase the corresponding port numbers and modify the `start-config.yml` file in the project root directory. Restart the service to take effect. For example, the configuration to start 2 instances of `openim-rpc-user` is as follows:
# OpenIM Configuration File Descriptions and Common Configuration Modifications

## External Component Configurations

| Configuration File | Description |
| ------------------ |-------------------------------------------------------------|
| **kafka.yml** | Configuration for Kafka username, password, address, etc. |
| **redis.yml** | Configuration for Redis password, address, etc. |
| **minio.yml** | Configuration for MinIO username, password, address, etc. |
| **mongodb.yml** | Configuration for MongoDB username, password, address, etc. |
| **discovery.yml** | Service discovery and etcd credentials and address. |

## OpenIMServer Related Configurations
| Configuration File | Description |
| ------------------------------- | ---------------------------------------------- |
| **log.yml** | Configuration for logging levels and storage directory |
| **notification.yml** | Event notification settings (e.g., add friend, create group) |
| **share.yml** | Common settings for all services (e.g., secrets) |
| **webhooks.yml** | Webhook URLs and related settings |
| **local-cache.yml** | Local cache settings (generally do not modify) |
| **openim-rpc-third.yml** | openim-rpc-third listen IP, port, and object storage settings |
| **openim-rpc-user.yml** | openim-rpc-user listen IP and port settings |
| **openim-api.yml** | openim-api listen IP, port, and other settings |
| **openim-crontask.yml** | openim-crontask scheduled task settings |
| **openim-msggateway.yml** | openim-msggateway listen IP, port, and other settings |
| **openim-msgtransfer.yml** | Settings for openim-msgtransfer service |
| **openim-push.yml** | openim-push listen IP, port, and offline push settings |
| **openim-rpc-auth.yml** | openim-rpc-auth listen IP, port, token validity settings |
| **openim-rpc-conversation.yml** | openim-rpc-conversation listen IP and port settings |
| **openim-rpc-friend.yml** | openim-rpc-friend listen IP and port settings |
| **openim-rpc-group.yml** | openim-rpc-group listen IP and port settings |
| **openim-rpc-msg.yml** | openim-rpc-msg listen IP and port settings |


## Monitoring and Alerting Related Configurations
| Configuration File | Description |
| ------------------------------ | --------------- |
| **prometheus.yml** | Prometheus configuration |
| **instance-down-rules.yml** | Alert rules |
| **alertmanager.yml** | Alertmanager configuration |
| **email.tmpl** | Email alert template |
| **grefana-template/Demo.json** | Default Grafana dashboard |

## Common Configuration Modifications
| Configuration Item | Configuration File |
| -------------------------------------------------------- | ----------------------- |
| Configure MinIO as object storage (focus on the externalAddress field) | `minio.yml` |
| Adjust log level and number of log files | `log.yml` |
| Enable or disable friend verification when sending messages | `openim-rpc-msg.yml` |
| OpenIMServer secret | `share.yml` |
| Configure OSS, COS, AWS, or Kodo as object storage | `openim-rpc-third.yml` |
| Multi-end mutual kick strategy and max concurrent connections per gateway | `openim-msggateway.yml` |
| Offline message push configuration | `openim-push.yml` |
| Configure webhooks for callback notifications (e.g., before/after message send) | `webhooks.yml` |
| Whether new group members can view historical messages | `openim-rpc-group.yml` |
| Token expiration time settings | `openim-rpc-auth.yml` |
| Scheduled task settings (e.g., how long to retain messages) | `openim-crontask.yml` |

## Starting Multiple Instances of a Service and Maximum File Descriptors


To start multiple instances of an OpenIM service, simply add the corresponding port numbers and modify the `start-config.yml` file in the project’s root directory,
then restart the service. For example, to start 2 instances of `openim-rpc-user`:

```yaml
rpc:
Expand All @@ -55,9 +73,15 @@ prometheus:
ports: [ 20100, 20101 ]
```

Modify `start-config.yml`:
Modify`start-config.yml`:

```yaml
serviceBinaries:
openim-rpc-user: 2
```

To set the maximum number of open file descriptors (typically one per online user):

```
maxFileDescriptors: 10000
```
93 changes: 57 additions & 36 deletions config/README_zh_CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,45 +1,63 @@
# OpenIM配置文件说明以及常用配置修改说明

## 配置文件说明
## 外部组件相关配置

| Configuration File | Description |
| ------------------------------- | ------------------------------------------------------------ |
| **kafka.yml** | Kafka用户名、密码、地址等配置 |
| **redis.yml** | Redis密码、地址等配置 |
| **minio.yml** | MinIO用户名、密码、地址及外网IP域名等配置；未修改外网IP或域名可能导致图片文件发送失败 |
| **zookeeper.yml** | ZooKeeper用户、密码、地址等配置 |
| **mongodb.yml** | MongoDB用户名、密码、地址等配置 |
| **log.yml** | 日志级别及存储目录等配置 |
| **notification.yml** | 添加好友、创建群组等事件通知配置 |
| **share.yml** | OpenIM各服务所需的公共配置，如secret等 |
| **webhooks.yml** | Webhook中URL等配置 |
| **local-cache.yml** | 本地缓存配置 |
| **openim-rpc-third.yml** | openim-rpc-third服务的监听IP、端口及图片视频对象存储配置 |
| **openim-rpc-user.yml** | openim-rpc-user服务的监听IP、端口配置 |
| **openim-api.yml** | openim-api服务的监听IP、端口等配置项 |
| **openim-crontask.yml** | openim-crontask服务配置 |
| **openim-msggateway.yml** | openim-msggateway服务的监听IP、端口等配置 |
| **openim-msgtransfer.yml** | openim-msgtransfer服务配置 |
| **openim-push.yml** | openim-push服务的监听IP、端口及离线推送配置 |
| **openim-rpc-auth.yml** | openim-rpc-auth服务的监听IP、端口及token有效期等配置 |
| **openim-rpc-conversation.yml** | openim-rpc-conversation服务的监听IP、端口等配置 |
| **openim-rpc-friend.yml** | openim-rpc-friend服务的监听IP、端口等配置 |
| **openim-rpc-group.yml** | openim-rpc-group服务的监听IP、端口等配置 |
| **openim-rpc-msg.yml** | openim-rpc-msg服务的监听IP、端口及消息发送是否验证好友关系等配置 |
| Configuration File | Description |
| ------------------ | ---------------------------------- |
| **kafka.yml** | Kafka用户名、密码、地址等配置 |
| **redis.yml** | Redis密码、地址等配置 |
| **minio.yml** | MinIO用户名、密码、地址等配置 |
| **mongodb.yml** | MongoDB用户名、密码、地址等配置 |
| **discovery.yml** | 服务发现以及etcd用户名、密码、地址 |

## OpenIMServer相关配置
| Configuration File | Description |
| ------------------------------- | ---------------------------------------------- |
| **log.yml** | 日志级别及存储目录等配置 |
| **notification.yml** | 添加好友、创建群组等事件通知配置 |
| **share.yml** | 各服务所需的公共配置，如secret等 |
| **webhooks.yml** | Webhook中URL等配置 |
| **local-cache.yml** | 本地缓存配置，一般不用修改 |
| **openim-rpc-third.yml** | openim-rpc-third监听IP、端口及对象存储配置 |
| **openim-rpc-user.yml** | openim-rpc-user监听IP、端口配置 |
| **openim-api.yml** | openim-api监听IP、端口等配置 |
| **openim-crontask.yml** | openim-crontask定时任务配置 |
| **openim-msggateway.yml** | openim-msggateway监听IP、端口等配置 |
| **openim-msgtransfer.yml** | openim-msgtransfer服务配置 |
| **openim-push.yml** | openim-push监听IP、端口及离线推送配置 |
| **openim-rpc-auth.yml** | openim-rpc-auth监听IP、端口及token有效期等配置 |
| **openim-rpc-conversation.yml** | openim-rpc-conversation监听IP、端口等配置 |
| **openim-rpc-friend.yml** | openim-rpc-friend监听IP、端口等配置 |
| **openim-rpc-group.yml** | openim-rpc-group监听IP、端口等配置 |
| **openim-rpc-msg.yml** | openim-rpc-msg服务的监听IP、端口等配置 |


## 监控告警相关配置
| Configuration File | Description |
| ------------------------------ | --------------- |
| **prometheus.yml** | prometheus配置 |
| **instance-down-rules.yml** | 告警规则 |
| **alertmanager.yml** | 告警管理配置 |
| **email.tmpl** | 邮件告警模版 |
| **grefana-template/Demo.json** | 默认的dashboard |

## 常用配置修改
| 修改配置项 | 配置文件 |
| -------------------------------------------------------- | ----------------------- |
| 使用minio作为对象存储时配置，重点关注externalAddress字段 | `minio.yml` |
| 日志级别及日志文件数量调整 | `log.yml` |
| 发送消息是否需要验证好友关系 | `openim-rpc-msg.yml` |
| OpenIMServer秘钥 | `share.yml` |
| 使用oss, cos, aws, kodo作为对象存储时配置 | `openim-rpc-third.yml` |
| 多端互踢策略，单个gateway同时最大连接数 | `openim-msggateway.yml` |
| 消息离线推送 | `openim-push.yml` |
| 配置webhook来通知回调服务器，如消息发送前后回调 | `webhooks.yml` |
| 新入群用户是否可以查看历史消息 | `openim-rpc-group.yml` |
| token 过期时间设置 | `openim-rpc-auth.yml` |
| 定时任务设置，例如消息保存多长时间 | `openim-crontask.yml` |

| 修改配置项 | 配置文件 |
| ----------------------------------------------- | ----------------------- |
| 使用minio作为图片视频文件对象存储 | `minio.yml` |
| 生产环境日志调整 | `log.yml` |
| 发送消息是否验证好友关系 | `openim-rpc-msg.yml` |
| 修改secret | `share.yml` |
| 使用oss, cos, aws, kodo作为图片视频文件对象存储 | `openim-rpc-third.yml` |
| 设置多端互踢策略 | `openim-msggateway.yml` |
| 设置离线推送 | `openim-push.yml` |
## 启动某个服务的多个实例和最大文件句柄数

## 启动某个OpenIM服务的多个实例

若要启动某个OpenIM的多个实例，只需增加对应的端口数，并修改项目根目录下的`start-config.yml`文件，重启服务即可生效。例如，启动2个`openim-rpc-user`实例的配置如下：

Expand All @@ -61,5 +79,8 @@ serviceBinaries:
openim-rpc-user: 2
```

修改最大同时打开的文件句柄数，一般是每个在线用户占用一个


```
maxFileDescriptors: 10000
```