简介聚合客服万能客服cy163_customerservice 22.0.0 全开源版安装更新一体包面向需要自建客服系统的开发者、运维人员与中小企业技术团队可用于网页在线咨询、工单流转、知识库自助服务及智能机器人应答等场景。压缩包共269个文件约2.93MB以html页面模板、php后端脚本、js交互逻辑和css样式表为主体并配有gif、png、jpg等界面素材及字体文件整体轻量便于本地部署与二次开发。已有1061人学习下载说明其在开源客服系统搭建方面具有一定参考价值。包内提供安装与更新一体化结构源码全部开放读者可据此研究多渠道整合、工单管理、权限控制与API对接的实现方式并按照自身业务需求调整界面与功能模块适合作为客服系统选型、学习和定制改造的实践样本。1. 三个窗口切到手腕疼万能客服到底把什么聚到了一起某公司的客服组一度是这么上班的一个人开着三个窗口来回切切错一次就把甲客户的报价发给了乙客户。这种事故靠加人解决不了靠的是把入口收拢。「万能客服」这个说法听着夸张落到技术实现上就是聚合客服多个外部渠道的消息统一回调、统一落库、统一分配给坐席、统一在工作台里回复。cy163_customerservice 22.0.0 这个全开源版给的是源码加安装更新一体包渠道适配层、坐席分配规则、会话与消息表都在自己手里不用等厂商排期改一个字段。它适合有 PHP 运维底子、要把客服面板嵌进自己业务后台的团队只想双击装完就用的得先接受后台那一堆配置项。2. 环境与安装22.0.0 一体包从解压到能登录这一章只干一件事让系统在你自己的机器上跑起来并且能用一个测试账号登录进工作台。一体包的好处是安装脚本和更新脚本放在同一份代码里省掉了「先找安装包、再找补丁」的两步坏处是它对运行环境的假设比较硬PHP 版本、扩展、目录权限任何一项不到位表现都不是报错而是白屏或者 500。2.1 运行环境与扩展清单这类 PHP 客服系统的通行结构是「PHP-FPM MySQL Nginx」长连接部分有的走 Workerman 常驻进程有的走前端轮询。我一般先按下面这张表把环境核对一遍再动安装脚本能省掉一半排错时间。版本上不要图新PHP 8.2 之后的弃用告警在老旧业务代码里非常密集7.4 或 8.0 更稳。组件建议版本说明PHP7.4 / 8.08.1 以上先小流量试注意动态属性弃用告警MySQL5.7 / 8.0字符集统一 utf8mb4排序规则统一Nginx1.20 以上需要能配伪静态与 fastcgi 超时Redis5.0 以上坐席在线状态、验证码、队列没有也能跑但会退化PHP 扩展fileinfo、curl、mbstring、openssl、pdo_mysql、gd、zip、bcmath少一个安装器就卡在某一步进程管理systemd / supervisor长连接进程掉线要能自动拉起扩展缺失是最常见的翻车点。安装器通常会做一轮环境检测但它只检测「有没有」不检测「开没开」比如zip装了但disable_functions里禁了exec解压更新包那一步就会静默失败。上线前把php -m的输出和上表对一遍比事后查日志快得多。2.2 建库、解压与目录权限我习惯把代码放在/www/wwwroot/cs这类路径下站点根目录指向public如果包内是扁平结构就直接指到根。先把库建好、字符集定死再解压避免安装器用默认字符集建表之后再来改。# 1. 建库字符集一次定死后面不用再改 mysql -uroot -p -e CREATE DATABASE cs_db DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; CREATE USER cs_user127.0.0.1 IDENTIFIED BY 换成你的强密码; GRANT ALL PRIVILEGES ON cs_db.* TO cs_user127.0.0.1; FLUSH PRIVILEGES; # 2. 解压一体包到站点目录 mkdir -p /www/wwwroot/cs unzip cy163_customerservice_22.0.0.zip -d /www/wwwroot/cs # 3. 属主统一给运行用户避免上传目录写不进去 chown -R www:www /www/wwwroot/cs # 4. 可写目录单独放开其余保持只读更安全 chmod -R 755 /www/wwwroot/cs chmod -R 775 /www/wwwroot/cs/runtime /www/wwwroot/cs/public/uploads代码里的几个点值得说明。第一行建库时指定utf8mb4_general_ci是因为客服消息里 emoji 和特殊符号占比不低用utf8三字节会在写入时直接截断表现为「用户发了个表情坐席端收到半条消息」。第三步的属主必须和执行 PHP-FPM 的用户一致www只是常见叫法实际用ps aux | grep php-fpm看一眼。第四步只放开runtime和uploads其余目录保持 755是因为这类系统历史上出过上传目录被塞脚本的事故权限收窄是最便宜的后悔药。解压后先别急着访问安装页确认一下包内是否已经有config或.env之类的配置文件。一体包为了「安装更新合一」往往会带一份示例配置如果站点根目录下残留了旧配置安装器会跳过建表直接连库然后报一个跟真实原因毫无关系的错。2.3 站点配置与首次登录Nginx 这边重点只有三处伪静态、上传体积、fastcgi 超时。客服工作台的长轮询请求会挂比较久超时给短了会出现「坐席端每隔几十秒掉一次线」的玄学现象。server { listen 80; server_name cs.example.internal; root /www/wwwroot/cs/public; index index.php index.html; # 伪静态把所有非静态请求交给入口文件 location / { try_files $uri $uri/ /index.php?$query_string; } location ~ \.php$ { fastcgi_pass unix:/run/php/php7.4-fpm.sock; fastcgi_index index.php; include fastcgi_params; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; # 长轮询和导入导出都吃时间30s 偏短 fastcgi_read_timeout 120s; } # 上传目录禁止执行脚本只留静态读取 location ~* ^/uploads/.*\.(php|phtml|phar)$ { deny all; } client_max_body_size 20m; access_log /var/log/nginx/cs.access.log; error_log /var/log/nginx/cs.error.log; }fastcgi_read_timeout从默认 30 秒提到 120 秒主要照顾消息拉取和报表导出但真正决定前端多久断一次的是工作台里配置的轮询间隔两者要一起看。client_max_body_size要和 PHP 的upload_max_filesize、post_max_size对齐只改一边会出现「小图能传、大图 413」。最后那条location是硬性防护上传目录里的文件一律不允许被当成脚本执行。配置改完nginx -t过一遍再 reload。然后浏览器打开站点按安装器提示填数据库、管理员账号完成后按惯例把安装目录删掉或改名。登录进后台先做三件事改默认管理员密码、检查「系统设置」里的站点地址是否与实际域名一致、确认时区是Asia/Shanghai。第三件事看着小实际影响会话时间线和统计报表时区错了所有「今日会话量」都会偏。3. 渠道接入与消息路由外部消息怎么进到统一工作台装完只是空壳聚合客服真正的价值在接入层。这一层的职责可以拆成三段外部渠道把消息推过来、系统验签并落库、然后按规则找到该接的人。三段里任何一段出问题表现都是「坐席端很安静」而日志里往往什么明显错误都没有所以每一段都得能单独验证。3.1 回调入口与验签常见做法是给每个接入渠道分配一个channel_code回调地址形如/api/callback/{channel_code}请求体里带timestamp、nonce、sign。验签逻辑必须是「先验签、再解析业务字段」顺序反了等于对外暴露一个谁都能调的消息写入接口。?php // 渠道回调统一入口的验签片段示意 class CallbackGuard { // 时间戳允许的偏移单位秒太小会被网络抖动误杀 const MAX_SKEW 300; public function verify(array $headers, string $rawBody, string $secret): bool { $ts $headers[X-Cs-Timestamp] ?? ; $nonce $headers[X-Cs-Nonce] ?? ; $sign $headers[X-Cs-Sign] ?? ; if ($ts || $nonce || $sign ) { return false; } // 1. 防重放时间戳偏移过大直接拒绝 if (abs(time() - (int)$ts) self::MAX_SKEW) { return false; } // 2. 签名用原始 body不能用解析后的数组重新拼接 $expect hash_hmac(sha256, $ts . \n . $nonce . \n . $rawBody, $secret); // 3. 定长比较避免时序侧信道 return hash_equals($expect, $sign); } }三个参数各有讲究。MAX_SKEW给 300 秒是折中给 60 秒在跨机房调用时偶发失败给太大又失去防重放意义。签名串里必须拼原始请求体不少实现图省事用json_encode($_POST)重新拼字段顺序一变签名就对不上这类问题在联调阶段极难定位。hash_equals不能换成这是常识但每年仍有人踩。验签通过之后第一件事是立刻返回成功把业务处理丢进队列。外部渠道普遍有重试机制你这边处理慢了三秒对面就重推一次重复消息会像滚雪球一样堆起来。3.2 消息落库与幂等设计消息表的设计决定了后面所有统计和检索能不能做。我一般把「会话」和「消息」拆两张表会话表存状态和归属消息表只追加不更新。这样历史记录天然可追溯坐席转接也不用改历史消息。-- 会话表一个客户在一个渠道上的一段连续对话 CREATE TABLE cs_session ( id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, channel_code VARCHAR(32) NOT NULL COMMENT 渠道标识, external_uid VARCHAR(128) NOT NULL COMMENT 渠道侧用户唯一标识, agent_id INT UNSIGNED NOT NULL DEFAULT 0 COMMENT 当前坐席0 为未分配, group_id INT UNSIGNED NOT NULL DEFAULT 0 COMMENT 技能组, status TINYINT NOT NULL DEFAULT 0 COMMENT 0待接入 1进行中 2已结束, last_msg_at INT UNSIGNED NOT NULL DEFAULT 0, created_at INT UNSIGNED NOT NULL DEFAULT 0, PRIMARY KEY (id), UNIQUE KEY uk_channel_uid (channel_code, external_uid, status), KEY idx_agent_status (agent_id, status) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4; -- 消息表只追加消息指纹做唯一键实现幂等 CREATE TABLE cs_message ( id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, session_id BIGINT UNSIGNED NOT NULL, msg_fp CHAR(40) NOT NULL COMMENT 渠道消息指纹 sha1, direction TINYINT NOT NULL COMMENT 1客户发来 2坐席发出, msg_type TINYINT NOT NULL DEFAULT 1 COMMENT 1文本 2图片 3文件, content TEXT NULL, created_at INT UNSIGNED NOT NULL DEFAULT 0, PRIMARY KEY (id), UNIQUE KEY uk_msg_fp (msg_fp), KEY idx_session (session_id, id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;uk_msg_fp是整套幂等的地基。渠道重推同一条消息时INSERT会撞唯一键捕获1062错误直接当成功返回即可不用先SELECT再INSERT那样在并发下仍有窗口。uk_channel_uid里带上了status是为了让同一个客户在会话结束后再发起咨询时能开新会话而不是永远挂在旧会话上。写入时的顺序也要注意先按channel_code external_uid status in (0,1)找会话找得到就复用找不到就开新会话然后插消息、更新last_msg_at。这三步放在一个事务里但事务粒度别太大图片和文件的消息体不要塞进同一个事务否则一个慢上传会拖住整条队列。3.3 坐席分配与在线状态分配规则通常是三层先按渠道绑定的技能组过滤再按在线状态过滤最后按策略挑人。策略一般有三种——轮询、最少会话数、指定坐席。轮询实现最简单但容易把新消息全给同一个人最少会话数更公平代价是每次分配都要统计一次会话量大时要有缓存。?php // 最少会话数分配候选人来自技能组 在线状态 function pickAgent(PDO $db, Redis $redis, int $groupId): int { // 在线状态用 Redis 集合维护心跳时写入过期自动剔除 $online $redis-smembers(cs:online:group:{$groupId}); if (!$online) { return 0; // 无人在线留在待接入池 } $in implode(,, array_map(intval, $online)); // 只统计进行中的会话已结束的不计入负载 $sql SELECT agent_id, COUNT(*) AS load FROM cs_session WHERE agent_id IN ({$in}) AND status 1 GROUP BY agent_id; $rows $db-query($sql)-fetchAll(PDO::FETCH_KEY_PAIR); $best 0; $min PHP_INT_MAX; foreach ($online as $aid) { $load (int)($rows[$aid] ?? 0); // 同负载时取 id 小的保证结果稳定可复现 if ($load $min || ($load $min $aid $best)) { $min $load; $best (int)$aid; } } return $best; }这段代码有两个隐含前提。一是坐席的在线状态必须有过期机制纯靠「上线写、下线删」在浏览器直接关掉时会残留幽灵坐席永远分到消息却没人回。常见做法是前端每 30 秒心跳一次Redis 里存带 TTL 的 key同时用一个集合做索引过期就查不到。二是分配结果要落库并加锁两个客户同时进来时可能选中同一个坐席靠UPDATE ... WHERE agent_id 0的乐观锁再确认一次才稳。分配完成后还有一步容易被忽略给坐席端推一条「新会话」事件。如果走的是长连接推完要检查连接是否还活着如果走轮询要注意别让坐席端每次都拉全量会话列表改成增量拉取last_msg_at之后的数据否则坐席一多数据库就顶不住。4. 二次开发会话模型、适配器与工作台钩子开源版真正的价值不是省一笔授权费而是能按自己业务改。改之前得先摸清三样东西表结构里哪些字段是业务语义、渠道适配器怎么注册、前端工作台有没有可用的事件出口。这三样摸清了加一个自有渠道、加一个工单字段、加一个快捷回复入口都是半天的事。4.1 核心表与字段语义除了前面两张主表一般还会有一张渠道配置表、一张坐席表和一张快捷回复表。理解字段语义比记住表名重要尤其是那些看着像冗余的字段往往是为了避免联表查询而做的反范式设计。表关键字段语义与注意点cs_channelcode、type、config_json、statuscode一旦上线不要改回调地址依赖它cs_agentaccount、group_ids、max_sessionmax_session是并发上限分配时先过滤cs_agent_groupname、strategystrategy决定走轮询还是最少会话cs_quick_replygroup_id、content按技能组隔离避免答非所问cs_sessionstatus、agent_idstatus变更要留操作日志便于追责config_json这类字段通常存的是渠道密钥、回调地址、欢迎语模板。存 JSON 的好处是加字段不用改表坏处是没法建索引、也没法用 SQL 直接筛选所以只放配置别把需要查询的业务字段塞进去。max_session是我见过最常被忽略的字段配了 10 但分配逻辑里没判断结果一个坐席挂 40 个会话响应速度断崖式下跌。4.2 自定义渠道适配器的写法接入一个新渠道本质是实现三个动作校验来消息、解析成内部结构、把回复发出去。绝大多数系统的扩展点都是一个基类继承它、实现抽象方法、然后在渠道配置里注册类名即可。?php // 自定义渠道适配器骨架 abstract class ChannelAdapter { protected array $config; public function __construct(array $config) { $this-config $config; } // 1. 校验并解析入站消息返回统一结构不合法返回 null abstract public function parse(array $raw): ?array; // 2. 发送出站消息返回是否成功 abstract public function send(string $externalUid, string $content, int $msgType): bool; } class DemoChannelAdapter extends ChannelAdapter { public function parse(array $raw): ?array { if (empty($raw[open_id]) || empty($raw[msg_id])) { return null; // 缺关键字段直接丢弃不要抛异常打断队列 } return [ external_uid $raw[open_id], msg_fp sha1($this-config[code] . : . $raw[msg_id]), msg_type $raw[type] image ? 2 : 1, content $raw[content] ?? , created_at (int)($raw[ts] ?? time()), ]; } public function send(string $externalUid, string $content, int $msgType): bool { // 真实实现里这里是 HTTP 调用务必设超时和重试次数 $resp $this-httpPost($this-config[api_url], [ to $externalUid, content $content, type $msgType, ], 3); return ($resp[code] ?? -1) 0; } }parse里返回null而不是抛异常是刻意的队列消费时一条脏数据不能让整批任务回滚。msg_fp用渠道标识加渠道消息 ID 拼 sha1保证跨渠道不撞车。send里的超时和重试次数必须显式给HTTP 客户端默认不超时是排队积压的头号原因一次调用挂 60 秒队列很快就堆到看不见头。注册适配器一般是在渠道配置里填类名或者在某个注册表文件里加一行映射。改完记得在后台把该渠道的状态从「停用」切到「启用」再切回来很多系统是靠这个动作触发配置缓存的只改文件不重启不生效。4.3 工作台前端的事件出口后台工作台通常是单页应用消息到达、会话转接、坐席状态变化都会经过一层事件总线。要做「新消息声音提醒」「会话超时标红」这类定制别去改核心文件挂在事件上更稳升级时也不会被覆盖。// 工作台事件钩子新消息到达时做本地提醒与超时标红 (function () { // 事件名以实际系统为准先在控制台打印总线对象确认 if (!window.CsBus || typeof window.CsBus.on ! function) { console.warn(未找到事件总线检查工作台是否已初始化); return; } // 记录每个会话最后一条客户消息时间用于超时判断 var lastCustomerMsg {}; window.CsBus.on(message:new, function (payload) { if (payload.direction ! 1) return; // 只处理客户发来的 lastCustomerMsg[payload.session_id] Date.now(); if (document.hidden) { // 页面不可见时才响避免坐席正在看还一直响 playBeep(); } }); // 每 20 秒扫一遍超过 3 分钟未回复的会话打标记 setInterval(function () { var now Date.now(); Object.keys(lastCustomerMsg).forEach(function (sid) { var waiting now - lastCustomerMsg[sid]; if (waiting 180000) { markSessionOverdue(sid); } }); }, 20000); })();事件名一定要先在浏览器控制台确认不同版本可能叫message:new也可能叫chat.message猜错就是静默不生效。document.hidden判断能避免坐席正在看屏幕时提示音一直响这个细节很影响使用体验。超时扫描用轮询而不是定时器堆叠是因为会话可能中途结束定时器不好回收。5. 避坑与排查升级和上线时最容易翻车的五处一体包最大的便利是「覆盖即升级」最大的风险也是「覆盖即升级」。配置文件、上传目录、二次开发的模板都堆在同一棵目录树下覆盖的时候一不小心就回到出厂设置。下面五条是我在实际环境里反复遇到的。现象一升级后后台一片白屏前端控制台没有任何请求。原因通常是 PHP 致命错误被关闭了显示加上 opcache 还在跑旧字节码。先看 Nginx 错误日志和 PHP-FPM 日志确认有没有PHP Fatal error再去runtime下清缓存目录然后重启 PHP-FPM 让 opcache 失效。解决之后把display_errors保持关闭但log_errors一定要开否则下次还是黑匣子。现象二同一条客户消息在工作台出现两三次。原因是回调入口先处理业务再返回外部渠道等不及就重推而消息表没有唯一约束。解决分两步回调入口改成「验签通过即返回 200业务入队异步处理」消息表补msg_fp唯一索引插入时捕获重复键错误当成功。补索引前先按指纹去重一遍历史数据否则建索引会直接失败。现象三图片和文件上传失败小文本消息正常。权限只是表象先查三处uploads目录属主是否是 PHP-FPM 运行用户、upload_max_filesize与post_max_size是否都调大、Nginx 的client_max_body_size是否同步。三处任意一处没对上都会失败而且报错文案各不相同。改完 php.ini 必须 reload PHP-FPM只 reload Nginx 没用。现象四坐席明明在线新会话就是分不过来。先看在线状态是不是幽灵数据坐席直接关浏览器没走登出流程状态残留。再看分配逻辑有没有判断max_session满了还继续分就会一直失败。最后看技能组绑定渠道改过分组而会话还挂在旧组上等于永远匹配不到人。排查顺序建议是「在线集合 → 负载上限 → 分组绑定」从快到慢。现象五会话时间线整体偏移几个小时统计报表对不上。PHP 的date.timezone、MySQL 的time_zone、服务器系统时区三者不一致。这类系统普遍用整型时间戳存消息理论上不受影响但只要有一处用了NOW()或date()写库就会错位。统一成Asia/Shanghai并且在代码里禁止用数据库时间函数写业务时间全部由应用层生成时间戳。6. 升级与压力验证一体包怎么用才不失控一体包的更新脚本一般叫update或upgrade做三件事覆盖代码、执行数据库迁移、清缓存。真正要命的不是脚本本身是执行顺序。我现在的固定动作是先在测试环境用生产库的脱敏副本跑一遍完整升级确认迁移脚本没有DROP或全表UPDATE然后生产上停写入把渠道回调临时切到排队模式、备份代码和库、覆盖、跑迁移、清缓存、重启 PHP-FPM、最后做冒烟。冒烟只验四条链路登录后台、发一条测试消息进工作台、坐席回复能出去、会话结束后历史记录能查到。这四条过了再放开回调。有次我省了「停写入」这一步升级过程中进来的消息落在了旧表结构上迁移脚本跑完这些消息的会话 ID 全是脏数据最后靠备份回滚才收场从那以后我每次升级都强制走一遍停写和备份哪怕只是改一个模板文件。压力验证不用搞得太复杂写个脚本按真实回调格式打并发重点观察三个指标而不是 QPS一是消息从回调到出现在工作台的 P95 延迟二是 MySQL 的慢查询数量三是 PHP-FPM 的活跃进程数和队列长度。P95 超过 3 秒就说明落库或队列有问题慢查询集中在cs_session的统计 SQL 上就该加索引或改成缓存计数。# 简易压测模拟 N 个并发回调观察 P95 与错误率 hey -n 2000 -c 50 -m POST \ -H Content-Type: application/json \ -H X-Cs-Timestamp: $(date %s) \ -H X-Cs-Nonce: testnonce \ -H X-Cs-Sign: 用测试密钥算出的签名 \ -d {open_id:u1001,msg_id:m1,type:text,content:hi,ts:$(date %s)} \ https://cs.example.internal/api/callback/demo压测数据里的msg_id要每次不同否则全被幂等键挡掉测出来的是唯一索引的性能而不是真实写入。签名要跟着时间戳一起算写死会全部 401。跑完之后去数据库看一眼消息表增量是否和请求数对得上对不上就说明有请求在队列里丢了。渠道侧还有一个进阶习惯给回调入口加一层「渠道健康度」看板。按channel_code统计最近 5 分钟的验签失败数、重复消息数、平均处理耗时任意一项异常就告警。这层看板比事后翻日志有用得多很多时候渠道那边改了签名算法或者限流策略你这边只表现为消息变少没有任何报错。希望帮到你。本文还有配套的精品资源点击获取