agent_9art/backend/archive-service/SDK_SETUP.md

企微会话存档 SDK 对接指南

一、SDK 下载

官方下载地址

• 企微开发者中心：https://developer.work.weixin.qq.com/document/path/91774
• 下载页面：「获取会话内容」→ SDK 下载

下载版本选择

环境	推荐版本	说明
Windows x64	SDK v3.0 (OpenSSL 3.0)	2025-02-13 更新
Linux x64	SDK v3.0 (OpenSSL 3.0)	2025-02-13 更新

Windows SDK 文件清单

解压后 financeWinSdk/java_sdk/WeWorkFinanceSdk/ 目录下包含：

文件	说明
WeWorkFinanceSdk.dll	主 SDK 动态库
libcrypto-3-x64.dll	OpenSSL 3.0 依赖
libssl-3-x64.dll	OpenSSL 3.0 依赖
libcurl-x64.dll	libcurl HTTP 依赖
Finance.java	官方 JNI 封装（本项目使用 JNA，无需此文件）

二、SDK 放置

Windows 环境

将上述 4 个 DLL 文件放到项目目录：

backend/archive-service/
└── sdk/                      <-- 新建此目录
    ├── WeWorkFinanceSdk.dll
    ├── libcrypto-3-x64.dll
    ├── libssl-3-x64.dll
    └── libcurl-x64.dll

Linux 环境

# 将 libWeWorkFinanceSdk_Java.so 重命名并放到系统库路径
sudo cp libWeWorkFinanceSdk_Java.so /usr/lib/libWeWorkFinanceSdk.so
sudo ldconfig

# 或者放到项目目录并通过环境变量指定
mkdir -p backend/archive-service/sdk
cp libWeWorkFinanceSdk_Java.so backend/archive-service/sdk/libWeWorkFinanceSdk.so

三、配置参数

环境变量方式（推荐）

# 企微会话存档 Secret
export WECOM_ARCHIVE_SECRET="your-archive-secret"

# RSA 私钥（PKCS#1 格式，Base64 编码）
export WECOM_ARCHIVE_RSA_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIE...\n-----END RSA PRIVATE KEY-----"

# 回调验证 Token（企微后台配置的 Token）
export WECOM_ARCHIVE_CALLBACK_TOKEN="your-callback-token"

# SDK 路径（指向存放 DLL/SO 的目录）
export WECOM_ARCHIVE_SDK_PATH="D:\www\agent_9art\backend\archive-service\sdk"

# Mock 模式（开发测试用，无真实 SDK 时设为 true）
export WECOM_ARCHIVE_MOCK=false

application.yml 配置项

wecom:
  archive:
    corp-id: wwd483c2fba24ae30a          # 企业微信 CorpID
    secret: ${WECOM_ARCHIVE_SECRET:}      # 会话存档 Secret
    rsa-private-key: ${WECOM_ARCHIVE_RSA_KEY:}           # RSA 私钥
    callback-token: ${WECOM_ARCHIVE_CALLBACK_TOKEN:}     # 回调 Token
    sdk-path: ${WECOM_ARCHIVE_SDK_PATH:}                 # SDK 目录路径
    mock-mode: ${WECOM_ARCHIVE_MOCK:false}               # Mock 模式开关

四、参数获取方式

1. CorpID

企微管理后台 → 「我的企业」→ 「企业ID」

2. 会话存档 Secret

企微管理后台 → 「管理工具」→ 「会话内容存档」→ 查看 Secret

3. RSA 密钥对

# 生成 RSA 私钥（PKCS#1 格式）
openssl genrsa -out private_key.pem 2048

# 提取公钥
openssl rsa -in private_key.pem -pubout -out public_key.pem

# 将公钥配置到企微后台
# 将私钥内容配置到 WECOM_ARCHIVE_RSA_KEY 环境变量

4. 回调 Token

企微后台配置接收消息时设置，用于验证回调请求签名。

五、Mock 模式（开发/测试）

当没有真实企微 SDK 或不想连接企微服务器时，启用 Mock 模式：

export WECOM_ARCHIVE_MOCK=true

Mock 模式下：

• 跳过 SDK 初始化，不会报错
• pullMessages() 返回 10 条模拟会话消息
• 完整的 saveAndNotify() 链路正常工作（入库 + MQ + Redis）
• 数据看板可以展示存档统计

测试接口：

# 手动触发拉取（Mock 模式下返回模拟数据）
curl -X POST "http://localhost:8082/api/v1/archive/pull" \
  -d "seq=0&limit=10"

六、验证对接成功

1. 启动服务时日志

# 真实 SDK 模式
企微存档SDK初始化成功

# Mock 模式
企微存档Mock模式已启用，跳过SDK初始化

2. 手动拉取测试

curl -X POST "http://localhost:8082/api/v1/archive/pull" \
  -d "seq=0&limit=5"

3. 回调测试（需配置可信域名）

企微后台配置回调 URL 为：

https://your-domain/api/v1/archive/callback

七、常见问题

Q1: 启动报错 UnsatisfiedLinkError: Unable to load library 'WeWorkFinanceSdk'

• 检查 WECOM_ARCHIVE_SDK_PATH 是否指向正确的 DLL 目录
• 确认 DLL 文件名正确（Windows 为 WeWorkFinanceSdk.dll）
• 确认依赖库（libcrypto/libssl/libcurl）也在同一目录

Q2: SDK 初始化返回非 0

• 检查 corp-id 和 secret 是否正确
• 确认企业已开通「会话内容存档」功能

Q3: 回调签名验证失败

• 检查 callback-token 是否与企微后台配置一致
• 确认回调 URL 没有被中间件修改参数

Q4: 数据库查询不到存档消息

• 检查 archive_messages 表是否有 deleted 字段（逻辑删除）
• MyBatis-Plus 全局配置 logic-delete-field: deleted