From 53a0088ba4491e21fd4f135c6d03cce155b13aeb Mon Sep 17 00:00:00 2001 From: dsx137 <70027572+dsx137@users.noreply.github.com> Date: Thu, 12 Mar 2026 11:41:54 +0800 Subject: [PATCH 1/2] docs(core): add PC Web verification note and clarifications --- docs/guides/gettingStarted/dockerCompose.md | 9 ++---- docs/guides/gettingStarted/env-comp.md | 28 +++++++++---------- docs/guides/gettingStarted/quickTestServer.md | 12 +++++++- .../current/gettingStarted/dockerCompose.md | 8 ++---- .../current/gettingStarted/env-comp.md | 4 +-- .../current/gettingStarted/quickTestServer.md | 12 +++++++- 6 files changed, 44 insertions(+), 29 deletions(-) diff --git a/docs/guides/gettingStarted/dockerCompose.md b/docs/guides/gettingStarted/dockerCompose.md index 5885aa775a..6302dc0eda 100644 --- a/docs/guides/gettingStarted/dockerCompose.md +++ b/docs/guides/gettingStarted/dockerCompose.md @@ -55,7 +55,7 @@ docker compose down - 查看日志： ```bash -docker logs -f openim-server +docker compose logs -f openim-server openim-chat ``` ### 2.4 监控告警（可选） @@ -77,14 +77,11 @@ docker compose --profile m up -d 快速体验 OpenIMSDK 核心能力，并测试 OpenIMServer/ChatServer 部署是否正常，请参考[快速验证](./quickTestServer)。 -> 补充（基于当前项目目录）：如果你是按 `open-im-server` + `chat` 两个源码仓库部署，`open-im-server/docker-compose.yml` 主要用于依赖组件，ChatServer 仍需在 `chat` 目录执行 `mage start`。可参考[源码部署](./imSourceCodeDeployment)。 - - ## 4. 常见问题 ### unhealthy定位 -1. 执行 `docker exec -it openim-server mage check` 确认是否超过一分钟； -2. 执行 docker logs -f openim-server 查看日志； +1. 执行 `docker exec -it openim-server mage check` 与 `docker exec -it openim-chat mage check`，确认是否持续超过一分钟； +2. 执行 `docker compose logs -f openim-server openim-chat` 查看日志； 3. 如果 `openim-chat` 在启动初期短暂报 `connect: connection refused`，先等待 `30-60s` 后再复查健康状态；这通常是依赖 `openim-server` 尚未完全就绪导致的启动时序现象。 ### 配置项修改 diff --git a/docs/guides/gettingStarted/env-comp.md b/docs/guides/gettingStarted/env-comp.md index a3af137f86..087f6c2303 100644 --- a/docs/guides/gettingStarted/env-comp.md +++ b/docs/guides/gettingStarted/env-comp.md @@ -22,23 +22,23 @@ sidebar_position: 1 ## 三、环境要求 -| 注意事项 | 详细说明 | 补充说明 | -| --- | --- | --- | -| 操作系统 | Linux | 官方使用 `ubuntu 22.04`，实测 `Debian 13` 也可运行 | +| 注意事项 | 详细说明 | 补充说明 | +| --- |------------------|------------------------------------------------| +| 操作系统 | 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) | +| CPU 架构 | `x86_64`、`arm64` | 其他架构需自行测试 | +| 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`） | +| 组件 | 建议版本 | 支持模式 | 支持云服务 / 备注 | +| --- | --- |----------------------------------- |---------------------------------------------------------------------| +| MongoDB | `v7.0` | `standalone`、`replicaSet`、`sharded` | 支持；如接副本集或分片集群，建议优先使用 `uri` | +| Redis | `v7.0.0` | `standalone`、`cluster`、`sentinel` | 支持 | +| Etcd | `v3.5.13` | 单机、多节点集群 | 不支持云服务 | +| Kafka | `v3.5.1` | 单机、分布式集群 | 支持；需[按文档预建 topic](./imSourceCodeDeployment#2.2-自行部署组件或使用云服务时的初始化要求) | +| MinIO | `RELEASE.2024-01-11T07-46-16Z` | 单机 | 可替换为 S3 兼容存储（`COS`、`OSS`、`Kodo`(社区维护)、`AWS S3`） | --- diff --git a/docs/guides/gettingStarted/quickTestServer.md b/docs/guides/gettingStarted/quickTestServer.md index 1d13542c60..d2934abdba 100644 --- a/docs/guides/gettingStarted/quickTestServer.md +++ b/docs/guides/gettingStarted/quickTestServer.md @@ -21,6 +21,14 @@ sidebar_position: 9 ![PC Web Interface](./assets/pc-web.png) +如果还没有测试账号，可按以下步骤完成注册： + +1. 在登录页底部点击 `立即注册`； +2. 按页面提示填写注册信息；如果当前部署启用了注册验证码，还需完成对应验证码校验； +3. 注册成功后返回登录页，使用新账号登录，再继续后续验证。 + +> 如果当前部署关闭了自助注册，请改用已有测试账号进行验证。 + 如果需要在 PC Web 上注册账号，默认配置下可直接使用验证码 `666666`。 > 该值来自 `chat/config/chat-rpc-chat.yml` 中的 `verifyCode.superCode`；默认 `phone.use` 和 `mail.use` 也都是 `superCode`。如果你已经修改过配置，请以实际部署值为准。 @@ -29,13 +37,15 @@ sidebar_position: 9 确认 OpenIMServer 与 ChatServer 进程状态正常。 +### Docker部署 + ```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 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 50f35e0ffe..509324ee39 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 @@ -52,7 +52,7 @@ docker compose down - View logs: ```bash -docker logs -f openim-server +docker compose logs -f openim-server openim-chat ``` ### 2.4 Monitoring & Alerting (Optional) @@ -74,13 +74,11 @@ Default ports follow the current `.env`. Common values are: 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` -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. +1. Run `docker exec -it openim-server mage check` and `docker exec -it openim-chat mage check`, then confirm whether either state lasts longer than one minute. +2. Run `docker compose logs -f openim-server openim-chat` 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. ### Configuration Changes 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 808697eaa8..83f4e0cbe8 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 @@ -26,7 +26,7 @@ sidebar_position: 1 | --- | --- | --- | | 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 | +| CPU architecture | `x86_64`, `arm64` | Other architectures require 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) | @@ -38,7 +38,7 @@ sidebar_position: 1 | 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 | +| Kafka | `v3.5.1` | Single node, distributed cluster | Supported; [create the required topics in advance according to the docs](./imSourceCodeDeployment#22-initialization-requirements-for-self-hosted-components-or-cloud-services) | | 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/quickTestServer.md b/i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/quickTestServer.md index 1c445cf9d8..a487b84e28 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 @@ -21,6 +21,14 @@ Enter `http://your_server_ip:11001` in your browser to access PC Web. `your_serv ![PC Web Interface](./assets/pc-web.png) +If you do not have a test account yet, complete registration with the following steps: + +1. Click the registration entry at the bottom of the login page. +2. Fill in the required registration information. If registration verification codes are enabled in the current deployment, complete that verification as well. +3. After registration succeeds, return to the login page, sign in with the new account, and continue the remaining verification steps. + +> If self-service registration is disabled in the current deployment, use an existing test account instead. + If you need to register an account on PC Web, the default verification code is `666666`. > This value comes from `verifyCode.superCode` in `chat/config/chat-rpc-chat.yml`. By default, both `phone.use` and `mail.use` are also set to `superCode`. If you have changed the configuration, use the actual deployed value. @@ -29,13 +37,15 @@ If you need to register an account on PC Web, the default verification code is ` Confirm that OpenIMServer and ChatServer are running normally. +### Docker Deployment + ```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: +### Source Code Deployment ```bash # Run in the open-im-server directory From c979824a67f835bf256c1cae501c18ccd63c67d2 Mon Sep 17 00:00:00 2001 From: dsx137 <70027572+dsx137@users.noreply.github.com> Date: Wed, 11 Mar 2026 14:44:43 +0800 Subject: [PATCH 2/2] docs(core): Add anchor link to Kafka setup guide --- docs/guides/gettingStarted/env-comp.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/gettingStarted/env-comp.md b/docs/guides/gettingStarted/env-comp.md index 087f6c2303..61450c576e 100644 --- a/docs/guides/gettingStarted/env-comp.md +++ b/docs/guides/gettingStarted/env-comp.md @@ -38,7 +38,7 @@ sidebar_position: 1 | MongoDB | `v7.0` | `standalone`、`replicaSet`、`sharded` | 支持；如接副本集或分片集群，建议优先使用 `uri` | | Redis | `v7.0.0` | `standalone`、`cluster`、`sentinel` | 支持 | | Etcd | `v3.5.13` | 单机、多节点集群 | 不支持云服务 | -| Kafka | `v3.5.1` | 单机、分布式集群 | 支持；需[按文档预建 topic](./imSourceCodeDeployment#2.2-自行部署组件或使用云服务时的初始化要求) | +| Kafka | `v3.5.1` | 单机、分布式集群 | 支持；需[按文档预建 topic](./imSourceCodeDeployment#22-自行部署组件或使用云服务时的初始化要求) | | MinIO | `RELEASE.2024-01-11T07-46-16Z` | 单机 | 可替换为 S3 兼容存储（`COS`、`OSS`、`Kodo`(社区维护)、`AWS S3`） | ---