让每一条问题反馈都有记录、有回应

一、服务器环境

• 可运行 PHP 的 Web 服务器，例如 Nginx 或 Apache。
• MySQL 或兼容的数据库服务，以及可连接该数据库的账号。
• PHP Web 运行环境和 PHP CLI；建议两者使用同一套 PHP 版本与配置。
• 数据库扩展：PDO、 pdo_mysql。
• 邮件同步必需：PHP CLI 中可用的 imap 扩展。
• 按实际部署启用 mbstring、 iconv、 fileinfo、 openssl； pcntl 可用于 Linux CLI 守护进程接收停止信号。图片处理所需扩展应按实际上传代码检查。
• 邮箱工作进程建议交给 Supervisor 守护；邮件同步进程必须能写入其日志、 UID 状态文件、锁文件和附件上传目录。

php -v
php --ini
php -m | grep -Ei 'imap|pdo_mysql|mbstring|iconv|fileinfo|openssl|pcntl'

二、安装及使用流程

1. 将项目文件部署到网站目录，并配置网站访问 PHP 和数据库的环境。
2. 访问项目的 install.php，按安装页面提示完成数据库与管理员账号配置。
3. 登录 admin.php，创建至少一个站点并取得站点密钥。
4. 访问本页，点击“💬 体验问题反馈”，或将后台生成的嵌入代码放到目标网站页面。
5. 如果需要邮件回复同步，再按下方步骤配置邮箱并启动 email_worker.php。

本页沿用原首页逻辑，自动取数据库中 ID 最小的站点作为体验站点； 没有站点时不会加载可用的反馈组件。

第一步：准备专用邮箱并开启 IMAP

1. 准备接收工单邮件、供管理员回复使用的系统邮箱。
2. 进入邮箱服务商设置，开启 IMAP 服务；若项目另有发信功能，同时按其发信配置开启 SMTP。
3. 若服务商要求“客户端授权码”或“应用密码”，使用该凭据填写 IMAP 密码，不要把网页登录密码直接写入配置。
4. 确认服务器可以连接邮箱的 IMAP 主机及端口，并确认实际监听文件夹是 INBOX。

例如使用普通 QQ 邮箱时，常用 IMAP 配置为 imap.qq.com、 993 端口和 SSL； 使用企业邮箱或其他服务商时，应以该邮箱服务商提供的参数为准。

第二步：配置项目的邮箱参数

你提供的 config.php 会加载 config.generated.php； email_worker.php 读取下列 IMAP 常量。 先检查生成的配置文件是否已有这些定义；已有定义时修改原值，不要重复定义。

/* 以下为示例：填入 config.generated.php 中对应的配置位置 */
define('IMAP_HOST', 'imap.qq.com');
define('IMAP_PORT', 993);
define('IMAP_ENCRYPTION', 'ssl');
define('IMAP_USER', 'your_mail@qq.com');
define('IMAP_PASS', '此处填写邮箱客户端授权码');
define('IMAP_FOLDER', 'INBOX');

/* 必须与实际发送管理员回复的邮箱地址一致 */
define('ADMIN_EMAIL', 'your_mail@qq.com');

配置文件应保持原有 PHP 语法及数据库配置不变。具体发信服务器、 SMTP 常量名称和端口，请以你项目现有的安装程序及发信代码为准； IMAP 收信配置不等于 SMTP 发信配置。

注意保护 config.generated.php： 不要将授权码提交到公开仓库，也不要通过网页展示真实配置文件内容。

第三步：安装并核对 PHP CLI 扩展

必须确保运行 email_worker.php 的那个 PHP 可执行文件加载了 IMAP 扩展。例如：

command -v php
php -v
php -r "echo function_exists('imap_open') ? 'IMAP OK' : 'IMAP MISSING'; echo PHP_EOL;"
php -r "echo extension_loaded('pdo_mysql') ? 'PDO MySQL OK' : 'PDO MySQL MISSING'; echo PHP_EOL;"

如果系统提示 IMAP MISSING， 安装与你当前 PHP CLI 版本匹配的 IMAP 扩展，并在 CLI 的 PHP 配置中启用它；不同 Linux 发行版和 PHP 仓库的包名可能不同。 PHP 8.4 起，IMAP 扩展不再随 PHP 捆绑，安装方式可能需要使用 对应系统软件包或 PECL。

第四步：准备写入权限，并先手动测试

邮件同步程序需要读取项目配置，并写入数据库。运行用户还需要对 email_worker.log、 email_worker.lock、 email_worker_state.json 所在目录以及 uploads/ 具有适当权限。

# 先进入项目实际目录；路径请按你的服务器修改
cd /var/www/ticket

# 使用与守护进程相同的 PHP CLI、相同的运行用户测试
/usr/bin/php email_worker.php

# 另开终端查看程序日志
tail -f /var/www/ticket/email_worker.log

第五步：使用 Supervisor 守护邮箱工作进程

安装 Supervisor 后，在其实际读取的配置目录中添加程序配置。 下例的 PHP 路径、项目路径及运行用户均为示例，须替换为实际值。 如果你已配置名为 ticket_email_worker 的进程，请修改现有配置，不要再创建第二个同名或不同名的邮件工作进程。

[program:ticket_email_worker]
command=/usr/bin/php /var/www/ticket/email_worker.php
directory=/var/www/ticket
user=www-data
autostart=true
autorestart=true
startsecs=5
startretries=10
stopsignal=TERM
stopwaitsecs=45
redirect_stderr=true
stdout_logfile=/var/log/ticket_email_worker.log
stdout_logfile_maxbytes=10MB
stdout_logfile_backups=5

确认 /var/log/ticket_email_worker.log 可由 Supervisor 正常创建和写入，且 www-data 对项目所需目录有权限。 有些服务器使用 nginx、 apache 或其他运行用户。

# 使用系统默认 Supervisor 配置时
supervisorctl reread
supervisorctl update
supervisorctl status ticket_email_worker

# 若服务器使用单独的 Supervisor 配置文件，例如：
supervisorctl -c /etc/supervisord-ticket.conf reread
supervisorctl -c /etc/supervisord-ticket.conf update
supervisorctl -c /etc/supervisord-ticket.conf status ticket_email_worker

修改 Supervisor 程序配置后使用 reread 和 update； 单独执行 restart 不会重新读取已修改的程序配置。

第六步：检查同步结果与常见问题

1. 在前台提交测试工单，确认工单号已生成。
2. 从与 ADMIN_EMAIL 一致的邮箱回复含该工单号的邮件。
3. 查看 email_worker.log 和 Supervisor 状态，确认邮件被识别、入库。
4. 在管理后台打开工单，确认沟通记录和状态正确；再检查用户端新回复提示。

• 邮箱连接失败：检查 IMAP 主机、端口、SSL、授权码、防火墙及邮箱是否启用 IMAP。
• 提示缺少 IMAP：确认安装扩展的是 Supervisor command 所用的 PHP CLI。
• MySQL server has gone away：检查数据库服务与连接恢复逻辑；仅调整邮箱轮询间隔不能修复失效的 PDO 连接。
• 日志显示跳过邮件：核对发件地址、主题中的工单号、工单是否已结单，以及正文或附件内容。
• 附件写入失败：核对 uploads/ 的目录权限及磁盘空间。
• 已入库但前台无未读提示：继续检查用户端 embed.js 及对应 API 返回值；本展示页不会替代这些业务逻辑。