PHP开源工单系统FeelDesk全解析：部署、模板定制与二次开发-北京尧图网络

简介一套面向中小团队、工单流程不复杂企业的轻量级开源工单系统源码。基于PHP构建前端配合JavaScript与HTML/CSS模板支持工单字段、状态自定义以及路由规则配置适合需要快速部署、按业务调整工单流程的PHP开发人员。压缩包共2000个文件约63.37MB核心以PHP业务逻辑文件为主另有JS交互脚本、HTML模板、CSS样式、TTF字体及JSON/Markdown配置文档并包含Windows启动批处理、Shell脚本等运维辅助文件目录组织清晰。源码内置xxtea加解密C文件与多组config配置便于理解数据加密及站点初始化通过模板机制可灵活配置不同业务工单满足轻型客服、IT支持等场景的落地需求。目前已有346人学习下载适合用作学习工单系统架构或企业内网二次开发的基础源码。1. 为什么选 FeelDeskPHP 开源工单系统里少见的“模板不锁死”常见开源工单系统我前后接触过好几套多数方案的表单和流程是写死的想加个字段得动核心代码升级一次就冲突一次。FeelDesk 是 PHP 开源工单系统里少见的把自定义模板和表单引擎拆出来的项目后端是原生 PHP前端模板里嵌了 JavaScript 联动逻辑适合中小团队自己改。它解决的核心问题很直接工单类型、字段、状态流转都能在后台配置再配合模板文件里的 JS 做条件展示和字段校验。对新手来说环境要求不高能跑 PHP 就能部署对熟手来说这套系统把数据结构暴露得很完整扩展成本低。下面按“部署到核心逻辑、模板改造、踩坑、进阶”的顺序把这套源码完整过一遍能帮你少走不少弯路。2. 部署与初始配置从压缩包到第一张工单产生要过的三关2.1 环境选型为什么 PHP 7.4 MySQL 5.7 是稳妥起点源码包里自带的安装说明写的是支持 PHP 5.6 以上但我实际复现下来PHP 7.4 是最舒服的版本。原因有两个一是项目里用了不少 7.x 才有的语法糖比如??空合并运算符和list()的短数组写法PHP 5.6 下这几个文件会直接报解析错误得手动改代码二是 PHP 8.0 之后源码里个别函数传参方式会触发 Deprecated 警告虽然不影响运行但日志会被刷爆排查问题时很碍眼。所以建议直接用 PHP 7.4配合 MySQL 5.7 或 8.0 都能跑5.7 在字符集处理上更保守适合做生产。PHP 扩展方面安装时重点确认这几个pdo_mysql、mbstring、gd、fileinfo、openssl。fileinfo 是用来在上传附件时做 MIME 类型检测的少了它附件上传会变成不可用状态mbstring 影响所有中文字符串的截断和转义。用宝塔面板或直接 apt/yum 安装的 PHP 通常默认带全但如果你用的是别人精简过的 PHP 包最好先执行一遍php -m看扩展清单。Nginx 下需要配一条伪静态规则把非真实文件路径的请求转发到index.php。这套系统的路由是index.php?ccontrolleraaction形式的不依赖 PATH_INFO所以伪静态其实只影响友好 URL 和后台部分跳转。配置文件放在站点 conf 里location / { try_files $uri $uri/ /index.php?$query_string; } location ~ \.php$ { include fastcgi_params; fastcgi_pass 127.0.0.1:9000; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; }try_files的作用是先找静态文件找不到就把请求交给index.php处理这样模板资源、附件目录能正常访问控制器路由也能正常工作。后面那一段是标准 PHP-FPM 配置注意SCRIPT_FILENAME路径要对否则会出现白屏加 502。2.2 安装步骤从拉取源码到后台可登录把源码放到 Web 目录后我习惯按下面这个顺序操作每一步都有依赖关系顺序反了容易出诡异问题。先建数据库再导入 SQL然后改配置最后设目录权限cd /data/www unzip feeldesk.zip -d feeldesk cd feeldesk # 建库字符集必须用 utf8mb4否则自定义字段里存 emoji 会变问号 mysql -uroot -p -e CREATE DATABASE feeldesk DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; mysql -uroot -p feeldesk install.sql # 目录权限storage 存缓存和附件upload 存上传文件runtime 存运行时日志 chown -R www:www storage upload runtime chmod -R 755 storage upload runtime # 修改配置把数据库账号密码填进去 cp application/config/config.php.bak application/config/config.php vim application/config/config.phpinstall.sql是完整建表脚本里边带了一部分初始数据包括默认管理员账号、工单类型示例和管理员角色。导入后先别急着进后台一定要把config.php里的db_host、db_user、db_pass、db_name四个值改对。文件里还有一处base_url配置项如果站点放在子目录下这里要写成http://你的域名/feeldesk/否则后台跳转和静态资源路径会全乱。这里有个细节config.php里默认debug是关闭的部署完如果页面白屏先把它改成true刷新页面把顶部报错信息截图排查完再关掉。不这样做的话PHP 错误会被吞掉所有排查都只能靠猜。2.3 初始配置工单类型、状态流转与权限组的首轮设置后台默认地址是/index.php?cadminalogin用安装 SQL 里自带的账号登录。第一次进去可以先配置工单类型、状态、优先级和客服分组。工单类型决定了创建工单时展示哪些自定义字段这一步我通常先建“故障报修”和“业务咨询”两个类型其他之后有需要再加。状态流转是这套系统的核心默认是“待分配 - 处理中 - 已解决 - 已关闭”四个状态但你可以在后台加自己的状态。我一般会加一个“待客户确认”因为很多工单其实就是用户没确认就提前关了然后又来问一次。填表时有个参数需要注意配置项推荐值说明通知客服方式站内信邮件站内信实时邮件做兜底自动分配规则轮流分配新团队最公平避免有人堆积超时提醒时间24 小时超过 24 小时未回复自动升为高优先级附件大小上限50 MB再大就考虑走对象存储水印开关开涉及内部系统截图外泄场景时有用客服分组这里有个坑用户注册后默认所属客服组是“未分组”如果某个工单类型的负责人组设成“一组”而未分组里的客服就会看不到这张工单。所以配置完工单类型后一定要回到用户列表里把客服的所属分组改过来不然就会出现“明明用户提交了工单但客服后台一张都看不到”的现象。3. 工单生命周期状态机、分配规则与通知触发的代码级拆解3.1 状态流转的表结构设计FeelDesk 的表结构整体偏实用主义核心表就两张工单主表和状态流转日志表。工单主表不冗余存客户姓名、电话这些信息而是把客户 ID 关联过去这样工单视图加载速度快数据也相对干净。下面是精简过的建表结构字段名我保留了原始风格方便后续和源码对照理解CREATE TABLE work_order ( id int(11) NOT NULL AUTO_INCREMENT, sn varchar(32) NOT NULL COMMENT 工单编号, type_id int(11) NOT NULL COMMENT 工单类型ID, status tinyint(4) NOT NULL DEFAULT 0 COMMENT 状态0待分配 1处理中 2待客户确认 3已解决 4已关闭, priority tinyint(4) NOT NULL DEFAULT 1 COMMENT 优先级1低 2中 3高, assignee_uid int(11) DEFAULT NULL COMMENT 当前处理人, creator_uid int(11) NOT NULL COMMENT 创建人, is_deleted tinyint(1) NOT NULL DEFAULT 0, created_at datetime DEFAULT NULL, updated_at datetime DEFAULT NULL, PRIMARY KEY (id), KEY idx_status (status), KEY idx_assignee (assignee_uid), KEY idx_created_at (created_at) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT工单主表; CREATE TABLE work_order_log ( id int(11) NOT NULL AUTO_INCREMENT, order_id int(11) NOT NULL COMMENT 工单ID, from_status tinyint(4) DEFAULT NULL COMMENT 变更前状态, to_status tinyint(4) NOT NULL COMMENT 变更后状态, action_user int(11) NOT NULL COMMENT 操作人, remark varchar(500) DEFAULT NULL COMMENT 备注, created_at datetime DEFAULT NULL, PRIMARY KEY (id), KEY idx_order_id (order_id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT工单状态变更日志;状态字段直接用tinyint而不是字符串读取时用常量映射比如STATUS_PENDING0、STATUS_PROCESSING1。我在二次开发时也沿用同样的做法新增状态时只改常量定义和后台配置不动表结构。这样做的代价是看数据库时不够直观但换来的是查询快、够稳定。状态日志表是后续做 SLA 统计的底表谁的工单超时了、在哪个环节卡的一条 SQL 就能查出来。3.2 分配规则轮询、优先级与自动分配的 PHP 实现自动分配的逻辑在application/controllers/api/ticket.php里核心是一个assignWorker()方法本质就是按规则从在线客服列表里挑人。源码默认是轮流分配我用伪代码还原了核心逻辑方便看分配顺序// 获取当前工单类型对应的客服组 $groupId $this-ticket_model-getGroupIdByType($typeId); // 该组内所有启用的客服按上次分配时间排序 $workers $this-db -where(group_id, $groupId) -where(status, 1) -order_by(last_assign_time ASC) -get(users) -result(); if (empty($workers)) { // 没有客服在线时工单进待分配池等上线后手动认领 return 0; } // 取排序后第一位并记录分配时间 $assignee $workers[0]; $this-db-where(id, $assignee-id) -update(users, [last_assign_time date(Y-m-d H:i:s)]); // 支持高优先级抢先分配优先级为3时跳过排队直接分给当前负载最低的客服 if ($priority 3) { $assignee $this-worker_model-getLeastLoadedWorker($groupId); } return (int)$assignee-id;按last_assign_time ASC排序是轮流分配的核心——谁上次分到工单时间最早谁就是当前最空闲的下次就该他接。这个做法比真正的轮询计数器简单而且天然处理了“有人请假、有人退出系统”的边界情况。优先级抢单那里是后加的优化逻辑高优先级工单不能按队轮流排不然大客户的问题会一直等。如果你需要负载最低策略可以像我注释里写的把getLeastLoadedWorker()的查询条件改成统计work_order表中当前处理中数量最少的客服。3.3 通知触发站内信、邮件与钉钉的接入点通知触发点散落在状态变更的各个 action 里源码的做法是通过一个notify()方法来统一调度不直接在控制器里写死。这样可以做到“状态一变通知就发”后面接钉钉或企微机器人时也只要改这一个文件private function notify($orderId, $type, $targetUser) { // type: assign分配 reply回复 transfer转交 close关闭 // 1. 站内信写入 notice 表后台右上角图标显示红点 $this-db-insert(notice, [ user_id $targetUser, order_id $orderId, type $type, content 工单 #{$orderId} 有新动态, is_read 0, created_at date(Y-m-d H:i:s) ]); // 2. 邮件通知通过内置的 sendmail 方法异步队列里处理 $email $this-user_model-getEmailById($targetUser); if ($email) { $this-email-send($email, 工单状态更新, $this-buildEmailContent($orderId)); } // 3. 钉钉/企微预留 webhook 地址配置了才推送 $webhook $this-config-item(dingtalk_webhook); if ($webhook in_array($type, [assign, close])) { $this-http-post($webhook, [msgtype text, text [content $this-buildMsg($orderId)]]); } }邮件建议接 SMTP 而不是服务器自带的 sendmail因为大多数云主机的 25 端口被运营商封了自带的 sendmail 大概率发不出去。后台邮件配置里填 QQ 邮箱或企业邮箱的 SMTP 地址和授权码就行。钉钉 webhook 是优先级高的工单才推送避免群里被无关消息刷屏。4. 自定义模板与 JavaScript 二次开发把表单改成你想要的形状4.1 模板机制模板文件结构与字段映射这套系统与其它工单系统最大的差异就在这里创建工单的表单不是写死的 HTML而是由“后台配置的字段”加“模板文件”组合渲染出来的。模板目录在application/views/pc/ticket/下主要文件有三个文件路径作用create.html前台用户创建工单的模板detail.html工单详情页字段只读展示print.html工单打印模板用于线下存档create.html里有一段遍历字段的 PHP 循环后台“工单类型 - 自定义字段”里新增的每个字段都会按顺序渲染出来。字段类型有单行文本、多行文本、下拉框、多选框、附件这几种。模板里的字段名是name属性比如custom[location]提交到后台后用$this-input-post(custom)接收再以 JSON 串存进work_order_data表。这个设计的好处是新增字段不用改数据库表结构缺点是想要按字段做查询统计就得解析 JSON性能会比较吃亏。4.2 自定义字段的 JavaScript 联动自定义字段不只是加个输入框很多时候要做联动逻辑比如选了“服务器故障”类型才出现“服务器 IP”和“紧急程度”两个额外选项。源码里用一个custom_field.js文件来处理这些联动规则监听 select 的 change 事件动态控制相邻字段的显示与隐藏// 监听从后台配置里渲染出来的类型选择框 $(#type_id).on(change, function () { var selectedType $(this).val(); // field_map 是在模板端输出的一段配置对象 // 结构类似 { server_fault: [server_ip, urgency], network: [vlan_id] } var rule field_map[selectedType]; // 先把所有自定义字段容器隐藏再按规则显示命中的字段 $(.custom-field-item).addClass(hidden); if (rule) { rule.forEach(function(fieldKey) { $([data-field fieldKey ]).removeClass(hidden); }); } // 下拉框的值变更后强制触发一次校验避免隐藏字段残留校验状态 $(.custom-field-item:visible input) .prop(required, true) .off(invalid) .on(invalid, function() { this.setCustomValidity(这个联动字段是必填项); }); });field_map这段配置在模板里通过 PHP 端json_encode输出后台管理界面可以维护这个映射关系不需要改前端代码。注意我给隐藏字段加了一层prop(required, true)因为隐藏字段如果不填HTML5 表单校验会报错导致工单提交不了。这种问题很隐蔽用户只会看到“请填写此字段”的提示但字段又看不见把新手直接卡死。在 detail.html 里同样可以用 JS 做字段合并展示比如把“服务器 IP”和“端口”放在同一行输出。4.3 样式改造从 Bootstrap 到自研样式的替换路径模板默认用的是 Bootstrap 3 那套样式外观上就是典型的管理后台样子。如果你需要给客户提供一套更现代的 UI不需要重写模板——项目里已经预留了assets/css/custom.css这个文件加载顺序排在 Bootstrap 后面。在create.html的底部加一行link引用然后覆盖 Bootstrap 的变量即可/* custom.css - 覆盖 Bootstrap 3 默认配色与圆角 */ body { background: #f5f7fa; font-family: PingFang SC, Microsoft YaHei, sans-serif; } .panel-default { border: none; border-radius: 6px; box-shadow: 0 1px 4px rgba(0, 21, 41, 0.08); } .form-control { border-radius: 4px; border-color: #e2e8f0; height: 38px; } .btn-primary { background-color: #2563eb; border-color: #2563eb; border-radius: 4px; } /* 联动字段淡入动画增强体感而不是生硬闪现 */ .custom-field-item:not(.hidden) { animation: fadeIn 0.2s ease-in; } keyframes fadeIn { from { opacity: 0; transform: translateY(4px); } to { opacity: 1; transform: translateY(0); } }这套覆盖方式的好处是保留了模板底的响应式布局改完不破坏栅格系统。如果追求重度定制比如把整个头部导航的布局都换掉建议直接复制一份create.html到assets/template/custom/目录在后台模板管理里切换模板源这样不会影响官方模板文件升级源码时也不冲突。5. 避坑部署和二次开发中常见的六个翻车现场5.1 后台登录页打不开直接跳 404现象后台地址输入后页面显示“404 Not Found”但前台页面是正常的。原因Nginx 的伪静态配置里try_files没有生效导致index.php?cadmin这类带 query string 的路径没被正确解析。更多时候是因为站点根目录配置指到了public/子目录但源码本身不在这个子目录里。解决确认站点访问目录和伪静态配置的对应关系如果站点直接在源码根目录把try_files配置加上如果加了伪静态还是 404执行php -l index.php检查入口文件语法是否有错误。5.2 附件上传报 413 Request Entity Too Large现象上传超过 8MB 的附件时Nginx 直接返回 413后台报错日志里没有 PHP 错误信息。原因Nginx 默认client_max_body_size是 1MBPHP 的upload_max_filesize默认限制 2MB后端配置没改附件大小限制是空话。解决改两处配置Nginx 的http块加client_max_body_size 50m;PHP.ini 里把upload_max_filesize 50M和post_max_size 60M都改掉。改完记得分别 restart Nginx 和 PHP-FPM配置不是热加载的。5.3 后台改了工单状态名称前台不生效现象把“已解决”改名成“已完成”后台显示是新名字前台客户看到的还是“已解决”。原因前台模板里状态展示做了数组映射模板里是硬编码的getStatusText($status)这个函数返回的是代码里的常量定义不读后台配置表。解决要么强行改函数里的$statusMap数组要么在后台不建议修改默认四态的名称只新增自定义状态。这个是模板设计的问题源码本身的文档里也比较含糊只能靠改代码解决。5.4 JavaScript 文件改动后后台一直跑旧逻辑现象改了custom_field.js清了浏览器缓存还是没效果按 CtrlF5 也不好使。原因模板里的 JS 引用没有带版本号浏览器和 CDN 会默认缓存这些静态资源。部分环境里 Nginx 对静态文件设置了expires头导致强缓存 24 小时。解决临时调试时在引用路径后面手动加参数?v20240601上线前把这个参数改成自动化版本号同时检查 Nginx 配置里location ~* \.(js|css)$块把expires值调成off。5.5 从旧系统导入工单数据出现中文乱码现象用 SQL 导入 CSV 或手动执行 insert 语句后工单标题和内容是“口口口”或一堆问号。原因数据库连接端和执行端的字符集不一致概率最大。老系统导入时有的是 GBK 编码直接灌进 utf8mb4 表里必乱。解决导入前先执行SET NAMES utf8mb4;同时用iconv -f GBK -t UTF-8 old_data.csv new_data.csv把数据文件转码。如果已经导入乱了用ALTER TABLE work_order CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;可以重新转换但已经损坏的数据只能删掉重新导。5.6 超时未回复提醒一直不触发现象工单到了超时时间客服也没收到任何提醒系统日志里没有任何相关记录。原因这套系统的定时任务不是靠 PHP 进程常驻而是依赖 Cron 定时去执行一个 URL 或 CLI 脚本。源码包里的cron.php文件若没有被 crontab 配置提醒功能就是空转。解决在 crontab 里加一行每五分钟执行一次*/5 * * * * cd /data/www/feeldesk /usr/bin/php cron.php check_timeout storage/logs/cron.log 21需要确认 PHP 的绝对路径用which php查一次再写进去否则会静默失败。6. 进阶用命令行脚本把工单系统接进自动化流程6.1 用 CLI 脚本批量导入历史工单旧系统迁移过来手工在后台创建几百条工单显然不现实。直接灌数据进work_order表会跳过分配和通知逻辑所以正确做法是复用模型的create()方法写一个 CLI 脚本批量导入且保留归属人?php // cli_import.php defined(BASEPATH) OR exit(No direct script access allowed); class Cli_import extends CI_Controller { public function index() { $file FCPATH . storage/tmp/import_data.json; if (!file_exists($file)) { fwrite(STDERR, import_data.json 不存在\n); exit(1); } $rows json_decode(file_get_contents($file), true); $this-load-model(ticket_model); foreach ($rows as $row) { $data [ type_id $row[type_id], creator_uid $row[creator_uid], title $row[title], content $row[content], priority isset($row[priority]) ? $row[priority] : 1, status isset($row[status]) ? $row[status] : 0, created_at $row[created_at], ]; // 用主表的 create 方法自动走分配和通知逻辑 // 第二个参数表示“不强制发通知”用于老数据导入 $orderId $this-ticket_model-create($data, $row[assignee_uid] ?? null); echo 导入工单 #{$orderId} 成功\n; } } }重点在$this-ticket_model-create()方法它会处理状态初始化、分配客服、写日志这些基础动作。比直接 insert 的好处是工单编号sn的生成、附件关联、通知触发这些逻辑不会被跳过。导入后要检查一遍assignee_uid是否为合法客服 ID因为旧系统里的处理人可能已经离职非法关联会导致工单详情页报错。6.2 通过 API 回调实现工单状态同步有监控系统或工单平台需要双向同步的场景可以让 FeelDesk 在工单状态变更时主动回调外部接口。实现方式是在work_order_log写入后的位置加一个after_insert钩子把变更新动态 POST 到外部地址public function after_insert($logData) { $orderId $logData[order_id]; $toStatus $logData[to_status]; $payload [ order_id $orderId, status $toStatus, update_time date(c), ]; // 外部接口地址配置在 config.php 的 external_callback $callbackUrl $this-config-item(external_callback); if ($callbackUrl) { $this-http-post($callbackUrl, $payload); } // 记录回调结果失败时写入 callback_fail_log 表备查 }这种改造适合把工单状态同步到企业微信群里做自动化播报的场景。外部接口要做好幂等处理因为系统异常重试时可能同一条状态变更触发多次。我自己的经验是接这类回调时永远先加签名校验最简单的做法是在请求头里带一个固定 token外部服务校验失败就直接拒绝避免内部工单数据被推测出来。那之后我每套系统做回调查都是先把接口鉴权写好再谈业务逻辑。调用回调的 HTTP 客户端里把超时设短一点比如 3 秒因为主流程不应该被外部服务拖慢。这套系统对我来说最大的价值就是扩展点设计得规整不漂亮但够直接真正拿来做深度定制时反而顺心。希望这套源码能帮你把工单流程梳理顺模板改造少踩几个坑。本文还有配套的精品资源点击获取

PHP开源工单系统FeelDesk全解析：部署、模板定制与二次开发

相关推荐

MATLAB/Simulink实现FM调制解调与预加重建模

基于GroundingDINO与SAM的开放词汇检测与分割实战指南

大屏编辑器数据源接入全攻略：打通MySQL、API与文件不再难

更多资讯

大时滞过程控制与MATLAB仿真：Smith预估器、内模控制及参数整定全解析

通道注意力LW-ResNet小麦病害识别系统

TensorRT加速SAM：从ONNX导出到C++服务部署全攻略

Keras+YOLO车辆检测实战：从环境搭建到TensorRT加速全流程

手写数字识别：从kNN到CNN的PyTorch实战指南

从无标题文档到正式发布：先定内核再取标题的创作流程

今日更新

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？