一、项目速览

入门 · 1 分钟版

Smart-API 是一个基于 Go 语言（Gin 框架）开发的开源工单系统，前端使用 Vue.js + Element UI，前后端分离。它不只是一个“工单列表工具”，而是自定义开放式工单平台——你可以根据业务需求，动态设计工单表单、审批流程、权限规则，甚至接入 LDAP 和第三方消息通知（飞书、钉钉等）。项目自带 RBAC 权限、多租户隔离、代码生成、图表统计等功能，适合需要灵活工单管理的团队。

它解决什么问题？ 传统工单系统（如 Jira、Zendesk）往往功能固定、定制成本高，Smart-API 让有一定开发能力的运维或开发人员，通过后台配置快速搭建吻合自家流程的工单体系。

谁最该用？ 中小型团队、DevOps 团队、企业内部审批流程负责人，以及希望用工单串联“申请→审批→执行→反馈”全流程的后端/全栈工程师。

作者视角：如果你是 Go 后端开发者，这套系统是很好的实战项目——它几乎涵盖了企业级应用的常用组件（ORM、认证、RBAC、WebSocket、配置管理），代码可读性也不错，适合学习或二次开发。

二、核心功能与架构

进阶 · 推荐细读

从“配置工单”到“自动流转”

Smart-API 的核心能力不在“处理工单”，而在“自定义一切”。它把工单的生命周期分成四层：

1. 工单类型：你可以为不同业务场景（如服务器申请、请假、故障报修）创建独立的工单分类。
2. 自定义表单：通过拖拽式表单构建器，无需写代码即可为每种工单类型设计字段（输入框、下拉、日期、文件上传等）。
3. 审批流程：每个工单类型可以绑定一条审批链，支持多人会签、或签、条件分支（例如：金额 > 5000 需要总监审批）。
4. 执行与追踪：工单提交后，系统通过 WebSocket 实时推送进度，任务完成后可评分、留言。

技术架构快照

内置模块精简版

• 用户/部门/角色管理：从组织架构到权限粒度，支持数据范围控制。
• 任务中心：分配、追踪、催办（支持飞书/钉钉通知）。
• 代码生成器：根据数据库表生成前端 CRUD 页面（零代码快速搭建业务模块）。
• 服务监控：查看服务器 CPU、内存、磁盘。
• 定时任务：可调用 API 或函数执行自动化操作。

这些模块并非孤立存在：工单流转过程中，会自动记录操作日志、调用定时任务、触发通知。这种模块间的联动才是系统的真正价值。

作者视角：实际使用中最容易忽略的是第三方通知配置——它依赖 LDAP 账号绑定，如果你的组织没有 LDAP，需要先搭建或修改代码。不过 README 提供了在线演示，你可以先体验再看要不要投入。

图：审批流程可视化配置界面

三、动手实践

入门

本节带你从零启动 smart-api，创建一个临时工单类型并提交测试。假设你已有 Go 1.18+、MySQL 5.7+、Git 环境。

环境准备

# 1. 克隆项目（后端 + 前端建议分别克隆）
git clone https://github.com/sunwenbo/smart-api.git
cd smart-api

# 2. 安装 Go 依赖
go mod tidy

# 3. 复制配置文件
cp config/settings.full.yml config/settings.yml

编辑 config/settings.yml，修改数据库连接（不要忘记先手动创建空数据库）：

# ... 找到 settings.database 部分
database:
  driver: mysql
  source: root:your_password@tcp(127.0.0.1:3306)/smart_api?charset=utf8mb4&parseTime=True&loc=Local

编译与初始化

# 4. 编译（Windows 下生成 smart-api.exe）
go build -o smart-api main.go

# 5. 初始化数据库（会创建表及初始数据）
./smart-api migrate -c config/settings.yml

# 6. 启动服务（默认 0.0.0.0:8888）
./smart-api server -c config/settings.yml

启动后访问 http://localhost:8888/swagger/index.html 可看到 API 文档。

最小可运行示例：创建第一个工单类型

打开浏览器登录演示环境（或自己运行后登录 admin/123456）：

http://localhost:8888/dashboard   # 前端需另外启动 smart-ui，见后文

由于本文主要讲后端，前端启动需要 npm 环境：

git clone https://github.com/sunwenbo/smart-ui.git
cd smart-ui
npm install
npm run dev

之后访问 http://localhost:8080，使用 admin/123456 登录。

创建工单类型：
1. 进入“流程中心”→“工单类型”→点击“新增”。
2. 填写名称（例如“服务器资源申请”），保存。
3. 进入“自定义表单”→新建表单→拖拽一个“输入框”和一个“下拉框”→保存并关联到该工单类型。
4. 进入“审批流程”→新建流程→选择“服务器资源申请”→添加审批节点（如指定审批人为 admin）→发布。
5. 回到“工单中心”→“工单申请”→选择刚创建的工单类型→填写表单→提交。

刷新“工单管理”页面即可看到新工单，状态为“待审批”。

常见踩坑

• 数据库连接失败：最常见错误是 MySQL 时区参数 loc=Local 导致连接超时。可以改成 loc=Asia%2FShanghai 或删除该参数。
• migrate 命令找不到表：确保先手动创建数据库，且用户有 CREATE 权限。
• 前端页面白屏：检查 smart-ui/.env 中的 VUE_APP_BASE_API 是否指向后端地址（默认 http://localhost:8888）。

图：提交工单的交互页面

四、进阶玩法

深入 · 老手可选

自定义审批流程：条件分支

Smart-API 的审批节点支持条件表达式，基于工单表单字段的值动态决定下一步。下面是配置文件里可能用到的思路（实际通过 UI 配置，无需写代码）：

{
  "nodes": [
    {
      "name": "主管审批",
      "assignees": ["manager"],
      "type": "approval"
    },
    {
      "name": "总监审批",
      "condition": "{\"field\":\"amount\",\"operator\":\">\",\"value\":5000}",
      "assignees": ["director"],
      "type": "approval"
    }
  ]
}

注意：这是流程引擎的底层数据结构，在 UI 界面上你只需勾选条件即可。如果你需要二次开发，可以扩展 Casbin 的适配器或自定义流程解析器。

多租户分库隔离

系统默认支持多租户，每个租户使用独立的数据库（按库分离）。配置方式：

1. 在 config/settings.yml 的 database 下添加 tenant_db 列表：

tenant:
  enable: true
  databases:
    - tenant1: root:pwd1@tcp(...)/smart_tenant1
    - tenant2: root:pwd2@tcp(...)/smart_tenant2

2. 初始化时，migrate 命令会为每个租户库创建表。

3. 用户登录时会根据租户标识（如子域名）动态切换数据库连接。

使用场景：SaaS 服务商为不同客户隔离数据，或大公司内部不同部门独立工单数据。

接入飞书/钉钉通知

在“系统配置”→“消息配置”中填写 Webhook URL 和密钥，并确保 LDAP 用户信息中已绑定第三方 ID。这样当工单被催办或状态变更时，系统会自动推送消息。

作者视角：我实际测试时发现飞书机器人需要 IP 白名单，且消息模板不能包含特殊字符。建议先用官方演示站（http://117.50.46.228/login）体验全部流程再本地部署。

图：工单统计仪表盘

五、判断与建议

进阶 · 推荐细读

什么场景下应该选 Smart-API？

• 你需要一个不绑死流程的工单系统：例如审批链需要随业务动态调整，或者工单表单字段经常变化。
• 团队有 Go 或 Vue 开发能力：系统提供代码生成和表单构建，但深度定制仍需要改代码。
• 希望集成 LDAP 和第三方通知：企业内部已经使用 AD 或飞书/钉钉。
• 预算紧张，追求开源替代：对比商业产品（如 Zendesk、锦亦），Smart-API 是免费且可自行部署的。

什么场景下不该选？

• 零编程基础的非技术团队：部署和配置需要一定的技术门槛，并非纯 SaaS 即开即用。
• 需要原生移动端 App：系统目前只有 Web 端，移动端需自建或通过响应式浏览。
• 超大规模并发工单：虽然 Go 性能优秀，但多租户按库分离的模式可能增加运维复杂度。建议每租户低于 10 万工单/天。

一句话结论：Smart-API 是“可定制的工单骨架”——适合愿意花时间搭建流程的开发团队，不适合“拿来就用”的管理者。如果你属于前者，它值得你投入一个周末。

延伸阅读：官方在线演示 http://117.50.46.228/login 可快速体验全部功能，建议先玩再装。

项目信息

参考链接

• GitHub 仓库
• 项目主页