OpenIM 集成指南

本指南介绍如何将 Dynamic Domain SDK 与 OpenIM 结合使用，以解决 IM 消息在特殊网络环境下的封锁问题。

集成思路

OpenIM 的核心逻辑运行在原生层（Go 核心），它不会自动接管 Flutter 的代理设置。因此，我们需要：

1. 启动 Dynamic Domain 隧道获取本地 SOCKS5 端口。
2. 将该端口显式传递给 OpenIM SDK。

代码实现

1. 启动并获取代理配置

final dynamicDomain = DynamicDomain();
await dynamicDomain.init("your_app_id");

// 获取配置并启动隧道
String config = await dynamicDomain.fetchRemoteConfig();
await dynamicDomain.startTunnel(config);

// 获取结构化的代理配置
final proxy = dynamicDomain.getProxyConfig();
if (proxy != null) {
  print("HTTP 代理: ${proxy.httpUrl}");
  print("SOCKS5 代理: ${proxy.socksUrl}");
}

2. 配置 OpenIM SDK

在初始化 OpenIM 时，根据其提供的 API 设置代理。

方案 A：一键应用环境变量 (最简便)

由于 OpenIM 的核心是用 Go 编写的，Go 运行时默认会读取进程的环境变量。我们提供了 applyToEnvironment() 方法来自动完成这一操作。

if (proxy != null) {
  // 一键将代理应用到 ALL_PROXY, HTTP_PROXY 等环境变量
  // 这会让底层的 Go Core 自动识别并使用隧道
  await proxy.applyToEnvironment();
}

方案 B：手动显式设置代理 (最稳健)

如果您的 OpenIM SDK 版本支持设置代理服务器地址，请务必优先使用 SOCKS5 协议，因为它对长连接（WebSocket）的支持更稳定。

// 伪代码示例，具体取决于 OpenIM Flutter SDK 的 API
OpenIM.iMManager.setProxy(
  proxyUrl: proxy.socksUrl, 
  type: 'socks5'
);

await OpenIM.iMManager.initSDK(
  platform: ...,
  apiAddr: "https://your-im-api.com",
  wsAddr: "ws://your-im-ws.com",
  ...
);

为什么使用 SOCKS5？

OpenIM 的核心通讯依赖 WebSocket。

• HTTP 代理：主要针对短连接请求，对长连接的转发效率较低，且容易断连。
• SOCKS5 代理：在传输层进行转发，完美支持 TCP/UDP 和 WebSocket，是 IM 场景的首选。

开发建议 (Pro Tips)

1. 时序控制

确保在调用 OpenIM.iMManager.initSDK 之前 已经完成了 proxy.applyToEnvironment()。如果 OpenIM 已经启动了连接线程，之后设置的环境变量可能不会立即生效。

2. 证书 Pinning 冲突

如果您的 OpenIM 服务端开启了严格的证书校验（SSL Pinning），经过隧道代理时可能会因为证书指纹改变而报错。此时建议：

• 在 DynamicDomain 中配置该域名为“直连”（如果该域名未被封锁）。
• 或者在 OpenIM SDK 中信任隧道的本地 CA（如果适用）。

3. 自动重连逻辑

IM 场景对连接敏感。当 Dynamic Domain 触发自动重连或切换节点时，本地代理端口可能会有短暂的瞬断。

• 建议：在 OpenIM 的连接回调中监听 onConnectFailed，并配合 dynamicDomain.isConnectionHealthy() 进行智能重连尝试。

常见问题

Q: 接入后消息依然发送失败？ A: 请确认您的 OpenIM 服务端域名是否在 DynamicDomain 的分流白名单中。如果服务端在国内，请确保配置为“直连”；如果在海外，请确保走“隧道代理”。