diff --git a/docs/guides/gettingStarted/cluster.md b/docs/guides/gettingStarted/cluster.md index dafad29060..7d81716e32 100644 --- a/docs/guides/gettingStarted/cluster.md +++ b/docs/guides/gettingStarted/cluster.md @@ -5,9 +5,9 @@ sidebar_position: 5 -# 同一内网下IMServer源码集群部署指南 +# 同一内网下 OpenIMServer 源码集群部署指南 -本文以A、B两台机器（内网 IP 分别为 `IP_A` 和 `IP_B`）为例，它们位于同一内网环境中，用于部署集群版 IM Server 与 Nginx。 +本文以 A、B 两台机器（内网 IP 分别为 `IP_A` 和 `IP_B`）为例，它们位于同一内网环境中，用于部署集群版 OpenIMServer 与 Nginx。 假设您已部署 Redis 集群、MongoDB 分片集群、Kafka 集群及 Etcd 集群，具体地址如下： - **Redis 集群地址**: `redisAddr1`, `redisAddr2`, `redisAddr3` - **MongoDB 集群地址**: `mongoAddr1`, `mongoAddr2`, `mongoAddr3` @@ -38,15 +38,22 @@ A 和 B 两台机器以及组件集群内网互通，且A、B两台机器都有 - **Etcd 集群** - **MinIO 服务** +> 本文仅覆盖两台 OpenIMServer 业务节点与 Nginx 的部署，不包含 Redis/MongoDB/Kafka/Etcd 集群本身的搭建过程。若当前只有两台空机器，请先完成这些外部组件集群的部署后再继续本文步骤。 + ### 1. 克隆仓库 -在两台机器（A 和 B）上分别执行以下命令以克隆 `open-im-server` 仓库： +在两台机器（A 和 B）上分别执行以下命令以克隆 OpenIMServer 仓库，并切到 GitHub Releases 页面绿色 **Latest** 对应的**最新正式发布 tag**： ```bash 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" ``` +> 这里的 latest 指 GitHub Releases 页面绿色 Latest 的**正式发布版**，不包含 alpha/beta/rc 等预发布版本。建议两台机器使用同一个正式版 tag；如需固定版本（例如 `v3.8.3-patch.12`），请在两台机器都执行 `git checkout v3.8.3-patch.12`。 + ### 2. 配置修改 在机器 A 和 B 上，按照以下步骤修改配置文件，确保各组件正确连接。所有地址字段均采用单行列表格式 `address: [addr1, addr2, addr3]`。 @@ -113,19 +120,19 @@ http { } upstream im_api { - # IM API 服务器地址，可根据部署情况指定多个 + # OpenIMServer API addresses; add more upstreams if needed server IP_A:10002; server IP_B:10002; } server { listen 443 ssl; - server_name yourhost.com; # 替换为您的域名 + server_name yourhost.com; # Replace with your domain - ssl_certificate /usr/local/nginx/conf/ssl/your_host_bundle.pem; # 替换为您的证书路径 - ssl_certificate_key /usr/local/nginx/conf/ssl/your_host.key; # 替换为您的证书密钥路径 + ssl_certificate /usr/local/nginx/conf/ssl/your_host_bundle.pem; # Replace with your certificate path + ssl_certificate_key /usr/local/nginx/conf/ssl/your_host.key; # Replace with your private key path - location ^~/api/ { + location ^~ /api/ { proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "Upgrade"; @@ -145,10 +152,10 @@ http { } } - # 可选: HTTP 重定向到 HTTPS + # Optional: redirect HTTP to HTTPS server { listen 80; - server_name yourhost.com; # 替换为您的域名 + server_name yourhost.com; # Replace with your domain return 301 https://$host$request_uri; } @@ -172,6 +179,15 @@ $ go env -w GOPROXY=https://goproxy.cn,direct ``` #### 5.1 编译 + +首次在每台机器执行前，建议先运行： + +```bash +bash bootstrap.sh +``` + +该步骤会安装 `mage`。如果你的机器已预装 `mage`，可跳过。 + ```bash mage ``` @@ -188,4 +204,3 @@ mage start 1. 部署`kafka`时，需要修改`kafka`广播的端口。如果使用`open-im-server`中的`docker-compose.yml`部署，修改`service.kafka.environment.KAFKA_CFG_ADVERTISED_LISTENERS`中的`EXTERNAL`为访问`kafka`组件的地址。其他部署方式请自行修改。 例如：`KAFKA_CFG_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092,EXTERNAL://192.168.2.36:19094`。 2. 多台机器部署需要保证时钟一致，服务才可正常运行。如`token`的签发允许各个机器的时钟误差在`5s`以内。 - diff --git a/docs/guides/gettingStarted/dockerCompose.md b/docs/guides/gettingStarted/dockerCompose.md index a6fa650b05..5885aa775a 100644 --- a/docs/guides/gettingStarted/dockerCompose.md +++ b/docs/guides/gettingStarted/dockerCompose.md @@ -6,16 +6,24 @@ sidebar_position: 2 ## 1.环境准备 🌍 对于服务器硬件、软件、操作系统、以及所依赖组件请参考[此文档](./env-comp) -## 2. 部署 IMServer +## 2. 部署 OpenIMServer ### 2.1 仓库克隆 🗂️ +建议使用 GitHub Releases 页面绿色 **Latest** 对应的**最新正式发布 tag**，不要直接按 tag 名字排序，也不要使用 alpha/rc 等预发布版本。 + ```bash git clone https://github.com/openimsdk/openim-docker && cd openim-docker +git fetch --tags +LATEST_STABLE_TAG=$(basename "$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/openimsdk/openim-docker/releases/latest)") +git checkout "$LATEST_STABLE_TAG" +echo "using openim-docker stable release tag: $LATEST_STABLE_TAG" ``` +> 这里的 latest 指 GitHub Releases 页面绿色 Latest 的**正式发布版**，不包含 alpha/beta/rc 等预发布版本。`main` 为开发版分支，生产环境不要直接使用 `main`。 + ### 2.2 配置修改 🔧 -- 修改 `.env` 文件，配置MinIO外网 IP，以支持发送图片视频文件，其中your-server-ip为服务端外网IP +- 修改 `.env` 文件，配置 MinIO 外网 IP，以支持发送图片和文件，其中 `your-server-ip` 为服务端外网 IP。 ```plaintext MINIO_EXTERNAL_ADDRESS="http://your-server-ip:10005" @@ -31,6 +39,12 @@ git clone https://github.com/openimsdk/openim-docker && cd openim-docker docker compose up -d ``` +> 首次执行会拉取较大的镜像，耗时可能较长。启动完成后建议等待 `30-60s`，再执行健康检查或接口验证。 + +> 本文档默认在**干净环境**下启动。如果机器上已经存在同名容器（如 `mongo`、`redis`、`kafka`、`etcd`、`minio`、`openim-server`、`openim-chat`），`docker compose up -d` 会因为 `container_name` 冲突而失败。此时应先停掉并删除同名容器，或改用已存在组件并调整配置。 + +> 如果启动时看到 `ETCD_USERNAME`、`ETCD_PASSWORD`、`KAFKA_USERNAME`、`KAFKA_PASSWORD` 未设置的 warning，而你并未启用这些组件的鉴权，这类提示通常可以忽略。 + - 停止服务： @@ -44,9 +58,26 @@ docker compose down docker logs -f openim-server ``` +### 2.4 监控告警（可选） + +如需同时启动 `Prometheus`、`Alertmanager`、`Grafana`、`node-exporter`，可执行： + +```bash +docker compose --profile m up -d +``` + +默认端口以当前 `.env` 为准，常用值如下： + +- `19090`：Prometheus +- `19093`：Alertmanager +- `13000`：Grafana +- `19100`：node-exporter + ## 3. 快速体验 ⚡ -快速体验 OpenIMSDK 核心能力，并测试部署是否正常，请参考[快速验证](./quickTestServer)。 +快速体验 OpenIMSDK 核心能力，并测试 OpenIMServer/ChatServer 部署是否正常，请参考[快速验证](./quickTestServer)。 + +> 补充（基于当前项目目录）：如果你是按 `open-im-server` + `chat` 两个源码仓库部署，`open-im-server/docker-compose.yml` 主要用于依赖组件，ChatServer 仍需在 `chat` 目录执行 `mage start`。可参考[源码部署](./imSourceCodeDeployment)。 ## 4. 常见问题 @@ -54,7 +85,8 @@ docker logs -f openim-server ### unhealthy定位 1. 执行 `docker exec -it openim-server mage check` 确认是否超过一分钟； 2. 执行 docker logs -f openim-server 查看日志； +3. 如果 `openim-chat` 在启动初期短暂报 `connect: connection refused`，先等待 `30-60s` 后再复查健康状态；这通常是依赖 `openim-server` 尚未完全就绪导致的启动时序现象。 ### 配置项修改 进入容器修改config目录下的修改配置文件无效！ -必须采用环境变量的方式修改配置，参考[设置环境变量指南](https://github.com/openimsdk/openim-docker/issues/136)。 \ No newline at end of file +必须采用环境变量的方式修改配置，参考[设置环境变量指南](https://github.com/openimsdk/openim-docker/issues/136)。 diff --git a/docs/guides/gettingStarted/env-comp.md b/docs/guides/gettingStarted/env-comp.md index f6a6030a32..a3af137f86 100644 --- a/docs/guides/gettingStarted/env-comp.md +++ b/docs/guides/gettingStarted/env-comp.md @@ -5,34 +5,40 @@ sidebar_position: 1 # 🧩 平台及组件要求 ---- - -## 🌐 操作系统及硬件 - -| 系统及硬件 | 详细说明 | -| --- | --- | -| **操作系统** | 支持 Linux、Windows、macOS 系统 | -| **硬件资源** | 4核CPU 8GB内存 10M带宽 100GB硬盘 以上| - - - - -## 🌐 软件 -| 软件 | 详细说明 | -| --- | --- | -| **Golang** | v1.21 或更高版本，[安装参考](https://go.dev/learn/) | -| **Docker** | v24.0.5 或更高版本，[安装参考](https://www.docker.com/get-started/) | -| **Git** | v2.17.1 或更高版本，[安装参考](https://git-scm.com/downloads) | - -## 💾 组件要求 - -| 存储组件 | 建议版本 | -| --- | --- | -| **MongoDB** | v7.0 | -| **Redis** | v7.0.0 | -| **Etcd** | v3.5.13 | -| **Kafka** | v3.5.1 | -| **MinIO** | RELEASE.2024-01-11T07-46-16Z | +## 一、名词约定 + +- **OpenIMSDK**：项目统称，包含 OpenIMClientSDK 与 OpenIMServer。 +- **OpenIMClientSDK**：客户端 SDK。 +- **OpenIMServer**：IM 基础服务端。 +- **ChatServer**：业务扩展服务端，文档中不再使用 `Chat` 作为独立产品名称。 +- **APP 管理员**：调用管理类接口（如 `10009`）的后台管理角色。 + +## 二、版本与分支策略 + +- `main`：开发版分支，用于持续集成未发布变更，不建议直接用于生产环境。 +- `vX.Y.Z...`：稳定版发布版本命名。 +- 生产环境建议优先使用 GitHub Releases 页面绿色 **Latest** 对应的**最新正式发布版**。 +- 如需问题复现、灰度回滚或多环境统一，请固定到明确的稳定版本 tag。 + +## 三、环境要求 + +| 注意事项 | 详细说明 | 补充说明 | +| --- | --- | --- | +| 操作系统 | Linux | 官方使用 `ubuntu 22.04`，实测 `Debian 13` 也可运行 | +| 硬件资源 | 8核16G，10M带宽，1T磁盘 | 按 10 万注册用户、10% 日常在线、5 万大群、每秒 600 条消息估算；需有外网 IP | +| CPU 架构 | `x86_64` | arm 架构需自行测试 | +| Golang | `v1.22.7` 或更高版本 | [安装参考](https://go.dev/learn/) | +| Docker | `v24.0.5` 或更高版本 | 自带 `compose` 功能 | +| Git | `v2.17.1` 或更高版本 | [安装参考](https://git-scm.com/downloads) | + +## 四、外部组件要求 + +| 组件 | 建议版本 | 支持模式 | 支持云服务 / 备注 | +| --- | --- |----------------------------------- |-------------------------------------------------| +| MongoDB | `v7.0` | `standalone`、`replicaSet`、`sharded` | 支持；如接副本集或分片集群，建议优先使用 `uri` | +| Redis | `v7.0.0` | `standalone`、`cluster`、`sentinel` | 支持 | +| Etcd | `v3.5.13` | 单机、多节点集群 | 不支持云服务 | +| Kafka | `v3.5.1` | 单机、分布式集群 | 支持；需按文档预建 topic | +| MinIO | `RELEASE.2024-01-11T07-46-16Z` | 单机 | 可替换为 S3 兼容存储（`COS`、`OSS`、`Kodo`(社区维护)、`AWS S3`） | --- - diff --git a/docs/guides/gettingStarted/faq.md b/docs/guides/gettingStarted/faq.md index bc22fc43fe..584acadf4c 100644 --- a/docs/guides/gettingStarted/faq.md +++ b/docs/guides/gettingStarted/faq.md @@ -5,7 +5,7 @@ sidebar_position: 10 ## 一、如何升级 -在同一大版本内，不同小版本之间的数据是兼容的。例如，版本 **3.8.0** 的数据可以在升级到 **3.8.2** 后正常运行。本文将重点介绍这种升级情况的具体操作步骤。 +在同一大版本内，不同小版本之间的数据通常兼容。建议优先升级到目标仓库 GitHub Releases 页面绿色 **Latest** 对应的**最新正式发布 tag**；如需固定版本（例如 `v3.8.3-patch.12`），请显式 checkout 对应 tag。 ### Docker 部署 @@ -14,22 +14,24 @@ sidebar_position: 10 cd openim-docker ``` -2. **编辑 `.env` 文件，修改相应的镜像标签（tag）。例如，将：** - ```env - OPENIM_SERVER_IMAGE=openim/openim-server:release-v3.8.0 - ``` - **修改为：** - ```env - OPENIM_SERVER_IMAGE=openim/openim-server:release-v3.8.2 +2. **拉取最新正式版 release tag 并切换：** + ```bash + git fetch --tags + TARGET_TAG=$(basename "$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/openimsdk/openim-docker/releases/latest)") + git checkout "$TARGET_TAG" + echo "upgrade openim-docker to stable release tag: $TARGET_TAG" ``` -3. **停止现有的 Docker 服务：** +3. **检查 `.env` 中镜像 tag 与当前仓库版本一致（必要时按发布说明手动调整）。** + +4. **停止现有的 Docker 服务：** ```bash docker compose down ``` -4. **启动更新后的 Docker 服务：** +5. **启动更新后的 Docker 服务：** ```bash + docker compose pull docker compose up -d ``` @@ -46,9 +48,11 @@ sidebar_position: 10 mage stop ``` -3. **切换分支并更新代码：** +3. **切换到最新正式版 release tag（或指定 tag）并更新代码：** ```bash - git pull + git fetch --tags + TARGET_TAG=$(basename "$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/openimsdk/open-im-server/releases/latest)") + git checkout "$TARGET_TAG" ``` 4. **编译并启动服务：** @@ -57,11 +61,15 @@ sidebar_position: 10 mage start ``` +5. **如果部署了 ChatServer，也建议同步升级到对应 tag 后再重启 ChatServer。** + +> 说明：这里的 latest 指 GitHub Releases 页面绿色 Latest 的**正式发布版**，不包含 alpha/beta/rc 等预发布版本。 + --- ## 二、 如何迁移数据 -在使用`docker compose up -d`命令启动`IMServer`依赖的各个组件之后，`IMServer`根目录下会生成一个`components`的文件夹，`IMServer`运行后产生的数据（如用户、群聊、消息等等）都保存在这个文件夹中。如果需要迁移数据，需要先关闭服务和组件： +在使用 `docker compose up -d` 启动组件后，当前部署仓库根目录下会生成一个 `components` 文件夹（例如 `openim-docker/components` 或 `open-im-server/components`）。运行后产生的数据（如用户、群聊、消息等）都保存在这个目录中。如果需要迁移数据，需要先关闭服务和组件： `docker`部署： @@ -72,8 +80,8 @@ docker compose down 源码部署： ```sh -mage stop # 关闭服务 -docker compose down # 关闭组件 +mage stop # Stop services +docker compose down # Stop components ``` 然后移动整个文件夹到数据目录，修改.env文件中DATA_DIR的值为新数据目录，再启动服务和组件： @@ -81,14 +89,14 @@ docker compose down # 关闭组件 `docker`部署： ```sh -docker compose up -d # 启动组 +docker compose up -d # Start components ``` 源码部署： ```sh -docker compose up -d # 启动组件 -mage start # 启动服务 +docker compose up -d # Start components +mage start # Start services ``` --- @@ -105,11 +113,11 @@ docker compose down 源码部署： ```sh -mage stop # 关闭服务 -docker compose down # 关闭组件 +mage stop # Stop services +docker compose down # Stop components ``` -然后删除`open-im-server`下的`components`文件夹。 +然后删除当前部署仓库下的 `components` 文件夹。 客户端方面需要重新卸载重装`app`。 @@ -117,15 +125,16 @@ docker compose down # 关闭组件 ## 四、 发送文本消息正常，但发送图片失败 一般发送图片失败是由于没有配置第三方存储的原因。默认使用的第三方存储为`minio`，需修改相关配置 -``` -源码部署： -修改 config/minio.yml 文件，配置MinIO外网 IP，以支持发送图片视频文件，其中your-server-ip为服务端外网IP -externalAddress="http://your-server-ip:10005" -``` +源码部署：修改 `config/minio.yml`，将 `externalAddress` 改为外网 IP 或域名路径。 + +```yaml +externalAddress: http://your-server-ip:10005 ``` -docker部署 -修改 .env 文件，配置MinIO外网 IP，以支持发送图片视频文件，其中your-server-ip为服务端外网IP + +Docker 部署：修改 `.env`，将 `MINIO_EXTERNAL_ADDRESS` 改为外网 IP 或域名路径。 + +```dotenv MINIO_EXTERNAL_ADDRESS="http://your-server-ip:10005" ``` --- @@ -134,12 +143,14 @@ MINIO_EXTERNAL_ADDRESS="http://your-server-ip:10005" 如果是是使用`docker`部署的各个组件，可以通过在`docker-compose.yml`文件中限制`mongo`和`kafka`的内存的方式来减小内存的占用。 -`mongo`： +`mongo`（`openim-docker` 中的服务名）或 `mongodb`（`open-im-server` 中的服务名）： + +> 如果你使用源码部署，请把下面示例中的 `mongo` 替换为 `mongodb`。 ```yml - mongodb: + mongo: environment: - - wiredTigerCacheSizeGB=0.5 # 修改为适当的值，单位GB + - wiredTigerCacheSizeGB=0.5 # Adjust to an appropriate value, unit: GB ``` `kafka`： @@ -147,7 +158,7 @@ MINIO_EXTERNAL_ADDRESS="http://your-server-ip:10005" ```yml kafka: environment: - KAFKA_HEAP_OPTS: "-Xms256m -Xmx256m" # 添加该限制 + KAFKA_HEAP_OPTS: "-Xms256m -Xmx256m" # Add this memory limit ``` --- diff --git a/docs/guides/gettingStarted/imSourceCodeDeployment.md b/docs/guides/gettingStarted/imSourceCodeDeployment.md index 1c60704f57..986142caf2 100644 --- a/docs/guides/gettingStarted/imSourceCodeDeployment.md +++ b/docs/guides/gettingStarted/imSourceCodeDeployment.md @@ -3,95 +3,205 @@ title: '源码部署' sidebar_position: 3 --- -# 🛠 源码部署 +# OpenIMServer 与 ChatServer 生产环境源码部署（单机） -## 1. 环境准备 +## 一、环境及组件要求 -对于服务器硬件、软件、操作系统、以及所依赖组件请参考[此文档](./env-comp) +OpenIMServer 与外部组件部署在同一台机器上，部分组件可按需使用云服务。 -## 2. 部署 IMServer +- 环境要求请先参考：[平台及组件要求](./env-comp) -### 2.1 clone仓库并切换到最新稳定版tag +## 二、获取 OpenIMServer 并部署依赖组件 -``` +建议通过仓库拉取并切到 GitHub Releases 页面绿色 **Latest** 对应的**最新正式发布 tag**。 + +```bash 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" ``` -### 2.2 部署组件 (mongodb/redis/kafka/MinIO/Etcd) -``` +> 这里的 latest 指 GitHub Releases 页面绿色 Latest 的**正式发布版**，不包含 alpha/beta/rc 等预发布版本。`main` 为开发版分支，生产环境不要直接使用 `main`。 + +> 注意：后续所有命令都在 OpenIMServer 项目根目录执行。 + +### 2.1 部署外部组件（Docker Compose） + +确保 `docker` 和 `docker compose` 已可用。 + +1. 如果本机已部署 `mongodb/redis/kafka/minio/etcd` 中一个或多个组件，或计划改用云服务（`etcd` 不支持云服务），可在 `docker-compose.yml` 注释对应组件。 +2. 强烈建议修改 `docker-compose.yml` 里的默认账号和密码。 + +| 组件 | 在 `docker-compose.yml` 中的位置 | +| --- | --- | +| MongoDB | `MONGO_INITDB_ROOT_USERNAME` `MONGO_INITDB_ROOT_PASSWORD` `MONGO_OPENIM_USERNAME` `MONGO_OPENIM_PASSWORD` | +| Redis | `redis-server --requirepass ...` | +| MinIO | `MINIO_ROOT_USER` `MINIO_ROOT_PASSWORD` | +| Etcd | `ETCD_ROOT_USER` `ETCD_ROOT_PASSWORD`（启用鉴权时） | +| Kafka | `KAFKA_USERNAME` `KAFKA_PASSWORD`（启用鉴权时） | + +3. 修改 `.env` 中的 `DATA_DIR`，指向大磁盘目录用于外部组件数据存储。 +4. 执行以下命令部署外部组件： + +```bash docker compose up -d ``` +> 当前 `open-im-server/docker-compose.yml` 除外部组件外，还会一并拉起 `openim-web-front`、`openim-admin-front`。如果你当前只想部署依赖组件，可以按需调整 compose 文件后再启动。 +### 2.2 自行部署组件或使用云服务时的初始化要求 -### 2.3 配置修改 🔧 +| 存储组件 | 初始化要求 | +| --- | --- | +| MongoDB | 预先创建数据库：`openim_v3` | +| Kafka | 预先创建 4 个 topic：`toRedis` `toMongo` `toPush` `toOfflinePush`，每个 topic 设置 8 个分区 | -- 修改 `config/minio.yml` 文件，配置MinIO外网 IP，以支持发送图片视频文件，其中your-server-ip为服务端外网IP +## 三、部署 OpenIMServer -```plaintext -externalAddress="http://your-server-ip:10005" - ``` +确保 Go 已正确安装。 +> `bootstrap.sh` 会尝试自动安装 `mage`，但前提是系统里已经有可用的 `go` 命令。因此如果 `go version` 不通过，后续 `bash bootstrap.sh`、`mage` 都无法执行。 +### 3.1 中国境内建议设置 Go 代理 -### 2.4 🛠️ 初始化下载mage +```bash +go env -w GO111MODULE=on +go env -w GOPROXY=https://goproxy.cn,direct +``` -第一次编译前，linux/mac 下执行： +### 3.2 初始化（仅执行一次） -``` +```bash bash bootstrap.sh ``` -windows 执行 +### 3.3 编译 -``` -bootstrap.bat +```bash +mage ``` +首次编译耗时较长，请耐心等待。 -中国境内建议设置go代理 -``` -$ go env -w GO111MODULE=on -$ go env -w GOPROXY=https://goproxy.cn,direct -``` +### 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 `secret` | `config/share.yml` | + +> `minio.yml` 的 `externalAddress` 必须改为外网 IP 或域名路径，否则 IM 无法正常发送图片和文件。 + +### 3.5 启动/停止/检测 + +| 任务 | 命令 | 说明 | +| --- | --- | --- | +| 后台启动 | `nohup mage start >> _output/logs/openim.log 2>&1 &` | 生产环境建议使用 | +| 停止 | `mage stop` | - | +| 检测 | `mage check` | - | + +> 首次启动后建议等待 `20-30s` 再执行 `mage check` 或接口验证，避免把启动过程中的短暂连接失败误判为最终异常。 + +## 四、获取 ChatServer -### 2.5 🛠️ 编译(linux/windows/mac 平台均可用) +> 如果已有自有账号体系，可不部署 ChatServer。 +同样建议拉取后切到 GitHub Releases 页面绿色 **Latest** 对应的**最新正式发布 tag**： +```bash +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 编译 + +```bash mage ``` -### 2.6 🚀 启动/停止/检测(linux/windows/mac 平台均可用) +### 5.2 基础配置修改 -``` -# 启动 -mage start -# 或 后台启动 收集日志 -nohup mage start >> _output/logs/openim.log 2>&1 & -# 停止 -mage stop -# 检测 -mage check -``` +| 描述 | 所在文件 | +| --- | --- | +| Redis 用户名、密码、地址 | `config/redis.yml` | +| Etcd 用户名、密码、地址 | `config/discovery.yml` | +| MongoDB 用户名、密码、地址 | `config/mongodb.yml` | +| OpenIMServer `secret` | `config/share.yml` | +| ChatServer `secret` | `config/chat-rpc-admin.yml` | +### 5.3 启动/停止/检测 +| 任务 | 命令 | 说明 | +| --- | --- | --- | +| 后台启动 | `nohup mage start >> _output/logs/chat.log 2>&1 &` | 生产环境建议使用 | +| 停止 | `mage stop` | - | +| 检测 | `mage check` | - | -## 3. 快速验证 +> ChatServer 启动时依赖 OpenIMServer 先可用，建议在 OpenIMServer `mage check` 正常后，再启动 ChatServer，并等待 `20-30s` 再验证 `10008/10009` 接口。 -请参考[快速验证](./quickTestServer)文档 +## 六、配置文件说明 ---- +- OpenIMServer 配置说明请以当前检出代码的 `config/README_zh_CN.md` 为准。 +- ChatServer 配置说明请以当前检出代码的 `config/README_zh_CN.md` 为准。 + +## 七、关于离线推送 + +- 个推：支持个推离线推送，按个推官方申请 `AppID`、`AppKey`、`MasterSecret` 后接入即可。 +- Firebase：修改 `config/openim-push.yml` 中 `fcm.filepath`。 + +## 八、服务实例个数修改（可选） + +在 `start-config.yml` 的 `serviceBinaries` 中，除 `openim-msggateway` 和 `openim-api` 外，其他服务可直接调整实例数。 + +对 `openim-msggateway` 与 `openim-api`： + +- 服务实例数要和对应配置文件里的端口数量保持一致。 +- 修改后重启服务生效。 + +## 九、监控告警（可选） + +待补充 + +## 十、重要指引 + +### 10.1 `secret` 修改 + +强烈建议修改默认 `secret`： + +- 至少 8 位 +- 数字 + 字母组合 +- 妥善保密 + +### 10.2 端口开放与客户端地址 -## 4. 常见问题 +不使用域名/SSL 时，端口开放与 SDK 地址请参考：[端口和防火墙](./ports) -### 4.1 📜 日志查看 +- `apiAddr: http://your_server_ip:10002` +- `wsAddr: ws://your_server_ip:10001` -IMServer日志位置： `_output/logs/openim-service-log.*` +使用域名/SSL 时，配置请参考：[域名及 SSL 证书配置](./nginxDomainConfig) -### 4.2 🚀 启动顺序 -启动顺序如下： -- 依赖的组件：mongodb/redis/kafka/minio/etcd -- IMServer +- 按部署要求修改域名解析，绑定 IP 与域名 +- 域名模式一般仅对外开放 `443` +- `apiAddr: https://your_domain.com/api` +- `wsAddr: wss://your_domain.com/msg_gateway` +### 10.3 单机生产环境数据备份及恢复 +请参考：[单机生产环境数据备份及恢复](./production) diff --git a/docs/guides/gettingStarted/internalDeployment.md b/docs/guides/gettingStarted/internalDeployment.md index 52d5e667b2..7c799923f8 100644 --- a/docs/guides/gettingStarted/internalDeployment.md +++ b/docs/guides/gettingStarted/internalDeployment.md @@ -2,123 +2,185 @@ title: '内网部署' sidebar_position: 4 --- + ## 📌 内网部署指南 -本指南将指导您在一台纯内网的机器上部署OpenIM相关服务。 +内网部署主流程：**在联网构建机执行 `mage export` 导出部署包，再拷贝到内网目标机运行**。 + + +## 一、版本与分支策略 + +- `main`：开发版分支，仅用于跟进未发布变更。 +- `vX.Y.Z...`：稳定版发布版本。 +- 内网生产环境建议统一使用 GitHub Releases 页面绿色 **Latest** 对应的**最新正式发布版**。 + +## 二、总体流程 + +1. 在**联网构建机**拉取 OpenIMServer / ChatServer 稳定版代码。 +2. 在联网构建机执行 `mage export`，生成可直接带走的部署归档。 +3. 将部署归档、配置文件、外部组件安装包拷贝到**内网目标机**。 +4. 在内网目标机解压部署归档，直接使用归档内自带的 `./mage` 启动和检查服务。 + +## 三、外部组件准备方式 + +OpenIMServer / ChatServer 的内网部署包只负责业务服务本身。外部组件（MongoDB、Redis、Kafka、Etcd、MinIO）有两种准备方式。 + +### 方案 A：目标机使用 Docker + +如果目标机尚未安装 Docker，建议在联网机器提前下载与目标机发行版、架构匹配的 Docker 离线安装包，再拷贝到内网目标机安装。 + +- Debian / Ubuntu：准备 `docker-ce`、`docker-ce-cli`、`containerd.io`、`docker-buildx-plugin`、`docker-compose-plugin` 对应的 `.deb` 包 +- RHEL / CentOS：准备上述组件对应的 `.rpm` 包 + +安装完成后，再通过 `docker load` 导入你提前保存好的外部组件镜像。 + +### 方案 B：目标机不使用 Docker + +可以直接将 MongoDB、Redis、Kafka、Etcd、MinIO 的官方二进制包或内部制品包拷贝到内网目标机，按各组件自己的 systemd / supervisor / 脚本方式启动。 + +这种模式下，OpenIMServer / ChatServer 只需要正确指向这些组件的地址与账号信息，不要求目标机安装 Docker。 + +## 四、联网构建机导出 OpenIMServer + +```bash +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" + +bash bootstrap.sh +PLATFORMS="linux_amd64" mage export +``` + +执行成功后，部署归档默认生成在： + +```text +_output/export/ +``` + +典型文件名示例： + +```text +exported_open-im-server_v3.8.3-patch.12_linux_amd64.tar.gz +``` + +## 五、联网构建机导出 ChatServer -### **Docker部署** +```bash +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" -1. 使用一台连接到互联网的机器，克隆仓库： +bash bootstrap.sh +PLATFORMS="linux_amd64" mage export +``` - ```sh - git clone https://github.com/openimsdk/openim-docker - ``` +典型文件名示例： -2. 运行`docker compose up -d`以拉取镜像。 +```text +exported_chat_v1.8.4-patch.3_linux_amd64.tar.gz +``` -3. 保存相应的镜像。命令如下： +## 六、部署包内容说明 - ```sh - docker save -o image-name.tar image-name:tag - ``` +`mage export` 生成的归档会包含： - 例如，需要保存`openim-server`镜像，命令应为： +- 已编译好的业务二进制 +- `start-config.yml` +- 运行所需配置文件 +- 可直接在目标机执行的 `mage` 启动器 - ```sh - docker save -o openim-server.tar openim/openim-server:release-v3.8.1 - ``` +因此，**内网目标机不需要再安装 Go，也不需要重新编译源码**。 - 保存`mongo`镜像，命令应为： +## 七、拷贝到内网目标机 - ```sh - docker save -o mongo.tar mongo:7.0 - ``` +将以下内容拷贝到内网目标机： - 可以使用`docker images`查看拉取的镜像信息，或者在`.env`文件中确认镜像的版本信息。 +- OpenIMServer 导出归档 +- ChatServer 导出归档 +- 外部组件镜像包或二进制安装包 +- 你的实际配置文件（如域名、外部组件地址、`secret`、MinIO `externalAddress`） - 所有需要保存的镜像为： +## 八、在内网目标机部署外部组件 - - `mongo:7.0` - - `redis:7.0.0` - - `bitnami/kafka:3.5.1` - - `minio/minio:RELEASE.2024-01-11T07-46-16Z` - - `quay.io/coreos/etcd:v3.5.13` - - `openim/openim-web-front:release-v3.8.1` - - `openim/openim-admin-front:release-v1.8.3` - - `openim/openim-server:release-v3.8.2` - - `openim/openim-chat:v1.8.2` +### 1. Docker 方式 - 以下为监控告警组件镜像，可根据需求选择性部署： +如果目标机使用 Docker： - - `prom/prometheus:v2.51.2` - - `prom/alertmanager:v0.27.0` - - `grafana/grafana:11.0.1` - - `prom/node-exporter:v1.7.0` +```bash +docker load -i image-name.tar +``` -4. 通过内网或者物理介质将**镜像文件**和**docker仓库文件**拷贝到部署机器上。 +导入完所有外部组件镜像后，再按你的组件编排文件启动。 -5. 导入镜像到`docker`中，命令为： - ```bash - docker load -i image-name.tar - ``` +### 2. 非 Docker 方式 - 例如`openim-server`镜像导入命令为： +如果目标机不用 Docker： - ```sh - docker load -i openim-server.tar - ``` +- 启动 MongoDB +- 启动 Redis +- 启动 Kafka +- 启动 Etcd +- 启动 MinIO -6. 在仓库目录下运行： - ```sh - docker compose up -d - ``` +然后把这些组件的地址、账号、密码写入 OpenIMServer / ChatServer 的配置文件。 - 需要启动监控组件则运行： - ```sh - docker compose --profile m up -d - ``` +## 九、在内网目标机解压并启动 OpenIMServer -### **源码部署** +```bash +mkdir -p /opt/openim/open-im-server +tar -xzf exported_open-im-server_v*.tar.gz -C /opt/openim/open-im-server +cd /opt/openim/open-im-server +``` -1. 使用一台连接到互联网的机器，克隆server仓库建议切换到 release-v3.8.2 分支： +修改配置文件中的外部组件地址、`secret`、MinIO `externalAddress` 后，执行： - ```sh - git clone https://github.com/openimsdk/open-im-server - ``` +```bash +./mage check +./mage start +./mage check +``` -2. 克隆`chat`仓库建议切换到 release-v1.8.3 分支 - ```bash - git clone https://github.com/openimsdk/chat - ``` +## 十、在内网目标机解压并启动 ChatServer -3. 参考[docker部署](#docker部署)步骤，保存镜像，区别为不需要`openim/openim-server:release-v3.8.2`和`openim/openim-chat:v1.8.2`。 +```bash +mkdir -p /opt/openim/chat +tar -xzf exported_chat_v*.tar.gz -C /opt/openim/chat +cd /opt/openim/chat +``` -4. 通过内网或者物理介质将**镜像文件**、**server仓库文件**、**chat仓库文件**拷贝到部署机器上。 +修改 ChatServer 配置文件中的 Redis、MongoDB、Etcd、OpenIMServer `secret` 后，执行： -5. 导入镜像到`docker`中，命令为： +```bash +./mage check +./mage start +./mage check +``` - ```bash - docker load -i image-name.tar - ``` +## 十一、运行时常用命令 - 例如`mongo`镜像导入命令为： +OpenIMServer： - ```sh - docker load -i mongo.tar - ``` +```bash +cd /opt/openim/open-im-server +./mage check +./mage stop +./mage start +``` -6. 在`server`目录下依次运行： - ```bash - docker compose up -d # 如需启用监控组件则为 docker compose --profile m up -d - mage - mage start - ``` +ChatServer： -7. 在`chat`目录下运行： - ```bash - mage - mage start - ``` +```bash +cd /opt/openim/chat +./mage check +./mage stop +./mage start +``` - +## 十二、内网部署注意事项 +1. `main` 是开发版，不要拿 `main` 做内网生产包。 +2. `mage export` 的目标机侧运行依赖已经随归档带出，因此不要再在目标机重新执行源码编译流程。 +3. 如果目标机与构建机架构不同，请在联网构建机通过 `PLATFORMS` 指定目标平台，例如 `PLATFORMS="linux_amd64" mage export` 或 `PLATFORMS="linux_arm64" mage export`。 +4. 外部组件无论使用 Docker 还是二进制拷贝方式，都需要先保证地址和鉴权信息与 OpenIMServer / ChatServer 配置一致。 diff --git a/docs/guides/gettingStarted/nginxDomainConfig.md b/docs/guides/gettingStarted/nginxDomainConfig.md index 71eb8f54cf..88824022d2 100644 --- a/docs/guides/gettingStarted/nginxDomainConfig.md +++ b/docs/guides/gettingStarted/nginxDomainConfig.md @@ -5,55 +5,53 @@ sidebar_position: 7 # 域名及 SSL 证书配置 -## 1. 前置条件 🛠️ +> 本页仅包含 OpenIMServer 与 ChatServer 相关域名配置。 -- **IMServer** 成功启动。 -- **Nginx** 已成功安装，包括 SSL 模块。 -- 申请域名（或子域名）及 SSL 证书，例如：`im.yourhost.com` ，用于 IMServer。 -- 开放 443端口。 +## 1. 前置条件 -## 2. 域名配置模板 📝 +- OpenIMServer、ChatServer 已成功启动。 +- Nginx 已安装并启用 SSL 模块。 +- 已申请域名和 SSL 证书（示例：`im.yourhost.com`）。 +- 服务器已放行 `443` 端口。 -> 🚀 **提示**: 确保替换成您的实际域名、SSL 证书路径和 SSL 密钥。 +如果系统尚未安装 Nginx，可先通过发行版包管理器安装（例如 Debian/Ubuntu：`apt-get install -y nginx`）。 -```nginx +## 2. Nginx 配置模板 + +> 请替换为你的实际域名、证书路径与服务地址。下面的注释说明了每一段配置的作用，建议直接按注释逐项替换。 -upstream msg_gateway{ - #IM Message server address Multiple can be specified according to the deployment +```nginx +upstream msg_gateway { + # OpenIMServer WebSocket gateway server 127.0.0.1:10001; } -upstream im_api{ - #IM Group user api server address Multiple can be specified according to the deployment + +upstream im_api { + # OpenIMServer REST API server 127.0.0.1:10002; } -upstream minio_s3_2{ - #Minio address can be assigned to multiple modules dependingon deployment - server 127.0.0.1:10005; +upstream im_chat_api { + # ChatServer API + server 127.0.0.1:10008; } +upstream minio_s3 { + # MinIO object storage + server 127.0.0.1:10005; +} server { - listen 443; #Listening on port 443 - server_name im.yourhost.com; #Your domain - ssl on; - #Path of pem file for ssl certificate - ssl_certificate /usr/local/nginx/conf/ssh/im.yourhost.com_bundle.pem; - #Key file path of ssl certificate - ssl_certificate_key /usr/local/nginx/conf/ssh/im.yourhost.com.key; - - gzip on; - gzip_min_length 1k; - gzip_buffers 4 16k; - gzip_comp_level 2; - gzip_types text/plain application/javascript application/x-javascript text/css application/xml text/javascript application/x-httpd-php image/jpeg image/gif image/png application/wasm; - gzip_vary off; - gzip_disable "MSIE [1-6]\."; - - default_type application/wasm; - - - location /msg_gateway{ + # Unified external HTTPS entry + listen 443 ssl; + server_name im.yourhost.com; + + # SSL certificate and private key paths + ssl_certificate /usr/local/nginx/conf/ssl/im.yourhost.com_bundle.pem; + ssl_certificate_key /usr/local/nginx/conf/ssl/im.yourhost.com.key; + + location /msg_gateway { + # OpenIMServer WebSocket reverse proxy; keep the Upgrade headers proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "Upgrade"; @@ -62,7 +60,8 @@ server { proxy_pass http://msg_gateway/; } - location ^~/api/{ + location ^~ /api/ { + # OpenIMServer REST API reverse proxy proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "Upgrade"; @@ -72,42 +71,71 @@ server { proxy_pass http://im_api/; } + location ^~ /chat/ { + # ChatServer API reverse proxy + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "Upgrade"; + proxy_set_header X-real-ip $remote_addr; + proxy_set_header X-Forwarded-For $remote_addr; + proxy_pass http://im_chat_api/; + } - - location ^~/im-minio-api/ { + location ^~ /im-minio-api/ { + # MinIO file access reverse proxy; keep it consistent with externalAddress 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 $scheme; proxy_connect_timeout 300; - proxy_http_version 1.1; proxy_set_header Connection ""; chunked_transfer_encoding off; - proxy_pass http://minio_s3_2/; + proxy_pass http://minio_s3/; } +} +``` +## 3. MinIO 配置 +- 源码部署：修改 `config/minio.yml` 中 `externalAddress` +- Docker 部署：修改 `.env` 中 `MINIO_EXTERNAL_ADDRESS` -} +示例值： +```text +https://im.yourhost.com/im-minio-api +``` +## 4. 重载 Nginx +```bash +nginx -t +nginx -s reload ``` -## 3. Minio 配置 🗄️ +## 5. OpenIMClientSDK 初始化参数 -- **源码部署**: 修改 `config/minio.yml` 文件中的 `externalAddress`值为 `"https://im.yourhost.com/im-minio-api"`. -- **Docker部署**: 修改 `.env` 文件中的 `MINIO_EXTERNAL_ADDRESS` 值为 `"https://im.yourhost.com/im-minio-api"`. - -## 4. 启动 Nginx 🚀 +```text +apiAddr: https://im.yourhost.com/api +wsAddr: wss://im.yourhost.com/msg_gateway +``` -执行命令 `nginx -s reload` 以重载 Nginx 配置。 +## 6. 网关路径对照 +| 路径 | 服务 | +| --- | --- | +| `/api/*` | OpenIMServer API（10002） | +| `/msg_gateway` | OpenIMServer WS（10001） | +| `/chat/*` | ChatServer API（10008） | +| `/im-minio-api/*` | MinIO 对象存储（10005） | -## 5. 修改客户端 SDK 初始化参数 +## 7. 命名统一 -在客户端 SDK 中，配置初始化参数如下： +- OpenIMSDK：项目整体名称。 +- OpenIMClientSDK：客户端 SDK。 +- OpenIMServer：IM 基础服务。 +- ChatServer：业务扩展服务，即 APP 业务服务器。 +- 管理类 REST API 调用账号统一称为 APP 管理员。 -- `apiAddr`: `https://im.yourhost.com/api` -- `wsAddr`: `wss://im.yourhost.com/msg_gateway` +> 当前模板仅覆盖 OpenIMServer 与 ChatServer（APP 业务服务器）的常用对外入口；如果你需要将 APP 管理员接口统一走域名入口，请额外为 `10009` 配置对应的 `upstream` 和 `location`。 diff --git a/docs/guides/gettingStarted/ports.md b/docs/guides/gettingStarted/ports.md index f996b5a841..49e8e698a5 100644 --- a/docs/guides/gettingStarted/ports.md +++ b/docs/guides/gettingStarted/ports.md @@ -5,54 +5,46 @@ sidebar_position: 6 # 🔐 端口及防火墙 ---- +## 一、不使用域名及 SSL 证书 -## 📡 IM Server 端口 +以下端口需要在服务器放行，其他端口不要对外。 -以下端口需在防火墙中放行，以确保 IMServer 正常通信。 +| 模块 | 端口 | 说明 | 操作 | +| --- | --- | --- | --- | +| OpenIMServer | TCP:10001 | ws 协议，消息端口，用于 OpenIMClientSDK | 端口放行 | +| OpenIMServer | TCP:10002 | api 端口，如用户、好友、群组、消息等接口 | 端口放行 | +| OpenIMServer | TCP:10005 | MinIO 作为对象存储 | 端口放行 | +| ChatServer | TCP:10008 | APP 业务服务器接口，如注册、登录等 | 端口放行 | +| ChatServer | TCP:10009 | APP 管理员接口，如统计、封号等 | 端口放行 | +| Web 前端（可选） | TCP:11001 | PC Web 前端，快速验证页面访问时需要放行 | 按需放行 | +| Admin 前端（可选） | TCP:11002 | APP 管理员前端页面 | 按需放行 | -| TCP 端口 | 说明 | 操作 ⚙️ | -| --- | --- | --- | -| **10001** | WebSocket 消息端口，用于客户端 SDK 通信 | ✅ 放行 | -| **10002** | API 端口，提供用户、好友、群组、消息等接口 | ✅ 放行 | -| **10005** | 当使用 MinIO 存储时需开启（IMServer 默认使用 MinIO） | ✅ 放行 | +在客户端 SDK 中，初始化参数如下： ---- +```text +apiAddr: http://your_server_ip:10002 +wsAddr: ws://your_server_ip:10001 +``` -## 💻 Web 前端与管理后台端口 +## 二、使用域名及 SSL 证书 -| TCP 端口 | 说明 | 操作 ⚙️ | -| --- | --- | --- | -| **11001** | PC Web 端与管理后台前端资源端口 | ✅ 放行 | +以下端口需要在服务器放行，其他端口不要对外。 ---- - -## 📊 Grafana 监控端口 - -| TCP 端口 | 说明 | 操作 ⚙️ | +| 端口 | 说明 | 操作 | | --- | --- | --- | -| **13000** | Grafana 监控可视化端口 | ✅ 放行 | - ---- +| TCP:443 | HTTPS 默认网络端口 | 端口放行 | -> ⚠️ **提示：** -> 若服务器启用了防火墙（如 `ufw` 或 `firewalld`），请确保以上端口已放行。 -> 例如在 Linux 上使用命令： -> -> ```bash -> sudo ufw allow 10001:10005/tcp -> sudo ufw allow 11001/tcp -> sudo ufw allow 13000/tcp -> sudo ufw reload -> ``` -> +配置参考：[域名及 SSL 证书配置](./nginxDomainConfig) -使用在线端口检测工具（适合公网服务器） +请先完成域名解析，设置 IP 与域名绑定关系。 -你也可以使用网页工具检测，例如： +在客户端 SDK 中，初始化参数如下： -https://portchecker.co/ +```text +apiAddr: https://your_domain.com/api +wsAddr: wss://your_domain.com/msg_gateway +``` -https://www.yougetsignal.com/tools/open-ports/ +> 说明：监控、前端等其他服务端口建议仅内网开放，按实际部署需求控制暴露范围。 -在输入框中填入你的服务器公网 IP 和端口号，即可查看是否能被访问。 +> 如果你要按 [快速验证](./quickTestServer) 中的浏览器步骤直接访问 `11001`，则对应前端端口必须可达；若不需要前端页面验证，可不对外开放 `11001/11002`。 diff --git a/docs/guides/gettingStarted/faultRecovery.assets/0.png b/docs/guides/gettingStarted/production.assets/0.png similarity index 100% rename from docs/guides/gettingStarted/faultRecovery.assets/0.png rename to docs/guides/gettingStarted/production.assets/0.png diff --git a/docs/guides/gettingStarted/production.md b/docs/guides/gettingStarted/production.md index 34f14503ab..ea70d827e2 100644 --- a/docs/guides/gettingStarted/production.md +++ b/docs/guides/gettingStarted/production.md @@ -1,61 +1,93 @@ --- title: '生产环境' sidebar_position: 8 +slug: /gettingStarted/production --- +# 生产环境 +本文只描述生产环境**运行时故障**会造成的影响，以及对应的恢复方式。 +## 一、通用恢复顺序 -在生产环境中，通常会采用集群部署来保证组件和服务的高可用性。然而，在资源有限的情况下，一些开发者可能会选择在生产环境中进行单机部署（使用源码部署或`docker`容器）。本文将介绍在单机部署环境下如何进行数据备份、异常恢复，以及潜在的风险。 +1. 先恢复外部组件。 +2. 再恢复 OpenIMServer。 +3. 最后恢复 ChatServer。 -## 一、mongo定时数据备份 -IMServer核心数据存储在MongoDB中，因此备份MongoDB数据就能恢复大部分数据。在容器启动之前，设置mongo数据备份目录和定时任务。 -### 数据备份 +## 二、外部组件运行时故障 -IMServer服务的核心数据存储在MongoDB中，因此备份MongoDB数据就能恢复大部分数据。以下是备份的步骤： +| 组件故障 | 运行时影响 | 恢复方式 | +| --- | --- | --- | +| MongoDB 不可用 | OpenIMServer `10002` 可能仍可返回，但 ChatServer 与 APP 管理员接口常失败 | 先恢复 MongoDB；恢复后立即复测 `10002/10008/10009`，若仍异常，再重启 OpenIMServer / ChatServer | +| Redis 不可用 | OpenIMServer 鉴权链路异常；源码部署常见 `auth-rpc-service down`，Docker 一体化部署常见 Redis 连接或解析错误 | 先恢复 Redis；观察 `30-60s`，若 OpenIMServer 鉴权仍异常，再重启 OpenIMServer | +| Kafka 不可用 | 基础探针可能仍正常，但消息转发、推送链路会异常 | 先恢复 Kafka；恢复后补做消息发送、消费、推送闭环验证 | +| Etcd 不可用 | 已运行实例通常短时可继续服务，但服务重启阶段可能失败 | 先恢复 Etcd；如果服务注册未恢复，再重启 OpenIMServer / ChatServer | +| MinIO 不可用 | 文件上传下载失败；源码部署下基础探针通常仍可用，Docker 一体化部署下可能连带 `10002/10008/10009` 异常 | 先恢复 MinIO，并检查 `externalAddress`；若 Docker 一体化部署在 `30-60s` 后基础探针仍未恢复，再重启 OpenIMServer / ChatServer 服务栈 | -1. **修改备份目录** +### 外部组件恢复命令 - - `.env`文件中修改`MONGO_BACKUP_DIR`的路径，默认值为`components/backup/mongo/`。建议将备份目录设置为与`components`目录不同的磁盘路径，以避免同一磁盘故障导致原始数据和备份数据同时丢失。 -3. **定时备份配置** - - 配置Linux系统的定时备份任务，执行以下命令编辑crontab： - ```sh - crontab -e - ``` - - 添加如下定时任务，表示每天凌晨2点执行备份，并保存最新的2个备份文件。如果需要其他定时规则，请调整`cron`表达式： - ```sh - 0 2 * * * docker exec mongo mongodump --uri="mongodb://openIM:openIM123@localhost:27017/openim_v3" --out="/data/backup/$(expr $(date +\%s) / 86400 \% 2)" - ``` - - 使用`crontab -l`命令可以查看当前定时任务是否设置成功。 +`openim-docker` 部署： +```bash +cd /path/to/openim-docker +docker compose up -d mongo redis kafka etcd minio +``` +`open-im-server` 源码部署： -## 二、组件异常停止处理 +```bash +cd /path/to/open-im-server +docker compose up -d mongodb redis kafka etcd minio +``` -1. 如果 `mongo`、`redis`、`kafka`、`etcd` 等组件异常停止，首先尝试重启所有组件和 IMServer 服务。 +> `openim-docker` 默认服务名为 `mongo`，`open-im-server` 默认服务名为 `mongodb`。 -2. 如果由于数据问题（如磁盘故障、磁盘满等）导致服务启动失败，则先停止所有组件和 IMServer 服务。 - - 如果 `redis` 启动失败，删除 `components/redis/` 目录。 - - 如果 `kafka` 启动失败，删除 `components/kafka/` 目录。 - - 如果 `mongo` 启动失败 - - 1. 删除 `components/redis/` `components/mongodb/` `components/kafka/`目录 - - 2. 恢复备份数据 docker exec -it mongo mongorestore --uri="mongodb://openIM:openIM123@localhost:27017/openim_v3" /data/backup/your_backup_name/openim_v3 - - **your_backup_name 为0 或者1， 选择时间较新的那个目录** - - 如果 `etcd` 启动失败，删除 `components/etcd/` 目录。 +## 三、OpenIMServer 运行时故障 -3. 在进行上述操作后，重启所有组件和 IMServer 服务。 +| 服务故障 | 运行时影响 | 恢复方式 | +| --- | --- | --- | +| `openim-api` | `10002` 通常不可用 | 在 `open-im-server` 目录执行 `mage stop && mage start` | +| `openim-rpc-auth` | OpenIMServer 鉴权探针失败，ChatServer 探针可能仍可用 | 在 `open-im-server` 目录执行 `mage stop && mage start` | +| `openim-msggateway` | WebSocket 实时链路中断 | 在 `open-im-server` 目录执行 `mage stop && mage start` | +| `openim-msgtransfer` / `openim-push` | 消息链路、推送链路退化，基础探针不一定失败 | 在 `open-im-server` 目录执行 `mage stop && mage start`，恢复后补做消息闭环验证 | +| `openim-crontask` | 定时任务停止执行 | 在 `open-im-server` 目录执行 `mage stop && mage start` | -## 三、潜在风险 +OpenIMServer 恢复命令： -1. **单机部署风险** - 如果机器故障导致原始数据磁盘和备份磁盘都无法访问，则无法直接恢复数据。此时，可能需要通过运营商的快照服务来恢复数据。 +```bash +cd /path/to/open-im-server +mage check +mage stop +mage start +mage check +``` -2. **备份目录建议** - 为防止由于单一磁盘故障导致的数据丢失，建议将 `mongo` 的备份目录 `MONGO_BACKUP_DIR` 设置为与 `components` 目录分开的磁盘。 +## 四、ChatServer 运行时故障 -3. **数据恢复风险** - 恢复 MongoDB 数据时，备份时间之后的数据将会丢失。因此，备份频率过快可能会对 MongoDB 的性能造成较大的影响。 +| 服务故障 | 运行时影响 | 恢复方式 | +| --- | --- | --- | +| `chat-api` | APP 业务服务器接口 `10008` 通常不可用 | 在 `chat` 目录执行 `mage stop && mage start` | +| `chat-rpc` | ChatServer 核心业务调用失败，基础 HTTP 端口可能仍在 | 在 `chat` 目录执行 `mage stop && mage start` | +| `admin-api` | APP 管理员接口 `10009` 通常不可用，但 `10008` 可能仍可用 | 在 `chat` 目录执行 `mage stop && mage start` | +| `admin-rpc` | APP 管理员业务调用失败 | 在 `chat` 目录执行 `mage stop && mage start` | +| `bot-api` / `bot-rpc` | Bot 相关能力异常 | 在 `chat` 目录执行 `mage stop && mage start` | -4. **Redis 数据删除的影响** - 如果删除 Redis 中的数据，可能会导致 **消息未读数不正确**。 +ChatServer 恢复命令： +```bash +cd /path/to/chat +mage check +mage stop +mage start +mage check +``` + +## 五、恢复后确认 + +恢复完成后，至少确认以下三项： + +1. `mage check` 或 `docker ps` 正常。 +2. `10002`、`10008`、`10009` 三个基础探针恢复。 +3. Kafka、MinIO 场景补做消息与文件链路验证。 + +> OpenIMServer、ChatServer 的基础探针都必须带 `operationID` 请求头。 diff --git a/docs/guides/gettingStarted/quickTestServer.md b/docs/guides/gettingStarted/quickTestServer.md index 0f22d1546d..37826bf3e8 100644 --- a/docs/guides/gettingStarted/quickTestServer.md +++ b/docs/guides/gettingStarted/quickTestServer.md @@ -2,6 +2,7 @@ title: '快速验证' sidebar_position: 9 --- + ## 📌 一、部署服务端 请参考 [docker部署](./dockerCompose) 或 [源码部署](./imSourceCodeDeployment) 来进行部署。 @@ -12,20 +13,82 @@ sidebar_position: 9 参考 [端口和防火墙](./ports) -## 三、PC Web验证 - +## 📌 三、PC Web验证 :::tip -在浏览器中输入 `http://your_server_ip:11001` 来访问 PC Web。`your_server_ip` 为IMServer服务端`ip`地址。 +在浏览器中输入 `http://your_server_ip:11001` 来访问 PC Web。`your_server_ip` 为部署前端服务的服务器 IP 地址。 ::: +![PC Web Interface](./assets/pc-web.png) + +## 📌 四、服务进程验证 + +确认 OpenIMServer 与 ChatServer 进程状态正常。 + +```bash +docker ps | grep -E 'openim-server|openim-chat' +``` + +> `docker部署` 场景下，`openim-server` 与 `openim-chat` 在启动初期可能先显示 `health: starting`；建议等待 `20-30s`，确认状态进入 `healthy` 后再继续接口验证。 + +如果是源码部署，可执行： + +```bash +# Run in the open-im-server directory +mage check + +# Run in the chat directory +mage check +``` + +## 📌 五、域名与网关验证 + +使用域名和 SSL 时，建议直接调用实际接口确认 OpenIMServer 与 ChatServer（APP 业务服务器）网关路由可达。 + +```bash +curl -sS -X POST "https://your_domain/api/auth/get_admin_token" \ + -H "Content-Type: application/json" \ + -H "operationID: verify-openim" \ + -d '{"secret":"your_openim_secret","userID":"imAdmin"}' +``` + +```bash +curl -sS -X POST "https://your_domain/chat/application/latest_version" \ + -H "Content-Type: application/json" \ + -H "operationID: verify-chat" \ + -d '{}' +``` + +> 如果接口返回业务错误但已返回 JSON，通常也表示网关反向代理链路已通。 + +> 如果当前仅部署了服务端而未部署前端页面，则 `11001` 的 PC Web 验证不适用；该步骤主要用于 `docker部署` 默认前端镜像已启动，或你已自行部署 Web 前端的场景。 +如果要验证 WebSocket 网关，可使用任意 ws 客户端测试： -import Image3 from './assets/pc-web.png'; +```text +wss://your_domain/msg_gateway +``` -PC Web Interface +> 建议在生产环境统一通过 `443` 端口访问，OpenIMClientSDK 初始化时使用： +> - `apiAddr`: `https://your_domain/api` +> - `wsAddr`: `wss://your_domain/msg_gateway` +## 📌 六、非域名场景接口验证 +如果当前未配置域名和 SSL，可直接通过服务端 IP + 默认端口验证： +```bash +curl -sS -X POST "http://your_server_ip:10002/auth/get_admin_token" \ + -H "Content-Type: application/json" \ + -H "operationID: verify-openim-local" \ + -d '{"secret":"your_openim_secret","userID":"imAdmin"}' +``` +```bash +curl -sS -X POST "http://your_server_ip:10008/application/latest_version" \ + -H "Content-Type: application/json" \ + -H "operationID: verify-chat-local" \ + -d '{}' +``` +> ChatServer（APP 业务服务器）的 POST 接口同样要求 `operationID` 请求头；缺少该请求头会直接返回参数错误。 diff --git a/i18n/en/docusaurus-plugin-content-docs-guides/current.json b/i18n/en/docusaurus-plugin-content-docs-guides/current.json index 7ed0a6e8bb..d1c4d10295 100644 --- a/i18n/en/docusaurus-plugin-content-docs-guides/current.json +++ b/i18n/en/docusaurus-plugin-content-docs-guides/current.json @@ -8,8 +8,8 @@ "description": "The label for category 'Quick Start' in sidebar 'tutorialSidebar'" }, "sidebar.tutorialSidebar.category.快速部署": { - "message": "Quick Deploy", - "description": "The label for category 'Quick Deploy' in sidebar 'tutorialSidebar'" + "message": "Quick Deployment", + "description": "The label for category 'Quick Deployment' in sidebar 'tutorialSidebar'" }, "sidebar.tutorialSidebar.category.解决方案": { "message": "Solutions", diff --git a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/_category_.json b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/_category_.json index 114965e1bb..3a8c0c3daf 100644 --- a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/_category_.json +++ b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/_category_.json @@ -1,6 +1,6 @@ { "position": 2, - "label": "Quick Deploy", + "label": "Quick Deployment", "collapsible": true, "collapsed": true } diff --git a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/cluster.assets/prometheus0.png b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/cluster.assets/prometheus0.png new file mode 100644 index 0000000000..ee4b154327 Binary files /dev/null and b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/cluster.assets/prometheus0.png differ diff --git a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/cluster.assets/rpc0.png b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/cluster.assets/rpc0.png new file mode 100644 index 0000000000..2f901229f3 Binary files /dev/null and b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/cluster.assets/rpc0.png differ diff --git a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/cluster.md b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/cluster.md index 32a8cf1725..05490cd25e 100644 --- a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/cluster.md +++ b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/cluster.md @@ -5,55 +5,62 @@ sidebar_position: 5 -# IMServer Source Code Cluster Deployment Guide (Same LAN) +# OpenIMServer Source Code Cluster Deployment Guide on the Same Internal Network -This guide uses machines A and B (with internal IPs `IP_A` and `IP_B`) as an example. They are located in the same LAN environment, used for deploying the clustered IM Server and Nginx. -Assuming you have already deployed Redis cluster, MongoDB sharded cluster, Kafka cluster, and Etcd cluster at the following addresses: -- **Redis Cluster**: `redisAddr1`, `redisAddr2`, `redisAddr3` -- **MongoDB Cluster**: `mongoAddr1`, `mongoAddr2`, `mongoAddr3` -- **Kafka Cluster**: `kafkaAddr1`, `kafkaAddr2`, `kafkaAddr3` -- **Etcd Cluster**: `etcdAddr1`, `etcdAddr2`, `etcdAddr3` +This guide uses machines A and B (with internal IPs `IP_A` and `IP_B`) as examples. They are located in the same internal network and are used to deploy clustered OpenIMServer and Nginx. +Assume that you have already deployed a Redis cluster, MongoDB sharded cluster, Kafka cluster, and Etcd cluster with the following addresses: +- **Redis cluster addresses**: `redisAddr1`, `redisAddr2`, `redisAddr3` +- **MongoDB cluster addresses**: `mongoAddr1`, `mongoAddr2`, `mongoAddr3` +- **Kafka cluster addresses**: `kafkaAddr1`, `kafkaAddr2`, `kafkaAddr3` +- **Etcd cluster addresses**: `etcdAddr1`, `etcdAddr2`, `etcdAddr3` -These components should be deployed on three or more nodes to ensure high availability and load balancing. +It is recommended to deploy these components on three or more nodes to ensure high availability and load balancing. -Additionally, MinIO's internal access address is configured as `your_minio_internal_address`, and the external access address is `your_minio_external_address`. -Machines A and B, as well as the component clusters, have internal network connectivity. Both machines A and B also have public IPs. +In addition, MinIO is configured with `your_minio_internal_address` for internal access and `your_minio_external_address` for external access. +Machines A and B, as well as the component clusters, must be reachable over the internal network, and both A and B must have public IPs. ### Table of Contents 1. [Prerequisites](#prerequisites) -2. [Clone Repository](#1-clone-repository) +2. [Clone the Repository](#1-clone-the-repository) 3. [Modify Configuration](#2-modify-configuration) 4. [Configure Nginx](#3-configure-nginx) -5. [Set Up DNS](#4-set-up-dns) +5. [Configure DNS](#4-configure-dns) 6. [Start Services](#5-start-services) ### Prerequisites -Ensure the following components are properly deployed and running: +Ensure that the following components are already deployed and running correctly: -- **Redis Cluster** -- **MongoDB Sharded Cluster** -- **Kafka Cluster** -- **Etcd Cluster** -- **MinIO Service** +- **Redis cluster** +- **MongoDB sharded cluster** +- **Kafka cluster** +- **Etcd cluster** +- **MinIO service** -### 1. Clone Repository +> This document only covers deploying two OpenIMServer business nodes and Nginx. It does not include the deployment of the Redis / MongoDB / Kafka / Etcd clusters themselves. If you currently only have two empty machines, complete those external component clusters first before continuing. -On both machines (A and B), run the following commands to clone the `open-im-server` repository: +### 1. Clone the Repository + +Run the following commands on both machines (A and B) to clone the OpenIMServer repository and switch to the latest official release tag marked with the green **Latest** badge on GitHub Releases: ```bash 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" ``` +> Here, `latest` means the latest official release marked with the green **Latest** badge on GitHub Releases. It does not include alpha, beta, rc, or other pre-releases. It is recommended that both machines use the same stable tag. If you need a fixed version such as `v3.8.3-patch.12`, run `git checkout v3.8.3-patch.12` on both machines. + ### 2. Modify Configuration -On both machines A and B, modify the configuration files as follows to ensure all components are correctly connected. All address fields use the inline list format `address: [addr1, addr2, addr3]`. +On machines A and B, modify the configuration files as follows so that all components connect correctly. All address fields use the single-line list format `address: [addr1, addr2, addr3]`. #### 2.1 Kafka Configuration -Edit the `open-im-server/config/kafka.yml` file, setting the `address` field to the Kafka cluster address list: +Edit `open-im-server/config/kafka.yml` and set the `address` field to the Kafka cluster address list: ```yaml address: [kafkaAddr1, kafkaAddr2, kafkaAddr3] @@ -61,7 +68,7 @@ address: [kafkaAddr1, kafkaAddr2, kafkaAddr3] #### 2.2 MinIO Configuration -Edit the `open-im-server/config/minio.yml` file, setting `internalAddress` and `externalAddress`: +Edit `open-im-server/config/minio.yml` and set `internalAddress` and `externalAddress`: ```yaml internalAddress: your_minio_internal_address @@ -70,7 +77,7 @@ externalAddress: your_minio_external_address #### 2.3 MongoDB Configuration -Edit the `open-im-server/config/mongodb.yml` file, setting the `address` field to the MongoDB cluster address list: +Edit `open-im-server/config/mongodb.yml` and set the `address` field to the MongoDB cluster address list: ```yaml address: [mongoAddr1, mongoAddr2, mongoAddr3] @@ -78,7 +85,7 @@ address: [mongoAddr1, mongoAddr2, mongoAddr3] #### 2.4 Etcd Configuration -Edit the `open-im-server/config/discovery.yml` file, setting the `etcd.address` field to the Etcd cluster address list: +Edit `open-im-server/config/discovery.yml` and set `etcd.address` to the Etcd cluster address list: ```yaml etcd: @@ -87,7 +94,7 @@ etcd: #### 2.5 Redis Configuration -Edit the `open-im-server/config/redis.yml` file, setting the `address` field to the Redis cluster address list and enabling cluster mode: +Edit `open-im-server/config/redis.yml`, set `address` to the Redis cluster address list, and enable cluster mode: ```yaml address: [redisAddr1, redisAddr2, redisAddr3] @@ -96,9 +103,9 @@ clusterMode: true ### 3. Configure Nginx -Deploy `nginx` on both machines A and B using the following configuration. Make sure to replace with your actual domain name, SSL certificate path, and SSL key path. +Deploy `nginx` on machines A and B using the following configuration. Make sure to replace it with your actual domain, SSL certificate path, and SSL private key path. -> 🚀 **Tip**: Make sure to replace with your actual domain name, SSL certificate path, and SSL key. +> 🚀 **Tip**: Be sure to replace the example domain, SSL certificate path, and SSL key path with your actual values. ```nginx events { @@ -113,7 +120,7 @@ http { } upstream im_api { - # IM API server addresses — specify multiple based on your deployment + # OpenIMServer API addresses; add more upstreams if needed server IP_A:10002; server IP_B:10002; } @@ -123,9 +130,9 @@ http { server_name yourhost.com; # Replace with your domain ssl_certificate /usr/local/nginx/conf/ssl/your_host_bundle.pem; # Replace with your certificate path - ssl_certificate_key /usr/local/nginx/conf/ssl/your_host.key; # Replace with your certificate key path + ssl_certificate_key /usr/local/nginx/conf/ssl/your_host.key; # Replace with your private key path - location ^~/api/ { + location ^~ /api/ { proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "Upgrade"; @@ -145,7 +152,7 @@ http { } } - # Optional: HTTP to HTTPS redirect + # Optional: redirect HTTP to HTTPS server { listen 80; server_name yourhost.com; # Replace with your domain @@ -155,23 +162,32 @@ http { } ``` -Add this configuration to your `nginx` config file and reload to apply: +Add this configuration to the Nginx configuration file and reload it to apply the changes: -### 4. Set Up DNS +### 4. Configure DNS Point your domain `yourhost.com` to the public IP addresses of machines A and B. ### 5. Start Services -On both machines (A and B), run the following commands in the `open-im-server` directory to build and start the services: +Run the following commands in the `open-im-server` directory on both machines (A and B) to build and start the services: -For users in China, it is recommended to set a Go proxy: +For users in Mainland China, setting a Go proxy is recommended: ``` $ go env -w GO111MODULE=on $ go env -w GOPROXY=https://goproxy.cn,direct ``` #### 5.1 Build + +Before the first execution on each machine, it is recommended to run: + +```bash +bash bootstrap.sh +``` + +This step installs `mage`. If `mage` is already installed on your machine, you can skip it. + ```bash mage ``` @@ -183,8 +199,8 @@ mage start ``` -## **FAQ / Important Notes** +## **FAQ / Notes** -1. When deploying `Kafka`, you need to modify the Kafka advertised port. If using the `docker-compose.yml` from `open-im-server`, modify `service.kafka.environment.KAFKA_CFG_ADVERTISED_LISTENERS` where `EXTERNAL` should be set to the address for accessing the Kafka component. For other deployment methods, modify accordingly. - Example: `KAFKA_CFG_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092,EXTERNAL://192.168.2.36:19094`. -2. Multi-machine deployments require clock synchronization across machines for services to run correctly. For example, the `token` signing process allows a maximum clock skew of `5 seconds` between machines. +1. When deploying `kafka`, you need to modify the Kafka advertised port. If you use `docker-compose.yml` from `open-im-server`, change the `EXTERNAL` listener in `service.kafka.environment.KAFKA_CFG_ADVERTISED_LISTENERS` to the address used to access the `kafka` component. If you use another deployment method, adjust it accordingly. + For example: `KAFKA_CFG_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092,EXTERNAL://192.168.2.36:19094`. +2. In multi-machine deployment, the clocks of all machines must stay synchronized, or services may fail. For example, token issuing only tolerates clock drift within `5s`. diff --git a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/dockerCompose.md b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/dockerCompose.md index 49dc09a1ba..50f35e0ffe 100644 --- a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/dockerCompose.md +++ b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/dockerCompose.md @@ -3,26 +3,32 @@ title: 'Docker Deployment' sidebar_position: 2 --- -## 1. Prerequisites 🌍 -For server hardware, software, operating system, and component requirements, please refer to [this document](./env-comp). +## 1. Environment Preparation 🌍 +For server hardware, software, operating system, and dependent components, please refer to [this document](./env-comp). -## 2. Deploy IMServer +## 2. Deploy OpenIMServer ### 2.1 Clone the Repository 🗂️ +Use the latest official release tag marked with the green **Latest** badge on the GitHub Releases page. Do not sort tags manually, and do not use pre-release versions such as alpha or rc. + ```bash git clone https://github.com/openimsdk/openim-docker && cd openim-docker +git fetch --tags +LATEST_STABLE_TAG=$(basename "$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/openimsdk/openim-docker/releases/latest)") +git checkout "$LATEST_STABLE_TAG" +echo "using openim-docker stable release tag: $LATEST_STABLE_TAG" ``` -### 2.2 Modify Configuration 🔧 +> Here, `latest` means the latest official release marked with the green **Latest** badge on GitHub Releases. It does not include alpha, beta, rc, or other pre-releases. `main` is the development branch and should not be used directly in production. + +### 2.2 Configuration Changes 🔧 -- Edit the `.env` file to configure the MinIO external IP for sending images, videos, and files. Replace `your-server-ip` with your server's public IP address: +- Edit `.env` and configure the MinIO external IP to support image and file sending. Replace `your-server-ip` with your server's public IP. ```plaintext MINIO_EXTERNAL_ADDRESS="http://your-server-ip:10005" ``` - - ### 2.3 Start Services 🚀 - Start services: @@ -31,6 +37,11 @@ git clone https://github.com/openimsdk/openim-docker && cd openim-docker docker compose up -d ``` +> The first run pulls large images and may take some time. After startup, wait `30-60s` before running health checks or API verification. + +> This document assumes a **clean environment**. If the machine already has containers with the same names such as `mongo`, `redis`, `kafka`, `etcd`, `minio`, `openim-server`, or `openim-chat`, `docker compose up -d` will fail because of `container_name` conflicts. In that case, stop and remove those containers first, or reuse the existing components after adjusting configuration. + +> If startup shows warnings such as missing `ETCD_USERNAME`, `ETCD_PASSWORD`, `KAFKA_USERNAME`, or `KAFKA_PASSWORD`, and you have not enabled authentication for those components, these warnings can usually be ignored. - Stop services: @@ -44,17 +55,34 @@ docker compose down docker logs -f openim-server ``` -## 3. Quick Verification ⚡ +### 2.4 Monitoring & Alerting (Optional) + +If you also want to start `Prometheus`, `Alertmanager`, `Grafana`, and `node-exporter`, run: + +```bash +docker compose --profile m up -d +``` + +Default ports follow the current `.env`. Common values are: + +- `19090`: Prometheus +- `19093`: Alertmanager +- `13000`: Grafana +- `19100`: node-exporter + +## 3. Quick Experience ⚡ -To quickly test the core capabilities of OpenIMSDK and verify your deployment, refer to [Quick Verification](./quickTestServer). +To quickly experience core OpenIMSDK capabilities and verify whether OpenIMServer / ChatServer deployment is working, refer to [Quick Verification](./quickTestServer). +> Additional note for the current project layout: if you deploy from the two source repositories `open-im-server` and `chat`, `open-im-server/docker-compose.yml` is mainly used for dependency components, and ChatServer still needs to be started with `mage start` in the `chat` directory. See [Source Code Deployment](./imSourceCodeDeployment). ## 4. FAQ -### Troubleshooting Unhealthy Status -1. Run `docker exec -it openim-server mage check` and verify if it has been running for more than one minute. -2. Run `docker logs -f openim-server` to view logs. +### Troubleshooting `unhealthy` +1. Run `docker exec -it openim-server mage check` and confirm whether the state lasts longer than one minute. +2. Run `docker logs -f openim-server` to inspect logs. +3. If `openim-chat` briefly reports `connect: connection refused` during startup, wait `30-60s` and check again. This is usually a startup ordering issue while `openim-server` is still becoming ready. -### Modifying Configuration -Editing configuration files inside the `config` directory within the container has no effect! -You must use environment variables to modify configuration. Refer to the [Environment Variable Configuration Guide](https://github.com/openimsdk/openim-docker/issues/136). +### Configuration Changes +Editing files under the container `config` directory does not work. +Configuration changes must be made through environment variables. See the [environment variable guide](https://github.com/openimsdk/openim-docker/issues/136). diff --git a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/env-comp.md b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/env-comp.md index 414e3b358f..808697eaa8 100644 --- a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/env-comp.md +++ b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/env-comp.md @@ -5,33 +5,40 @@ sidebar_position: 1 # 🧩 Platform & Component Requirements ---- - -## 🌐 Operating System & Hardware - -| Requirement | Details | -| --- | --- | -| **Operating System** | Linux, Windows, macOS | -| **Hardware Resources** | 4-core CPU, 8 GB RAM, 10 Mbps bandwidth, 100 GB disk minimum | - - - - -## 🌐 Software -| Software | Details | -| --- | --- | -| **Golang** | v1.21 or higher, [Installation Guide](https://go.dev/learn/) | -| **Docker** | v24.0.5 or higher, [Installation Guide](https://www.docker.com/get-started/) | -| **Git** | v2.17.1 or higher, [Installation Guide](https://git-scm.com/downloads) | - -## 💾 Component Requirements - -| Component | Recommended Version | -| --- | --- | -| **MongoDB** | v7.0 | -| **Redis** | v7.0.0 | -| **Etcd** | v3.5.13 | -| **Kafka** | v3.5.1 | -| **MinIO** | RELEASE.2024-01-11T07-46-16Z | +## 1. Terminology + +- **OpenIMSDK**: The overall project name, including OpenIMClientSDK and OpenIMServer. +- **OpenIMClientSDK**: The client SDK. +- **OpenIMServer**: The IM core server. +- **ChatServer**: The business extension server. This documentation no longer uses `Chat` as a standalone product name. +- **APP Administrator**: The backend management role that calls management APIs such as `10009`. + +## 2. Version and Branch Strategy + +- `main`: The development branch for unreleased changes in continuous integration. It is not recommended for production. +- `vX.Y.Z...`: Stable release version naming. +- For production, prefer the latest official release marked with the green **Latest** badge on the GitHub Releases page. +- If you need reproducible troubleshooting, rollback, or multi-environment consistency, pin an explicit stable release tag. + +## 3. Environment Requirements + +| Item | Details | Notes | +| --- | --- | --- | +| Operating system | Linux | Officially uses `ubuntu 22.04`; `Debian 13` has also been verified to work | +| Hardware resources | 8 CPU cores, 16 GB RAM, 10 Mbps bandwidth, 1 TB disk | Estimated for 100k registered users, 10% daily online ratio, 50k-member large groups, and 600 messages per second; requires a public IP | +| CPU architecture | `x86_64` | ARM requires separate verification | +| Golang | `v1.22.7` or higher | [Installation reference](https://go.dev/learn/) | +| Docker | `v24.0.5` or higher | Must include `compose` support | +| Git | `v2.17.1` or higher | [Installation reference](https://git-scm.com/downloads) | + +## 4. External Component Requirements + +| Component | Recommended Version | Supported Modes | Cloud Support / Notes | +| --- | --- | --- | --- | +| MongoDB | `v7.0` | `standalone`, `replicaSet`, `sharded` | Supported; for replica sets or sharded clusters, `uri` is preferred | +| Redis | `v7.0.0` | `standalone`, `cluster`, `sentinel` | Supported | +| Etcd | `v3.5.13` | Single node, multi-node cluster | No managed cloud support | +| Kafka | `v3.5.1` | Single node, distributed cluster | Supported; create the required topics in advance according to the docs | +| MinIO | `RELEASE.2024-01-11T07-46-16Z` | Single node | Can be replaced with S3-compatible storage such as `COS`, `OSS`, `Kodo` (community-maintained), or `AWS S3` | --- diff --git a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/faq.md b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/faq.md index e6184c6b0b..5851092f4b 100644 --- a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/faq.md +++ b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/faq.md @@ -5,37 +5,39 @@ sidebar_position: 10 ## 1. How to Upgrade -Within the same major version, data is compatible across different minor versions. For example, data from version **3.8.0** will work correctly after upgrading to **3.8.2**. This section covers the specific upgrade steps for this scenario. +Within the same major version, data is usually compatible across minor versions. It is recommended to upgrade to the latest official release tag marked with the green **Latest** badge on GitHub Releases. If you need a fixed version (for example `v3.8.3-patch.12`), explicitly checkout that tag. ### Docker Deployment -1. **Navigate to the existing `openim-docker` directory:** +1. **Enter the existing `openim-docker` directory:** ```bash cd openim-docker ``` -2. **Edit the `.env` file and modify the image tag. For example, change:** - ```env - OPENIM_SERVER_IMAGE=openim/openim-server:release-v3.8.0 - ``` - **to:** - ```env - OPENIM_SERVER_IMAGE=openim/openim-server:release-v3.8.2 +2. **Fetch and switch to the latest official release tag:** + ```bash + git fetch --tags + TARGET_TAG=$(basename "$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/openimsdk/openim-docker/releases/latest)") + git checkout "$TARGET_TAG" + echo "upgrade openim-docker to stable release tag: $TARGET_TAG" ``` -3. **Stop the existing Docker services:** +3. **Check whether the image tags in `.env` match the current repository version, and adjust them manually according to the release notes if necessary.** + +4. **Stop the current Docker services:** ```bash docker compose down ``` -4. **Start the updated Docker services:** +5. **Start the upgraded Docker services:** ```bash + docker compose pull docker compose up -d ``` ### Source Code Deployment -1. **Navigate to the existing `open-im-server` directory:** +1. **Enter the existing `open-im-server` directory:** ```bash cd open-im-server @@ -46,9 +48,11 @@ Within the same major version, data is compatible across different minor version mage stop ``` -3. **Switch branch and update code:** +3. **Switch to the latest official release tag (or a specified tag) and update the code:** ```bash - git pull + git fetch --tags + TARGET_TAG=$(basename "$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/openimsdk/open-im-server/releases/latest)") + git checkout "$TARGET_TAG" ``` 4. **Build and start the service:** @@ -57,11 +61,14 @@ Within the same major version, data is compatible across different minor version mage start ``` +5. **If ChatServer is also deployed, it is recommended to upgrade ChatServer to the corresponding tag and then restart it as well.** + +> Here, `latest` means the latest official release marked with the green **Latest** badge on GitHub Releases. It does not include alpha, beta, rc, or other pre-releases. --- ## 2. How to Migrate Data -After starting each component that IMServer depends on using `docker compose up -d`, a `components` folder is generated in the IMServer root directory. All data produced by IMServer (such as users, groups, messages, etc.) is stored in this folder. To migrate data, first stop all services and components: +After starting components with `docker compose up -d`, a `components` directory is created in the current deployment repository root (for example `openim-docker/components` or `open-im-server/components`). Runtime data such as users, groups, and messages is stored there. If you need to migrate data, stop services and components first: `Docker` deployment: @@ -76,7 +83,7 @@ mage stop # Stop services docker compose down # Stop components ``` -Then move the entire folder to the new data directory, update the `DATA_DIR` value in the `.env` file to the new data directory path, and restart services and components: +Then move the entire folder to the new data directory, update the `DATA_DIR` value in `.env`, and start services and components again: `Docker` deployment: @@ -94,7 +101,7 @@ mage start # Start services --- ## 3. How to Clear Data -To clear all data, first stop all services and components: +If you need to clear all data, stop services and components first: `Docker` deployment: @@ -109,42 +116,44 @@ mage stop # Stop services docker compose down # Stop components ``` -Then delete the `components` folder under `open-im-server`. +Then delete the `components` directory under the current deployment repository. -On the client side, uninstall and reinstall the `app`. +On the client side, you need to uninstall and reinstall the app. --- ## 4. Text Messages Work but Image Sending Fails -Image sending failures are typically caused by unconfigured third-party object storage. The default object storage is `MinIO` — you need to modify the relevant configuration: -``` -Source code deployment: -Edit the config/minio.yml file and configure the MinIO external IP to support sending images, videos, and files. -Replace your-server-ip with your server's public IP. -externalAddress="http://your-server-ip:10005" -``` +If text messages work but images fail, the usual reason is that third-party object storage is not configured correctly. The default object storage is `minio`, so you need to modify the related configuration. + +For source deployment, edit `config/minio.yml` and change `externalAddress` to the public IP or domain path: +```yaml +externalAddress: http://your-server-ip:10005 ``` -Docker deployment: -Edit the .env file and configure the MinIO external IP to support sending images, videos, and files. -Replace your-server-ip with your server's public IP. + +For Docker deployment, edit `.env` and change `MINIO_EXTERNAL_ADDRESS` to the public IP or domain path: + +```dotenv MINIO_EXTERNAL_ADDRESS="http://your-server-ip:10005" ``` + --- -## 5. Reducing MongoDB and Kafka Memory Usage +## 5. Reduce MongoDB and Kafka Memory Usage + +If the components were deployed with `docker`, you can reduce memory usage by limiting `mongo` and `kafka` in `docker-compose.yml`. -If you deployed components using `Docker`, you can limit the memory usage of `mongo` and `kafka` in the `docker-compose.yml` file. +`mongo` (service name in `openim-docker`) or `mongodb` (service name in `open-im-server`): -`MongoDB`: +> If you use source deployment, replace `mongo` in the following example with `mongodb`. ```yml - mongodb: + mongo: environment: - - wiredTigerCacheSizeGB=0.5 # Set to an appropriate value in GB + - wiredTigerCacheSizeGB=0.5 # Adjust to an appropriate value, unit: GB ``` -`Kafka`: +`kafka`: ```yml kafka: diff --git a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/imSourceCodeDeployment.md b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/imSourceCodeDeployment.md index 4d25578b7d..9b8db3060b 100644 --- a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/imSourceCodeDeployment.md +++ b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/imSourceCodeDeployment.md @@ -3,93 +3,205 @@ title: 'Source Code Deployment' sidebar_position: 3 --- -# 🛠 Source Code Deployment +# Production Source Code Deployment for OpenIMServer and ChatServer (Single Node) -## 1. Prerequisites +## 1. Environment and Component Requirements -For server hardware, software, operating system, and component requirements, please refer to [this document](./env-comp). +OpenIMServer and external components are deployed on the same machine in this guide. Some components can be replaced with cloud services if needed. -## 2. Deploy IMServer +- For environment requirements, refer to [Platform & Components](./env-comp) -### 2.1 Clone the Repository and Switch to the Latest Stable Tag +## 2. Get OpenIMServer and Deploy Dependency Components -``` +It is recommended to pull the repository and switch to the latest official release tag marked with the green **Latest** badge on GitHub Releases. + +```bash 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" ``` -### 2.2 Deploy Components (MongoDB/Redis/Kafka/MinIO/Etcd) -``` +> Here, `latest` means the latest official release marked with the green **Latest** badge on GitHub Releases. It does not include alpha, beta, rc, or other pre-releases. `main` is the development branch and should not be used directly in production. + +> Note: all commands below are executed in the OpenIMServer project root directory. + +### 2.1 Deploy External Components (Docker Compose) + +Make sure `docker` and `docker compose` are available. + +1. If one or more components among `mongodb/redis/kafka/minio/etcd` are already deployed on this machine, or if you plan to use cloud services instead (`etcd` does not support cloud services), comment out the corresponding components in `docker-compose.yml`. +2. It is strongly recommended to change the default usernames and passwords in `docker-compose.yml`. + +| Component | Location in `docker-compose.yml` | +| --- | --- | +| MongoDB | `MONGO_INITDB_ROOT_USERNAME` `MONGO_INITDB_ROOT_PASSWORD` `MONGO_OPENIM_USERNAME` `MONGO_OPENIM_PASSWORD` | +| Redis | `redis-server --requirepass ...` | +| MinIO | `MINIO_ROOT_USER` `MINIO_ROOT_PASSWORD` | +| Etcd | `ETCD_ROOT_USER` `ETCD_ROOT_PASSWORD` (when auth is enabled) | +| Kafka | `KAFKA_USERNAME` `KAFKA_PASSWORD` (when auth is enabled) | + +3. Modify `DATA_DIR` in `.env` so that it points to a large disk for storing external component data. +4. Run the following command to deploy the external components: + +```bash docker compose up -d ``` +> The current `open-im-server/docker-compose.yml` starts not only external components but also `openim-web-front` and `openim-admin-front`. If you only want dependency components, adjust the compose file before starting. +### 2.2 Initialization Requirements for Self-Hosted Components or Cloud Services -### 2.3 Modify Configuration 🔧 +| Component | Initialization Requirement | +| --- | --- | +| MongoDB | Create the database `openim_v3` in advance | +| Kafka | Create 4 topics in advance: `toRedis`, `toMongo`, `toPush`, `toOfflinePush`, and set each topic to 8 partitions | -- Edit the `config/minio.yml` file to configure the MinIO external IP for sending images, videos, and files. Replace `your-server-ip` with your server's public IP address: +## 3. Deploy OpenIMServer -```plaintext -externalAddress="http://your-server-ip:10005" - ``` +Make sure Go is installed correctly. +> `bootstrap.sh` attempts to install `mage`, but it requires a working `go` command in the system first. If `go version` fails, then `bash bootstrap.sh` and `mage` will also fail. +### 3.1 Go Proxy Recommendation for Mainland China -### 2.4 🛠️ Initialize and Download Mage +```bash +go env -w GO111MODULE=on +go env -w GOPROXY=https://goproxy.cn,direct +``` -Before the first build, run on Linux/macOS: +### 3.2 Initialization (Run Once Only) -``` +```bash bash bootstrap.sh ``` -On Windows: +### 3.3 Build -``` -bootstrap.bat +```bash +mage ``` +The first build may take a long time. Please be patient. -For users in China, it is recommended to set a Go proxy: -``` -$ go env -w GO111MODULE=on -$ go env -w GOPROXY=https://goproxy.cn,direct -``` +### 3.4 Basic Configuration Changes + +| Description | File | +| --- | --- | +| Kafka username, password, and address | `config/kafka.yml` | +| Redis password and address | `config/redis.yml` | +| MinIO username, password, and address; `externalAddress` must be changed to a public IP or domain path | `config/minio.yml` | +| S3 cloud storage credentials (when using S3) | `config/openim-rpc-third.yml` | +| Etcd username, password, and address | `config/discovery.yml` | +| MongoDB username, password, and address | `config/mongodb.yml` | +| OpenIMServer `secret` | `config/share.yml` | + +> The `externalAddress` in `minio.yml` must be changed to a public IP or domain path, otherwise IM will not be able to send images and files correctly. -### 2.5 🛠️ Build (Linux/Windows/macOS) +### 3.5 Start / Stop / Check +| Task | Command | Notes | +| --- | --- | --- | +| Start in background | `nohup mage start >> _output/logs/openim.log 2>&1 &` | Recommended for production | +| Stop | `mage stop` | - | +| Check | `mage check` | - | +> After the first startup, wait `20-30s` before running `mage check` or API verification, to avoid mistaking short startup connection failures for final errors. + +## 4. Get ChatServer + +> If you already have your own account system, ChatServer may be optional. + +It is also recommended to pull the repository and switch to the latest official release tag marked with the green **Latest** badge on GitHub Releases: + +```bash +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" ``` + +> If you need to reproduce a specific version, switch to the required fixed tag according to the release notes. If server-side integration must stay aligned with the version corresponding to `v3.8.3-patch.12`, also pin ChatServer to the matching official release tag. + +## 5. Deploy ChatServer + +> Note: all commands below are executed in the ChatServer project root directory. + +### 5.1 Build + +```bash mage ``` -### 2.6 🚀 Start/Stop/Check (Linux/Windows/macOS) +### 5.2 Basic Configuration Changes -``` -# Start -mage start -# Or start in background and collect logs -nohup mage start >> _output/logs/openim.log 2>&1 & -# Stop -mage stop -# Health check -mage check -``` +| Description | File | +| --- | --- | +| Redis username, password, and address | `config/redis.yml` | +| Etcd username, password, and address | `config/discovery.yml` | +| MongoDB username, password, and address | `config/mongodb.yml` | +| OpenIMServer `secret` | `config/share.yml` | +| ChatServer `secret` | `config/chat-rpc-admin.yml` | +### 5.3 Start / Stop / Check +| Task | Command | Notes | +| --- | --- | --- | +| Start in background | `nohup mage start >> _output/logs/chat.log 2>&1 &` | Recommended for production | +| Stop | `mage stop` | - | +| Check | `mage check` | - | -## 3. Quick Verification +> ChatServer depends on OpenIMServer being available first. It is recommended to start ChatServer only after `mage check` succeeds on OpenIMServer, then wait `20-30s` before verifying the `10008/10009` APIs. -Please refer to the [Quick Verification](./quickTestServer) document. +## 6. Configuration File Reference ---- +- For OpenIMServer configuration details, use `config/README_zh_CN.md` in the currently checked-out code. +- For ChatServer configuration details, use `config/README_zh_CN.md` in the currently checked-out code. + +## 7. Offline Push + +- GeTui: supported. Apply for `AppID`, `AppKey`, and `MasterSecret` from GeTui, then integrate them according to the official process. +- Firebase: modify `fcm.filepath` in `config/openim-push.yml`. + +## 8. Change the Number of Service Instances (Optional) + +In `start-config.yml`, all services except `openim-msggateway` and `openim-api` can have their instance counts adjusted directly in `serviceBinaries`. + +For `openim-msggateway` and `openim-api`: + +- the number of service instances must match the number of ports configured in the corresponding config files +- restart the service after modification for the change to take effect + +## 9. Monitoring & Alerting (Optional) + +WIP + +## 10. Important Guidance + +### 10.1 Change the `secret` + +It is strongly recommended to change the default `secret`: + +- at least 8 characters +- use a combination of letters and digits +- keep it secret and secure + +### 10.2 Open Ports and Client Addresses + +Without a domain or SSL, refer to [Ports and Firewall](./ports) + +- `apiAddr: http://your_server_ip:10002` +- `wsAddr: ws://your_server_ip:10001` -## 4. FAQ +With a domain and SSL, refer to [Domain and SSL Certificate Configuration](./nginxDomainConfig) -### 4.1 📜 Viewing Logs +- modify DNS records and bind the IP to the domain +- in domain mode, usually only `443` is exposed externally +- `apiAddr: https://your_domain.com/api` +- `wsAddr: wss://your_domain.com/msg_gateway` -IMServer log location: `_output/logs/openim-service-log.*` +### 10.3 Backup and Recovery for Single-Node Production -### 4.2 🚀 Startup Order -The startup order is as follows: -- Dependencies: MongoDB/Redis/Kafka/MinIO/Etcd -- IMServer +Please refer to [Backup and Recovery for Single-Node Production](./production) diff --git a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/internalDeployment.md b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/internalDeployment.md index 68e44358bc..a6eae8d0c2 100644 --- a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/internalDeployment.md +++ b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/internalDeployment.md @@ -2,120 +2,184 @@ title: 'Air-Gapped Deployment' sidebar_position: 4 --- + ## 📌 Air-Gapped Deployment Guide -This guide walks you through deploying OpenIM services on a machine without internet access (air-gapped/internal network). +The main air-gapped deployment workflow is: **run `mage export` on an internet-connected build machine, then transfer the deployment package to the internal target machine and run it there**. + +## 1. Version and Branch Strategy + +- `main`: development branch, used only for unreleased changes. +- `vX.Y.Z...`: stable release versions. +- For air-gapped production, use the latest official release marked with the green **Latest** badge on GitHub Releases. + +## 2. Overall Workflow + +1. On an **internet-connected build machine**, pull the stable OpenIMServer / ChatServer source code. +2. Run `mage export` on the build machine to generate deployable archives. +3. Transfer the archives, configuration files, and external component installation packages to the **internal target machine**. +4. Extract the archives on the internal target machine and directly use the bundled `./mage` launcher to start and check services. + +## 3. Ways to Prepare External Components + +The OpenIMServer / ChatServer air-gapped deployment package only contains the business services themselves. External components (MongoDB, Redis, Kafka, Etcd, MinIO) can be prepared in two ways. + +### Option A: The Target Machine Uses Docker + +If Docker is not installed on the target machine, it is recommended to download Docker offline installation packages matching the target OS and architecture on an internet-connected machine first, and then transfer them to the internal target machine. + +- Debian / Ubuntu: prepare `.deb` packages for `docker-ce`, `docker-ce-cli`, `containerd.io`, `docker-buildx-plugin`, and `docker-compose-plugin` +- RHEL / CentOS: prepare the corresponding `.rpm` packages for the same components + +After installation, use `docker load` to import the external component images you exported in advance. + +### Option B: The Target Machine Does Not Use Docker + +You can directly copy the official binaries or internal artifact packages of MongoDB, Redis, Kafka, Etcd, and MinIO to the internal target machine, and run them with their own systemd / supervisor / script-based startup methods. + +In this mode, OpenIMServer / ChatServer only need correct addresses and credentials for these components. Docker is not required on the target machine. + +## 4. Export OpenIMServer on the Internet-Connected Build Machine + +```bash +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" + +bash bootstrap.sh +PLATFORMS="linux_amd64" mage export +``` + +After a successful run, the deployment archive is generated by default in: + +```text +_output/export/ +``` + +A typical filename looks like: + +```text +exported_open-im-server_v3.8.3-patch.12_linux_amd64.tar.gz +``` + +## 5. Export ChatServer on the Internet-Connected Build Machine + +```bash +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" + +bash bootstrap.sh +PLATFORMS="linux_amd64" mage export +``` -### **Docker Deployment** +A typical filename looks like: -1. On an internet-connected machine, clone the repository: +```text +exported_chat_v1.8.4-patch.3_linux_amd64.tar.gz +``` - ```sh - git clone https://github.com/openimsdk/openim-docker - ``` +## 6. Deployment Package Contents -2. Run `docker compose up -d` to pull all required images. +The archive generated by `mage export` includes: -3. Save the required images. The command is: +- prebuilt service binaries +- `start-config.yml` +- required runtime configuration files +- a `mage` launcher that can be executed directly on the target machine - ```sh - docker save -o image-name.tar image-name:tag - ``` +Therefore, **the internal target machine does not need to install Go and does not need to rebuild source code**. - For example, to save the `openim-server` image: +## 7. Transfer to the Internal Target Machine - ```sh - docker save -o openim-server.tar openim/openim-server:release-v3.8.1 - ``` +Transfer the following to the internal target machine: - To save the `mongo` image: +- the OpenIMServer export archive +- the ChatServer export archive +- external component images or binary installation packages +- your real configuration files, such as domain settings, external component addresses, `secret`, and MinIO `externalAddress` - ```sh - docker save -o mongo.tar mongo:7.0 - ``` +## 8. Deploy External Components on the Internal Target Machine - You can use `docker images` to view pulled image information, or check the `.env` file for image version details. +### 1. Docker Method - All images that need to be saved: +If the target machine uses Docker: - - `mongo:7.0` - - `redis:7.0.0` - - `bitnami/kafka:3.5.1` - - `minio/minio:RELEASE.2024-01-11T07-46-16Z` - - `quay.io/coreos/etcd:v3.5.13` - - `openim/openim-web-front:release-v3.8.1` - - `openim/openim-admin-front:release-v1.8.3` - - `openim/openim-server:release-v3.8.2` - - `openim/openim-chat:v1.8.2` +```bash +docker load -i image-name.tar +``` - The following are monitoring and alerting component images (optional): +After importing all external component images, start them with your component orchestration files. - - `prom/prometheus:v2.51.2` - - `prom/alertmanager:v0.27.0` - - `grafana/grafana:11.0.1` - - `prom/node-exporter:v1.7.0` +### 2. Non-Docker Method -4. Transfer the **image files** and **docker repository files** to the deployment machine via internal network or physical media. +If the target machine does not use Docker: -5. Import images into Docker: - ```bash - docker load -i image-name.tar - ``` +- start MongoDB +- start Redis +- start Kafka +- start Etcd +- start MinIO - For example, to import the `openim-server` image: +Then write the addresses, usernames, and passwords of these components into the OpenIMServer / ChatServer configuration files. - ```sh - docker load -i openim-server.tar - ``` +## 9. Extract and Start OpenIMServer on the Internal Target Machine -6. In the repository directory, run: - ```sh - docker compose up -d - ``` +```bash +mkdir -p /opt/openim/open-im-server +tar -xzf exported_open-im-server_v*.tar.gz -C /opt/openim/open-im-server +cd /opt/openim/open-im-server +``` - To start with monitoring components: - ```sh - docker compose --profile m up -d - ``` +After updating external component addresses, `secret`, and MinIO `externalAddress`, run: -### **Source Code Deployment** +```bash +./mage check +./mage start +./mage check +``` -1. On an internet-connected machine, clone the server repository (recommended: switch to the release-v3.8.2 branch): +## 10. Extract and Start ChatServer on the Internal Target Machine - ```sh - git clone https://github.com/openimsdk/open-im-server - ``` +```bash +mkdir -p /opt/openim/chat +tar -xzf exported_chat_v*.tar.gz -C /opt/openim/chat +cd /opt/openim/chat +``` -2. Clone the `chat` repository (recommended: switch to the release-v1.8.3 branch): - ```bash - git clone https://github.com/openimsdk/chat - ``` +After updating Redis, MongoDB, Etcd, and the OpenIMServer `secret` in the ChatServer configuration, run: -3. Follow the [Docker deployment](#docker-deployment) steps to save images, except you do not need `openim/openim-server:release-v3.8.2` and `openim/openim-chat:v1.8.2`. +```bash +./mage check +./mage start +./mage check +``` -4. Transfer the **image files**, **server repository files**, and **chat repository files** to the deployment machine via internal network or physical media. +## 11. Common Runtime Commands -5. Import images into Docker: +OpenIMServer: - ```bash - docker load -i image-name.tar - ``` +```bash +cd /opt/openim/open-im-server +./mage check +./mage stop +./mage start +``` - For example, to import the `mongo` image: +ChatServer: - ```sh - docker load -i mongo.tar - ``` +```bash +cd /opt/openim/chat +./mage check +./mage stop +./mage start +``` -6. In the `server` directory, run the following commands in order: - ```bash - docker compose up -d # To enable monitoring: docker compose --profile m up -d - mage - mage start - ``` +## 12. Notes for Air-Gapped Deployment -7. In the `chat` directory, run: - ```bash - mage - mage start - ``` +1. `main` is the development branch and should not be used for air-gapped production packages. +2. The runtime dependencies for the target machine are already bundled in the `mage export` archive, so do not rerun the source build workflow on the target machine. +3. If the target machine architecture differs from the build machine, specify the target platform with `PLATFORMS`, for example `PLATFORMS="linux_amd64" mage export` or `PLATFORMS="linux_arm64" mage export`. +4. Whether you use Docker or direct binary deployment for external components, make sure the addresses and credentials match the OpenIMServer / ChatServer configuration. diff --git a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/nginxDomainConfig.md b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/nginxDomainConfig.md index c043530cb3..c5bbca3d61 100644 --- a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/nginxDomainConfig.md +++ b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/nginxDomainConfig.md @@ -1,59 +1,57 @@ --- -title: 'Domain & SSL Configuration' +title: 'Domain Configuration' sidebar_position: 7 --- -# Domain & SSL Certificate Configuration +# Domain and SSL Certificate Configuration -## 1. Prerequisites 🛠️ +> This page only covers domain configuration related to OpenIMServer and ChatServer. -- **IMServer** is successfully running. -- **Nginx** is installed with the SSL module enabled. -- A domain (or subdomain) and SSL certificate have been obtained, e.g., `im.yourhost.com` for IMServer. -- Port 443 is open. +## 1. Prerequisites -## 2. Domain Configuration Template 📝 +- OpenIMServer and ChatServer are already running successfully. +- Nginx is installed with SSL support enabled. +- You have applied for a domain and SSL certificate (for example `im.yourhost.com`). +- Port `443` is open on the server. -> 🚀 **Tip**: Make sure to replace with your actual domain name, SSL certificate path, and SSL key. +If Nginx is not installed yet, install it first using the package manager of your distribution (for example on Debian/Ubuntu: `apt-get install -y nginx`). -```nginx +## 2. Nginx Configuration Template + +> Replace the domain, certificate paths, and service addresses with your real values. The comments below explain the purpose of each block; it is recommended to replace them line by line according to the comments. -upstream msg_gateway{ - #IM Message server address Multiple can be specified according to the deployment +```nginx +upstream msg_gateway { + # OpenIMServer WebSocket gateway server 127.0.0.1:10001; } -upstream im_api{ - #IM Group user api server address Multiple can be specified according to the deployment + +upstream im_api { + # OpenIMServer REST API server 127.0.0.1:10002; } -upstream minio_s3_2{ - #Minio address can be assigned to multiple modules depending on deployment - server 127.0.0.1:10005; +upstream im_chat_api { + # ChatServer API + server 127.0.0.1:10008; } +upstream minio_s3 { + # MinIO object storage + server 127.0.0.1:10005; +} server { - listen 443; #Listening on port 443 - server_name im.yourhost.com; #Your domain - ssl on; - #Path of pem file for ssl certificate - ssl_certificate /usr/local/nginx/conf/ssh/im.yourhost.com_bundle.pem; - #Key file path of ssl certificate - ssl_certificate_key /usr/local/nginx/conf/ssh/im.yourhost.com.key; - - gzip on; - gzip_min_length 1k; - gzip_buffers 4 16k; - gzip_comp_level 2; - gzip_types text/plain application/javascript application/x-javascript text/css application/xml text/javascript application/x-httpd-php image/jpeg image/gif image/png application/wasm; - gzip_vary off; - gzip_disable "MSIE [1-6]\."; - - default_type application/wasm; - - - location /msg_gateway{ + # Unified external HTTPS entry + listen 443 ssl; + server_name im.yourhost.com; + + # SSL certificate and private key paths + ssl_certificate /usr/local/nginx/conf/ssl/im.yourhost.com_bundle.pem; + ssl_certificate_key /usr/local/nginx/conf/ssl/im.yourhost.com.key; + + location /msg_gateway { + # OpenIMServer WebSocket reverse proxy; keep the Upgrade headers proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "Upgrade"; @@ -62,7 +60,8 @@ server { proxy_pass http://msg_gateway/; } - location ^~/api/{ + location ^~ /api/ { + # OpenIMServer REST API reverse proxy proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "Upgrade"; @@ -72,42 +71,71 @@ server { proxy_pass http://im_api/; } + location ^~ /chat/ { + # ChatServer API reverse proxy + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "Upgrade"; + proxy_set_header X-real-ip $remote_addr; + proxy_set_header X-Forwarded-For $remote_addr; + proxy_pass http://im_chat_api/; + } - - location ^~/im-minio-api/ { + location ^~ /im-minio-api/ { + # MinIO file access reverse proxy; keep it consistent with externalAddress 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 $scheme; proxy_connect_timeout 300; - proxy_http_version 1.1; proxy_set_header Connection ""; chunked_transfer_encoding off; - proxy_pass http://minio_s3_2/; + proxy_pass http://minio_s3/; } +} +``` +## 3. MinIO Configuration +- Source deployment: modify `externalAddress` in `config/minio.yml` +- Docker deployment: modify `MINIO_EXTERNAL_ADDRESS` in `.env` -} +Example value: +```text +https://im.yourhost.com/im-minio-api +``` +## 4. Reload Nginx +```bash +nginx -t +nginx -s reload ``` -## 3. MinIO Configuration 🗄️ +## 5. OpenIMClientSDK Initialization Parameters -- **Source code deployment**: Edit the `externalAddress` value in `config/minio.yml` to `"https://im.yourhost.com/im-minio-api"`. -- **Docker deployment**: Edit the `MINIO_EXTERNAL_ADDRESS` value in the `.env` file to `"https://im.yourhost.com/im-minio-api"`. - -## 4. Start Nginx 🚀 +```text +apiAddr: https://im.yourhost.com/api +wsAddr: wss://im.yourhost.com/msg_gateway +``` -Run `nginx -s reload` to reload the Nginx configuration. +## 6. Gateway Path Mapping +| Path | Service | +| --- | --- | +| `/api/*` | OpenIMServer API (`10002`) | +| `/msg_gateway` | OpenIMServer WebSocket (`10001`) | +| `/chat/*` | ChatServer API (`10008`) | +| `/im-minio-api/*` | MinIO object storage (`10005`) | -## 5. Update Client SDK Initialization Parameters +## 7. Naming Consistency -In the client SDK, configure the initialization parameters as follows: +- OpenIMSDK: the overall project name. +- OpenIMClientSDK: the client SDK. +- OpenIMServer: the IM core service. +- ChatServer: the business extension service, i.e. the APP Business Server. +- Accounts calling management REST APIs are uniformly referred to as APP Administrators. -- `apiAddr`: `https://im.yourhost.com/api` -- `wsAddr`: `wss://im.yourhost.com/msg_gateway` +> The current template only covers the common external entry points for OpenIMServer and ChatServer (APP Business Server). If you also need to expose APP Administrator APIs through the domain entry, add an additional `upstream` and `location` for `10009`. diff --git a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/ports.md b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/ports.md index 798c83c1c6..5aabe306c4 100644 --- a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/ports.md +++ b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/ports.md @@ -1,56 +1,50 @@ --- -title: 'Ports & Firewall' +title: 'Ports' sidebar_position: 6 --- -# 🔐 Ports & Firewall +# 🔐 Ports and Firewall ---- - -## 📡 IM Server Ports +## 1. Without a Domain Name and SSL Certificate -The following ports must be allowed through the firewall for IMServer to communicate properly. - -| TCP Port | Description | Action ⚙️ | -| --- | --- | --- | -| **10001** | WebSocket message port for client SDK communication | ✅ Allow | -| **10002** | API port providing user, contact, group, and message interfaces | ✅ Allow | -| **10005** | Required when using MinIO storage (default in IMServer) | ✅ Allow | +The following ports must be opened on the server. Other ports should not be exposed publicly. ---- +| Module | Port | Description | Action | +| --- | --- | --- | --- | +| OpenIMServer | TCP:10001 | WebSocket message port used by OpenIMClientSDK | Open the port | +| OpenIMServer | TCP:10002 | API port for users, friends, groups, messages, and related APIs | Open the port | +| OpenIMServer | TCP:10005 | MinIO object storage | Open the port | +| ChatServer | TCP:10008 | APP Business Server APIs such as registration and login | Open the port | +| ChatServer | TCP:10009 | APP Administrator APIs such as statistics and user bans | Open the port | +| Web frontend (optional) | TCP:11001 | PC Web frontend; needed for browser-based quick verification | Open if needed | +| Admin frontend (optional) | TCP:11002 | APP Administrator frontend page | Open if needed | -## 💻 Web Frontend & Admin Dashboard Ports +In the client SDK, initialize with: -| TCP Port | Description | Action ⚙️ | -| --- | --- | --- | -| **11001** | PC Web client and admin dashboard frontend resources | ✅ Allow | +```text +apiAddr: http://your_server_ip:10002 +wsAddr: ws://your_server_ip:10001 +``` ---- +## 2. With a Domain Name and SSL Certificate -## 📊 Grafana Monitoring Port +The following ports must be opened on the server. Other ports should not be exposed publicly. -| TCP Port | Description | Action ⚙️ | +| Port | Description | Action | | --- | --- | --- | -| **13000** | Grafana monitoring dashboard | ✅ Allow | +| TCP:443 | Default HTTPS port | Open the port | ---- +Configuration reference: [Domain and SSL Certificate Configuration](./nginxDomainConfig) -> ⚠️ **Note:** -> If your server has a firewall enabled (such as `ufw` or `firewalld`), make sure the above ports are allowed. -> For example, on Linux: -> -> ```bash -> sudo ufw allow 10001:10005/tcp -> sudo ufw allow 11001/tcp -> sudo ufw allow 13000/tcp -> sudo ufw reload -> ``` -> +Complete DNS resolution first so that the IP is bound to the domain. -You can also use online port checking tools (for public-facing servers): +In the client SDK, initialize with: -https://portchecker.co/ +```text +apiAddr: https://your_domain.com/api +wsAddr: wss://your_domain.com/msg_gateway +``` -https://www.yougetsignal.com/tools/open-ports/ +> Monitoring, frontend, and other service ports are recommended to stay internal-only and be exposed only when needed. -Enter your server's public IP and port number to check if it is accessible. +> If you want to access `11001` directly from the browser as described in [Quick Verification](./quickTestServer), the frontend port must be reachable. If you do not need frontend page verification, you do not need to expose `11001/11002` publicly. diff --git a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/production.assets/0.png b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/production.assets/0.png new file mode 100644 index 0000000000..4703f00f9a Binary files /dev/null and b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/production.assets/0.png differ diff --git a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/production.md b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/production.md index dc70defb89..8aa802bb1e 100644 --- a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/production.md +++ b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/production.md @@ -1,62 +1,93 @@ --- -title: 'Production Environment' +title: 'Production' sidebar_position: 8 +slug: /gettingStarted/production --- +# Production +This page only describes the impact of **runtime failures** in production and how to recover from them. +## 1. General Recovery Order -In production environments, cluster deployments are typically used to ensure high availability of components and services. However, with limited resources, some developers may opt for single-machine deployment (using source code or Docker containers) in production. This document covers data backup, failure recovery, and potential risks in single-machine deployment environments. +1. Recover external components first. +2. Recover OpenIMServer next. +3. Recover ChatServer last. -## 1. Scheduled MongoDB Backup -IMServer stores its core data in MongoDB, so backing up MongoDB data can recover most of the data. Set up the MongoDB backup directory and scheduled tasks before starting containers. +## 2. Runtime Failures of External Components -### Data Backup +| Failed Component | Runtime Impact | Recovery Action | +| --- | --- | --- | +| MongoDB unavailable | OpenIMServer `10002` may still respond, but ChatServer and APP Administrator APIs often fail | Recover MongoDB first; immediately retest `10002/10008/10009`; if still abnormal, restart OpenIMServer / ChatServer | +| Redis unavailable | OpenIMServer authentication becomes abnormal; source deployment often shows `auth-rpc-service down`, while all-in-one Docker deployment often shows Redis connection or resolution errors | Recover Redis first; observe for `30-60s`; if OpenIMServer authentication is still abnormal, restart OpenIMServer | +| Kafka unavailable | Basic probes may still pass, but message transfer and push paths become abnormal | Recover Kafka first; then run end-to-end message send / consume / push verification | +| Etcd unavailable | Running instances can usually keep serving for a short period, but service restarts may fail | Recover Etcd first; if service registration does not recover, restart OpenIMServer / ChatServer | +| MinIO unavailable | File upload/download fails; in source deployment the basic probes usually remain healthy, while all-in-one Docker deployment may also break `10002/10008/10009` | Recover MinIO and verify `externalAddress`; if all-in-one Docker deployment still does not recover within `30-60s`, restart the OpenIMServer / ChatServer service stack | -IMServer stores its core data in MongoDB, so backing up MongoDB data enables recovery of most data. Here are the backup steps: +### External Component Recovery Commands -1. **Modify Backup Directory** +For `openim-docker` deployment: - - Edit the `MONGO_BACKUP_DIR` path in the `.env` file (default: `components/backup/mongo/`). It is recommended to set the backup directory to a different disk than the `components` directory to avoid losing both original data and backups due to a single disk failure. +```bash +cd /path/to/openim-docker +docker compose up -d mongo redis kafka etcd minio +``` -3. **Scheduled Backup Configuration** - - Configure a scheduled backup task in Linux by editing crontab: - ```sh - crontab -e - ``` - - Add the following scheduled task to run a backup at 2:00 AM daily, keeping the 2 most recent backups. Adjust the `cron` expression as needed for different schedules: - ```sh - 0 2 * * * docker exec mongo mongodump --uri="mongodb://openIM:openIM123@localhost:27017/openim_v3" --out="/data/backup/$(expr $(date +\%s) / 86400 \% 2)" - ``` - - Use `crontab -l` to verify the scheduled task was set up correctly. +For `open-im-server` source deployment: +```bash +cd /path/to/open-im-server +docker compose up -d mongodb redis kafka etcd minio +``` +> The default service name is `mongo` in `openim-docker`, and `mongodb` in `open-im-server`. -## 2. Handling Component Failures +## 3. OpenIMServer Runtime Failures -1. If `mongo`, `redis`, `kafka`, `etcd`, or other components stop unexpectedly, first try restarting all components and the IMServer service. +| Failed Service | Runtime Impact | Recovery Action | +| --- | --- | --- | +| `openim-api` | `10002` is usually unavailable | Run `mage stop && mage start` in the `open-im-server` directory | +| `openim-rpc-auth` | OpenIMServer auth probes fail, while ChatServer probes may still be available | Run `mage stop && mage start` in the `open-im-server` directory | +| `openim-msggateway` | Real-time WebSocket connectivity is interrupted | Run `mage stop && mage start` in the `open-im-server` directory | +| `openim-msgtransfer` / `openim-push` | Message delivery and push degrade; basic probes may still pass | Run `mage stop && mage start` in the `open-im-server` directory, then run message-path verification | +| `openim-crontask` | Scheduled tasks stop running | Run `mage stop && mage start` in the `open-im-server` directory | -2. If services fail to start due to data issues (e.g., disk failure, disk full), first stop all components and the IMServer service. - - If `redis` fails to start, delete the `components/redis/` directory. - - If `kafka` fails to start, delete the `components/kafka/` directory. - - If `mongo` fails to start: - - 1. Delete the `components/redis/`, `components/mongodb/`, and `components/kafka/` directories. - - 2. Restore from backup: `docker exec -it mongo mongorestore --uri="mongodb://openIM:openIM123@localhost:27017/openim_v3" /data/backup/your_backup_name/openim_v3` - - **your_backup_name is either 0 or 1 — choose the more recent directory** - - If `etcd` fails to start, delete the `components/etcd/` directory. +OpenIMServer recovery command: -3. After performing the above steps, restart all components and the IMServer service. +```bash +cd /path/to/open-im-server +mage check +mage stop +mage start +mage check +``` -## 3. Potential Risks +## 4. ChatServer Runtime Failures -1. **Single-Machine Deployment Risk** - If a machine failure makes both the original data disk and backup disk inaccessible, data cannot be directly recovered. In this case, you may need to use your cloud provider's snapshot service for data recovery. +| Failed Service | Runtime Impact | Recovery Action | +| --- | --- | --- | +| `chat-api` | The APP Business Server API `10008` is usually unavailable | Run `mage stop && mage start` in the `chat` directory | +| `chat-rpc` | Core ChatServer business calls fail, while the basic HTTP port may still exist | Run `mage stop && mage start` in the `chat` directory | +| `admin-api` | The APP Administrator API `10009` is usually unavailable, while `10008` may still work | Run `mage stop && mage start` in the `chat` directory | +| `admin-rpc` | APP Administrator business calls fail | Run `mage stop && mage start` in the `chat` directory | +| `bot-api` / `bot-rpc` | Bot-related capabilities fail | Run `mage stop && mage start` in the `chat` directory | -2. **Backup Directory Recommendation** - To prevent data loss from a single disk failure, it is recommended to set MongoDB's backup directory `MONGO_BACKUP_DIR` on a separate disk from the `components` directory. +ChatServer recovery command: -3. **Data Recovery Risk** - When restoring MongoDB data, any data created after the backup time will be lost. However, backing up too frequently may significantly impact MongoDB performance. +```bash +cd /path/to/chat +mage check +mage stop +mage start +mage check +``` -4. **Impact of Deleting Redis Data** - Deleting Redis data may cause **incorrect unread message counts**. +## 5. Post-Recovery Verification + +After recovery, verify at least the following: + +1. `mage check` or `docker ps` is healthy. +2. The three basic probes `10002`, `10008`, and `10009` are restored. +3. For Kafka and MinIO incidents, run additional message-path and file-path verification. + +> Basic probes for OpenIMServer and ChatServer must include the `operationID` request header. diff --git a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/quickTestServer.md b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/quickTestServer.md index f9ba92d731..30178c2751 100644 --- a/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/quickTestServer.md +++ b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/quickTestServer.md @@ -2,25 +2,93 @@ title: 'Quick Verification' sidebar_position: 9 --- + ## 📌 1. Deploy the Server -Refer to [Docker Deployment](./dockerCompose) or [Source Code Deployment](./imSourceCodeDeployment) for deployment instructions. +Refer to [Docker Deployment](./dockerCompose) or [Source Code Deployment](./imSourceCodeDeployment). --- ## 📌 2. Open Ports -Refer to [Ports & Firewall](./ports) - -## 3. PC Web Verification +Refer to [Ports and Firewall](./ports). +## 📌 3. PC Web Verification :::tip -Enter `http://your_server_ip:11001` in your browser to access the PC Web interface. Replace `your_server_ip` with the public IP address of your IMServer. +Enter `http://your_server_ip:11001` in your browser to access PC Web. `your_server_ip` is the server IP where the frontend is deployed. ::: +![PC Web Interface](./assets/pc-web.png) + +## 📌 4. Service Process Verification + +Confirm that OpenIMServer and ChatServer are running normally. + +```bash +docker ps | grep -E 'openim-server|openim-chat' +``` + +> In the `docker deployment` scenario, `openim-server` and `openim-chat` may initially show `health: starting`. Wait `20-30s` until they become `healthy` before continuing with API verification. + +If you use source deployment, run: + +```bash +# Run in the open-im-server directory +mage check + +# Run in the chat directory +mage check +``` + +## 📌 5. Domain and Gateway Verification + +When using a domain name and SSL, call the real interfaces directly to verify the OpenIMServer and ChatServer (APP Business Server) gateway routes. + +```bash +curl -sS -X POST "https://your_domain/api/auth/get_admin_token" \ + -H "Content-Type: application/json" \ + -H "operationID: verify-openim" \ + -d '{"secret":"your_openim_secret","userID":"imAdmin"}' +``` + +```bash +curl -sS -X POST "https://your_domain/chat/application/latest_version" \ + -H "Content-Type: application/json" \ + -H "operationID: verify-chat" \ + -d '{}' +``` + +> If the interface returns JSON with a business error, it usually still means the reverse-proxy path is already connected. + +> If you have deployed only the backend services and not the frontend pages, the `11001` PC Web step does not apply. It is mainly for the `docker deployment` scenario where the frontend image is started by default, or for cases where you deployed the web frontend yourself. + +To verify the WebSocket gateway, use any WebSocket client to test: + +```text +wss://your_domain/msg_gateway +``` + +> In production, it is recommended to access everything through port `443`. OpenIMClientSDK should use: +> - `apiAddr`: `https://your_domain/api` +> - `wsAddr`: `wss://your_domain/msg_gateway` + +## 📌 6. API Verification Without a Domain + +If you have not configured a domain name or SSL yet, verify directly through the server IP and default ports: +```bash +curl -sS -X POST "http://your_server_ip:10002/auth/get_admin_token" \ + -H "Content-Type: application/json" \ + -H "operationID: verify-openim-local" \ + -d '{"secret":"your_openim_secret","userID":"imAdmin"}' +``` -import Image3 from './assets/pc-web.png'; +```bash +curl -sS -X POST "http://your_server_ip:10008/application/latest_version" \ + -H "Content-Type: application/json" \ + -H "operationID: verify-chat-local" \ + -d '{}' +``` -PC Web Interface +> ChatServer (APP Business Server) POST APIs also require the `operationID` request header. Without it, the server returns a parameter error.