别再造轮子了:一套自带 AI 助手和 RAG 知识库的 Laravel 13 企业级套件
前言
做后台系统这些年,有个事我一直挺烦的。每开一个新项目,都要把同一批东西从头写一遍:登录注册、双端认证、角色权限、菜单管理、操作日志、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 能调业务接口,越权怎么办?这里做了三层防线:
- 入口:控制器中间件
permission:chat.use,没权限的管理员根本进不来 - 过滤:Agent 装配工具时,按当前管理员的角色权限动态裁剪,没权限的工具不暴露给模型
- 兜底:工具
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 协议》,转载必须注明作者和本文链接
关于 LearnKu
推荐文章: