Merge pull request #225 from icey-yu/feat-doc

feat: doc

Author: skiffer-git

docs/guides/gettingStarted/_category_.json

@@ -1,6 +1,6 @@
 {
   "position": 2,
-  "label": "快速开始",
+  "label": "快速部署",
   "collapsible": true,
   "collapsed": true
 }

docs/guides/gettingStarted/admin.assets/login1.png

@@ -1,27 +1,30 @@
 ---
-title: '监控及告警'
-sidebar_position: 5
+title: '运维系统'
+sidebar_position: 9
 ---
 
 
 
 ## 组件说明
-docker compose部署时，会自动部署如下组件，如使用源码部署，需手动开启docker-compose.yaml中的相关组件。
 
 | 组件名称       | 组件说明                                      | 部署说明                                    |
 |-------------|-----------------------------------------|--------------------------------------|
-| openim-admin | 管理后台，提供监控页面入口                           | Docker和源码部署均自动开启                     |
-| prometheus  | 用于收集和存储指标数据的监控系统组件                     | Docker部署自动开启；源码部署需手动启用         |
-| alertmanager | 管理和发送告警的组件                               | Docker部署自动开启；源码部署需手动启用         |
-| grafana     | 用于展示监控数据的仪表板组件                         | Docker部署自动开启；源码部署需手动启用         |
-| node-exporter | 用于采集节点（如服务器）指标信息 | Docker部署自动开启；源码部署需手动启用         |
-
+| prometheus  | 用于收集和存储指标数据的监控系统组件                     | 需手动启用                 |
+| alertmanager | 管理和发送告警的组件                               | 需手动启用                 |
+| grafana     | 用于展示监控数据的仪表板组件                         | 需手动启用         |
+| node-exporter | 用于采集节点（如服务器）指标信息 | 需手动启用         |
 
+## 启动方式
 
+目前`OpenIM`使用的监控告警组件为`prometheus`、`alertmanager`、`grafana`、`node_exporter`。在使用`docker compose up -d`启动组件时，默认**不会**启动监控组件。如需启动监控组件，需要使用命令为：
 
+```sh
+docker compose --profile m up -d
+```
 
+> 注意：以上方式不适用于windows系统。如果需要在windows系统中启用监控组件，需要自行修改docker-compose.yml中监控组件的网络模式，并映射相应的端口，最后将prometheus.yml中的`127.0.0.1`替换为内网ip地址。
 
-## 配置文件说明
+## 配置文件和告警说明
 
 
 | 文件名称  | 文件说明                    | 修改项                       |
@@ -33,28 +36,44 @@ docker compose部署时，会自动部署如下组件，如使用源码部署，
 | config/email.tmpl| 邮件告警模版 | 默认邮件模版，可自行修改 |
 | config/grefana-template/Demo.json| 自定义dashboard | 无需修改 |
 
-
-## 配置文件和告警说明
-
-1. prometheus.yml 文件说明：主要用来配置告警规则文件路径，告警管理服务地址，抓取监控数据ip地址。需要把其中所有的`internal_ip`替换为自己的私网ip地址。如下：
-
+1. prometheus.yml 文件说明：主要用来配置告警规则文件路径，告警管理服务地址，抓取监控数据ip地址。
    ```yaml
    # Alertmanager configuration
+   global:
+     scrape_interval:     15s # prometheus抓取指标数据间隔时间
+     evaluation_interval: 15s # prometheus评估规则间隔时间
+     
    alerting:
      alertmanagers:
        - static_configs:
-           - targets: ['192.168.0.1:19093']
+           - targets: [127.0.0.1:19093]  # alertmanager 组件地址
+           
+   rule_files:
+     - instance-down-rules.yml # 告警规则配置地址
+     
+   scrape_configs:
+     # The job name is added as a label "job=job_name" to any timeseries scraped from this config.
+     # Monitored information captured by prometheus
+   
+     # prometheus fetches application services
+     - job_name: node_exporter
+       static_configs:
+         - targets: [ 127.0.0.1:20500 ]  # node_exporter地址
+   
+     - job_name: openimserver-openim-api
+       http_sd_configs:
+         - url: "http://127.0.0.1:10002/prometheus_discovery/api"  # api数据抓取地址
 
    ...
    ```
-
+   
    如果需要添加告警文件，需要在`rule_files`下添加。默认告警文件为`instance-down-rules.yml`。
-
-2. 邮件告警架构说明图：Prometheus组件加载告警规则instance-down-rules.yml文件，将符合条件的告警信息发送到alertmanager组件，alertmanager组件加载alertmanager.yml和email.tmpl文件，通过配置的告警邮箱信息和邮件模版发送邮件
+   
+3. 邮件告警架构说明图：Prometheus组件加载告警规则instance-down-rules.yml文件，将符合条件的告警信息发送到alertmanager组件，alertmanager组件加载alertmanager.yml和email.tmpl文件，通过配置的告警邮箱信息和邮件模版发送邮件
 
    ![PC Web Interface](./assets/alert2.png)
 
-3. 告警规则instance-down-rules.yaml文件说明：默认实现了两条(instance_down,database_insert_failure_alerts)邮件告警规则，如果增加告警规则可以在instance-down-rules.yml文件中添加规则。
+4. 告警规则instance-down-rules.yaml文件说明：默认实现了两条(instance_down,database_insert_failure_alerts)邮件告警规则，如果增加告警规则可以在instance-down-rules.yml文件中添加规则。
 
    ```yaml
    groups:
@@ -81,17 +100,17 @@ docker compose部署时，会自动部署如下组件，如使用源码部署，
              description: "Either MsgInsertRedisFailedCounter or MsgInsertMongoFailedCounter has increased in the last 5 minutes, indicating failures in message insert operations to Redis or MongoDB,maybe the redis or mongodb is crash."
    ```
 
-4. 告警管理alertmanager.yml文件说明：修改发送者和接收者邮箱配置信息，即可接收告警信息，如果想实现钉钉，企业微信等方式的告警通知，需要自行改写alertmanager.yml，可以参阅告警管理模块官方文档：https://prometheus.io/docs/alerting/latest/alertmanager/
+5. 告警管理alertmanager.yml文件说明：修改发送者和接收者邮箱配置信息，即可接收告警信息，如果想实现钉钉，企业微信等方式的告警通知，需要自行改写alertmanager.yml，可以参阅告警管理模块官方文档：https://prometheus.io/docs/alerting/latest/alertmanager/
 
    ```yaml
    global:
      resolve_timeout: 5m
-     smtp_from: alert@openim.io #告警信息发送邮箱
-     smtp_smarthost: smtp.163.com:465 #发送邮箱smtp地址
-     smtp_auth_username: alert@openim.io #发送邮箱授权用户名，一般和smtp_from邮箱相同
-     smtp_auth_password: YOURAUTHPASSWORD #发送邮箱授权码
+     smtp_from: your_email #告警信息发送邮箱
+     smtp_smarthost: your_smtp_addr #发送邮箱smtp地址
+     smtp_auth_username: your_username #发送邮箱授权用户名，一般和smtp_from邮箱相同
+     smtp_auth_password: your_password #发送邮箱授权码
      smtp_require_tls: false
-     smtp_hello: openim alert
+     smtp_hello: hello
 
    templates:
      - /etc/alertmanager/email.tmpl #邮件模版
@@ -111,7 +130,7 @@ docker compose部署时，会自动部署如下组件，如使用源码部署，
            send_resolved: true  # 告警解决时是否发送通知
    ```
 
-5. 邮件模版文件email.tmpl说明：此文件是html格式，告警管理模块会填充里面的变量信息，然后渲染成html格式文件，进行邮件的发送，可根据需求自行改写:
+6. 邮件模版文件email.tmpl说明：此文件是html格式，告警管理模块会填充里面的变量信息，然后渲染成html格式文件，进行邮件的发送，可根据需求自行改写:
 
    ```tmpl
    {{ define "email.to.html" }}
@@ -158,18 +177,22 @@ docker compose部署时，会自动部署如下组件，如使用源码部署，
 
 在浏览器中输入 `http://ip:11002` 来访问管理后台。此 IP 为服务端 OPENIM_IP，确保您的浏览器能访问。默认账号和密码均为 chatAdmin
 
-
 import Image4 from './assets/admin.jpg';
 
 <img src={Image4} width="700" alt="admin " />
 
 
+
 ## 登录grafana
+
 先登录管理后台，再点击左侧数据监控菜单，输入默认用户名(admin)和密码(admin)登入grafana.
+
+也可以直接访问`your_ip:13000`进行访问，将`youre_ip`改为部署机器的ip地址。
+
 ![PC Web Interface](./assets/login1.png)
 
 ## 添加Prometheus数据源
-如下图，输入Prometheus数据源的URL: http://172.28.0.1:19090 (19090为Prometheus默认端口)  点击"Save and Test"保存.
+如下图，输入Prometheus数据源的URL: http://your_ip:19090 (19090为Prometheus默认端口)  点击"Save and Test"保存.
 ![PC Web Interface](./assets/database.png)
 
 
@@ -223,16 +246,11 @@ node-exporter指标信息，如下图
 
 
 
-
 ## 告警体验
-可手动触发instancedown告警规则，如果是源码部署openim方式，执行 `make stop`命令停止openim-server服务，等待5m分钟以上，即可收到告警邮件，内容如下：
 
-![PC Web Interface](./assets/alert6.png)
+可手动触发instancedown告警规则，如果是源码部署openim方式，执行 `mage stop`命令停止`open-im-server`服务，等待1m分钟以上，即可收到告警邮件，内容如下：
 
-## 日志系统
-如果是在k8s环境通过helm chart方式部署的OpenIM服务，即通过grafana查看OpenIM所有服务的日志信息。
-目前二进制和docker部署没有集成loki日志收集组件，想体验loki日志收集功能，请采用helm chart部署，
-详情请查阅链接https://github.com/openimsdk/helm-charts/blob/main/docs/user-guide-zh.md
+![PC Web Interface](./assets/alert6.png)
 
 ## **自定义prometheus指标配置**
 
@@ -273,13 +291,3 @@ rpc_count
 ```
 
 即可查询到指标信息。
-
-
-## 常见问题
-
-1. `docker compose up -d`启动后，`prometheus`容器一直重启。
-
-   prometheus容器没启动成功一般是两个原因：
-
-   1. 没有在`prometheus.yml`中配置内网ip。
-   2. 第一次启动`prometheus`容器时可能会遇到权限问题，在`open-im-server`项目下运行`chmod -R 777 components`后重新启动容器即可。

docs/guides/gettingStarted/admin.mdx

@@ -1,6 +1,6 @@
 ---
-title: '源码集群部署指南'
-sidebar_position: 6
+title: '集群部署-源码'
+sidebar_position: 5
 ---
 
 
@@ -9,13 +9,15 @@ sidebar_position: 6
 ## open-im-server 源码集群部署指南
 
 本指南将指导您在两台机器（A 和 B，内网 IP 分别为 `IP_A` 和 `IP_B`）上集群部署 `open-im-server` 和 `nginx`，并在机器 A 上部署监控组件（Prometheus、Grafana、Alertmanager）。
-假设您已部署 Redis 集群、MongoDB 分片集群、Kafka 集群及 Etcd 集群，具体地址如下：
+此文档中假设您已部署 Redis 集群、MongoDB 分片集群、Kafka 集群及 Etcd 集群，具体地址如下：
 
 - **Redis 集群地址**: `redisAddr1`, `redisAddr2`, `redisAddr3`
 - **MongoDB 集群地址**: `mongoAddr1`, `mongoAddr2`, `mongoAddr3`
 - **Kafka 集群地址**: `kafkaAddr1`, `kafkaAddr2`, `kafkaAddr3`
 - **Etcd 集群地址**: `etcdAddr1`, `etcdAddr2`, `etcdAddr3`
 
+本文假设以上组件都部署在三台机器上，实际上不限于三台，您可根据需求自行选择多台或者一台。
+
 此外，MinIO 的内部服务访问地址配置为 `your_minio_internal_address`，外部访问地址配置为 `your_minio_external_address`。
 A 和 B 两台机器以及组件集群内网互通，且A、B两台机器都有外网IP。
 
@@ -107,7 +109,7 @@ events {
 }
 
 http {
-    # open-im-server 
+    # open-im-server
     upstream msg_gateway {
         server IP_A:10001;
         server IP_B:10001;
@@ -126,14 +128,6 @@ http {
         ssl_certificate     /usr/local/nginx/conf/ssl/your_domain_bundle.pem;  # 替换为您的证书路径
         ssl_certificate_key /usr/local/nginx/conf/ssl/your_domain.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]\.";
-
         location ^~/api/ {
             proxy_http_version 1.1;
             proxy_set_header Upgrade $http_upgrade;
@@ -166,8 +160,6 @@ http {
 
 将此配置添加到 `nginx` 的配置文件中， 并reload使配置生效：
 
-
-
 ### 4. 设置 DNS
 
 将您的域名 `your_domain.com` 指向机器A、B的外网 IP 地址。
@@ -201,6 +193,8 @@ mage start
 
 
 
+
+
 ## **常见问题/注意事项**
 
 1. 部署`kafka`时，需要修改`kafka`广播的端口。如果使用`open-im-server`中的`docker-compose.yml`部署，修改`service.kafka.environment.KAFKA_CFG_ADVERTISED_LISTENERS`中的`EXTERNAL`为访问`kafka`组件的地址。其他部署方式请自行修改。