我去年帮朋友的公司做过一套在线客服系统从需求梳理到上线前后折腾了将近两个月后来又陆续迭代了几版沉淀出一套比较通用的源码。最近整理之后直接开源了含访客端、坐席工作台、管理面板和后台服务部署好就能用。这篇文章就把这套系统的设计思路、技术选型、核心模块、部署方式和踩坑记录完整写一遍算是给打算自建客服系统的团队一份可以直接抄作业的参考。这套源码的大致定位是中小团队拿来即用的智能客服系统能支撑在线咨询、多坐席协作、机器人自动回复、数据统计和工单处理等常见场景。它不是为了取代几家大厂商业客服产品而是解决“不想按坐席数付年费、不想被SaaS锁定、需要源码级定制”这类问题。下面我就按真实项目推进的顺序来拆解从技术选型到部署上线再到二次开发每一部分都会讲清楚当初为什么这么做。1. 从一次救火需求说起为什么我最终选择了开源这套源码1.1 中小团队自建客服系统的真实痛点最开始的需求其实很简单朋友的公司做电商代运营客服团队十几个人每天要处理大量售前售后咨询。他们试过几款商业SaaS客服最直接的问题是按坐席数收费一年下来费用不低其次是定制需求响应慢比如想自定义会话标签、把客服面板接进内部工单系统服务商排期往往要等一两个月。于是他们动了自建的念头这也是很多中大型团队迟早会走的路。但自建客服系统的坑比想象中多得多。我在前期调研时列了一张表对比了商业SaaS和开源自建的主要差异对比项商业SaaS开源自建初次投入按年付费坐席越多越贵主要是服务器和开发人力定制能力受限于平台开放接口全量源码想怎么改怎么改数据归属存放在服务商平台完全在自己服务器维护成本服务商负责省心需要自己维护和发版上线速度注册即可用需要部署和对接结论很明确只要团队有基本的技术维护能力自建是长期更划算的选择。但“自建”不等于从零造轮子更靠谱的路径是站在一套成熟开源源码的基础上做二次开发。1.2 开源而不是卖部署服务的取舍这套系统最初是公司内部用的后面我抽时间把通用逻辑剥离出来把代码里的公司和项目相关信息全部脱敏再补全部署文档和初始化脚本最后决定直接开源。很多人问我为什么不定制收费、做成商业项目我的回答是客服系统这个赛道已经很成熟商业化需要投入的销售、交付、运维成本远超出代码本身开源反而能吸引更多使用者帮忙反馈问题和提交补丁让项目进入正向循环。开源的另一个好处是可信度。源码就摆在仓库里数据表结构、接口文档、部署脚本全部可见使用方不用担心里面藏了什么不干净的东西。我这里也提醒一句凡是要部署到生产环境的开源项目无论对方是谁都要自己过一遍代码里的密钥、回调地址和后门风险这是基本安全意识跟我这套代码是否“清白”无关。2. 技术选型思路哪些组件经得起真实业务折腾2.1 后端框架和语言选型客服系统的后端要同时处理长连接推送、REST API、消息持久化和定时任务我用的是我这几年最顺手的组合后端用某主流Web框架做API服务和WebSocket网关数据库选MySQL再加上Redis负责任务队列和在线状态缓存消息推送则通过长连接通道下发。之所以没有上更重的微服务架构是因为这套系统初期单机就能扛住几千并发拆得太碎只会增加部署和排障成本。选型时最重要的判断是团队的技术储备。如果你们团队擅长PHP那就不要为了“潮流”去用某个还不熟悉的语言重写全部服务如果擅长Node.js那就用Node.js。技术选型没有标准答案但有一条通用原则运维和排障能力覆盖范围内的方案才是好方案。这套源码对服务器要求很低2核4G的机器跑单实例也能应付中小团队日常咨询量。2.2 前端三端分离访客端、坐席端、管理面板整个系统分成三个前端各自的技术侧重点完全不同访客端浏览用户直接打开要求加载快、体积小、不稳定网络下也能正常发消息所以使用了轻量级的原生前端框架不引入重型UI库。坐席端客服每天长时间使用需要实时消息提醒、多会话切换、快捷回复和工单操作这类重交互场景必须用组件化框架主界面是两栏多列表布局左侧是会话队列右侧是聊天窗口。管理面板主要用于配置和查看报表逻辑偏表单和图表跟坐席端分离开发避免业务代码互相干扰。三端分离还有个额外好处坐席端和管理面板可以分别部署管理面板的升级不会影响正在接待中的客服这在真实业务里很重要。2.3 通信方案WebSocket长连接和消息补偿策略一开始我考虑过轮询接口的老方案但客服场景对消息实时性要求极高轮询的延迟和服务器压力都不可接受所以最终采用WebSocket长连接。访客端和坐席端都通过WebSocket接入消息网关由后端负责消息路由和持久化。WebSocket方案最大的坑是断线重连和消息补偿。移动端网络切换、浏览器休眠都会导致连接断开如果没有消息补偿机制用户收到消息就全凭运气。我的做法是所有消息先写数据库再通过长连接推送客户端收到后回执确认服务端根据回执更新消息状态如果客户端离线重连后主动拉取未读消息。这套机制保证了“消息一条都不会丢”实现细节在后面的踩坑章节里专门展开。2.4 数据库设计中的核心表结构如果要用一句话总结客服系统的数据模型那就是“围绕会话Session建一切”。访客、坐席、消息、工单、评价、机器人命中日志所有核心数据都挂在会话ID上。下面给出最核心的四张表的简化设计CREATE TABLE chat_session ( id bigint NOT NULL AUTO_INCREMENT, session_no varchar(32) NOT NULL COMMENT 会话编号, visitor_id bigint NOT NULL COMMENT 访客ID, agent_id bigint DEFAULT NULL COMMENT 当前坐席ID, status tinyint NOT NULL COMMENT 0排队中 1进行中 2已转接 3已结束, channel varchar(16) NOT NULL COMMENT 来源渠道, last_message_at datetime DEFAULT NULL COMMENT 最后消息时间, created_at datetime NOT NULL, PRIMARY KEY (id), KEY idx_visitor (visitor_id), KEY idx_agent (agent_id), KEY idx_status (status) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4; CREATE TABLE chat_message ( id bigint NOT NULL AUTO_INCREMENT, session_id bigint NOT NULL, sender_type tinyint NOT NULL COMMENT 1访客 2坐席 3机器人 4系统, sender_id bigint NOT NULL, content_type tinyint NOT NULL COMMENT 1文本 2图片 3商品卡片, content text NOT NULL, status tinyint NOT NULL DEFAULT 0 COMMENT 0未读 1已读 2已撤回, msg_no varchar(64) NOT NULL COMMENT 全局消息序号用于去重, created_at datetime NOT NULL, PRIMARY KEY (id), UNIQUE KEY uk_msg_no (msg_no), KEY idx_session (session_id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4; CREATE TABLE chat_agent ( id bigint NOT NULL AUTO_INCREMENT, username varchar(64) NOT NULL, nickname varchar(64) NOT NULL, avatar varchar(255) DEFAULT NULL, status tinyint NOT NULL COMMENT 0离线 1在线 2忙碌, max_sessions int NOT NULL DEFAULT 5 COMMENT 最大同时接待数, skills varchar(255) DEFAULT NULL COMMENT 技能标签逗号分隔, created_at datetime NOT NULL, PRIMARY KEY (id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4; CREATE TABLE chat_robot_rule ( id bigint NOT NULL AUTO_INCREMENT, keyword varchar(128) NOT NULL COMMENT 触发关键词, match_type tinyint NOT NULL COMMENT 1包含 2正则, reply_type tinyint NOT NULL COMMENT 1文本 2图文 3转人工, reply_content text, sort int NOT NULL DEFAULT 0, is_active tinyint NOT NULL DEFAULT 1, created_at datetime NOT NULL, PRIMARY KEY (id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;其中chat_message表的msg_no字段是有讲究的我在实际开发中吃过消息重复的亏。客户端生成全局唯一ID服务端用唯一索引去重这样即使网络重试导致同一内容发送多次数据库层面也能挡掉重复落库。3. 核心功能模块拆解访客端、坐席工作台和管理面板3.1 访客端用户侧完整的咨询体验闭环访客端是整个系统的门面用户在这里发起会话、等待回复、接收消息和提交满意度评价。这个界面要做到极简我只保留了对话列表、聊天窗口、输入框和常见问题入口颜色风格全部通过参数配置方便接入方在自己的官网、小程序或App里做视觉适配。访客端的核心逻辑是会话创建。用户第一次打开的时候前端向服务端申请一个访客ID并带着渠道参数发起会话服务端根据排队策略把会话分配给在线坐席如果没有空闲坐席则进入排队状态这时候访客端要明确展示“当前排队人数”和预计等待时间减少用户焦虑感。等真正接入坐席后双方进入正常的实时对话访客还能发送图片和商品卡片这部分是电商客服场景的高频需求。3.2 坐席工作台客服一天到晚都在看的界面坐席工作台是整个系统里最复杂的模块。它的主界面分为三个区域左侧是会话队列按未回复时间倒序排列方便客服优先处理等待最久的会话中间是聊天记录区展示当前会话的上下文右侧是访客信息、快捷回复和转接按钮。这里有一个容易被忽略但实际很重要的细节快捷键。客服处理会话的动作高度重复我们做了很多快捷键支持比如CtrlEnter发送消息、ShiftTab切换会话、F2呼出快捷回复面板。这种细节功能看着不起眼但对客服日常效率的提升非常明显。记得在设计阶段去问真正的客服人员“你们最讨厌哪个环节”而不是自己坐在工位前拍脑袋。坐席状态管理也是重点。坐席的状态直接决定分配策略我把状态分成离线、在线、忙碌三档在线又分空闲和接待中。当坐席超过最大接待数时自动切到忙碌状态新会话不再分配给他。这样能避免客服被消息淹没也方便管理者通过报表观察团队负载。3.3 管理面板配置权限、机器人规则和统计报表管理面板是后台管理员使用的控制台核心就三块内容坐席与权限管理、机器人规则配置、运营数据报表。坐席与权限管理里我会特别说明“角色”的概念。系统内置管理员、组长、客服三种角色管理员能看全部报表和配置组长只能管理自己小组的坐席客服只能处理分配给自己的会话。权限控制一定要在接口层面做不能只靠前端按钮隐藏否则绕过界面直接调API就能越权这是很多自建系统的通病。机器人规则配置是这套系统称为“智能”的关键所在。管理员可以配置关键词匹配规则例如用户消息里包含“退款”两个字机器人就自动回复退款流程说明也支持正则表达式匹配比如判断订单编号格式后调取订单状态接口然后把结果拼装成回复内容。机器人解决不了的问题可以设置关键词直接转人工整个规则都有优先级排序。统计报表我做了会话量趋势、坐席响应时长、满意度评分、机器人命中率和转人工率五个核心维度。这些数据对运营团队调整人力排班和优化话术非常关键也是自建系统相比SaaS产品的主要优势之一——报表能按自己需求无限定制想怎么钻取就怎么钻取。3.4 智能客服模块关键词匹配、多轮FAQ和人工接管谈到智能客服很多团队上来就想做大模型和深度学习我的建议是先把规则引擎做好。这套系统当前实现的智能客服是基于关键词和FAQ库的规则引擎管理员维护一问一答知识库访客提问时先精确匹配再模糊匹配都匹配不上就提示转人工。这套逻辑在电商、教育、金融等行业的售前咨询场景中已经能拦截掉相当比例的重复问题。FAQ知识库我特意做了“命中未解决”的反馈按钮。当机器人给出了答案但访客仍然追问“不对我要问的不是这个”时系统会记录一次负反馈。管理员在后台能看到哪些FAQ经常被否定回答从而优化答案或改走转人工流程。这个小功能对提升智能客服体验的帮助远大于堆砌更多的复杂算法。说白了客服系统的AI能力不在于模型多大而在于能否围绕业务数据不断迭代。4. 部署与拿来即用从零开始跑起整条系统链路4.1 环境要求与目录结构这套源码对部署方的要求比较低一台Linux服务器主流的云主机1核2G即可跑开发环境、Nginx或Caddy、MySQL 5.7以上、Redis 6以上以及对应的语言运行时环境。项目根目录下我做好了清晰的目录划分后端服务、前端三个子项目、初始化SQL脚本和Docker部署文件全部独立放置拿到代码后第一件事不是看代码而是先看部署文档。目录结构核心部分大致长这样service/ # 后端API服务 ├── src/ # 源代码 ├── config/ # 配置文件 └── sql/ # 初始化脚本 web_visitor/ # 访客端 web_agent/ # 坐席工作台 web_admin/ # 管理面板 docker/ # Docker Compose部署文件如果你的团队之前没有部署经验建议先不要在服务器上直接操作而是在自己电脑上把整套环境用Docker拉起来跑通再搬到服务器上。本地跑通后再照着部署文档往服务器上搬能省掉大量排查环境差异的时间。4.2 Docker Compose一键部署实践项目根目录的Docker Compose文件已经把后端服务、MySQL、Redis打包好了。我自己亲测过的流程是这样的服务器安装好Docker和Docker Compose插件后进入项目目录把.env.example复制一份改成.env填上数据库密码和密钥然后执行:docker compose up -d首次启动会自动初始化数据库后端启动时会自动执行表结构迁移。之后构建三个前端项目把静态文件扔到Nginx站点目录再把Nginx配置里的API地址和WebSocket地址指到后端服务的对应端口整个系统就活了。这套流程如果按文档操作熟练的话半小时内能全部跑起来。4.3 “拿来即用”的隐藏工作配置项与初始化数据源码里包含一套开箱即用的初始化数据包括默认管理员账号、演示客服账号、几条基础FAQ和机器人规则。这样做的好处是第一次登录就能看到完整的效果而不是对着空白面板一脸茫然。但要注意默认账号一定要在正式上线前改掉密码并且把演示数据清理干净。配置文件里有几项必须过一遍对外访问域名、WebSocket地址、文件上传存储路径、QPS限制阈值。尤其是WebSocket地址如果配错前端能打开页面但消息就是发不出去而且控制台报错不一定明显这是新手部署最容易卡住的地方。我在部署文档里放了一张配置核对清单每一项都标了示例值和注意事项。这里也建议所有使用开源项目的团队把配置核对当成上线前的一个正式检查步骤不要嫌麻烦因为线上环境一旦跑起来再改域名和地址会牵连到已经下发的客户端缓存非常折腾。4.4 管理面板操作体验从创建坐席到查看报表系统部署完成后管理员通过管理面板就能完成日常运营。创建坐席时填用户名、昵称、密码和最大接待数保存后该坐席就能登录坐席工作台配置机器人规则的界面是表格形式每一行是一条规则支持拖动调整优先级查看报表则通过一个独立的数据看板页面呈现。这里我尤其想强调“操作闭环”的体验。很多自建系统功能都有但按钮摆放不合理使用者的操作路径绕来绕去。我的设计原则是任何一项后台配置在保存后都应该在对应的前台场景中直接生效不需要清缓存、不需要重启服务、也不需要等定时任务。坐到这个标准后运营人员对系统的接受度会明显提高。5. 开发过程中踩过的几个坑连接、消息与状态的翻车现场5.1 消息乱序并发写导致聊天上下文错乱第一个让我印象深刻的坑是消息乱序。测试阶段我用两个账号同时发消息结果发现聊天记录里两条消息的先后顺序偶发颠倒。排查发现原因是后端处理消息时先落库再推送两条消息并发请求时由于数据库写入耗时抖动后到的请求反而先写完先到的请求后写完前端按收到推送的先后渲染顺序自然就错了。修复方案分两层数据库层面保证全局递增应用层面做到最终有序展示。我在消息表里增加了一个msg_no序号字段由服务端统一生成保证每个会话内的序号严格递增前端收到消息推送后先进入一个本地的待排序队列按序号排好序再渲染而不是来一条显示一条。这个修复解决了乱序代价是代码复杂度增加了一些但对客服场景来说消息顺序错误会直接造成业务误解这个复杂度必须承担。5.2 WebSocket断线重连导致的重复消息断线重连的重复消息问题前面提过解决方案这里详细说说排查链路。当时用户反馈“客服发一句话我这边看到两条”第一反应是不是前端push组件写重了后来发现事件监听回调里确实注册了两次但修复后依然偶发重复。继续追查才发现是WebSocket断线后自动重连服务端把断线期间的消息重新下发而部分消息客户端其实已经收到过了。修复方案是双管齐下服务端记录每个访客/坐席的最近消息序号重连时只下发大于该序号的消息客户端收到消息后先用消息表去重如果发现重复直接丢弃。这个坑给我最大的教训是凡是涉及网络通信的功能设计阶段就应该把“至少一次、可能重复、无序到达”这三个网络基本问题考虑进去而不是等问题暴露后再补救。5.3 客服分配策略中的“高优先级饿死”现象客服分配一开始用的简单策略新会话分配给当前空闲坐席中接待量最少的人。看起来公平但实际运行一段时间后出现了“饿死”现象。原因是有几个坐席被分配了高优先级渠道的会话比如VIP客户始终优先插入导致普通渠道的会话长时间堆在一个接待量已经很少的坐席手上而最忙的坐席还在接新单。调整后的分配策略加了两层判断先看坐席状态和渠道匹配度再按当前排队时间最长优先分配避免新会话反复插队同时增加“溢出”机制如果某个坐席超过1分钟未响应新会话系统会把会话重新分配回公共队列。这套策略上线后排队超时率和客服负载不均问题都明显改善。5.4 服务重启丢状态内存数据不能用于关键业务开发初期为了图省事把“当前在线坐席”和“排队中的会话”都放在进程内存里管理不落库。平时运行没毛病但只要服务一重启在线状态全部丢失排队中的会话也没人接管用户那边看到的就是“客服离线了”或者“队列消失”。这个问题在预发布环境压测时暴露直接促使我把在线状态和排队队列全部改造为Redis持久化存储。这里也给大家一个通用经验凡是业务上不能接受丢失的数据都不要只存在进程内存里哪怕重启概率很低。Redis、数据库、消息队列总有一层是要负责持久化的。对于一个要上线给真实用户使用的系统稳定性设计不是加分项而是必须项。6. 扒完代码之后二次开发方向和个人经验总结6.1 接入自己的业务系统源码到手后最容易做的二次开发是接入业务系统。很多团队的客服场景都有专属逻辑比如订单查询、物流对接、知识库联动这些需要把客服系统跟内部系统打通。我在后端预留了事件钩子在关键节点会话创建、消息到达、会话转接、会话结束会触发Webhook回调接入方只需要按照回调协议处理业务数据即可。具体到常见需求例如访客发来订单号后自动调取内部API返回订单状态可以在消息收到事件里拦截调用内部接口再把结果作为系统消息回填到会话。整个过程对访客无感但对客服效率提升非常显著这是很多商业SaaS产品做不了的深度定制能力。6.2 扩展方向接入AI大模型能力和企业IM当前系统的智能特性还停留在规则引擎阶段如果想要更强的AI能力可以在机器人回复模块上做扩展。比如接入大语言模型开放平台的接口当FAQ规则没有命中时把访客问题交给模型生成候选答案再人工确认后发送或者把模型作为“兜底机器人”集成到现有链路中。我在代码里把机器人回复的接口抽象成了策略模式接大模型只需要新增一个策略类不用改动主流程。另一个常见扩展方向是接入企业IM比如把客服系统的消息同步到团队常用的内部沟通工具让不在工位上的客服也能用手机响应客户。这个扩展的技术点在于消息网关的适配层本质上是一个消息的双向转发器但要注意消息去重和会话同步的状态一致性否则会出现两边显示的内容不一致。6.3 开源维护的几点心得与注意事项最后说几点维护开源项目的个人体会。首先文档比代码更重要很多用户判断一个开源项目能否使用第一眼看的就是部署文档和示例是否清晰其次少做破坏性更新我的习惯是每次发版写清楚变更记录涉及数据库变更的一定提供迁移SQL脚本避免使用方升级后直接跑不起来最后及时回应用户的Issue哪怕只是确认“我也遇到同样的问题正在排查”也能极大提升社区信任度。另外建议所有二次开发者在动手改代码之前先跑一遍完整测试。我在项目里提供了自动化测试用例覆盖消息收发、会话分配和权限校验三个核心模块。不要轻视这些测试客服系统最怕的是改了一处逻辑导致另一处崩溃而自动化回归能在几分钟内把最核心的功能全跑一遍。这套源码目前已经被几个项目部署到生产环境运行最久的一个已经稳定跑了几个月累计处理了几万次会话。如果你正打算自建客服系统不妨直接拿这套代码上手跑一遍有什么问题可以按反馈渠道提给我我会持续更新。最后再分享一个小技巧修改WebSocket心跳间隔参数时默认建议调到60秒左右太短会频繁产生无效心跳请求太长可能导致中间网络设备超时静默断开连接这个参数在真实网络环境中非常敏感值得反复测一测。
