简介这是一套面向企业与开发者的工单管理完整源码包围绕工单创建、分配、处理、协同、统计等核心流程展开。适合用来搭建内部服务台也适合作为计算机毕业设计论文的实践案例帮助学习者理解工作流系统的前后端实现。压缩包共 643 个文件约 6.89MB以 Go 后端122 个和 JavaScript 前端438 个为主同时包含 SVG 图标、CSS 样式、HTML 页面、TTF/WOFF 字体资源以及 SQL 初始化脚本、Dockerfile、Makefile 和 YAML 配置覆盖从页面展示到服务部署的完整链路。ferry-master 目录内还保留了版本控制相关信息便于跟踪代码变更与团队协作目前已有 345 人学习下载。通过研究这套源码可以掌握工单系统的数据库建模、权限校验、API 接口及任务流转逻辑理解优先级、状态更新、报表统计等功能的具体实现同时借助前端模板与后端脚手架快速改造出符合自身业务需求的工单平台。1. ferry 工单系统 v1.0.zip 是什么先别急着解压ferry 工单系统 v1.0.zip 是 Go 社区里一种常见形态的开源工单项目的发布包前端 Vue、后端 Go产物打成一个 zip 分发。多数人下载它是想把 IT 报修、内部审批从 Excel 和聊天记录里搬出来但真正动手后会发现工单系统的门槛不在表单而在流程引擎一个节点到达后下一步该给谁、什么条件下走哪个分支、权限怎么过滤可见范围。这篇博客以 v1.0.zip 的部署为起点先讲清楚这套系统的流程与权限模型再给出一套能直接照做的安装、配置、验证命令。适合小团队运维和想读 Go 项目源码的后端工程师。2. ferry 工单系统的技术底座与流程模型先立概念再动手2.1 Go Gin Vue 的选型为什么常见在工单这类企业系统里最常见的后端组合不是 Spring Boot而是 Go Gin Vue 的轻量组合。ferry 的惯例架构是前后端分离后端用 Gin 提供 REST APIGORM 操作 MySQL前端用 Vue 和 Element UI 做后台界面权限模型用 Casbin。这样选型不是偶然工单系统大多跑在企业内网部署环境可能是 Windows Server 也可能是麒麟一个编译好的二进制文件加一个前端静态目录拷贝过去就能启动不依赖 JDK 或 Node 运行时。如果拿它和 Java 系的 Activiti/Flowable 对比差异在流程建模的深度。Activiti 支持完整的 BPMN 2.0 规范包括子流程、边界事件、并行网关而 ferry 这类 Go 项目的流程引擎一般只覆盖线性审批和条件分支。这不是缺陷是取舍。多数 IT 运维工单本质上就是提交 - 分派 - 处理 - 验证 - 关闭的线性流转把模型做重了反而增加理解成本。下面这张表列了两种方案在部署、建模型和二次开发上的差别。对比项ferryGo 轻量工作流Activiti/Flowable部署单二进制 静态文件JVM 应用容器流程建模节点数组 条件路由学习成本低BPMN 2.0 XML符号多二开语言Go / 前端 JSJava / 前端 JS适合场景部门级工单、审批流跨系统复杂编排实际选型时如果团队里没有专门读 BPMN 的人ferry 这种轻量模型更容易交付。2.2 流程由节点数组和路由条件构成看源码时会发现它不会把流程画成图而是用结构化的节点数组表达。通俗地讲一张工单就是一个状态机每个状态是一个节点节点与节点之间由路由条件连接。以下 JSON 是这种结构的典型写法我一般会在配置流程时先在记事本里写一版再贴进界面。{ workflow_name: 服务器故障报修, nodes: [ {node_id: start_apply, type: start, next: it_assign}, {node_id: it_assign, type: approval, handler: group:it_service_desk, next: repair}, {node_id: repair, type: task, handler: user:zhangsan, next: verify}, {node_id: verify, type: approval, handler: group:it_manager, next: end_close} ] }把这段拆分来看start 节点只做入口没有处理人approval 节点表示需要有人点通过或驳回task 节点表示一个执行动作。handler 是关键字段user:zhangsan 是指定单个用户group:it_service_desk 是指定某个角色或用户组。next 决定流转去向这段配置里每一步都只有一个出口所以是直线流程。节点参数通常涉及五个核心字段参数取值说明node_id英文字符串节点唯一标识路由引用typestart / approval / task / end决定节点行为和是否能驳回handleruser:xxx / group:xxx处理人建议优先用 groupnext节点 id 或数组单出口写字符串多出口写数组配合条件condition表达式多出口时判断走哪个分支多出口的条件路由会写成数组例如 verify 节点后面既有 end_close 也有 back_to_repair引擎根据表单字段或者审批结果选择分支。理解这个模型后配置界面里那些下一节点处理人就不是孤立的表单而是这个状态机的一小段映射。2.3 权限模型Casbin 控制谁能看到什么另一个容易忽略的点是权限。ferry 体系内一般用 Casbin 的 RBAC 模型规则存在数据库表里典型的 p 和 g 两类策略关系如下。表类型规则写法含义p策略p, alice, /api/v1/workflow, GET允许 alice 读取流程接口g角色继承g, alice, it_adminalice 属于 it_admin 角色工单列表的可见性除了走 Casbin还会在 SQL 层加过滤普通用户只能看到自己创建的工单组内成员能看到本组单子管理员看全部。所以二次开发时不要只改前端路由做菜单隐藏真正的权限控制必须落到 API 的参数校验和查询条件里。这一节内容对应到后面就是部署时先初始化权限表再登录后台建角色、绑菜单最后才能分派工单。3. 从 v1.0.zip 部署 ferry 工单系统校验、解压、配置 MySQL 与启动排错3.1 先校验 zip 完整性避免 error read zip archive网上下载的 v1.0.zip 可能经过网盘转存、断点续传第一个动作不应该是双击解压而是校验。官方发布通常会附一个 SHA-256 校验值在 Linux 或 Git Bash 下执行三件套。sha256sum ferry工单系统-v1.0.zip unzip -t ferry工单系统-v1.0.zip zipinfo -v ferry工单系统-v1.0.zip | head -40sha256sum 把本地文件的哈希和发布页的校验值比对能排除下载不完整或被替换的可能。unzip -t 是测试模式会逐个文件检查 CRC。如果看到 error read zip archive 或 could not find EOCDEnd of Central Directory这类报错说明压缩包尾部目录缺失本质是文件没下完或者被第三方工具改过结构。常见处理方式重新下载、换用支持断点续传的下载器、检查磁盘剩余空间。还有个小坑有人在拿到 zip 后会用压缩软件直接改包里的文件再保存这种操作会把原 zip 的中央目录搞坏后续部署时出现 EOCD 错误。正确的做法是先解压到临时目录改完重新打包并重新生成 sha256。如果下载下来的 zip 带打开密码比如企业内部分发时用了加密压缩流程应该是向分发方确认口令后用 7-Zip 或 unzip 正常解压而不是去搜zip密码移除并跑爆破工具。密码移除类操作只适用于自己遗忘密码且拥有合法副本的场景用在工作环境里可能引来合规风险。3.2 准备 MySQL 数据库和 config.ymlv1.0.zip 解压后一般会有编译好的二进制、web 静态目录、sql 目录和 config.yml也可能只有源码。先把数据库准备好常见初始化语句如下。mysql -uroot -p -e CREATE DATABASE ferry DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; mysql -uroot -p -e CREATE USER ferry% IDENTIFIED BY ChangeMe_2024; mysql -uroot -p -e GRANT ALL PRIVILEGES ON ferry.* TO ferry%;使用 utf8mb4 是为了让备注、标题里的 emoji 不变成乱码。接着打开 config.yml核心配置项如下。app: name: ferry port: 8080 # 对外服务端口 run_mode: release # debug 会打印大量 SQL 日志 database: host: 127.0.0.1 port: 3306 user: ferry password: ChangeMe_2024 dbname: ferry max_idle_conns: 10 max_open_conns: 100参数说明run_mode 在首次联调时可以设 debug正式跑再切 releasemax_open_conns 不要盲目调大工单系统并发不高100 足够过大反而让 MySQL 线程切换变慢。GORM 启动时会自动按 model 建表或迁移字段所以不需要手工执行全部 sql 文件。3.3 源码包处理从 GitHub 的 zip 包怎样装到能跑如果你的 v1.0.zip 是源码包而不是已经编译好的产物会遇到一个常见场景后端能编译但前端 dist 目录是空的。GitHub 上直接下载的 zip 包往往不带 node_modules也不会把构建后的静态文件打进压缩包。此时先按顺序执行。# 后端依赖Go 1.18 go mod tidy go build -o ferry main.go # 前端构建Node 14 cd web npm install npm run build cd ..npm install 期间出现 node-sass 类的报错通常是 Node 版本太新或网络源问题可以改用 nvm 切到项目要求的 Node 大版本再把 registry 换成国内镜像。前后端构建完成后把 web 的 dist 目录放到 backend 静态文件目录再启动后端就能访问管理界面。3.4 启动并确认日志启动命令和检查项如下。./ferry -c config.yml ferry.log 21 sleep 3 tail -50 ferry.log curl http://127.0.0.1:8080/healthz第一次启动时日志里会打印数据库迁移结果、监听端口并提示初始化管理员账户。此时如果 curl /healthz 返回 200或对应 JSON说明服务起来了。第一次启动后必须立刻登录后台把安装向导生成的默认密码改掉再关闭 debug 模式。否则你的工单系统等于裸奔在内网。常见的启动失败原因有三类按日志关键字定位很快。现象日志关键字排错方向连不上数据库dial tcp 127.0.0.1:3306 超时检查 MySQL 远程权限、端口、密码转义端口被占bind: address already in use杀旧进程或改 app.port前端白屏无静态资源请求确认 dist 路径和接口前缀把这三项按日志逐个排除部署基本就能通过。4. 配置 ferry 工单系统的第一个流程工单类型、节点路由与接口验证4.1 建工单类型和表单字段部署完成后下一个需求通常是把服务器报修这类业务固化成流程。后台界面的惯例顺序是先在工单类型里建一个类型再在表单设计里添加字段字段类型包括单行文本、多行文本、数字、日期、下拉选择以及对当前登录用户只读的申请人和所属部门字段。建类型时要注意一点字段建好后再删改会牵涉历史工单的数据结构运营期尽量只增不改。如果需要批量初始化可以直接往对应字典表插入数据但绕过后台容易漏掉缓存刷新。我一般不会手动写 SQL 来建类型除非是给测试环境做脚本化准备。4.2 配置审批节点处理人用角色而不是个人以一次机房故障报修为例子流程设计成四步申请 - 服务台分派 - 工程师处理 - 主管验证。在流程配置界面填入节点时节点 JSON 对应如下。{ workflow_name: 机房故障报修, nodes: [ {node_id: apply, type: start, next: dispatch}, {node_id: dispatch, type: approval, handler: group:it_service_desk, next: handle}, {node_id: handle, type: task, handler: group:engineer, next: verify}, {node_id: verify, type: approval, handler: group:it_manager, next: [{target: close, condition: verify_result pass}, {target: handle, condition: verify_result fail}]} ] }这段比第 2 章的示例多了一个条件路由。verify 节点后面有两个出口引擎在审批动作发生时读取表单里的 verify_result 字段等于 pass 就走 close等于 fail 就退回 handle。处理人全部用 group 而不是 user是因为工程师离职、转岗是常态改角色成员比改流程定义更安全这是配置环节最容易踩的坑。4.3 用 curl 走一遍工单接口验证配置界面点一遍只能验证人肉流程想确认接口权限和流程引擎都正常我用 curl 跑冒烟测试。以下以默认的路由前缀 /api/v1 为例实际安装版本以登录后 F12 看到的地址为准。# 登录拿 token curl -s -X POST http://127.0.0.1:8080/api/v1/login \ -H Content-Type: application/json \ -d {username:alice,password:ChangeMe_2024} \ | tee login.json # 从 login.json 里提取 token创建工单 TOKEN$(python3 -c import json;print(json.load(open(login.json))[data][token])) curl -s -X POST http://127.0.0.1:8080/api/v1/tickets \ -H Authorization: Bearer $TOKEN \ -H Content-Type: application/json \ -d {type:机房故障报修,title:机房空调告警,fields:{room:A-302}} # 查未处理列表 curl -s http://127.0.0.1:8080/api/v1/tickets?statusopen \ -H Authorization: Bearer $TOKEN逻辑说明第一步登录拿到 JWT第二步把工单类型和业务字段按 JSON 提交第三步验证列表接口能否按当前人的权限返回数据。如果第二步返回 403 而不是 200说明当前账号的角色没有建单权限回去检查 Casbin 策略如果返回 200 但列表看不到问题多半在数据权限的部门过滤 SQL而不在流程配置。4.4 节点配置的三个习惯与常见问题对照做流程配置时我习惯遵循三条规则。第一每个审批节点都设置一个默认处理人组避免条件分支全部落空时工单卡死。第二验收前把驳回路径走一遍很多隐藏 bug 出在驳回时字段被清空。第三节点名称和工单状态别混用一套枚举节点是引擎概念工单状态是业务视角二者通过路由关联混在一起会让后来接手的人看不懂。下面是几类高频问题的对照。现象通常原因建议处理工单卡在某节点没人处理处理人写成 user人员已离职改用 group 并维护成员驳回后字段值丢失流程引擎只路由不保存单据快照重新进入节点时回填原值多出口分支全部不匹配next 条件没有默认值加一个兜底节点这三条不是系统功能而是配置规范。工单系统真正难维护的地方多半不是代码而是流程定义里混乱的命名和过度设计的状态数。5. 升级 v1.0.zip 前必做的三件事文件清单对比、二进制信息核对与冒烟脚本5.1 用 unzip -Z1 快速对比两个版本的差异拿到 v1.0.zip 之后手上有旧版本的话先用 unzip -Z1 把两个压缩包的文件清单导出再 diff 一眼看出这次发布动了哪些目录。unzip -Z1 ferry工单系统-v1.0.zip new.files unzip -Z1 ferry工单系统-v0.9.zip old.files diff old.files new.files如果 diff 结果只有 web/dist 下的文件变化说明升级是纯前端替换反之若是主二进制变大几十 MB说明后端依赖或运行时版本有变升级要重点回归接口。5.2 核对二进制构建信息源码编译的二进制可以用 go version -m 看模块依赖这一条信息量很大。go version -m ferry | head -30输出里能看到 Go 版本、包路径、依赖模块的版本号。把它和发布说明比对能确认 v1.0.zip 确实出自同一份代码也方便之后复现编译环境。5.3 写一个 30 行的冒烟脚本再上线把第 4 章的 curl 流程落成脚本作为每次升级后执行一次的检查项。脚本内容不复杂登录、建单、查列表、登出。#!/bin/bash set -euo pipefail BASEhttp://127.0.0.1:8080/api/v1 TOKEN$(curl -s -X POST $BASE/login -H Content-Type: application/json \ -d {username:smoketest,password:ChangeMe_2024} \ | python3 -c import sys,json;print(json.load(sys.stdin)[data][token])) curl -s -X POST $BASE/tickets -H Authorization: Bearer $TOKEN \ -H Content-Type: application/json \ -d {type:机房故障报修,title:smoke test} /dev/null curl -s $BASE/tickets?statusopen -H Authorization: Bearer $TOKEN \ | python3 -c import sys,json; djson.load(sys.stdin); assert len(d[data])0 echo smoke ok脚本退出码为 0 才算通过配合 CI 的定时任务就是最简单的可用性监控。这套方法比盯着界面点十遍可靠也比引入压测工具更贴近日常运维的真实需求。本文还有配套的精品资源点击获取
ferry工单系统v1.0部署实践：流程引擎与Casbin权限模型详解
简介这是一套面向企业与开发者的工单管理完整源码包围绕工单创建、分配、处理、协同、统计等核心流程展开。适合用来搭建内部服务台也适合作为计算机毕业设计论文的实践案例帮助学习者理解工作流系统的前后端实现。压缩包共 643 个文件约 6.89MB以 Go 后端122 个和 JavaScript 前端438 个为主同时包含 SVG 图标、CSS 样式、HTML 页面、TTF/WOFF 字体资源以及 SQL 初始化脚本、Dockerfile、Makefile 和 YAML 配置覆盖从页面展示到服务部署的完整链路。ferry-master 目录内还保留了版本控制相关信息便于跟踪代码变更与团队协作目前已有 345 人学习下载。通过研究这套源码可以掌握工单系统的数据库建模、权限校验、API 接口及任务流转逻辑理解优先级、状态更新、报表统计等功能的具体实现同时借助前端模板与后端脚手架快速改造出符合自身业务需求的工单平台。1. ferry 工单系统 v1.0.zip 是什么先别急着解压ferry 工单系统 v1.0.zip 是 Go 社区里一种常见形态的开源工单项目的发布包前端 Vue、后端 Go产物打成一个 zip 分发。多数人下载它是想把 IT 报修、内部审批从 Excel 和聊天记录里搬出来但真正动手后会发现工单系统的门槛不在表单而在流程引擎一个节点到达后下一步该给谁、什么条件下走哪个分支、权限怎么过滤可见范围。这篇博客以 v1.0.zip 的部署为起点先讲清楚这套系统的流程与权限模型再给出一套能直接照做的安装、配置、验证命令。适合小团队运维和想读 Go 项目源码的后端工程师。2. ferry 工单系统的技术底座与流程模型先立概念再动手2.1 Go Gin Vue 的选型为什么常见在工单这类企业系统里最常见的后端组合不是 Spring Boot而是 Go Gin Vue 的轻量组合。ferry 的惯例架构是前后端分离后端用 Gin 提供 REST APIGORM 操作 MySQL前端用 Vue 和 Element UI 做后台界面权限模型用 Casbin。这样选型不是偶然工单系统大多跑在企业内网部署环境可能是 Windows Server 也可能是麒麟一个编译好的二进制文件加一个前端静态目录拷贝过去就能启动不依赖 JDK 或 Node 运行时。如果拿它和 Java 系的 Activiti/Flowable 对比差异在流程建模的深度。Activiti 支持完整的 BPMN 2.0 规范包括子流程、边界事件、并行网关而 ferry 这类 Go 项目的流程引擎一般只覆盖线性审批和条件分支。这不是缺陷是取舍。多数 IT 运维工单本质上就是提交 - 分派 - 处理 - 验证 - 关闭的线性流转把模型做重了反而增加理解成本。下面这张表列了两种方案在部署、建模型和二次开发上的差别。对比项ferryGo 轻量工作流Activiti/Flowable部署单二进制 静态文件JVM 应用容器流程建模节点数组 条件路由学习成本低BPMN 2.0 XML符号多二开语言Go / 前端 JSJava / 前端 JS适合场景部门级工单、审批流跨系统复杂编排实际选型时如果团队里没有专门读 BPMN 的人ferry 这种轻量模型更容易交付。2.2 流程由节点数组和路由条件构成看源码时会发现它不会把流程画成图而是用结构化的节点数组表达。通俗地讲一张工单就是一个状态机每个状态是一个节点节点与节点之间由路由条件连接。以下 JSON 是这种结构的典型写法我一般会在配置流程时先在记事本里写一版再贴进界面。{ workflow_name: 服务器故障报修, nodes: [ {node_id: start_apply, type: start, next: it_assign}, {node_id: it_assign, type: approval, handler: group:it_service_desk, next: repair}, {node_id: repair, type: task, handler: user:zhangsan, next: verify}, {node_id: verify, type: approval, handler: group:it_manager, next: end_close} ] }把这段拆分来看start 节点只做入口没有处理人approval 节点表示需要有人点通过或驳回task 节点表示一个执行动作。handler 是关键字段user:zhangsan 是指定单个用户group:it_service_desk 是指定某个角色或用户组。next 决定流转去向这段配置里每一步都只有一个出口所以是直线流程。节点参数通常涉及五个核心字段参数取值说明node_id英文字符串节点唯一标识路由引用typestart / approval / task / end决定节点行为和是否能驳回handleruser:xxx / group:xxx处理人建议优先用 groupnext节点 id 或数组单出口写字符串多出口写数组配合条件condition表达式多出口时判断走哪个分支多出口的条件路由会写成数组例如 verify 节点后面既有 end_close 也有 back_to_repair引擎根据表单字段或者审批结果选择分支。理解这个模型后配置界面里那些下一节点处理人就不是孤立的表单而是这个状态机的一小段映射。2.3 权限模型Casbin 控制谁能看到什么另一个容易忽略的点是权限。ferry 体系内一般用 Casbin 的 RBAC 模型规则存在数据库表里典型的 p 和 g 两类策略关系如下。表类型规则写法含义p策略p, alice, /api/v1/workflow, GET允许 alice 读取流程接口g角色继承g, alice, it_adminalice 属于 it_admin 角色工单列表的可见性除了走 Casbin还会在 SQL 层加过滤普通用户只能看到自己创建的工单组内成员能看到本组单子管理员看全部。所以二次开发时不要只改前端路由做菜单隐藏真正的权限控制必须落到 API 的参数校验和查询条件里。这一节内容对应到后面就是部署时先初始化权限表再登录后台建角色、绑菜单最后才能分派工单。3. 从 v1.0.zip 部署 ferry 工单系统校验、解压、配置 MySQL 与启动排错3.1 先校验 zip 完整性避免 error read zip archive网上下载的 v1.0.zip 可能经过网盘转存、断点续传第一个动作不应该是双击解压而是校验。官方发布通常会附一个 SHA-256 校验值在 Linux 或 Git Bash 下执行三件套。sha256sum ferry工单系统-v1.0.zip unzip -t ferry工单系统-v1.0.zip zipinfo -v ferry工单系统-v1.0.zip | head -40sha256sum 把本地文件的哈希和发布页的校验值比对能排除下载不完整或被替换的可能。unzip -t 是测试模式会逐个文件检查 CRC。如果看到 error read zip archive 或 could not find EOCDEnd of Central Directory这类报错说明压缩包尾部目录缺失本质是文件没下完或者被第三方工具改过结构。常见处理方式重新下载、换用支持断点续传的下载器、检查磁盘剩余空间。还有个小坑有人在拿到 zip 后会用压缩软件直接改包里的文件再保存这种操作会把原 zip 的中央目录搞坏后续部署时出现 EOCD 错误。正确的做法是先解压到临时目录改完重新打包并重新生成 sha256。如果下载下来的 zip 带打开密码比如企业内部分发时用了加密压缩流程应该是向分发方确认口令后用 7-Zip 或 unzip 正常解压而不是去搜zip密码移除并跑爆破工具。密码移除类操作只适用于自己遗忘密码且拥有合法副本的场景用在工作环境里可能引来合规风险。3.2 准备 MySQL 数据库和 config.ymlv1.0.zip 解压后一般会有编译好的二进制、web 静态目录、sql 目录和 config.yml也可能只有源码。先把数据库准备好常见初始化语句如下。mysql -uroot -p -e CREATE DATABASE ferry DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; mysql -uroot -p -e CREATE USER ferry% IDENTIFIED BY ChangeMe_2024; mysql -uroot -p -e GRANT ALL PRIVILEGES ON ferry.* TO ferry%;使用 utf8mb4 是为了让备注、标题里的 emoji 不变成乱码。接着打开 config.yml核心配置项如下。app: name: ferry port: 8080 # 对外服务端口 run_mode: release # debug 会打印大量 SQL 日志 database: host: 127.0.0.1 port: 3306 user: ferry password: ChangeMe_2024 dbname: ferry max_idle_conns: 10 max_open_conns: 100参数说明run_mode 在首次联调时可以设 debug正式跑再切 releasemax_open_conns 不要盲目调大工单系统并发不高100 足够过大反而让 MySQL 线程切换变慢。GORM 启动时会自动按 model 建表或迁移字段所以不需要手工执行全部 sql 文件。3.3 源码包处理从 GitHub 的 zip 包怎样装到能跑如果你的 v1.0.zip 是源码包而不是已经编译好的产物会遇到一个常见场景后端能编译但前端 dist 目录是空的。GitHub 上直接下载的 zip 包往往不带 node_modules也不会把构建后的静态文件打进压缩包。此时先按顺序执行。# 后端依赖Go 1.18 go mod tidy go build -o ferry main.go # 前端构建Node 14 cd web npm install npm run build cd ..npm install 期间出现 node-sass 类的报错通常是 Node 版本太新或网络源问题可以改用 nvm 切到项目要求的 Node 大版本再把 registry 换成国内镜像。前后端构建完成后把 web 的 dist 目录放到 backend 静态文件目录再启动后端就能访问管理界面。3.4 启动并确认日志启动命令和检查项如下。./ferry -c config.yml ferry.log 21 sleep 3 tail -50 ferry.log curl http://127.0.0.1:8080/healthz第一次启动时日志里会打印数据库迁移结果、监听端口并提示初始化管理员账户。此时如果 curl /healthz 返回 200或对应 JSON说明服务起来了。第一次启动后必须立刻登录后台把安装向导生成的默认密码改掉再关闭 debug 模式。否则你的工单系统等于裸奔在内网。常见的启动失败原因有三类按日志关键字定位很快。现象日志关键字排错方向连不上数据库dial tcp 127.0.0.1:3306 超时检查 MySQL 远程权限、端口、密码转义端口被占bind: address already in use杀旧进程或改 app.port前端白屏无静态资源请求确认 dist 路径和接口前缀把这三项按日志逐个排除部署基本就能通过。4. 配置 ferry 工单系统的第一个流程工单类型、节点路由与接口验证4.1 建工单类型和表单字段部署完成后下一个需求通常是把服务器报修这类业务固化成流程。后台界面的惯例顺序是先在工单类型里建一个类型再在表单设计里添加字段字段类型包括单行文本、多行文本、数字、日期、下拉选择以及对当前登录用户只读的申请人和所属部门字段。建类型时要注意一点字段建好后再删改会牵涉历史工单的数据结构运营期尽量只增不改。如果需要批量初始化可以直接往对应字典表插入数据但绕过后台容易漏掉缓存刷新。我一般不会手动写 SQL 来建类型除非是给测试环境做脚本化准备。4.2 配置审批节点处理人用角色而不是个人以一次机房故障报修为例子流程设计成四步申请 - 服务台分派 - 工程师处理 - 主管验证。在流程配置界面填入节点时节点 JSON 对应如下。{ workflow_name: 机房故障报修, nodes: [ {node_id: apply, type: start, next: dispatch}, {node_id: dispatch, type: approval, handler: group:it_service_desk, next: handle}, {node_id: handle, type: task, handler: group:engineer, next: verify}, {node_id: verify, type: approval, handler: group:it_manager, next: [{target: close, condition: verify_result pass}, {target: handle, condition: verify_result fail}]} ] }这段比第 2 章的示例多了一个条件路由。verify 节点后面有两个出口引擎在审批动作发生时读取表单里的 verify_result 字段等于 pass 就走 close等于 fail 就退回 handle。处理人全部用 group 而不是 user是因为工程师离职、转岗是常态改角色成员比改流程定义更安全这是配置环节最容易踩的坑。4.3 用 curl 走一遍工单接口验证配置界面点一遍只能验证人肉流程想确认接口权限和流程引擎都正常我用 curl 跑冒烟测试。以下以默认的路由前缀 /api/v1 为例实际安装版本以登录后 F12 看到的地址为准。# 登录拿 token curl -s -X POST http://127.0.0.1:8080/api/v1/login \ -H Content-Type: application/json \ -d {username:alice,password:ChangeMe_2024} \ | tee login.json # 从 login.json 里提取 token创建工单 TOKEN$(python3 -c import json;print(json.load(open(login.json))[data][token])) curl -s -X POST http://127.0.0.1:8080/api/v1/tickets \ -H Authorization: Bearer $TOKEN \ -H Content-Type: application/json \ -d {type:机房故障报修,title:机房空调告警,fields:{room:A-302}} # 查未处理列表 curl -s http://127.0.0.1:8080/api/v1/tickets?statusopen \ -H Authorization: Bearer $TOKEN逻辑说明第一步登录拿到 JWT第二步把工单类型和业务字段按 JSON 提交第三步验证列表接口能否按当前人的权限返回数据。如果第二步返回 403 而不是 200说明当前账号的角色没有建单权限回去检查 Casbin 策略如果返回 200 但列表看不到问题多半在数据权限的部门过滤 SQL而不在流程配置。4.4 节点配置的三个习惯与常见问题对照做流程配置时我习惯遵循三条规则。第一每个审批节点都设置一个默认处理人组避免条件分支全部落空时工单卡死。第二验收前把驳回路径走一遍很多隐藏 bug 出在驳回时字段被清空。第三节点名称和工单状态别混用一套枚举节点是引擎概念工单状态是业务视角二者通过路由关联混在一起会让后来接手的人看不懂。下面是几类高频问题的对照。现象通常原因建议处理工单卡在某节点没人处理处理人写成 user人员已离职改用 group 并维护成员驳回后字段值丢失流程引擎只路由不保存单据快照重新进入节点时回填原值多出口分支全部不匹配next 条件没有默认值加一个兜底节点这三条不是系统功能而是配置规范。工单系统真正难维护的地方多半不是代码而是流程定义里混乱的命名和过度设计的状态数。5. 升级 v1.0.zip 前必做的三件事文件清单对比、二进制信息核对与冒烟脚本5.1 用 unzip -Z1 快速对比两个版本的差异拿到 v1.0.zip 之后手上有旧版本的话先用 unzip -Z1 把两个压缩包的文件清单导出再 diff 一眼看出这次发布动了哪些目录。unzip -Z1 ferry工单系统-v1.0.zip new.files unzip -Z1 ferry工单系统-v0.9.zip old.files diff old.files new.files如果 diff 结果只有 web/dist 下的文件变化说明升级是纯前端替换反之若是主二进制变大几十 MB说明后端依赖或运行时版本有变升级要重点回归接口。5.2 核对二进制构建信息源码编译的二进制可以用 go version -m 看模块依赖这一条信息量很大。go version -m ferry | head -30输出里能看到 Go 版本、包路径、依赖模块的版本号。把它和发布说明比对能确认 v1.0.zip 确实出自同一份代码也方便之后复现编译环境。5.3 写一个 30 行的冒烟脚本再上线把第 4 章的 curl 流程落成脚本作为每次升级后执行一次的检查项。脚本内容不复杂登录、建单、查列表、登出。#!/bin/bash set -euo pipefail BASEhttp://127.0.0.1:8080/api/v1 TOKEN$(curl -s -X POST $BASE/login -H Content-Type: application/json \ -d {username:smoketest,password:ChangeMe_2024} \ | python3 -c import sys,json;print(json.load(sys.stdin)[data][token])) curl -s -X POST $BASE/tickets -H Authorization: Bearer $TOKEN \ -H Content-Type: application/json \ -d {type:机房故障报修,title:smoke test} /dev/null curl -s $BASE/tickets?statusopen -H Authorization: Bearer $TOKEN \ | python3 -c import sys,json; djson.load(sys.stdin); assert len(d[data])0 echo smoke ok脚本退出码为 0 才算通过配合 CI 的定时任务就是最简单的可用性监控。这套方法比盯着界面点十遍可靠也比引入压测工具更贴近日常运维的真实需求。本文还有配套的精品资源点击获取
