异常处理及数据恢复

在生产环境中，通常会采用集群部署来保证组件和服务的高可用性。然而，在资源有限的情况下，也可能采用单机部署（源码部署或 Docker 部署）。

一、mongo 定时数据备份

OpenIMServer 核心数据存储在 MongoDB 中，因此备份 MongoDB 数据可以恢复大部分业务数据。

1. 修改备份目录

在 .env 中修改 MONGO_BACKUP_DIR（默认 components/backup/mongo/）。
建议将备份目录放在与 components 不同的磁盘，避免同盘故障导致源数据与备份同时损坏。

2. 配置定时备份

crontab -e

添加示例任务（每天 2 点备份，保留最近 2 份）：

0 2 * * * docker exec mongo mongodump --uri="mongodb://openIM:openIM123@localhost:27017/openim_v3" --out="/data/backup/$(expr $(date +\%s) / 86400 \% 2)"

检查是否生效：

crontab -l

二、异常测试范围与执行方法

1. 测试范围

外部组件：MongoDB Redis Kafka Etcd MinIO
OpenIMServer 服务：openim-api openim-msggateway openim-rpc-* openim-msgtransfer openim-push openim-crontask
ChatServer 服务：chat-api chat-rpc admin-api admin-rpc bot-api bot-rpc

2. 标准执行步骤

记录基线：mage check、核心接口探针、关键日志状态。
故障注入：停组件或 kill 单个服务。
影响观察：记录“完全不可用 / 部分可用 / 可用但退化”。
执行恢复：重启组件或服务，必要时恢复数据。
验收复测：探针恢复、链路恢复、日志无持续报错。
分时复测：恢复后建议在 0s / 3s / 10s / 30s 各复测一次；涉及 Etcd 的场景建议延长到 60s+ 观察服务注册回稳。

3. 测试前基线命令

源码部署执行 mage 相关命令前，请先确保安装 Go 与 mage。

# OpenIMServer
cd /path/to/open-im-server
mage check

# ChatServer
cd /path/to/chat
mage check

# 外部组件（docker compose 部署时）
docker ps --format '{{.Names}}\t{{.Status}}' | grep -E 'mongo|redis|kafka|etcd|minio'

# OpenIMServer 鉴权探针
curl -sS -X POST "http://127.0.0.1:10002/auth/get_admin_token" \
  -H "Content-Type: application/json" \
  -H "operationID: fault-baseline" \
  -d '{"secret":"your_openim_secret","userID":"imAdmin"}'

# ChatServer 业务探针
curl -sS -X POST "http://127.0.0.1:10008/application/latest_version" \
  -H "Content-Type: application/json" \
  -H "operationID: fault-baseline-chat" \
  -d '{}'

三、异常测试方案

1. 外部组件故障

注入对象	注入方式（示例）	主要影响	是否可部分服务	修复动作
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`
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`

2. OpenIMServer 单服务故障

注入对象	注入方式（示例）	主要影响	是否可部分服务	修复动作
`openim-api`	`pkill -f openim-api`	REST API 不可用，Chat 对 OpenIM 调用失败	否	实测单独 `mage start openim-api` 不足以恢复完整链路，建议 `mage stop && mage start`
`openim-msggateway`	`pkill -f openim-msggateway`	WS 连接断开，实时消息中断	否（实时链路）	同上
`openim-rpc-auth`	`pkill -f openim-rpc-auth`	token 相关能力异常	是（部分不依赖鉴权链路）	同上
`openim-rpc-msg`	`pkill -f openim-rpc-msg`	消息发送/拉取异常	是（非消息接口可用）	同上
`openim-msgtransfer`	`pkill -f openim-msgtransfer`	消息转发链路中断或高延迟	是（非消息接口可用）	同上
`openim-push`	`pkill -f openim-push`	离线推送失败	是（在线消息通常可用）	同上
`openim-crontask`	`pkill -f openim-crontask`	定时任务不执行	是（实时链路通常可用）	同上

3. ChatServer 单服务故障

注入对象	注入方式（示例）	主要影响	是否可部分服务	修复动作
`chat-api`	`pkill -f chat-api`	业务系统接口失败（10008）	否（Chat 业务入口受阻）	实测单独 `mage start chat-api` 可能连带影响其他 Chat 服务，建议 `mage stop && mage start`
`chat-rpc`	`pkill -f chat-rpc`	Chat 核心业务接口异常	否（Chat 核心链路）	同上
`admin-api`	`pkill -f admin-api`	管理后台接口失败（10009），10008 可继续提供服务	是（用户侧链路可继续）	实测单独 `mage start admin-api` 可能出现 `admin-rpc` 不可用，建议 `mage stop && mage start`
`admin-rpc`	`pkill -f admin-rpc`	管理后台业务失败	是	同上
`bot-api`/`bot-rpc`	`pkill -f bot-api` / `pkill -f bot-rpc`	Bot 相关能力失败	是（主链路可继续）	同上

说明：上表“单服务拉起风险”主要针对 mage start <service> 场景。mage 在单服务启动时会先停止现有服务并执行全量状态校验，异常恢复期可能出现联动影响；若直接拉起对应二进制且依赖健康，单服务通常可恢复。

四、组件异常停止处理

1. 通用恢复顺序

先恢复外部组件。
再恢复 OpenIMServer。
最后恢复 ChatServer。
全量执行 mage check + 探针复测。

2. 外部组件恢复

cd /path/to/open-im-server
docker compose up -d mongodb redis kafka etcd minio

docker ps --format '{{.Names}}\t{{.Status}}' | grep -E 'mongo|redis|kafka|etcd|minio'

3. OpenIMServer 恢复

cd /path/to/open-im-server
mage check
mage stop
mage start
mage check

4. ChatServer 恢复

cd /path/to/chat
mage check
mage stop
mage start
mage check

5. MongoDB 数据恢复

docker exec -it mongo mongorestore \
  --uri="mongodb://openIM:openIM123@localhost:27017/openim_v3" \
  /data/backup/your_backup_name/openim_v3

五、潜在风险

单机部署存在单点故障，无法等价替代高可用集群。
若源数据盘与备份盘同时损坏，无法直接恢复，只能依赖云厂商快照或其他离线备份。
MongoDB 恢复到历史备份点后，备份时间点之后的数据会丢失。
删除 Redis 数据可能导致未读数、会话状态等短期不一致。
OpenIM/Chat 相关 API 探针必须带 operationID 请求头，否则会返回参数错误。
Redis 恢复后多数场景可自动恢复；若鉴权仍异常，再执行 OpenIM 全量重启（mage stop && mage start）。
Etcd 宕机时，已运行实例可短时可用；但在服务重启阶段可能失败，且恢复后可能存在短暂注册延迟，需先恢复 Etcd 并观察。
Chat 单服务拉起（如 mage start chat-api、mage start admin-api）在异常场景下可能导致其他 Chat 进程缺失，故障恢复优先采用 Chat 全量重启。
Kafka/MinIO 场景应补充消息链路、文件链路闭环探针，避免仅依据基础探针判断恢复完成。

异常处理及数据恢复

一、mongo 定时数据备份​

1. 修改备份目录​

2. 配置定时备份​

二、异常测试范围与执行方法​

1. 测试范围​

2. 标准执行步骤​

3. 测试前基线命令​

三、异常测试方案​

1. 外部组件故障​

2. OpenIMServer 单服务故障​

3. ChatServer 单服务故障​

四、组件异常停止处理​

1. 通用恢复顺序​

2. 外部组件恢复​

3. OpenIMServer 恢复​

4. ChatServer 恢复​

5. MongoDB 数据恢复​

五、潜在风险​