企业微信同步账号
同步企业微信通讯录指南
本文介绍如何将企业微信的用户与组织架构同步到 TDuck 系统，包括应用配置、通讯录同步、自动同步设置与常见问题说明。
一、企业微信后台配置
1. 创建企业微信自建应用
登录企业微信管理后台，创建自建应用。 参考官方文档 👉 如何创建自建应用
应用创建后将展示在企业微信的“工作台”中，供成员使用。
2. 获取 AgentId 与 Secret
进入你创建的应用，获取以下两个关键参数：
- AgentId
- Secret
这两个参数稍后将用于 TDuck 后台配置。
二、配置 TDuck 后台
进入 TDuck 后台 → 系统配置 → 企业微信配置，填写以下参数：
- 企业ID
- 应用AgentId
- 应用Secret
- 通讯录Secret
- Token（推荐随机生成）
- EncodingAESKey（推荐随机生成）
👉 可使用在线工具生成 Token 与 AESKey：https://www.ittools.top/token-generator
⚠️ 修改完后建议重启后端服务以确保配置生效。
配置界面示意图：
三、同步通讯录数据
进入 用户管理 → 用户列表，点击右上角 “同步企微账号” 按钮，即可同步数据：
- 同步成员信息（姓名、账号、部门等）
- 支持更新已存在的用户数据
- 支持同步主部门（如属于多个部门）
- 默认账号为企微账号
默认密码与岗位配置： 进入 系统管理 → 初始参数 中查看，对应项填写的是岗位 ID、默认密码等信息。
四、配置通讯录自动同步
企业微信支持通过“回调地址”自动同步事件变更。
1. 配置通讯录同步
进入企业微信后台：
路径： 安全与管理 → 管理工具（顶部导航）→ 通讯录同步
官方文档 👉 通讯录同步指引
获取 通讯录同步 Secret，并配置可信 IP（服务器公网 IP）。
2. 设置回调地址（接收事件服务器）
进入企业微信后台 → 通讯录同步 → 设置接收事件服务器：
回调 URL 示例：
https://你的域名/tduck-api/wx/cp/portal/应用ID示例：
https://dev.tduckcloud.com/tduck-api/wx/cp/portal/1000023Token 与 EncodingAESKey 必须与 TDuck 后台中配置一致。
⚠️ 如果保存失败，尝试重启后端再进行校验。
2. 支持的回调事件
详见文档 👉 事件回调列表
当前支持的事件类型包括：
提示： 某些字段的修改不会触发回调（如用户名），建议定期手动点击同步。
五、企业微信免登配置（自动登录）
导入全量用户后，可以在 系统配置中开启企微自动登录，用户在企业微信点击应用图标后可自动登录系统。
六、常见问题解答
Q1：修改用户名为什么没有自动同步？
企业微信的变更回调事件中 不包含用户名修改事件。
只有在“部门变更”等行为发生时，才会触发更新并获取新用户名。
如有其他问题，建议配合企业微信开发者文档进行排查： 👉 企业微信开发文档首页