feat: gettingStarted

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`以内。
-

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,17 +58,35 @@ 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. 常见问题
 
 ### 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)。
+必须采用环境变量的方式修改配置，参考[设置环境变量指南](https://github.com/openimsdk/openim-docker/issues/136)。

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`） |
 
 ---
-