别再造轮子了:一套自带 AI 助手和 RAG 知识库的 Laravel 13 企业级套件

AI摘要
【知识分享】文章介绍开源套件 Ai Forge,基于 Laravel 13 与 Vue 3 构建企业级后台底座,涵盖双 Guard 认证、按钮级 RBAC、钱包账本、审核体系、审计日志等模块。重点说明 AI 助手接入业务工具的权限三层防线、RAG 知识库与多模态模型接入、MCP Server 封装 70 个 C 端工具,以及 1725 个测试用例等工程化实践,并给出演示环境与快速开始方式。

前言

做后台系统这些年,有个事我一直挺烦的。每开一个新项目,都要把同一批东西从头写一遍:登录注册、双端认证、角色权限、菜单管理、操作日志、Excel 导出……等地基打完,一两周过去了,真正要写的业务还一行没动。今年这份清单又变长了,AI 助手、工具调用、知识库检索,客户张嘴就问能不能加一个。

我不想再重写第五遍了,就把这些收口做成了一个套件,叫 Ai Forge。这篇文章介绍下它做了什么、怎么设计的,演示环境也搭好了,地址在文末。

一、Ai Forge 是什么

一个套件,三个部分。

组成 说明
Ai Forge API 后端服务,Laravel 13 + PHP 8.4,DDD 分层架构,RESTful 规范
Ai Forge Admin 管理后台前端,Vue 3 + TypeScript + Element Plus,按钮级权限、暗黑模式、主题切换自带
Ai Forge 文档站 VitePress,产品文档、接口文档、技术方案都在里面

定位一句话:企业级后台的「开箱即用」。不是那种只给了个登录页的玩具骨架,是把后台系统该有的模块全部做完、做全。

技术栈速览:

分层 技术
框架 Laravel 13.x / PHP 8.4
认证 / 权限 Sanctum 4 + spatie/laravel-permission 8
队列 / 监控 Horizon 5、Pulse、Telescope
实时通信 Reverb + Echo(WebSocket)
AI laravel/ai + larva/laravel-ai-volc(火山方舟驱动)
AI 客户端接入 laravel/mcp(MCP Server)
搜索 Scout 11 + 可选 Meilisearch
测试 PHPUnit 12(属性语法)+ Pint

二、业务模块做到什么程度

先说结论:一般 CRUD 骨架不做的东西,它也做完了。

后台管理端:

  • 认证与权限:管理员和前台用户双 Guard 隔离,RBAC 精确到按钮级权限点,菜单和角色可视化配置

  • 钱包:真实货币余额账本,充值下单、提现审核打款、超时订单自动关闭、流水导出,全链路闭环

  • 审核体系:评论、举报、反馈、实名认证四类全流程,支持隐藏评论、删除评论、冻结用户等联动处置

  • 运营工具:用户分群(手动 + 规则,每日增量同步,批量打标超 1000 自动转异步)、任务中心、邀请关系与统计、PV/UV 访问记录

  • 审计:操作日志、调度日志、登录历史三类全量记录;导出走同步/异步双通道,大数据量进队列生成后站内信推下载链接

如果你的下一个项目是 APP,这套骨架基本就是现成后端。C 端要用的基础接口全都齐了:

能力域 已具备的接口
账户 注册登录(手机/邮箱/微信/Apple)、Token 刷新、账户注销
用户中心 资料、头像(自动转 WebP)、联系方式、密码、VIP、积分/金币流水、社交账号、登录历史、实名认证
资产 钱包概览、流水、充值下单与订单查询、提现申请
增长与留存 任务中心(进度查询、领奖)、邀请关系与统计、访问记录(PV/UV、最近浏览)
内容与互动 多态点赞/收藏/关注/评论、Banner、公告、协议
服务与合规 通知、收货地址、反馈提交、举报提交

拿到手不需要再搭架子,直接写你的业务就行。

三、AI 助手,不是摆个聊天框

很多后台接 AI,就是在角落放一个叫「智能助手」的聊天框,问它什么都答非所问——因为它根本碰不到你的业务。

Ai Forge 的做法是把 AI 接进业务里。内置 50 多个业务工具,查钱包流水、审提现、审实名认证、发站内通知、查队列失败任务、同步用户分群,AI 都能直接调。对话是 SSE 流式的,思考过程和文本输出分开推。

Agent 定义长这样,属性即配置:

#[MaxSteps(12)]
#[Temperature(0.3)]
#[Timeout(300)]
class  Assistant  implements  Agent, Conversational, HasTools
{
use  Promptable, RemembersConversations;
// ...
}

真正花心思的地方在权限。AI 能调业务接口,越权怎么办?这里做了三层防线:

  1. 入口:控制器中间件 permission:chat.use,没权限的管理员根本进不来
  2. 过滤:Agent 装配工具时,按当前管理员的角色权限动态裁剪,没权限的工具不暴露给模型
  3. 兜底:工具 handle() 执行前再校验一次,模型被诱导也越不过去

落地靠一个契约加一个 trait,工具声明自己需要的权限点即可:

interface  RequiresPermission
{
/**
* 执行该工具所需的权限点(任一满足即可);返回 null 或空数组表示不限制
*/
public  function  permission():  string|array|null;

/**
* 注入当前操作的管理员(由 Agent 装配工具时调用)
*/
public  function  forAdmin(?Admin  $admin):  static;

}
protected  function  authorizeAdmin():  ?string
{

$permission  =  $this->permission();
if ($permission  ===  null  ||  $permission  === []) {
return  null;
}

if (!  $this->admin  instanceof  Admin) {
return  '无法识别当前操作者身份,出于安全考虑该操作已被拒绝。';
}

if (!  $this->admin->canAny((array) $permission)) {
return  '您当前的角色没有执行此操作所需的权限,操作已被拒绝。如需开通,请联系超级管理员。';
}

return  null;
}

这套防线是给 AI 设计的,但防越权这件事,对人和对模型是同一套逻辑。

另外,调整余额、重置密码这类敏感操作,AI 发起之后不会直接执行,会挂起等管理员点「批准」才继续。

四、RAG 知识库与多模态

RAG 知识库是标配。文档保存后自动分块、向量化、建索引,全程走队列。检索默认在库内算余弦相似度,零外部依赖;数据量大了一行配置切到 Meilisearch。把微信公众号接进来,粉丝发来的文本消息会由智能客服基于知识库自动回复,不用人盯后台。

模型接入走火山方舟,一个 provider 包圆五种能力:

'providers'  => [
'volc'  => [
'driver'  =>  'volc', // larva/laravel-ai-volc 注册,在 OpenAI 兼容协议上扩展了 TTS / 视频生成
'models'  => [
'text'  => ['default'  =>  env('VOLC_TEXT_MODEL', 'doubao-seed-2-1-lite-260915')],
'embeddings'  => ['default'  =>  env('VOLC_EMBEDDINGS_MODEL', 'doubao-embedding-vision-251215')],
'audio'  => ['default'  =>  env('VOLC_AUDIO_MODEL', 'doubao-seed-tts-2.0')], // TTS
'image'  => ['default'  =>  env('VOLC_IMAGE_MODEL', 'doubao-seedream-5-0-pro-260628')], // Seedream
'video'  => ['default'  =>  env('VOLC_VIDEO_MODEL', 'doubao-seedance-2-5-260628')], // Seedance,异步任务
],
],
],

运营侧的生产场景也落了地:公告和 Banner 的文案让 AI 起草,Banner 配图直接让 Seedream 画,评论被敏感词命中后让 AI 复核一遍语境,减少误杀。

五、MCP Server:C 端 API 直接变成 AI 客户端的工具

还有一个我个人挺喜欢的点。前台 API 基于 laravel/mcp 封装成了 MCP Server,进程内直调业务层,没有 HTTP 转发开销。

  • 端点 POST /mcp/v1(JSON-RPC 2.0),认证走 Sanctum 个人访问令牌
  • 已封装 70 个工具(35 只读 + 35 写),覆盖资料、钱包、任务、内容互动、地址、反馈举报、通知等域
  • 列表类工具分页约定统一(page / per_page,返回 items + pagination)
  • 全部工具带 readOnlyHint 与 idempotentHint,AI 客户端可安全缓存;写操作里发布类内容自动过敏感词,点赞收藏关注内置防重复
  • 调试直接 php artisan mcp:inspector mcp/v1

也就是说,你的 APP 数据能力,天然就能被 Cursor、Claude 这类 AI 客户端直接调用。

六、工程化,不是口号

  • 测试不是摆设:首个正式版全量跑通 1725 个用例、4507 条断言,控制器、模型、AI 工具都有覆盖
  • 监控三件套 Pulse、Horizon、Telescope 开箱自带
  • 定时任务从代码迁进了数据库,后台可配 Cron、可手动执行,执行日志自动落
  • 接口文档是 Apifox 在线版,前台后台分开发布,支持在线调试
  • 代码风格 Pint 统一把守,提交信息走 Conventional Commits

这些细节看着小,团队一上人就知道值钱了。

快速开始

composer  run  setup

一条命令完成:装依赖、复制 .env、生成密钥、迁移、建存储链接、编译前端资源。默认管理员账号 admin / 12345678。

总结

AI 把「写代码」这件事变得越来越快之后,我反而觉得底座变贵了。页面可以让 AI 糊,业务逻辑可以让 AI 凑,但权限、审计、钱和数据的一致性,恰恰是骨架最该替你做对的部分。这些地方做错了,上面长出来的东西越快越危险。

Ai Forge 想做的,就是把这些「不能错」的部分,先做对。

相关链接:

  • 官网与文档站:www.aiforge.cn

  • 演示后台:admin-demo.aiforge.cn (账号 admin,密码 12345678)

  • Apifox 在线接口文档入口在官网「附录」一页,前台后台都有

如果你的下一个项目不想从登录页开始写,可以试试。

本作品采用《CC 协议》,转载必须注明作者和本文链接
《L03 构架 API 服务器》
你将学到如 RESTFul 设计风格、PostMan 的使用、OAuth 流程,JWT 概念及使用 和 API 开发相关的进阶知识。
《L02 从零构建论坛系统》
以构建论坛项目 LaraBBS 为线索,展开对 Laravel 框架的全面学习。应用程序架构思路贴近 Laravel 框架的设计哲学。
讨论数量: 2
Dcatplus-杨光

可以的,我也借鉴一下。

2周前 评论

讨论应以学习和精进为目的。请勿发布不友善或者负能量的内容,与人为善,比聪明更重要!