常见问题

一、如何升级

在同一大版本内，不同小版本之间的数据通常兼容。建议优先升级到目标仓库的 latest tag；如需固定版本（例如 v3.8.3-patch.12），请显式 checkout 对应 tag。

Docker 部署

1. 进入已有的 openim-docker 目录：

   cd openim-docker

2. 拉取最新 tag 并切换：

   git fetch --tags
   TARGET_TAG=$(git tag --sort=-v:refname | head -n 1)
   git checkout "$TARGET_TAG"
   echo "upgrade openim-docker to tag: $TARGET_TAG"

3. 检查 .env 中镜像 tag 与当前仓库版本一致（必要时按发布说明手动调整）。

4. 停止现有的 Docker 服务：

   docker compose down

5. 启动更新后的 Docker 服务：

   docker compose pull
   docker compose up -d

源码部署

1. 进入已有的 open-im-server 目录：

   cd open-im-server

2. 停止当前服务：

   mage stop

3. 切换到最新 tag（或指定 tag）并更新代码：

   git fetch --tags
   TARGET_TAG=$(git tag --sort=-v:refname | head -n 1)
   git checkout "$TARGET_TAG"

4. 编译并启动服务：

   mage
   mage start

5. 如果部署了 ChatServer，也建议同步升级到对应 tag 后再重启 Chat 服务。

---

二、 如何迁移数据

在使用docker compose up -d命令启动 OpenIMServer 依赖的各个组件之后，OpenIMServer 根目录下会生成一个components文件夹，OpenIMServer 运行后产生的数据（如用户、群聊、消息等）都保存在这个文件夹中。如果需要迁移数据，需要先关闭服务和组件：

docker部署：

docker compose down

源码部署：

mage stop  # 关闭服务
docker compose down  # 关闭组件

然后移动整个文件夹到数据目录，修改.env文件中DATA_DIR的值为新数据目录，再启动服务和组件：

docker部署：

docker compose up -d  # 启动组

源码部署：

docker compose up -d  # 启动组件
mage start  # 启动服务

---

三、 如何清除数据

如需要清除数据，需要先关闭服务和组件：

docker部署：

docker compose down

源码部署：

mage stop  # 关闭服务
docker compose down  # 关闭组件

然后删除open-im-server下的components文件夹。

客户端方面需要重新卸载重装app。

---

四、 发送文本消息正常，但发送图片失败

一般发送图片失败是由于没有配置第三方存储的原因。默认使用的第三方存储为minio，需修改相关配置

源码部署：
修改 config/minio.yml 文件，配置 MinIO 外网 IP，以支持发送图片和文件，其中 `your-server-ip` 为服务端外网 IP
externalAddress="http://your-server-ip:10005"

docker部署
修改 .env 文件，配置 MinIO 外网 IP，以支持发送图片和文件，其中 `your-server-ip` 为服务端外网 IP
MINIO_EXTERNAL_ADDRESS="http://your-server-ip:10005"

---

五、 减少Mongo、Kafka内存占用

如果是是使用docker部署的各个组件，可以通过在docker-compose.yml文件中限制mongo和kafka的内存的方式来减小内存的占用。

mongo：

  mongodb:
    environment:
    - wiredTigerCacheSizeGB=0.5  # 修改为适当的值，单位GB

kafka：

  kafka:
    environment:
      KAFKA_HEAP_OPTS: "-Xms256m -Xmx256m"  # 添加该限制

---