企业官网建设流程全解析

简介：这是一套面向企业客服团队、独立开发者与二次开发者的聚合客服系统源码包，对应 cy163_customerservice 22.0.0 全开源版本，安装与更新集成在同一个压缩包中。系统围绕多渠道整合、工单流转、知识库自助问答、智能机器人应答、交互数据分析、API 对接 CRM/ERP、角色权限控制等模块展开，可用于搭建网页在线聊天与社交媒体统一接入的客服平台，也适合在开源代码基础上做定制改造与功能验证。压缩包共 269 个文件，体积约 2.93MB，以 68 个 html 页面模板、28 个 php 服务端脚本、30 个 js 交互逻辑、16 个 css 与 76 个 gif 图标素材为主体，另含 png、jpg 图片、ttf/woff/eot 字体及 json、xml 配置，前端界面、后端接口与资源素材分层清晰。已有 1061 人学习下载。借助完整源码与一体化安装更新结构，读者可快速完成环境部署，对照页面与接口梳理客服系统的模块划分和调用关系，并在此基础上调整界面样式、扩展渠道接入或补充业务逻辑。

1. 装之前先把版本固定住：22.0.0 一体包到底落在哪套 PHP 上

聚合客服（万能客服）cy163_customerservice 22.0.0 全开源版安装更新一体包，我第一次拆的时候直接扔到一台 PHP 7.2 还没升级的老机器上跑，向导第三步填完数据库账号密码，页面白屏，错误日志干干净净，排查了两个多小时，才发现是扩展和版本对不上。后来把 PHP 换到 8.0、MySQL 关掉严格模式，同一份包十分钟就走完了。这类聚合客服系统把网页、公众号、小程序、H5 几个入口的会话放到同一个后台处理，装不好不只是少个页面：访客消息全进黑洞，坐席端一直转圈，事后再回头查，成本高得多。这篇给的是我实际走过的环境清单和安装顺序，适合自己动手部署的开发者，也适合接手别人半装状态的运维。

2. 环境清点：PHP 8.0 + MySQL 8.0 + Nginx 这套组合怎么定

先把机器上已有的东西确认清楚，再开始动手。客服系统属于「页面多、接口多、上传多」的一类应用，环境要求比单页站高一档，但也没到要上集群的程度。一台 2 核 4G 的云主机跑单机版足够，硬盘至少留 40G，主要是聊天记录和访客上传的图片、语音会持续增长。系统盘小的机器，建议一开始就把附件目录指到数据盘，后面再迁移比现在麻烦。

我的选择是 PHP 8.0 + MySQL 8.0 + Nginx 1.20 以上，架构用 php-fpm 而不是 Apache 的 mod_php。理由很直接：一体包里带的第三方库大多停留在 PHP 7.4 到 8.0 这个区间，8.1 之后动态属性弃用、字符串与数字比较规则变化这些改动，会让一些没同步升级的老代码直接抛警告，在把警告当异常处理的环境里就是 500。22.0.0 这种跨了大版本号的一体包，选 8.0 是折中风险最低的一档，别一上来就追最新。

2.1 PHP 版本与扩展清单：少一个扩展向导就停在那一屏

装 PHP 之前先看清楚要哪些扩展。客服系统常见的功能点——数据库读写、HTTP 请求外部渠道、图片验证码、附件上传、压缩包解压、加密签名——每一个都对应一个扩展，缺哪个，安装向导的环境检测页就会标红，或者更糟：检测页过了，跑到某个功能才炸。

Debian/Ubuntu 系的机器，我一般直接用 apt 装一整套，省得一个个补：

# 安装 PHP 8.0 及客服系统常用扩展 apt install -y php8.0-fpm php8.0-cli php8.0-mysql php8.0-mbstring \ php8.0-gd php8.0-curl php8.0-xml php8.0-zip php8.0-bcmath \ php8.0-fileinfo php8.0-opcache php8.0-redis # 装完确认扩展都在，缺的会直接从这里看出来 php -m | grep -Ei 'pdo_mysql|mbstring|gd|fileinfo|curl|openssl|zip|bcmath'

命令本身没什么花活，重点在第二条校验。php -m列的是 CLI 模式下加载的扩展，php-fpm 用的是同一份配置目录，所以这里能看到的基本就是 fpm 能用的。如果你装完发现 CLI 有、网页上没有，大概率是 fpm 单独装过一份、扩展目录不同，去/etc/php/8.0/fpm/conf.d/下对一下软链。

还有两个参数我习惯在安装阶段就调，不等它出问题再改：

; /etc/php/8.0/fpm/php.ini 里改这几行 memory_limit = 512M ; 默认 128M，导入数据或生成报表时不够 max_execution_time = 300 ; 安装向导写配置阶段容易超时 upload_max_filesize = 50M ; 访客上传图片、语音 post_max_size = 50M ; 必须大于等于 upload_max_filesize date.timezone = Asia/Shanghai ; 不设的话聊天时间戳会偏 8 小时

改完记得systemctl restart php8.0-fpm。date.timezone这一行特别容易漏，漏了之后客服对话记录的时间会整体偏移，很多人以为是服务器时区问题，其实是 PHP 自己的默认值。

2.2 数据库与字符集：utf8mb4 和严格模式的取舍

数据库这块有两个决定会影响后面所有数据。第一是字符集，客服系统里有访客昵称、聊天内容、表情符号，emoji 占四字节，utf8存不下，必须utf8mb4。第二是 SQL 模式，MySQL 5.7 之后默认开STRICT_TRANS_TABLES，插入时字段超长或者类型不匹配会直接报错，而不是以前那种「截断加个警告」就过去了。

老代码在这件事上基本都会踩到。安装过程里经常有「某个字段没传值、插个空字符串进 int 列」的写法，严格模式下一律报错。

-- 建库语句，字符集和排序规则必须一次定对，后期改代价很大 CREATE DATABASE cy_customerservice DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; -- 单独建个账号，别用 root 跑业务 CREATE USER 'cy_cs'@'127.0.0.1' IDENTIFIED BY '换成你自己的强密码'; GRANT ALL PRIVILEGES ON cy_customerservice.* TO 'cy_cs'@'127.0.0.1'; FLUSH PRIVILEGES;

排序规则我选utf8mb4_unicode_ci而不是utf8mb4_general_ci，因为前者对多语言和重音字符的排序更准，客服系统里访客昵称什么字符都可能出现，搜索时不容易漏结果。性能差异在这个数据量级可以忽略。

严格模式我的做法是分两步走：安装阶段先在 MySQL 配置里放宽，让向导能顺利跑完；装完之后再把严格模式开回来，逐个修那几条不规范的 SQL。一步到位开严格模式，很可能卡在安装中途，你连后台都进不去，更别说改代码了。

# /etc/mysql/mysql.conf.d/mysqld.cnf [mysqld] # 安装阶段临时放宽，装完向导后把 STRICT_TRANS_TABLES 加回来 sql_mode = NO_ENGINE_SUBSTITUTION character-set-server = utf8mb4 collation-server = utf8mb4_unicode_ci max_connections = 300 # 客服坐席并发 + 访客轮询会占不少连接 innodb_buffer_pool_size = 1G # 4G 内存的机器给 1G 比较稳

提示：装完向导、确认后台能正常登录之后，把sql_mode改回STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION再重启一次 MySQL。这一步不是可选项，长期关着严格模式，脏数据会悄悄写进库里，等到做统计报表时才发现对不上。

2.3 站点根目录与运行目录：public 与伪静态要先定

解包之后先别急着配 Nginx，先看目录结构。一体包常见的布局是把入口文件放在public/下，框架代码、配置、缓存目录在上一级；也有把入口直接放根目录的版本。判断方法很简单：找index.php在哪儿，那个目录就是站点根目录。

Nginx 的root必须指到入口文件所在的那一层，指错一层的结果是首页能打开但所有静态资源 404，或者反过来，页面裸奔、样式全丢。

server { listen 80; server_name cs.example.internal; # 换成你自己的域名 root /var/www/cy_customerservice/public; # 指向 index.php 所在目录 index index.php index.html; # 伪静态：先找文件，找不到再交给入口文件 location / { try_files $uri $uri/ /index.php?$query_string; } location ~ \.php$ { include fastcgi_params; fastcgi_pass unix:/run/php/php8.0-fpm.sock; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; fastcgi_read_timeout 300; } # 附件目录直出，别让 PHP 去读文件再吐出来 location /uploads/ { expires 7d; access_log off; } }

几个参数值得单独说。try_files那行是伪静态的核心，客服系统后台的路由基本都靠它，漏了这行会出现「后台点菜单刷新就 404」。fastcgi_read_timeout 300要和 PHP 的max_execution_time对齐，否则 PHP 还在跑、Nginx 已经断开，用户看到 504，日志里两边都留不下有效信息。

location /uploads/这一段是性能优化。访客上传的图片、语音如果都走 PHP 转发，并发一上来 CPU 直接满。让 Nginx 直接返回文件，PHP 只负责处理上传写入，压力差好几倍。

配完nginx -t检查语法，再systemctl reload nginx。别用 restart，reload 不会断开现有连接，线上环境养成习惯。

3. 解包与安装：cy163_customerservice 22.0.0 的落地步骤

环境就位之后进入正题。这一章按实际操作顺序走：先上传解压、给权限，再跑安装向导，然后讲清楚「一体包」里那个更新目录到底什么时候用，最后把入口重写和伪静态补齐。顺序别跳，尤其是权限那一步，很多人图快直接chmod -R 777，当时能跑，后面出安全问题还得回滚。

3.1 上传解压与目录权限

上传方式看你的条件，小文件用 scp 最省事，几十兆的包一条命令就过去了。传到/tmp再解压到目标目录，不要直接往/var/www里解，解压过程中目录是半成品状态，万一 Web 服务正在扫描，会读到一堆残缺文件。

# 上传并解压到目标目录 scp cy163_customerservice_22.0.0.zip root@your-host:/tmp/ mkdir -p /var/www/cy_customerservice cd /var/www/cy_customerservice unzip -q /tmp/cy163_customerservice_22.0.0.zip # 确认解压后的层级，别多套一层同名目录 ls -la /var/www/cy_customerservice

unzip -q是静默模式，几百个文件不会刷屏。解压完第一件事是看层级：有些打包工具会多套一层同名文件夹，导致入口文件变成/var/www/cy_customerservice/cy163_customerservice/public/index.php，Nginx 的 root 就指错了。如果确实多套了一层，用mv把内容提上来，别改 Nginx 配置去迁就它。

权限这块，原则是「属主给 Web 用户，目录 755，需要写的才给写权限」。全量 777 是最省事也最危险的做法。

# 属主给 php-fpm 运行用户，Debian/Ubuntu 上通常是 www-data chown -R www-data:www-data /var/www/cy_customerservice # 目录 755、文件 644，先按只读定基线 find /var/www/cy_customerservice -type d -exec chmod 755 {} \; find /var/www/cy_customerservice -type f -exec chmod 644 {} \; # 只给真正需要写的目录开写权限，目录名以解包后的实际结构为准 chmod -R 775 /var/www/cy_customerservice/runtime chmod -R 775 /var/www/cy_customerservice/public/uploads chmod -R 775 /var/www/cy_customerservice/config

runtime存缓存和日志，uploads存附件，config在安装阶段要被写入数据库配置。这三个目录是必须可写的，其余保持只读基线。装完之后config的写权限可以收回，配置文件一旦生成就不该再被进程改。

3.2 安装向导走查：数据库、管理员、演示数据三屏

浏览器打开域名，会自动跳到安装入口。如果没跳，手动访问/install或/install/index.php，具体路径以解包后实际目录为准。向导一般是三到四屏，每一屏卡人的点不一样。

第一屏是环境检测和目录权限检测。这一屏最容易被快速点过，但它恰恰是最该停下来看的一屏。PHP 版本、扩展、目录可写状态会逐项列出来，凡是标红的必须先解决，别指望「跳过继续」能顺利装完。检测通过之后会让你填数据库信息，主机名填127.0.0.1而不是localhost，因为后者在部分系统上会走 socket 连接，mysql.sock路径不一致时连不上，用 IP 走 TCP 最稳。

第二屏通常还要填管理员账号、站点名称、访问地址。站点地址要填完整带协议的 URL，后面生成的回调地址、邮件里的链接都基于它，填错了得进数据库改。

演示数据这一项看用途。自己评估或者给团队演示，装上演示数据省事，能直接看到完整的会话列表和统计报表长什么样；正式对外用就别装，演示数据里的假会话和假访客记录清理起来很麻烦，有些系统还不提供一键清空。安装完成后向导一般会提示删除install目录，这一步别拖，留着等于把重装入口暴露在公网上。

# 安装完成后立刻锁死安装入口 cd /var/www/cy_customerservice rm -rf install/ # 或者改名为 install.lock 目录 ls -d install 2>/dev/null || echo "安装入口已移除"

有的版本不是让你删目录，而是提示生成install.lock文件。两种方式等价，目的都是让安装程序检测到「已安装」状态从而拒绝再次运行。判断方法很简单：装完再访问一次安装地址，如果还能进向导界面，就说明锁没生效。

3.3 更新一体包的正确用法：覆盖与增量的分界

这个包名字里带「安装更新一体」，意思是它同时能当全新安装包和升级包用。这里容易翻车：拿它直接覆盖正在跑的老版本，配置文件被覆盖成默认值，数据库连接信息全丢，站点立刻挂掉。

我的做法是先判断当前处于什么状态：全新机器、还是已有旧版本要升级。

• 全新安装：按 3.1 和 3.2 走，解压覆盖到空目录。
• 已有旧版升级：覆盖之前先把config/、public/uploads/、以及数据库完整备份，覆盖时排除这三处。

# 升级前的备份，三样东西一个都不能少 cd /var/www tar czf /backup/cy_cs_config_$(date +%F).tar.gz cy_customerservice/config tar czf /backup/cy_cs_uploads_$(date +%F).tar.gz cy_customerservice/public/uploads mysqldump -u cy_cs -p --default-character-set=utf8mb4 \ cy_customerservice > /backup/cy_cs_db_$(date +%F).sql # 解包新版到临时目录，再增量覆盖，避免直接覆盖掉配置 mkdir -p /tmp/cy_new && cd /tmp/cy_new unzip -q /tmp/cy163_customerservice_22.0.0.zip rsync -av --exclude='config/' --exclude='public/uploads/' \ /tmp/cy_new/ /var/www/cy_customerservice/

rsync的--exclude是关键，它保证配置和附件不会被新版包里的默认文件盖掉。--default-character-set=utf8mb4在 mysqldump 里也不能省，否则导出时按 latin1 处理，恢复回来中文全是问号，这个坑我在早期项目里踩过一次，返工重导了两小时。

覆盖完成之后，有些版本要求在浏览器访问一次升级入口执行数据库结构变更，页面会列出版本号和待执行的 SQL 条数。这一步必须在业务低峰做，因为它可能给大表加字段，锁表时间不好预估。

3.4 伪静态规则与入口重写

前面 2.3 已经给过基础配置，这里补两点客服系统特有的。一是后台路径经常带多层参数，try_files之后要保留$query_string，否则分页和筛选条件全丢。二是如果系统开了「强制 HTTPS」或者后台地址自定义，Nginx 里要额外做一次跳转，别在 PHP 层做，PHP 层做跳转会把 POST 请求体丢掉。

# 强制 HTTPS，注意保留原始请求路径 server { listen 80; server_name cs.example.internal; return 301 https://$host$request_uri; } # 后台自定义路径的反向代理（如果前面挂了网关） location /admin/ { proxy_pass http://127.0.0.1:8080/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; proxy_read_timeout 300; }

X-Forwarded-Proto这行在挂了网关或 CDN 的场景下必须加。客服系统生成回调地址、判断是否 HTTPS 全靠它，不加的话你会看到后台一直提示「当前为非安全连接」，或者回调地址生成成 http 导致渠道校验失败。

proxy_read_timeout和前面 fastcgi 的超时保持一致。超时配置最忌讳各层不一样，A 层等 60 秒、B 层等 300 秒，最后表现是随机性的 504，查起来像玄学。

4. 参数配置：会话、推送与附件的三板斧

装完能进后台只是及格线，真正决定这套客服系统好不好用的是三块配置：数据库与缓存、会话与消息轮询、附件上传。这三块配错，症状都很隐蔽——不是打不开，而是「能用但很卡」「消息延迟十几秒」「图片传上去看不见」。这一章逐个拆开说，每块都给出改哪几行、改完看什么现象。

4.1 数据库与缓存配置：改哪几行、改完看什么

安装向导会生成配置文件，通常在config/目录下，文件名可能是database.php、config.php或者.env，以解包后的实际结构为准。生成之后这几行值得再核对一遍，尤其是从旧版本升级上来的场景，配置文件可能还带着旧库的地址。

// config/database.php 结构与字段名以实际文件为准 return [ 'host' => '127.0.0.1', // 用 IP，避免 localhost 走 socket 'port' => 3306, 'database' => 'cy_customerservice', 'username' => 'cy_cs', 'password' => '换成你自己的强密码', 'charset' => 'utf8mb4', 'prefix' => 'cy_', // 表前缀，升级时不要改 'debug' => false, // 生产环境必须关，开了会吐 SQL 'params' => [ PDO::ATTR_TIMEOUT => 5, // 连接超时，避免慢查询拖死整个请求 ], ];

prefix这一项升级时绝对不能动，改了之后系统会去找一套全新的空表，表现是「装完了但后台什么数据都没有」。debug生产环境关掉，开着的时候一旦出异常，页面上会把完整 SQL 和文件路径打出来。

缓存这块，如果系统支持 Redis，我强烈建议开。客服系统里高频读的是坐席列表、快捷回复、知识库条目，这些数据量不大但读得极频繁，走 MySQL 每次都要连接、查询、序列化，坐席一多数据库连接数就顶不住。

# 确认 Redis 在跑，并且能写能读 redis-cli ping # 期望返回 PONG redis-cli set cy_cs_test 1 EX 60 redis-cli get cy_cs_test # 配置里打开缓存开关后，观察命中率 redis-cli info stats | grep -E 'keyspace_hits|keyspace_misses'

命中率这个指标比「有没有报错」有用得多。如果keyspace_misses远高于hits，说明缓存键设计有问题或者过期时间太短，等于白开。常见原因是缓存键里带了时间戳或随机数，每次都是新键，永远不命中。

4.2 会话与消息轮询：间隔、超时、长连接的取舍

访客端的消息「实时」是怎么实现的，取决于这套系统用哪种方案。常见的有三种：短轮询（前端每隔几秒请求一次接口）、长轮询（请求挂住，有消息才返回）、WebSocket 常驻进程。22.0.0 这类一体包默认多半是短轮询，因为部署最简单，不需要额外开端口和守护进程。

短轮询的参数调优，核心是平衡「延迟」和「服务器压力」。间隔 1 秒，消息很及时，但 500 个在线访客就是每秒 500 次请求；间隔 10 秒，压力小了，访客发完消息等十秒才看到客服回复，体验直接崩。

// 访客端轮询配置的典型位置，具体文件名以实际结构为准 const CHAT_CONFIG = { pollInterval: 3000, // 轮询间隔，3 秒是延迟和压力的折中点 pollTimeout: 8000, // 单次请求超时，必须大于间隔，否则请求堆积 retryLimit: 3, // 连续失败重试次数 retryBackoff: 2000, // 重试退避，避免故障时疯狂重试打垮后端 heartbeat: 30000 // 心跳，用于判断访客是否已离开 };

pollTimeout必须大于pollInterval，这条最容易被忽略。如果超时时间比间隔还短，前一个请求还没结束下一个就发出来了，网络一抖动请求就堆积，浏览器并发连接被占满，表现是整个页面卡死、按钮点不动。

heartbeat关系到坐席端看到的「在线访客」准不准。心跳太长，访客关了页面还显示在线；太短，网络波动一下就误判离线。30 秒是个比较稳的值。

如果坐席规模上去了，短轮询扛不住，那就得上常驻进程方案。这部分要看包里是否带了 WebSocket 服务端，一般在server/或socket/这类目录下，启动方式多为命令行常驻。这类进程必须用 supervisor 托管，直接nohup跑，机器一重启就没了，而且挂了没人拉起来。

; /etc/supervisor/conf.d/cy_cs_socket.conf [program:cy_cs_socket] command=php /var/www/cy_customerservice/socket/start.php start directory=/var/www/cy_customerservice autostart=true autorestart=true user=www-data stdout_logfile=/var/log/cy_cs_socket.log stderr_logfile=/var/log/cy_cs_socket.err.log

autorestart=true是这行的价值所在。客服系统的消息通道断开，访客端不会报错，只是消息一直转圈，用户以为是自己网络问题就走了。有个守护进程盯着，进程挂了秒级拉起，比事后看日志强。

4.3 附件上传：目录、大小与 Nginx 的三个限制

附件这块的坑特别集中，因为限制不止一层。PHP 有upload_max_filesize和post_max_size，Nginx 有client_max_body_size，框架自己还有一套业务层的类型和大小校验。三层的限制值不统一，就会出现「PHP 说能传 50M、Nginx 卡在 1M」这种诡异现象，用户传大图直接 413，页面上什么提示都没有。

# 三个限制必须对齐，最大值取最小那一层 client_max_body_size 50m; # 默认 1m，不改的话超过就 413 client_body_timeout 120s; # 大文件上传要给够时间 fastcgi_request_buffering off; # 大文件直接转给 PHP，别先缓冲到临时文件

fastcgi_request_buffering off这行在上传大文件时作用明显。默认 Nginx 会把整个请求体先缓冲到本地临时文件再转给 PHP，50M 的文件等于写一遍磁盘再读一遍，慢而且占空间。关掉之后边收边转。

业务层的配置一般在后台的「系统设置 → 上传设置」里，能看到允许的扩展名和单文件大小。这里设的值不要超过 PHP 和 Nginx 的限制，否则校验永远走不到业务层就被挡了。

# 检查附件目录属主，root 属主是裂图的头号原因 ls -ld /var/www/cy_customerservice/public/uploads # 期望输出里属主是 www-data，不是 root # 检查磁盘余量，附件区写满后上传会静默失败 df -h /var/www/cy_customerservice/public/uploads

属主这件事值得单独强调。用 root 解压、用 root 改配置，很容易把整个目录的属主都变成 root，而 php-fpm 是以www-data跑的，写文件失败但很多框架不报错，用户看到「上传成功」，回头一看是裂图。chown -R www-data:www-data这一步在 3.1 做过，但每次手动改过文件之后都要复查一遍。

4.4 多端接入：域名、跨域与回调地址

聚合客服的价值就在「聚合」，网页、公众号、小程序、H5 几个入口的会话汇到一起。每个入口的接入方式不一样，但共同的坑是地址填错。后台填的域名必须和实际访问的域名完全一致，包括协议和端口，http和https在这个场景下是两个完全不同的地址。

# H5 端跨域访问接口时的响应头，只在确实需要跨域时加 add_header Access-Control-Allow-Origin "https://h5.example.internal" always; add_header Access-Control-Allow-Methods "GET, POST, OPTIONS" always; add_header Access-Control-Allow-Headers "Content-Type, Authorization" always; add_header Access-Control-Allow-Credentials "true" always;

Access-Control-Allow-Origin不要图省事写*。带了Allow-Credentials: true的情况下，通配符会被浏览器直接拒绝，而且写死具体域名也更安全。always参数保证错误响应里也带这些头，否则一旦接口报错，前端看到的是跨域错误，把真正的问题盖住了。

公众号和小程序这类渠道，后台要填的是回调 URL 和 Token，验证时平台会发一个 GET 请求过来，系统要原样返回一个校验串。这个环节失败，八成是前面 3.4 提到的X-Forwarded-Proto没配，系统生成的校验地址是 http 而实际是 https，签名自然对不上。

注意：改完任何一处域名或回调地址，都要在对应渠道后台重新点一次「验证」或「保存」。很多渠道的校验结果是有缓存的，不重新触发，改了也不生效。

5. 避坑与排查：安装阶段五条血泪记录

这一章是我自己踩过、也帮别人收拾过的五条。前三条是「装都装不完」的硬故障，后两条是「装完了但不对」的软故障。每条按现象、原因、解决三段说，遇到对得上的，直接照着排。

5.1 三个硬故障：白屏、502、装到一半停住

现象一：访问首页或安装向导，页面纯白，浏览器控制台 200，服务器错误日志里没有内容。

原因通常是 PHP 致命错误但display_errors关着，加上error_log指向了没权限写的路径，两头都留不下痕迹，这就是典型的黑匣子。最省事的定位办法是临时把错误打到页面或者指定一个可写的日志文件。

# 临时开错误显示，仅用于排查，排完必须关掉 php -i | grep -E 'display_errors|error_log|log_errors' # 修改 /etc/php/8.0/fpm/php.ini # display_errors = On # log_errors = On # error_log = /var/log/php-fpm/error.log systemctl restart php8.0-fpm tail -f /var/log/php-fpm/error.log

八成情况这里会直接告诉你缺哪个扩展或者哪个文件没找到。我这台机器上第一次就是fileinfo没装，报的是「Class 'finfo' not found」，日志一开一眼就看到了。

现象二：安装向导跑到「写入配置」那一步，转很久然后 502 Bad Gateway。

原因有两个，一是 php-fpm 进程被杀了，二是 Nginx 等不及先断了。request_terminate_timeout默认 30 秒左右，导入初始 SQL 或者生成大量演示数据时很容易超。

; /etc/php/8.0/fpm/pool.d/www.conf request_terminate_timeout = 300 pm.max_children = 20 ; 并发不够也会表现为 502 pm.max_requests = 500 ; 定期回收，防止内存泄漏累积

pm.max_children这个值要按内存算：单个 PHP 进程峰值大概 60 到 100M，4G 内存的机器给 20 比较合适，给太多反而会因为内存不足被 OOM Killer 干掉，表现还是 502。

现象三：装完了，后台输入账号密码登录，页面闪一下又回到登录页。

原因基本是 session 没存住。可能是session.save_path目录不存在或没权限，也可能是配置里的 cookie 域名和实际访问域名不一致，浏览器直接把 cookie 丢了。

# 检查 session 目录 php -i | grep session.save_path ls -ld /var/lib/php/sessions # 属主应是 www-data，权限 1733 或 700 chown www-data:www-data /var/lib/php/sessions

如果目录没问题，去看后台配置里的 cookie 域名字段，填的是顶级域名还是完整域名，和浏览器地址栏对一下。跨域情况下还要注意SameSite属性，新版浏览器默认Lax，跨站请求不带 cookie，登录态自然保不住。

5.2 两个软故障：乱码与附件丢失

现象四：后台能进，但菜单、访客昵称、聊天记录里的中文全是问号或者方块。

原因是导入初始 SQL 时字符集不对。命令行客户端默认按 latin1 处理，utf8mb4的中文进去就变成乱码。这种损坏是不可逆的，只能重导。

# 正确的导入姿势，字符集必须显式指定 mysql -u cy_cs -p --default-character-set=utf8mb4 \ cy_customerservice < /backup/cy_cs_init.sql

验证方法也简单，导完之后直接查一条中文看看：SELECT nickname FROM cy_visitor LIMIT 1;，能正常显示就是对的。要是已经乱码了，别试图在数据库里改字符集修复，直接清库重导，快得多。

现象五：访客上传图片提示成功，坐席端看到的是裂图，或者下载 404。

原因分两种。一是目录属主是 root，php-fpm 以www-data写入失败但代码没检查返回值；二是 Nginx 里location /uploads/的路径和实际存储路径不一致，文件确实在，但 HTTP 请求打到了空目录。

# 先确认文件到底有没有落盘 find /var/www/cy_customerservice/public/uploads -type f -mmin -10 | head # 有文件但访问 404，检查 Nginx 配置里的路径映射 nginx -T | grep -A3 'location /uploads/'

文件不在，就是权限问题，chown -R www-data:www-data加上重启 fpm。文件在但 404，就是 Nginx 路径配错了，或者try_files把请求交给了 PHP 而 PHP 那边路由没匹配上。这两个原因表现一模一样，必须先用find区分开，别一上来就改配置。

6. 装完怎么验证：五个检查点跑通再交付

装完不等于装好。我的习惯是走完五个检查点再把这套环境交出去，缺一个都不算完成，因为客服系统的故障大多不是「完全打不开」，而是某个环节悄悄不工作，等到业务跑起来才发现，那时候排查成本翻好几倍。

第一个检查点，环境自检。装完之后再手动访问一次安装地址，必须被拒绝，能进向导就说明锁没生效。第二个，后台登录，而且要退出再登一次，验证 session 真的持久化了，不是靠当前页面缓存的登录态。第三个，访客端发起会话，用无痕窗口打开访客页面，发一条消息，看坐席端能不能在几秒内收到。第四个，反向发一条，看访客端是否及时显示，这一步验证的是轮询或 WebSocket 真的在跑。第五个，传一张图、下一个附件，确认上传和回显完整。

命令行能覆盖的先用命令行过一遍，比点页面快：

# 入口可用性，期望 200 或 302 curl -o /dev/null -s -w '%{http_code}\n' https://cs.example.internal/ # 安装入口必须已关闭，期望 404 或 403 curl -o /dev/null -s -w '%{http_code}\n' https://cs.example.internal/install/ # 附件目录能否直出，先放一个测试文件进去 echo test > /var/www/cy_customerservice/public/uploads/_probe.txt curl -s https://cs.example.internal/uploads/_probe.txt # 期望输出 test rm -f /var/www/cy_customerservice/public/uploads/_probe.txt

三条命令分别验证了路由、安装锁、静态直出。第二条尤其别省，我见过装完之后忘了删安装目录、被扫描器重装一遍的情况，数据全没。

验收清单我一般会记在部署文档里，交付时对着勾：

最后一行是我后来加的。前面五项都过了，但日志写不出来，等于下次出问题时又是黑匣子，还得从头摸一遍。日志可用这条，验证方法就是手动制造一个错误——比如临时改错一次数据库密码——然后看日志里有没有对应记录，确认完再改回来。

从那以后我每次装这类客服系统，都强制走一遍「锁安装目录 → 退出重登 → 双端互发消息 → 传一张图 → 制造一次错误看日志」这套动作，顺序都不换。看着麻烦，但比出事后翻日志省太多时间。希望帮到你。

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