feat: faultRecovery

docs/guides/gettingStarted/faq.mdx

@@ -140,7 +140,38 @@ docker compose down  # 关闭组件
       KAFKA_HEAP_OPTS: "-Xms256m -Xmx256m"  # 添加该限制
 ```
 
+---
 
+## 六、 如何单步调试
 
----
+这一部分介绍在源码部署场景下，以单步调试`open-im-server`的`openim-api`服务为例，如何进行单步调试。
+
+1. 运行`docker compose up -d`和`mage start`启动服务。
+
+2. 查看控制台输出，如下所示：
+   ![debug0](faq.assets/debug0.png)
+
+   找到需要单步调试的服务，查看其`PID`，并使用命令停止服务。
+   从图中可看到`openim-api`服务的`PID`为`854942`，可以使用如下命令停止：
+
+   ```sh
+   kill -9 854942  # 类Unix系统
+   taskkill /PID 854942 /F  # windows系统
+   ```
+
+3. 找到相应的服务启动入口，统一在`open-im-server/cmd`目录下，在编辑器中使用`Debug`模式启动服务，`openim-api`服务的启动入口文件为`open-im-server/cmd/openim-api/main.go`。
+
+4. 设置启动参数。以`Goland`编辑器为例，点击启动箭头，点击`Modify Run Configuration`，如下所示：
+   ![debug1](faq.assets/debug1.png)
+
+5. 在控制台的输出找到`openim-api`服务的启动参数。从输出中提取到`openim-api`的启动命令为：`/data/open-im-server/_output/bin/platforms/linux/amd64/openim-msggateway -i 0 -c /data/open-im-server/config/`，其中`-i 0 -c /data/icey/open-im-server/config/`就是启动参数，将其复制并粘贴到`Program arguments`，并点击`OK`，如下：
+
+   ![debug2](faq.assets/debug2.png)
+
+6. 在需要测试的代码段中打上断点。
+
+7. 使用`debug`模式启动，如下：
+   ![debug3](faq.assets/debug3.png)
 
+8. 此时代码运行到断点处会停止，即可进行单步调试，如下：
+   ![debug4](faq.assets/debug4.png)

docs/guides/gettingStarted/faultRecovery.mdx

@@ -0,0 +1,89 @@
+---
+title: '生产环境注意事项'
+sidebar_position: 21
+---
+
+本文主要讲解在单机（源码和`docker`部署）生产环境下，从数据备份到故障恢复需要关注的事项。
+
+## 一、Mongo数据备份、恢复
+
+服务端的核心数据保存在`mongo`中，只需要对mongo数据进行备份就足以恢复大部分数据，步骤如下：
+
+1. 修改`.env`文件中的`MONGO_BACKUP_DIR`为需要保存备份文件的目录（默认备份目录为`components/backup/mongo/`），尽量选择和`components`目录不同磁盘的目录。
+2. 运行`docker compose up -d`启动容器。
+3. 运行`docker exec -it mongo mongodump --uri="mongodb://openIM:openIM123@localhost:27017/openim_v3" --out="/data/backup/$(date +\%Y-\%m-\%d_\%H-\%M-\%S)";`，即可完成一次当前数据的备份。
+
+### 定时备份
+
+如果想要实现定时备份的功能，建议使用`linux`的`Crontab`定时任务实现。例如，想要每天凌晨2时进行一次数据备份，可以参考下面的步骤：
+
+1. 创建定时脚本，例如在`/data/open-im-server/`目录下创建一个名为`backup_mongo.sh`的脚本：
+   ```sh
+   vim /data/open-im-server/backup_mongo.sh
+   ```
+
+2. 在脚本中添加如下内容：
+   ```sh
+   #!/bin/bash
+   docker exec mongo mongodump --uri="mongodb://openIM:openIM123@localhost:27017/openim_v3" --out="/data/backup/$(date +\%Y-\%m-\%d_\%H-\%M-\%S)"   # 备份数据
+   docker exec mongo sh -c 'find /data/backup/ -mindepth 1 -maxdepth 1 -type d -exec stat --format="%Y %n" {} \; | sort -n | head -n -2 | cut -d" " -f2- | xargs rm -rf'   # 只保留最新两个备份
+   ```
+
+3. 添加执行权限：
+   ```bash
+   chmod +x /data/open-im-server/backup_mongo.sh
+   ```
+
+4. 创建定时任务：
+
+   ```sh
+   crontab -e  # 打开cron配置
+   # 在crontab文件中添加下面一行表示每天2时执行命令,并且只保留最新的2个备份。
+   0 2 * * * /data/open-im-server/backup_mongo.sh
+   ```
+
+   然后在编辑器中保存并退出 `crontab` 配置（通常按 `CTRL+X`，然后按 `Y` 保存）。
+
+5. 运行`crontab -l`命令可查看定时任务是否添加成功。
+
+如果需要其他定时规则，修改`cron`表达式即可。
+
+以上命令会保留的最新的两个备份，可以防止在备份的过程中出现异常导致备份数据损坏而损失数据的情况。
+
+### 恢复备份数据
+
+如果需要恢复备份的数据，需要进行以下步骤：
+
+1. 停止`open-im-server`服务，运行`docker compose down`删除容器。
+
+2. 删除`components/redis/`和`components/mongodb/data/`文件夹。
+
+3. 到备份的目录中找到需要恢复的数据的名称，将下面命令中的`your_backup_name`替换为备份数据目录名称并运行：
+
+   ```sh
+   docker exec -it mongo mongorestore --uri="mongodb://openIM:openIM123@localhost:27017/openim_v3" /data/backup/your_backup_name/openim_v3
+   ```
+
+4. 运行`docker compose up -d`启动容器，启动`open-im-server`服务。
+
+## 二、组件异常停止
+
+1. 如果`mongo`、`redis`、`kafka`异常停止，先尝试重启服务。
+
+2. 如果由于数据原因启动失败：
+
+   - `redis`启动失败：删除`components/redis/`目录。
+   - `kafka`启动失败：删除`components/kafka/`目录。
+   - `mongo`启动失败：尝试[恢复备份数据文件](#恢复备份数据)。
+
+   对数据进行相应操作后启动服务。
+
+3. 如果`etcd`异常停止，需要首先关闭`open-im-server`和`chat`服务，然后重启`etcd`组件后，再启动`open-im-server`和`chat`服务。
+   如果`etcd`启动失败，删除`components/etcd/`目录，再尝试启动。
+
+## 三、潜在风险
+
+1. 单机情况下，如果由于机器故障导致服务崩溃，则无法恢复数据。
+2. 为了防止由于磁盘硬件故障导致的数据丢失，建议将`mongo`的备份目录设置为与`components`目录不同磁盘的目录下。
+3. 当恢复备份数据时，会丢失备份时间之后的所有数据。备份数据的间隔如果过短，**会对性能造成较大损耗**。
+4. 恢复备份数据为了保证数据一致性，需要删除`redis`中的数据，会导致**消息的未读数异常**。