docs(getting-started): refactor and improve getting started guide

- Add health check timing and operational warnings across deployment docs
- Clarify naming differences between openim-docker and open-im-server
- Restructure validation steps and deployment procedures for clarity
- Include missing scenarios: non-domain validation, internal deployment
- Update compatibility notes (Debian 13) and port configurations
- Enhance fault recovery with more detailed scenarios and steps

Author: dsx137

docs/guides/gettingStarted/cluster.md

@@ -38,6 +38,8 @@ A 和 B 两台机器以及组件集群内网互通，且A、B两台机器都有
 - **Etcd 集群**
 - **MinIO 服务**
 
+> 本文仅覆盖两台 OpenIMServer 业务节点与 Nginx 的部署，不包含 Redis/MongoDB/Kafka/Etcd 集群本身的搭建过程。若当前只有两台空机器，请先完成这些外部组件集群的部署后再继续本文步骤。
+
 ### 1. 克隆仓库
 
 在两台机器（A 和 B）上分别执行以下命令以克隆 OpenIMServer 仓库，并切到 GitHub Releases 页面绿色 **Latest** 对应的**最新正式发布 tag**：
@@ -130,7 +132,7 @@ http {
         ssl_certificate     /usr/local/nginx/conf/ssl/your_host_bundle.pem;  # 替换为您的证书路径
         ssl_certificate_key /usr/local/nginx/conf/ssl/your_host.key;        # 替换为您的证书密钥路径
 
-        location ^~/api/ {
+        location ^~ /api/ {
             proxy_http_version 1.1;
             proxy_set_header Upgrade $http_upgrade;
             proxy_set_header Connection "Upgrade";
@@ -177,6 +179,15 @@ $ go env -w GOPROXY=https://goproxy.cn,direct
 ```
 
 #### 5.1 编译
+
+首次在每台机器执行前，建议先运行：
+
+```bash
+bash bootstrap.sh
+```
+
+该步骤会安装 `mage`。如果你的机器已预装 `mage`，可跳过。
+
 ```bash
 mage
 ```

docs/guides/gettingStarted/dockerCompose.md

@@ -39,6 +39,12 @@ echo "using openim-docker stable release tag: $LATEST_STABLE_TAG"
 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，而你并未启用这些组件的鉴权，这类提示通常可以忽略。
+
 
 - 停止服务：
 
@@ -64,6 +70,7 @@ 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目录下的修改配置文件无效！

docs/guides/gettingStarted/env-comp.md

@@ -13,7 +13,7 @@ sidebar_position: 1
 
 | 注意事项 | 详细说明 | 补充说明 |
 | --- | --- | --- |
-| 操作系统 | Linux | 官方使用 `ubuntu 22.04` |
+| 操作系统 | 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/) |

docs/guides/gettingStarted/faq.md

@@ -69,7 +69,7 @@ sidebar_position: 10
 ---
 ## 二、 如何迁移数据
 
-在使用`docker compose up -d`命令启动 OpenIMServer 依赖的各个组件之后，OpenIMServer 根目录下会生成一个`components`文件夹，OpenIMServer 运行后产生的数据（如用户、群聊、消息等）都保存在这个文件夹中。如果需要迁移数据，需要先关闭服务和组件：
+在使用 `docker compose up -d` 启动组件后，当前部署仓库根目录下会生成一个 `components` 文件夹（例如 `openim-docker/components` 或 `open-im-server/components`）。运行后产生的数据（如用户、群聊、消息等）都保存在这个目录中。如果需要迁移数据，需要先关闭服务和组件：
 
 `docker`部署：
 
@@ -89,7 +89,7 @@ docker compose down  # 关闭组件
 `docker`部署：
 
 ```sh
-docker compose up -d  # 启动组
+docker compose up -d  # 启动组件
 ```
 
 源码部署：
@@ -117,7 +117,7 @@ mage stop  # 关闭服务
 docker compose down  # 关闭组件
 ```
 
-然后删除`open-im-server`下的`components`文件夹。
+然后删除当前部署仓库下的 `components` 文件夹。
 
 客户端方面需要重新卸载重装`app`。
 
@@ -128,7 +128,7 @@ docker compose down  # 关闭组件
 ```
 源码部署：
 修改 config/minio.yml 文件，配置 MinIO 外网 IP，以支持发送图片和文件，其中 `your-server-ip` 为服务端外网 IP
-externalAddress="http://your-server-ip:10005"
+externalAddress: http://your-server-ip:10005
 ```
 
 ```
@@ -142,10 +142,12 @@ 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
 ```

docs/guides/gettingStarted/faultRecovery.mdx

@@ -94,10 +94,10 @@ curl -sS -X POST "http://127.0.0.1:10008/application/latest_version" \
 | 注入对象 | 注入方式（示例） | 主要影响 | 是否可部分服务 | 修复动作 |
 | --- | --- | --- | --- | --- |
 | MongoDB | `docker stop mongo` | 注册/登录、历史消息与业务数据读写异常 | 是（鉴权可用，业务数据链路受阻） | `docker start mongo`，必要时执行备份恢复 |
-| Redis | `docker stop redis` | OpenIM 鉴权链路报 `auth-rpc-service down` | 是（部分接口仍可返回） | `docker start redis` 后先观察 `30-60s`；若鉴权仍异常再执行 OpenIM `mage stop && mage start` |
+| Redis | `docker stop redis` | OpenIM 鉴权链路异常；源码部署常见 `auth-rpc-service down`，Docker 一体化部署常见 Redis 连接/解析错误 | 是（部分接口仍可返回） | `docker start redis` 后先观察 `30-60s`；若鉴权仍异常再执行 OpenIM `mage stop && mage start` |
 | Kafka | `docker stop kafka` | 消息转发与推送链路受阻，可能积压 | 是（非消息链路可部分可用） | `docker start kafka`，核查 topic 消费恢复 |
 | Etcd | `docker stop etcd` | 运行中实例短时可用；`mage start` 阶段会卡在组件检查/服务注册 | 是（短时） | 先 `docker start etcd` 并等待服务注册回稳（建议 `5-10s`），再执行 OpenIM/Chat 全量重启与复检 |
-| MinIO | `docker stop minio` | 图片/文件上传下载失败 | 是（文本消息通常可用） | `docker start minio`，检查 `externalAddress` |
+| MinIO | `docker stop minio` | 图片/文件上传下载失败；源码部署下基础探针通常仍可用，Docker 一体化部署下可能连带 `10002/10008/10009` 基础探针异常 | 视部署方式而定 | `docker start minio`，检查 `externalAddress`；若 `30-60s` 后基础探针仍未恢复，再重启 OpenIM/Chat 服务栈 |
 
 ### 2. OpenIMServer 单服务故障
 
@@ -139,6 +139,8 @@ cd /path/to/open-im-server
 docker compose up -d mongodb redis kafka etcd minio
 ```
 
+> 如果你使用的是 `openim-docker` 仓库，对应服务名为 `mongo redis kafka etcd minio`；如果你使用的是 `open-im-server` 仓库，对应服务名为 `mongodb redis kafka etcd minio`。
+
 ```bash
 docker ps --format '{{.Names}}\t{{.Status}}' | grep -E 'mongo|redis|kafka|etcd|minio'
 ```

docs/guides/gettingStarted/imSourceCodeDeployment.md

@@ -49,6 +49,8 @@ echo "using open-im-server stable release tag: $LATEST_STABLE_TAG"
 docker compose up -d
 ```
 
+> 当前 `open-im-server/docker-compose.yml` 除外部组件外，还会一并拉起 `openim-web-front`、`openim-admin-front`。如果你当前只想部署依赖组件，可以按需调整 compose 文件后再启动。
+
 ### 2.2 自行部署组件或使用云服务时的初始化要求
 
 | 存储组件 | 初始化要求 |
@@ -60,6 +62,8 @@ docker compose up -d
 
 确保 Go 已正确安装。
 
+> `bootstrap.sh` 会尝试自动安装 `mage`，但前提是系统里已经有可用的 `go` 命令。因此如果 `go version` 不通过，后续 `bash bootstrap.sh`、`mage` 都无法执行。
+
 ### 3.1 中国境内建议设置 Go 代理
 
 ```bash
@@ -103,6 +107,8 @@ mage
 | 停止 | `mage stop` | - |
 | 检测 | `mage check` | - |
 
+> 首次启动后建议等待 `20-30s` 再执行 `mage check` 或接口验证，避免把启动过程中的短暂连接失败误判为最终异常。
+
 ## 四、获取 Chat
 
 > 如果已有自有账号系统，可不部署 ChatServer。
@@ -147,6 +153,8 @@ mage
 | 停止 | `mage stop` | - |
 | 检测 | `mage check` | - |
 
+> ChatServer 启动时依赖 OpenIMServer 先可用，建议在 OpenIMServer `mage check` 正常后，再启动 ChatServer，并等待 `20-30s` 再验证 `10008/10009` 接口。
+
 ## 六、配置文件说明
 
 - OpenIMServer 配置说明请以当前检出代码的 `config/README_zh_CN.md` 为准。
@@ -196,4 +204,4 @@ mage
 
 ### 10.3 单机生产环境数据备份及恢复
 
-请参考：[单机生产环境数据备份及恢复](./faultRecovery)
+请参考：[单机生产环境数据备份及恢复](./faultRecovery.mdx)

docs/guides/gettingStarted/internalDeployment.md

@@ -84,8 +84,14 @@ sidebar_position: 4
 
 3. 参考 [docker部署](#docker部署) 步骤保存依赖组件镜像（源码部署场景不需要服务端业务镜像）。
 
+   > 注意：`open-im-server/docker-compose.yml` 当前默认还会拉起 `openim-web-front`、`openim-admin-front`。如果部署机上的 compose 文件不做裁剪，则还需要一并准备这两个前端镜像；如果你只想部署依赖组件，请先在联网机器调整 compose 文件后再离线拷贝。
+
 4. 通过内网或者物理介质将**镜像文件**、**OpenIMServer 仓库文件**、**ChatServer 仓库文件**拷贝到部署机器上。
 
+   > 纯内网机器如果无法访问 Go 模块源，直接执行 `mage` 可能失败，因为源码仓库默认**不包含 vendor 依赖**。这种场景建议二选一：
+   > 1. 在联网机器提前编译好 `_output/bin` 后再拷贝到内网机器；
+   > 2. 在联网机器预先准备 `go` 依赖缓存和 `mage` 可执行文件，再一起拷贝到内网机器。
+
 5. 导入镜像到`docker`中，命令为：
 
    ```bash
@@ -101,12 +107,14 @@ sidebar_position: 4
 6. 在 OpenIMServer 目录下依次运行：
    ```bash
    docker compose up -d  # 如需启用监控组件则为 docker compose --profile m up -d
+   bash bootstrap.sh     # 已预装 mage 时可跳过
    mage
    mage start
    ```
 
 7. 在 ChatServer 目录下运行：
     ```bash
+    bash bootstrap.sh     # 已预装 mage 时可跳过
     mage
     mage start
     ```

docs/guides/gettingStarted/nginxDomainConfig.md

@@ -14,6 +14,8 @@ sidebar_position: 7
 - 已申请域名和 SSL 证书（示例：`im.yourhost.com`）。
 - 服务器已放行 `443` 端口。
 
+如果系统尚未安装 Nginx，可先通过发行版包管理器安装（例如 Debian/Ubuntu：`apt-get install -y nginx`）。
+
 ## 2. Nginx 配置模板
 
 > 请替换为你的实际域名、证书路径与服务地址。
@@ -40,12 +42,11 @@ upstream minio_s3 {
 }
 
 server {
-    listen 443;
+    listen 443 ssl;
     server_name im.yourhost.com;
 
-    ssl on;
-    ssl_certificate /usr/local/nginx/conf/ssh/im.yourhost.com_bundle.pem;
-    ssl_certificate_key /usr/local/nginx/conf/ssh/im.yourhost.com.key;
+    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 {
         proxy_http_version 1.1;
@@ -56,7 +57,7 @@ server {
         proxy_pass http://msg_gateway/;
     }
 
-    location ^~/api/ {
+    location ^~ /api/ {
         proxy_http_version 1.1;
         proxy_set_header Upgrade $http_upgrade;
         proxy_set_header Connection "Upgrade";
@@ -66,7 +67,7 @@ server {
         proxy_pass http://im_api/;
     }
 
-    location ^~/chat/ {
+    location ^~ /chat/ {
         proxy_http_version 1.1;
         proxy_set_header Upgrade $http_upgrade;
         proxy_set_header Connection "Upgrade";
@@ -75,7 +76,7 @@ server {
         proxy_pass http://im_chat_api/;
     }
 
-    location ^~/im-minio-api/ {
+    location ^~ /im-minio-api/ {
         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;
@@ -103,6 +104,7 @@ https://im.yourhost.com/im-minio-api
 ## 4. 重载 Nginx
 
 ```bash
+nginx -t
 nginx -s reload
 ```
 

docs/guides/gettingStarted/ports.md

@@ -16,6 +16,8 @@ sidebar_position: 6
 | OpenIMServer | TCP:10005 | MinIO 作为对象存储 | 端口放行 |
 | ChatServer | TCP:10008 | 业务系统，如注册、登录等 | 端口放行 |
 | ChatServer | TCP:10009 | 管理后台，如统计、封号等 | 端口放行 |
+| Web 前端（可选） | TCP:11001 | PC Web 前端，快速验证页面访问时需要放行 | 按需放行 |
+| Admin 前端（可选） | TCP:11002 | 管理后台前端页面 | 按需放行 |
 
 在客户端 SDK 中，初始化参数如下：
 
@@ -44,3 +46,5 @@ wsAddr: wss://your_domain.com/msg_gateway
 ```
 
 > 说明：监控、前端等其他服务端口建议仅内网开放，按实际部署需求控制暴露范围。
+
+> 如果你要按 [快速验证](./quickTestServer) 中的浏览器步骤直接访问 `11001`，则对应前端端口必须可达；若不需要前端页面验证，可不对外开放 `11001/11002`。

docs/guides/gettingStarted/quickTestServer.md

@@ -31,9 +31,15 @@ import Image3 from './assets/pc-web.png';
 docker ps | grep -E 'openim-server|openim-chat'
 ```
 
+> `docker部署` 场景下，`openim-server` 与 `openim-chat` 在启动初期可能先显示 `health: starting`；建议等待 `20-30s`，确认状态进入 `healthy` 后再继续接口验证。
+
 如果是源码部署，可执行：
 
 ```bash
+# 在 open-im-server 目录执行
+mage check
+
+# 在 chat 目录执行
 mage check
 ```
 
@@ -51,11 +57,14 @@ curl -sS -X POST "https://your_domain/api/auth/get_admin_token" \
 ```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 客户端测试：
 
 ```text
@@ -65,3 +74,23 @@ wss://your_domain/msg_gateway
 > 建议在生产环境统一通过 `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 的 POST 接口同样要求 `operationID` 请求头；缺少该请求头会直接返回参数错误。