binarywang · Copilot · Jan 14, 2026 · Jan 14, 2026 · Jan 14, 2026 · Jan 14, 2026
diff --git a/docs/CP_MSG_AUDIT_SDK_SAFE_USAGE.md b/docs/CP_MSG_AUDIT_SDK_SAFE_USAGE.md
@@ -0,0 +1,295 @@
+# 企业微信会话存档SDK安全使用指南
+
+## 问题背景
+
+在使用企业微信会话存档功能时，部分开发者遇到了JVM崩溃的问题。典型错误信息如下：
+
+```
+SIGSEGV (0xb) at pc=0x00007fcd50460d93
+Problematic frame:
+C  [libWeWorkFinanceSdk_Java.so+0x260d93]  WeWorkFinanceSdk::TryRefresh(std::string const&, std::string const&, int)+0x23
+```
+
+## 问题原因
+
+旧版API设计存在以下问题：
+
+1. **SDK生命周期管理混乱**
+   - `getChatDatas()` 方法会返回SDK实例给调用方
+   - 开发者需要手动调用 `Finance.DestroySdk()` 来销毁SDK
+   - 但SDK在框架内部有7200秒的缓存机制
+
+2. **手动销毁导致缓存失效**
+   - 当开发者手动销毁SDK后，框架缓存中的SDK引用变为无效
+   - 后续调用（如 `getMediaFile()`）仍然使用已销毁的SDK
+   - 底层C++库访问无效指针，导致SIGSEGV错误
+
+3. **多线程并发问题**
+   - 在多线程环境下，一个线程销毁SDK后
+   - 其他线程仍在使用该SDK，导致崩溃
+
+## 解决方案
+
+从 **4.8.0** 版本开始，WxJava提供了新的安全API，完全由框架管理SDK生命周期。
+
+### 新API列表
+
+| 旧API（已废弃） | 新API（推荐使用） | 说明 |
+|----------------|------------------|------|
+| `getChatDatas()` | `getChatRecords()` | 拉取聊天记录，不暴露SDK |
+| `getDecryptData(sdk, ...)` | `getDecryptChatData(...)` | 解密聊天数据，无需传入SDK |
+| `getChatPlainText(sdk, ...)` | `getChatRecordPlainText(...)` | 获取明文数据，无需传入SDK |
+| `getMediaFile(sdk, ...)` | `downloadMediaFile(...)` | 下载媒体文件，无需传入SDK |
+
+### 使用示例
+
+#### 错误用法（旧API，已废弃）
+
+```java
+// ❌ 不推荐：容易导致JVM崩溃
+WxCpMsgAuditService msgAuditService = wxCpService.getMsgAuditService();
+
+// 拉取聊天记录
+WxCpChatDatas chatDatas = msgAuditService.getChatDatas(seq, 1000L, null, null, 1000L);
+
+for (WxCpChatDatas.WxCpChatData chatData : chatDatas.getChatData()) {
+    // 解密数据
+    WxCpChatModel model = msgAuditService.getDecryptData(chatDatas.getSdk(), chatData, 2);
+
+    // 下载媒体文件
+    if ("image".equals(model.getMsgType())) {
+        String sdkFileId = model.getImage().getSdkFileId();
+        msgAuditService.getMediaFile(chatDatas.getSdk(), sdkFileId, null, null, 1000L, targetPath);
+    }
+}
+
+// ❌ 危险操作：手动销毁SDK可能导致后续调用崩溃
+Finance.DestroySdk(chatDatas.getSdk());
+```
+
+#### 正确用法（新API，推荐）
+
+```java
+// ✅ 推荐：SDK生命周期由框架自动管理，安全可靠
+WxCpMsgAuditService msgAuditService = wxCpService.getMsgAuditService();
+
+// 拉取聊天记录（不返回SDK）
+List<WxCpChatDatas.WxCpChatData> chatRecords = 
+    msgAuditService.getChatRecords(seq, 1000L, null, null, 1000L);
+
+for (WxCpChatDatas.WxCpChatData chatData : chatRecords) {
+    // 解密数据（无需传入SDK）
+    WxCpChatModel model = msgAuditService.getDecryptChatData(chatData, 2);
+
+    // 下载媒体文件（无需传入SDK）
+    if ("image".equals(model.getMsgType())) {
+        String sdkFileId = model.getImage().getSdkFileId();
+        msgAuditService.downloadMediaFile(sdkFileId, null, null, 1000L, targetPath);
+    }
+}
+
+// ✅ 无需手动销毁SDK，框架会自动管理
+```
+
+### 完整示例：拉取并处理会话存档
+
+```java
+import me.chanjar.weixin.cp.api.WxCpService;
+import me.chanjar.weixin.cp.api.WxCpMsgAuditService;
+import me.chanjar.weixin.cp.bean.msgaudit.WxCpChatDatas;
+import me.chanjar.weixin.cp.bean.msgaudit.WxCpChatModel;
+import me.chanjar.weixin.cp.constant.WxCpConsts;
+
+import java.util.List;
+
+public class MsgAuditExample {
+
+    private final WxCpService wxCpService;
+
+    public void processMessages(long seq) throws Exception {
+        WxCpMsgAuditService msgAuditService = wxCpService.getMsgAuditService();
+
+        // 拉取聊天记录
+        List<WxCpChatDatas.WxCpChatData> chatRecords = 
+            msgAuditService.getChatRecords(seq, 1000L, null, null, 1000L);
+
+        for (WxCpChatDatas.WxCpChatData chatData : chatRecords) {
+            seq = chatData.getSeq();
+
+            // 获取明文数据
+            String plainText = msgAuditService.getChatRecordPlainText(chatData, 2);
+            WxCpChatModel model = WxCpChatModel.fromJson(plainText);
+
+            // 处理不同类型的消息
+            switch (model.getMsgType()) {
+                case WxCpConsts.MsgAuditMediaType.TEXT:
+                    processTextMessage(model);
+                    break;
+
+                case WxCpConsts.MsgAuditMediaType.IMAGE:
+                    processImageMessage(model, msgAuditService);
+                    break;
+
+                case WxCpConsts.MsgAuditMediaType.FILE:
+                    processFileMessage(model, msgAuditService);
+                    break;
+
+                default:
+                    // 处理其他类型消息
+                    break;
+            }
+        }
+    }
+
+    private void processTextMessage(WxCpChatModel model) {
+        String content = model.getText().getContent();
+        System.out.println("文本消息：" + content);
+    }
+
+    private void processImageMessage(WxCpChatModel model, WxCpMsgAuditService msgAuditService) 
+            throws Exception {
+        String sdkFileId = model.getImage().getSdkFileId();
+        String md5Sum = model.getImage().getMd5Sum();
+        String targetPath = "/path/to/save/" + md5Sum + ".jpg";
+
+        // 下载图片（无需传入SDK）
+        msgAuditService.downloadMediaFile(sdkFileId, null, null, 1000L, targetPath);
+        System.out.println("图片已保存：" + targetPath);
+    }
+
+    private void processFileMessage(WxCpChatModel model, WxCpMsgAuditService msgAuditService) 
+            throws Exception {
+        String sdkFileId = model.getFile().getSdkFileId();
+        String fileName = model.getFile().getFileName();
+        String targetPath = "/path/to/save/" + fileName;
+
+        // 下载文件（无需传入SDK）
+        msgAuditService.downloadMediaFile(sdkFileId, null, null, 1000L, targetPath);
+        System.out.println("文件已保存：" + targetPath);
+    }
+}
+```
+
+### 使用Lambda处理媒体文件流
+
+新API同样支持使用Lambda表达式处理媒体文件的数据流：
+
+```java
+msgAuditService.downloadMediaFile(sdkFileId, null, null, 1000L, data -> {
+    try {
+        // 处理每个数据分片（大文件会分片传输）
+        // 例如：上传到云存储、写入数据库等
+        uploadToCloud(data);
+    } catch (Exception e) {
+        e.printStackTrace();
+    }
+});
+```
+
+## 技术实现原理
+
+### 引用计数机制
+
+新API在内部实现了SDK引用计数机制：
+
+1. **获取SDK时**：引用计数 +1
+2. **使用完成后**：引用计数 -1
+3. **计数归零时**：SDK被自动释放
+
+```java
+// 框架内部实现（简化版）
+public void downloadMediaFile(String sdkFileId, ...) {
+    long sdk = initSdk();  // 获取或初始化SDK
+    configStorage.incrementMsgAuditSdkRefCount(sdk);  // 引用计数 +1
+
+    try {
+        // 执行实际操作
+        getMediaFile(sdk, sdkFileId, ...);
+    } finally {
+        // 确保引用计数一定会减少
+        configStorage.decrementMsgAuditSdkRefCount(sdk);  // 引用计数 -1
+    }
+}
+```
+
+### SDK缓存机制
+
+SDK初始化后会缓存7200秒（企业微信官方文档规定），避免频繁初始化：
+
+- **首次调用**：初始化新的SDK
+- **7200秒内**：复用缓存的SDK
+- **超过7200秒**：重新初始化SDK
+
+新API的引用计数机制与缓存机制完美配合，确保SDK不会被提前销毁。
+
+## 迁移指南
+
+### 第一步：使用新API替换旧API
+
+查找代码中的旧API调用：
+
+```java
+// 查找模式
+getChatDatas(
+getDecryptData(.*sdk
+getChatPlainText(.*sdk
+getMediaFile(.*sdk
+Finance.DestroySdk(
+```
+
+替换为对应的新API（参考前面的对照表）。
+
+### 第二步：移除手动SDK管理代码
+
+删除所有 `Finance.DestroySdk()` 调用，SDK生命周期由框架自动管理。
+
+### 第三步：测试验证
+
+1. 在测试环境验证新API功能正常
+2. 观察日志，确认没有SDK相关的错误
+3. 进行压力测试，验证多线程环境下的稳定性
+
+## 常见问题
+
+### Q1: 旧代码会立即停止工作吗？
+
+**A:** 不会。旧API被标记为 `@Deprecated`，但仍然可用，只是不推荐继续使用。建议尽快迁移到新API以避免潜在问题。
+
+### Q2: 如何知道SDK是否被正确释放？
+
+**A:** 框架会自动管理SDK生命周期，开发者无需关心。如果需要调试，可以查看配置存储中的引用计数。
+
+### Q3: 多线程环境下新API安全吗？
+
+**A:** 是的。新API使用了引用计数机制，配合 `synchronized` 关键字，确保多线程环境下的安全性。
+
+### Q4: 性能会受影响吗？
+
+**A:** 不会。新API在实现上增加了引用计数的开销，但这是轻量级的操作（原子操作），对性能影响可以忽略不计。SDK缓存机制保持不变。
+
+### Q5: 可以同时使用新旧API吗？
+
+**A:** 技术上可以，但强烈不推荐。混用可能导致SDK生命周期管理混乱，建议统一使用新API。
+
+## 相关链接
+
+- [企业微信会话存档官方文档](https://developer.work.weixin.qq.com/document/path/91360)
+- [WxJava GitHub 仓库](https://github.com/binarywang/WxJava)
+- [问题反馈](https://github.com/binarywang/WxJava/issues)
+
+## 版本要求
+
+- **最低版本**: 4.8.0
+- **推荐版本**: 最新版本
+
+## 反馈与支持
+
+如果在使用过程中遇到问题，请：
+
+1. 查看本文档的常见问题部分
+2. 在 GitHub 上提交 Issue
+3. 加入微信群获取社区支持
+
+---
+
+**最后更新时间**: 2026-01-14