企业官网建设流程全解析

简介：这是一套基于人工智能的企业微信SCRM系统源码，面向需要搭建私域流量管理平台的企业或开发者，帮助解决客户管理、引流获客、社群运营与营销转化等核心问题。资源共1542个文件，压缩包约9.57MB，其中包含877个Java后端源码、195个Vue前端页面、120个JavaScript脚本，以及XML、SQL、properties等配置和数据库文件，并附带build.bat、run-web.bat等构建启动脚本，目录结构清楚，方便直接导入开发。系统拆分为运营中心、引流获客、客户中心、客情维系、社群运营、全能营销、企业风控、企业管理八大模块，覆盖从客户数据报表、多渠道精准引流到朋友圈红包促活、企微会话存档的完整链路；全面对接企微开放API，对接口进行二次封装，避免重复踩坑，降低接入成本。采用主流Java架构，前后端分离，兼具高拓展性与灵活性，避免PHP架构常见问题，并提供内部API接口，可作为企业级私域流量运营系统的开发基座。目前已有1059人下载学习，适合Java开发人员、企业运营团队及方案整合者参考使用。

1. 企业微信 SCRM 系统：为什么 Java 开发者值得在这套源码上花时间

企业微信 SCRM 这几年几乎成了私域运营的标配，市面上大多解决方案要么是 SaaS 按年收费，要么是 PHP 或 Node 写的，Java 团队想二次开发总得先解决语言不通的问题。这套 Java 企业微信 SCRM 系统源码，核心价值在于把企业微信的客户联系、客户群、标签、会话存档这些官方 API 能力，封装成了可以直接部署的 Spring Boot 工程，并且保留了完整的数据库表和 REST 接口，既能让运营团队马上用起来，也能让 Java 工程师在现有技术栈上做扩展。

它适合两类人：一类是公司要搭建私域客户管理系统，技术选型锁定 Java，不想被 SaaS 厂商绑定；另一类是个人开发者想研究企业微信 API 的接入方式，比如回调验签、会话存档拉取、群发任务这些典型场景，这套源码提供了很好的参考骨架。接下来我会从技术选型、核心模块、部署流程、避坑指南到二次开发，把这套源码完整拆一遍。

2. 从官方 API 到本地表：选型、同步策略与项目结构

2.1 技术栈选型：为什么是 Spring Boot + MyBatis Plus 而不是更重的框架

这套源码的基础架构是 Spring Boot 作为主框架，配合 MyBatis Plus 做 ORM，MySQL 存储业务数据，Redis 承担 token 缓存和分布式锁。这个组合在 Java 生态的 SCRM 项目里是目前最常见的搭配，尤其是 MyBatis Plus，它能直接根据实体类生成建表 SQL 和 CRUD 代码，热词里那条“mybatisplus 根据 java 实体类生成创建表的 sql 语句”恰好就是这套源码里的常见操作。

相比一些老项目用 SSM（Spring + SpringMVC + MyBatis）甚至更早的架构，Spring Boot 的优势在于自动配置和内置容器，拿到源码后不需要额外安装 Tomcat，直接mvn spring-boot:run就能起服务。对于 SCRM 这种需要频繁对接企业微信回调、处理异步任务的系统，Spring Boot 的异步任务支持和 Actuator 监控端点也省了不少事。

从企业微信 API 对接角度讲，服务端需要处理的凭证是企业微信的 access_token，这个 token 有效期是 7200 秒，而且获取频率有限制。源码里用 Redis 做 token 缓存是正确做法，如果每次接口调用都向企业微信请求 token，很快会触发频率限制。同时，企业微信接口对回调 URL 有 5 秒响应要求，Spring Boot 的 Web 容器默认线程池应对这种短请求足够，但要注意回调处理逻辑里不能有慢操作，否则会超时重试。

2.2 数据同步策略：本地表和企业微信远端数据的四种同步模式

SCRM 系统绕不开的一个问题是本地数据和企微远端数据的同步。这套源码里把数据分成四类，每一类的同步策略都不一样：

第一类是基础静态数据，比如部门列表，企业微信提供了department/list接口，数据量小、变更频率低，采用定时轮询。源码里用@Scheduled注解配了 5 分钟的固定间隔，数据落库到sys_department表。

第二类是客户联系数据，包括客户列表和客户详情。这类数据变化快，但企微接口不支持 Webhook 主动推送客户详情变更，只能通过externalcontact/get接口拉取，源码的策略是：用户点击某个客户详情时实时请求企微接口，同时把返回结果写进本地缓存表，下次再查优先读本地，配合 Redis 缓存设置 10 分钟过期，兼顾实时性和接口频率限制。

第三类是会话存档数据，这是 SCRM 系统里最有价值但也最麻烦的部分。企微提供的是拉取模式，而且消息是加密的，需要先用企业微信提供的公钥做 RSA 解密。源码里写入了一个msg_archive_sync定时任务，每 5 分钟拉取一次增量消息，解密后明文存储到chat_msg表。这里有个关键参数——拉取的起始时间，源码默认从部署当天开始，历史消息需要手动指定时间范围。

第四类是客户标签和客户群成员变更，这一部分企微支持回调事件推送。源码把回调地址配置成了/wecom/callback，收到事件后写入event_queue表，由一个消费者线程异步处理，避免回调接口响应超时。

2.3 项目目录结构与核心配置文件解读

拿到源码包后建议先看整体目录结构。标准的 Maven 工程，src/main/java下按照controller、service、mapper、entity、config、task分包，其中config包里的WeComConfig和RedisConfig是启动前必须确认的地方。

配置文件application.yml里有几个关键项：

wecom: corpid: ww1234567890abcdef # 企业ID，企业微信后台“我的企业”页面获取 contact-secret: xxxxxx # 客户联系Secret，在“客户联系”应用里获取 chat-secret: xxxxxx # 会话存档Secret，需要单独开通会话存档服务 token: xxxxxx # 回调Token，接收企微事件推送时用来验签 encoding-aes-key: xxxxxx # 回调EncodingAESKey，事件的解密密钥，43位字符串 agent-id: 1000002 # 自建应用AgentId，用于发送消息和获取客户 callback-url: https://your-domain.com/wecom/callback # 必须是公网可访问的HTTPS地址

这里注意chat-secret和contact-secret是两个不同的 Secret，很多人在部署时只配了客户联系的 Secret，导致会话存档一直在报签名错误。另外，企微回调需要公网 HTTPS，本地调试一般用内网穿透工具把端口暴露出去，或者用云服务器的 Nginx 做反代。

3. 客户资产与群发实战：会话存档、标签和营销活动的 Java 实现

3.1 客户联系 API 封装：从企业微信拉取客户列表的核心代码

SCRM 最基础的功能是把企业微信里的客户同步到本地。企业微信的客户联系接口，核心是externalcontact/list，参数需要员工的userid，返回这个员工添加的所有客户。

源码里WeComClient类封装了这个逻辑：

public List<ExternalContact> getExternalContacts(String userId, String cursor) { // 先从Redis获取accessToken，避免每次都向企微请求 String accessToken = redisService.getAccessToken(); String url = "https://qyapi.weixin.qq.com/cgi-bin/externalcontact/list?access_token=" + accessToken + "&userid=" + userId; // 分页游标，企微接口返回next_cursor，用于拉取下一页 if (StringUtils.isNotEmpty(cursor)) { url += "&cursor=" + cursor; } RestTemplate restTemplate = new RestTemplate(); ResponseEntity<JsonNode> response = restTemplate.getForEntity(url, JsonNode.class); JsonNode body = response.getBody(); // errcode为0表示成功，42001表示token过期需要刷新 if (body.get("errcode").asInt() == 42001) { redisService.refreshAccessToken(); return getExternalContacts(userId, cursor); // 刷新后重试一次 } List<ExternalContact> contacts = new ArrayList<>(); if (body.has("external_contact_list")) { for (JsonNode item : body.get("external_contact_list")) { ExternalContact contact = new ExternalContact(); contact.setExternalUserId(item.get("external_userid").asText()); contact.setUserId(userId); contact.setName(item.get("name").asText()); contacts.add(contact); } } return contacts; }

这段代码信息量比较大。第一是 access_token 的获取统一走 Redis，这是企微接口调用的底线要求；第二是错误码 42001 的处理，token 过期后自动刷新并重试一次，这是企微开发者最容易遗漏的点；第三是分页游标cursor的处理，企微接口单次最多返回 500 条客户数据，超过部分必须用游标循环拉取。我见过不少人在这一步偷懒，直接把external_contact_list拉完就完事，结果客户数一多就出现数据缺失。

3.2 会话存档解密：RSA 解密与消息明文映射

会话存档是 SCRM 系统的重头戏，也是和普通 CRM 最大的区别。企业微信 SDK 提供的会话存档接口，拉下来的是经过两层处理的数据——先用 AES 加密，外层还要用 RSA 公钥加密一个随机密钥。解密顺序是：先用 RSA 私钥解开得到 AESKey，再用 AESKey 解开消息体。

源码里ChatArchiveService的关键方法：

public String decryptChatMessage(String encryptKey, String encryptMsg) { // 第一步：用RSA私钥解密AESKey // 私钥是企业在企微后台配置会话存档时自己生成的，只在本地保存 PrivateKey privateKey = loadPrivateKey("your_private_key.pem"); Cipher cipher = Cipher.getInstance("RSA/ECB/OAEPPadding"); cipher.init(Cipher.DECRYPT_MODE, privateKey); byte[] aesKeyBytes = cipher.doFinal(Base64.getDecoder().decode(encryptKey)); // 第二步：用AESKey解密消息体 // 注意企微的AES是CBC模式，IV是密钥的前16字节 byte[] aesKey = new byte[32]; System.arraycopy(aesKeyBytes, 0, aesKey, 0, 32); IvParameterSpec iv = new IvParameterSpec(Arrays.copyOfRange(aesKey, 0, 16)); SecretKeySpec keySpec = new SecretKeySpec(aesKey, "AES"); Cipher aesCipher = Cipher.getInstance("AES/CBC/PKCS5Padding"); aesCipher.init(Cipher.DECRYPT_MODE, keySpec, iv); byte[] plainBytes = aesCipher.doFinal(Base64.getDecoder().decode(encryptMsg)); return new String(plainBytes, StandardCharsets.UTF_8); }

这里有两个容易翻车的地方。第一，企微的 RSA 填充方式是 OAEP，如果用了常见的PKCS1Padding会直接报解密错误；第二，AES 解密的 IV 是 AESKey 的前 16 个字节，而不是常规的固定 IV。这两个点如果不对着官方文档逐字核对，大概率要折腾半天。源码里已经处理好了，但如果是你自己从零写，建议先把官方文档的加解密流程图打出来对照着写。

3.3 群发任务和客户标签：把运营动作变成可追踪的 Java 服务

SCRM 的群发功能，本质是把「运营人员手动复制文案发给几百个客户」这件事变成系统批量执行。企业微信的群发接口有两条路径：一种是「企业群发」，由管理员创建任务，员工确认后执行，适合合规性要求高的场景；另一种是「个人群发」，直接调用externalcontact/add_msg_template接口，传文案和客户 ID 列表。

源码里群发服务的实现，核心是任务表和状态机：

public String createMassTask(MassTask task) { // 把任务先落到本地表，状态为待发送 task.setStatus("PENDING"); massTaskMapper.insert(task); // 异步执行发送，避免接口超时 massTaskExecutor.submit(() -> { List<String> externalUserIds = task.getExternalUserIds(); // 企微群发接口单次最多100个客户，超过要分批 List<List<String>> partitions = Lists.partition(externalUserIds, 100); for (List<String> partition : partitions) { JSONObject param = new JSONObject(); param.put("chat_type", "single"); param.put("external_userid", partition); param.put("sender", task.getSenderUserId()); // 文本消息直接传text字段，链接消息要用link类型 JSONObject text = new JSONObject(); text.put("content", task.getContent()); param.put("text", text); String result = weComClient.post("/externalcontact/add_msg_template", param); JSONObject resultObj = JSONObject.parseObject(result); if (resultObj.getInteger("errcode") == 0) { task.setStatus("SENT"); } else { task.setStatus("FAILED"); task.setErrorMsg(resultObj.getString("errmsg")); } massTaskMapper.updateById(task); } }); return task.getId(); }

这个设计有几个值得借鉴的地方：第一是任务先落库再异步执行，这样即使服务重启，任务状态也不会丢；第二是 100 个客户一批的分组，这是企微接口的硬限制，超过会报错；第三是状态从 PENDING 到 SENT/FAILED 的可追踪流转，运营可以在前端看到每个任务的执行情况。

客户标签这块，源码采用的是定时全量同步加操作事件增量更新。全量同步的定时任务每天凌晨跑一次，把企微的externalcontact/get返回的标签 ID 同步到本地customer_tag表，同时保留标签 ID 和标签名的映射关系。运营在系统里给客户打标记时，实际是调企微的externalcontact/mark_tag接口，同时更新本地表和 Redis 缓存，保证界面上即时生效。

4. 部署与配置改造：从空服务器到跑起来的三小时实录

4.1 环境准备：JDK、MySQL、Redis 的版本与配置要点

这套源码部署，建议的环境是 JDK 1.8 及以上、MySQL 5.7 或 8.0、Redis 5.0 及以上。JDK 版本可以直接用 1.8，如果你的服务器装的是更高版本，要注意 MyBatis Plus 的老版本可能不支持 JDK 17 以上的一些废弃 API。

MySQL 初始化时，字符集设置为utf8mb4，因为企微的客户昵称、群公告里经常有 emoji 和特殊符号，utf8存不了。数据库创建语句：

CREATE DATABASE wecom_scrm DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

Redis 端要确认 maxmemory 策略，因为 session 和 token 这类缓存会持续增长，建议设置maxmemory 512mb和allkeys-lru淘汰策略。

4.2 数据库初始化：源码自带的 SQL 脚本与手动修正字段

源码包里带了一个sql目录，里面是初始化脚本，按顺序执行schema.sql和data.sql即可。schema.sql 里建了核心的几张表：sys_user（系统用户）、customer（客户信息）、customer_tag（客户标签）、chat_msg（聊天记录）、mass_task（群发任务）、event_queue（回调事件队列）。

这里提醒一个常见坑：schema.sql 里customer表的external_userid字段长度默认是 64，但企微实际返回的 external_userid 最长是 94 个字符。如果不改，同步客户时会报 Data truncation 错误。我已经把字段类型改成VARCHAR(128)，如果你用的是旧版 SQL，需要手动执行：

ALTER TABLE customer MODIFY COLUMN external_userid VARCHAR(128) NOT NULL;

同样的还有chat_msg表的msg_content字段，建议直接用TEXT，因为长聊天记录经常超过 255 字符。

4.3 启动三步走：配置文件、编译打包、首次启动验证

配置好application.yml后，编译和启动的命令如下：

# 第一步：编译打包，跳过测试减少耗时 mvn clean package -DskipTests # 第二步：启动服务，nohup后台运行并输出日志到文件 nohup java -jar target/wecom-scrm-1.0.0.jar --spring.profiles.active=prod > app.log 2>&1 & # 第三步：确认端口监听和健康检查 lsof -i:8080 curl http://localhost:8080/actuator/health

首次启动后，观察app.log里是否有Started WeComScrmApplication字样。有两个地方需要重点确认：一是 Redis 连接是否成功，日志里会出现RedisConnection相关的初始化信息；二是定时任务是否注册成功，源码里的@Scheduled任务启动时会在日志打一条scheduled task registered之类的信息。

更稳妥的方式是直接测试一个真实接口。源码里有一个不需要企业微信凭证就能访问的健康接口：

curl http://localhost:8080/api/system/version

如果返回了版本号 JSON，说明 Spring 容器正常。之后再调需要企微凭证的接口，比如/api/customer/list，如果返回 40001（不合法的 secret）或 42001（access_token 过期），大概率是 Secret 配错了，回头检查application.yml。

5. 二次开发避坑：回调验签、Token 刷新与企微数据权限

5.1 回调 URL 验证：签名算法和响应格式的踩坑记录

现象：在企微后台配置回调 URL 时，一直提示「回调 URL 验证失败」。

原因：企微后台保存回调配置时，会向callback-url发送一个 GET 请求，带msg_signature、timestamp、nonce、echostr四个参数，你的服务需要解密echostr并原样返回明文。源码里虽然实现了这个逻辑，但如果你自定义了回调路径，或者 Nginx 层做了重定向，签名验算就会失败。

解决：确认路径和源码里的 Controller 一致，/wecom/callback。同时，企业微信验签的方式是先用token、timestamp、nonce拼成字符串做 SHA-1 加密，再和msg_signature比对。源码里WXBizMsgCrypt类已经封装好，直接注入使用即可：

@GetMapping("/wecom/callback") public String verifyCallback(@RequestParam("msg_signature") String signature, @RequestParam("timestamp") String timestamp, @RequestParam("nonce") String nonce, @RequestParam("echostr") String echostr) { WXBizMsgCrypt crypt = new WXBizMsgCrypt(wecomToken, wecomEncodingAesKey, wecomCorpId); return crypt.VerifyURL(signature, timestamp, nonce, echostr); }

这段代码返回的是解密后的明文 echostr，注意不能加引号或者 JSON 包装，企微后台要的是裸字符串。

5.2 access_token 并发刷新：多个线程同时更新 Token 的问题

现象：系统运行一段时间后，日志开始出现invalid credential或40164错误，重启后恢复。

原因：access_token 快过期时，如果有多个线程同时检测到 token 失效，会一起去请求新 token，结果后一个请求把前一个请求的 token 挤下线。企微的 access_token 机制是「获取新 token 后，旧 token 立即失效」。

解决：在刷新 token 的方法上加分布式锁。用 Redis 的 SETNX 命令实现：

public String getAccessToken() { String token = redisService.get("wecom_access_token"); if (StringUtils.isNotEmpty(token)) { return token; } // 加锁防止并发刷新，设置5秒过期防止死锁 boolean locked = redisService.setIfAbsent("wecom_token_lock", "1", 5, TimeUnit.SECONDS); if (locked) { try { // 再次检查缓存，避免拿到锁后重复刷新 token = redisService.get("wecom_access_token"); if (StringUtils.isEmpty(token)) { token = fetchNewTokenFromWeCom(); redisService.set("wecom_access_token", token, 7100, TimeUnit.SECONDS); } } finally { redisService.delete("wecom_token_lock"); } return token; } // 没抢到锁的线程稍后重试 Thread.sleep(100); return getAccessToken(); }

这里把 token 有效期设置为 7100 秒而不是企微默认的 7200 秒，留出 100 秒的余量，减少临界期并发刷新的概率。从那以后，我每次在代码里看到「先取后判空」这种逻辑，都会下意识检查一下并发环境会不会踩进同一个坑。

5.3 会话存档拉取超时与消息遗漏

现象：定时任务在拉取会话存档时，经常超时或者拉到的消息不连续，中间缺了一段。

原因：企微的会话存档接口get_chat_data是按消息产生的顺序拉取，且单次最多拉 1000 条。如果短时间内消息量很大，你的定时任务就会不断追赶；更关键的是这个接口用seq（消息序号）作为游标，不是按时间。如果上一次任务执行到一半失败，seq没有正确保存，下次会重复拉取或跳过一部分。

解决：源码里的处理方式是每次拉取完成后，把最新的seq存入 Redis，并开启一个新任务指针；如果中途失败，seq不会被更新，下次任务从原位置继续拉取，保证不丢弃也不重复。另外，拉取接口要放进线程池异步执行，给一个合理的超时时间，源码默认设置的是 30 秒。如果消息量特别大，可以拆成多个线程按房间维度并行拉取，但要注意企微接口的调用频率限制，一般 1 秒最多 20 次调用。

5.4 企微敏感操作权限：为什么「新增客户」接口报错「insufficient permission」

现象：调用客户联系相关的写接口，比如externalcontact/add_contact_way（配置联系我二维码），返回错误insufficient permission。

原因：企业微信的每个 API 都有独立的权限范围。客户联系接口不是只要拿到「客户联系 Secret」就能全用，不同接口要求的权限级别不一样。尤其是修改客户备注、转移客户跟进人这几类高危操作，需要企业的「客户联系」应用开通「客户联系」中的「读写」权限，且用户的角色要匹配。

解决：在企微管理后台，进入「应用管理」-「客户联系」-「API 权限」，确认你要用的接口已经开通。另外，企微对调用人的权限也有区分：如果你用的是自建应用，调用受限于该应用可见范围的员工；如果见不到所有客户数据，检查应用是否勾选了「所有员工可见」。这套源码默认是用自建应用来调客户接口的，如果你的自建应用只配置了部分员工可见，那你就只能同步到这部分员工名下的客户。

6. 进阶：把企微 SCRM 接进自己的业务系统——一个批量客户排行看板的落地方案

源码默认带了客户列表和标签管理，但真实业务往往需要把企微客户和自有业务数据打通。比如你在做电商，要看「每个销售的企微客户产生了多少订单」，这就得把customer表和订单表做关联。源码里预留了customer_ext扩展表，放了一个customer_id作为业务主键关联，但默认没有填充业务字段。我一般会在CustomerServiceImpl里加一段同步逻辑，把企微的external_userid和自有系统的用户 ID 做映射。

具体做法是改造客户同步流程，在从企微拉取客户列表后，调用自有用户服务查询手机号是否存在，存在则回填user_id：

// CustomerSyncTask.java 中新增的关联逻辑 for (ExternalContact contact : contacts) { Customer customer = convertToCustomer(contact); // 调用自有系统的用户查询接口，通过手机号匹配用户ID String phone = contact.getPhone(); // 企微返回的手机号字段 Long localUserId = userService.findUserIdByPhone(phone); if (localUserId != null) { customer.setLocalUserId(localUserId); } customerMapper.insertOrUpdate(customer); }

有了local_user_id关联后，写一个简单的排行看板 SQL，就能直接统计每个销售的企微客户在自有系统里的订单价值：

SELECT s.real_name AS 销售姓名, COUNT(DISTINCT c.external_userid) AS 企微客户数, COALESCE(SUM(o.order_amount), 0) AS 关联订单总额 FROM sys_user s LEFT JOIN customer c ON c.owner_user_id = s.user_id LEFT JOIN orders o ON o.user_id = c.local_user_id AND o.create_time >= DATE_SUB(NOW(), INTERVAL 30 DAY) WHERE s.role = 'SALES' GROUP BY s.user_id, s.real_name ORDER BY 关联订单总额 DESC LIMIT 20;

这条 SQL 的逻辑是把销售员、企微客户、本地订单三张表串起来，按销售维度聚合 30 天的订单金额。注意LEFT JOIN的使用，避免销售名下没有客户或客户没下单时被过滤掉。

这个看板跑起来后，运营每天早上的第一件事就不是打开企微后台看聊天记录，而是看这个榜单——谁名下的客户在流失、哪个销售的企微客户转化率高，一目了然。从那以后，我每次给团队做这类系统，都会习惯性地在客户同步流程里预留自定义字段，先把客户 ID 关联好，再谈后续的业务分析。这个习惯帮我避开了不少「数据要分析时发现关联字段没存」的尴尬。希望这套源码的拆解和这些踩坑记录能帮你少走一段弯路，落地时更顺畅。

本文还有配套的精品资源，点击获取