feat: gettingStarted (#290)

* feat(docs): add fault recovery guide and enhance getting started docs

- Add faultRecovery.mdx with backup, recovery, and testing procedures
- Update all getting started guides with OpenIMSDK naming consistency
- Enhance dockerCompose.mdx with better instructions and troubleshooting
- Update cluster.mdx with proper OpenIMServer naming
- Add comprehensive quickTestServer.mdx with validation steps

# Conflicts:
#	docs/guides/gettingStarted/production.md

* fix(docs): Update faultRecovery.mdx with improved recovery steps

This commit updates the faultRecovery.mdx documentation to clarify and improve the steps for OpenIMServer and ChatServer recovery, including specific commands and considerations for various failure scenarios.  The changes address inconsistencies and provide more detailed instructions for restoring services after an outage.

* refactor(docs): refine deployment and fault recovery docs

* refactor: replace latest tag with stable release tag
Update documentation and config to enforce stable release usage instead of luminous 'latest' tags, clarifying terminology and reducing instability risks.

* 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

* feat(docs): add production deployment guide and reorganize gettingStarted docs

Add production.md with single-machine production deployment guide, internalDeployment.md with internal network deployment guide, and env-comp.md with platform requirements. Reorganize gettingStarted docs with clearer structure and improved content.

* feat: translate to English

* refactor(docs): remove redundant text and fix links

- Remove "APP business server" redundancy from nginx config
- Fix relative link format in deployment docs
- Clean up duplicate content in test server guide

* refactor: docs - Update environment configuration documentation

The documentation for environment configuration has been updated. This includes clarifying naming conventions, versioning strategies, and environment requirements. Also updated external component requirements and default port configurations.

Author: dsx137

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