Laravel 12 后端开发骨架 + 配套新手教程
从零开始，一步步搭建一个带代码生成器、JWT 登录认证和完整系统管理的 Laravel 后端——并且每一步都能真机跑通，不是纸上谈兵。
这个仓库有两部分：
-
一个可运行的 Laravel 12 骨架项目（在
engine/目录）
已接入 moo-scaffold 代码生成器 + JWT 认证 + moo-system 系统管理模块，并带一个 moo-feedback 匿名提交 / 后台受理示例，是个「开箱即用」的起点。 -
一套完整的新手教程（在
docs/目录，带截图）
从空目录出发，教你一步步搭出这个骨架。每一步都经过真机测试，跟着做就能跑起来。
- 新手：第一次用 Laravel 搭后端，不知道从哪开始
- 想快速上手代码生成的：看过 moo-scaffold 文档，但希望有个完整示例项目
- 需要系统管理功能的：不想从头写部门 / 人员 / 权限，直接用现成模块
跟完教程（主线 7 章 + 部署指引 + 增量开发 + 云端进阶），你会掌握：
- Laravel 12 基础搭建（连 MariaDB、建库、配 .env）
- 运行时监控采集与云端推送（moo-monitor-laravel + moo-scaffold-cloud，含 AI 辅助处理）
- moo-scaffold 代码生成器使用（YAML → Model / Controller / Migration）
- JWT 登录认证（自建用户，零付费依赖，含生产加固）
- 动作级授权（ACL，细到每个接口）
- 双守卫隔离（后台 admin + 移动端 user）
- 接入 moo-system 系统管理模块（部门 / 人员 / 角色）
- 用 moo-feedback 演练“匿名提交 + 独立认证的后台受理”
- 部署上线（nginx + supervisor + Redis）
- 日常增量开发（改表 / 加接口 / 同步 ACL）
教程共 14 章：前 6 章讲零商业依赖的基础能力，第 7 章接入 moo-system，第 8~11 章覆盖部署、增量开发、监控与身份契约，第 12 章提供正式的新项目起手入口，第 13 章用 moo-feedback 演示扩展包接入与独立安全组，第 14 章讲扩展包 resolver 与 Host 胶水组合。
克隆后运行初始化器。它会先准备 SQLite，再安装依赖、生成密钥、移除 Food 演示、重建 ACL、发布 scaffold 静态资源、创建开发账号并跑完整验证：
git clone git@gitee.com:charsen/moo-engine-skeleton.git orders
cd orders
./init-project \
--name=acme/orders \
--app-name="Orders" \
--author="你的名字" \
--app-url=http://orders.test \
--scaffold-user=developer \
--fresh-git默认输出是保留移动端 /app 的完整 API 项目；官网后端使用 --profile=website，会删除 User/JWT 移动端切片并保留公开 /api 生成区。需要保留 Food 教学样例时加 --keep-demo，需要连教程一起保留时加 --keep-tutorial。完整参数见 ./init-project --help。
从空目录开始，一步步跟着 docs/ 里的教程做：
# 第 1 章：安装 Laravel 12
composer create-project "laravel/laravel:^12.0" engine
# 第 2 章：接入 moo-scaffold 代码生成器
# （开源包；按正式版本约束从 Packagist 安装）
# 第 3~6 章：JWT 认证 + ACL + 双守卫
# 第 7 章：接入 moo-system（可选）
# 第 8 章：部署上线
# 第 9 章：增量开发演练教程入口：docs/README.md（带「踩过的坑」速查表）
推荐用网页引导器跟做（分步模式 + 进度记忆）：
cd docs
php -S 127.0.0.1:9999
# 浏览器打开 http://127.0.0.1:9999本骨架依赖作者的另外几个包。moo-scaffold、moo-monitor-laravel 是开源包，
目标通过 Packagist 直接安装；私有 moo-system 及其上传基础依赖 moo-upload 必须通过 Composer
授权仓库接入。正式使用不要求 clone 到同级目录；本仓本地联调可用 path repository。
访问前提：
# 克隆本仓库
git clone git@gitee.com:charsen/moo-engine-skeleton.git
# 第 7 章需要 moo-system 与 moo-upload 两个私有仓库的访问权。| 包 | 定位 | 是否必装 | 说明 |
|---|---|---|---|
moo-scaffold |
开源（MIT，发布到 Packagist） | 必装 | 代码生成器 + 开发后台（教程第 2 章接入） |
moo-system |
进阶 / 私有包 | 可选 | 系统管理模块（部门 / 人员 / 角色，教程第 7 章接入） |
moo-upload |
私有基础包 | 随 moo-system 接入 | purpose 约束上传、引用消费与清理；Host 配独立安全组 |
moo-monitor-laravel |
开源（MIT） | 必装 | 监控采集 SDK（教程第 1.7 节显式接入） |
moo-feedback |
开源（MIT，发布到 Packagist） | 示例内置 | 意见反馈扩展包；第 13 章演示公开提交与独立后台认证组 |
为什么还要配置 VCS 仓库？
开源包发布到 Packagist 且目标版本可解析后，不需要额外 repositories 配置。
moo-system 与 moo-upload 都不在 Packagist 公开分发，接入第 7 章时需要在
composer.json 的 repositories 分别声明两个授权仓库；Composer 不继承依赖包自己的仓库配置。
本仓库口径：开源包统一使用正式版本约束安装；
moo-system与moo-upload使用授权私有源。
| 软件 | 版本（实测） | 说明 |
|---|---|---|
| PHP | 8.2+ | Laravel 12 要求 ^8.2；当前 lock 已按 PHP 8.2 可安装版本解析 |
| Composer | 2.9 | |
| Node | 26 | 可选；只有传 --with-frontend 或自行构建 Vite 资源时需要 |
| npm | 11 | 同上 |
| 数据库 | SQLite / MariaDB 12 / MySQL 8 | 起手默认 SQLite 零依赖；投产前切 MySQL/MariaDB |
教程共 14 章：第 1
7 章搭建主线，第 811 章讲部署、增量开发、云端监控和操作人身份契约；第 12 章收敛新项目起手流程，第 13 章给出 moo-feedback 扩展包实例，第 14 章说明 resolver 与 Host 胶水组合。
🧭 两条路，按需选：
- 从骨架直接起手（本仓库就是起点）——
clone → 改名 → 配 env → 直接跑，几分钟起一个干净新项目。 下面「方式 A」是它的最短版；完整 checklist（改名/密钥/双 composer/外部接线、冒烟五命令、教学样例 Food 去留）见 第 12 章 从骨架起手新项目。- 跟教程从零搭——从空目录一步步搭出这套骨架，理解每一块怎么来的（下面「方式 B」/ 第 1~11 章，推荐新手）。
方式 A：初始化成自己的项目（推荐）：
⚠️ 前置： ① 需 PHP 8.2+； ② 需配好 moo-system / moo-upload 的 Gitee SSH 仓库访问权（私有包）； ③ 仓库最终态已接入 moo-system / moo-upload（第 7 章）——没有它们的授权时composer install会失败，请走方式 B 从第 1 章跟做，或联系作者获取授权； ④ 初始化默认使用 SQLite；生产通常切 MySQL/MariaDB 和 Redis。单机低写入项目若明确继续使用 SQLite，按SQLITE-DEPLOYMENT-TEMPLATE.md把数据库放到代码目录外并建立备份。
git clone git@gitee.com:charsen/moo-engine-skeleton.git orders
cd orders
./init-project \
--name=acme/orders \
--app-name="Orders" \
--author="你的名字" \
--app-url=http://orders.test \
--scaffold-user=developer \
--fresh-git初始化器结束前会执行 moo-system check、全量测试、迁移状态、路由清单和两份 Composer 校验；任一步失败都会非零退出。默认移除 Food 和教程历史，生成项目自己的 README、CLAUDE 与首个 Git 提交。
纯官网后端再加 --profile=website；该 profile 不包含移动端 User 模型、/app 路由或 user guard。受控私有仓如果确认要同步 Scaffold 调试账号的 bcrypt 文件，再显式加 --track-scaffold-accounts。
💡 关于
php artisan test：phpunit.xml 把测试数据库定为 sqlite:memory:。 完全不碰本机 MariaDB——所以 MariaDB 没装/没建库测试照样全绿，反过来测试通过也 不代表.env的数据库配好了，两者别互相误判。仓库还自带 GitHub Actions CI （.github/workflows/tests.yml），push 后自动跑同一套测试。
方式 B：从 0 跟教程搭（推荐新手，带截图的完整教程见 docs/）：
# 1. 安装 Laravel 12 到 engine/ 子目录
composer create-project "laravel/laravel:^12.0" engine
cd engine
# 2. 建库（本机示例账号 root / 7777）
mysql -uroot -p7777 -h127.0.0.1 -e \
"CREATE DATABASE IF NOT EXISTS moo_engine_from_zero CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
# 3. 配 .env 的数据库（DB_CONNECTION=mysql / DB_DATABASE=moo_engine_from_zero / DB_USERNAME=root / DB_PASSWORD=7777）
# 4. 接入监控标准件 + moo-scaffold（完整讲解见 docs 第 1.7 / 2 章；moo-system 见第 7 章）
composer require "charsen/moo-monitor-laravel:^0.1"
composer require "charsen/moo-scaffold:^2.1.7" --with-all-dependencies
php artisan vendor:publish --provider="Mooeen\Scaffold\ScaffoldProvider" --tag=public --force # 发布 /scaffold 静态资源
# 5. 本地学习环境：迁移 + 演示 seed + 调试台账号（生产禁止运行该 DatabaseSeeder）
php artisan migrate --seed # 创建公开演示账号，仅供 local/testing
php artisan moo:account:add <用户名> --password=<密码> --role=admin # 没有它登不进 /scaffold
# 6. 启动（必须多 worker，原因见下方说明）
PHP_CLI_SERVER_WORKERS=4 php artisan serve --host=127.0.0.1 --port=8088 --no-reload💡 为什么必须多 worker：scaffold 的接口调试器是「代理」模式——它收到你的调试请求后， 会从服务内部再向同一个服务发一次真实 HTTP 请求。
php artisan serve默认单 worker、 一次只能处理一个请求：外层请求占着唯一的 worker 等内层请求，内层请求又排不上队——互相 等待即死锁。PHP_CLI_SERVER_WORKERS=4开多 worker 即可；换成 nginx + php-fpm、valet 等多进程环境天然没有这个问题，无需此变量。
启动后的入口（注意：「后台」没有独立网页，它是纯 API）：
- 应用首页：http://127.0.0.1:8088
- 代码生成 / 接口调试台：http://127.0.0.1:8088/scaffold（登录用
moo:account:add创建的账号） - 后台管理 API：
http://127.0.0.1:8088/api/admin（登录接口POST /api/admin/authenticate； 日常在/scaffold的接口调试器里带账号调它，不是打开网页登录） - 移动端 API：
http://127.0.0.1:8088/app
Laravel 应用放在 engine/（与作者其它项目的目录约定一致），仓库根目录是文档与工程配置：
moo-engine-skeleton/
├── README.md # 本文，仓库入口
├── HANDOFF.md # 换机/交接速查（Packagist + Moo 私有 VCS + 初始化清单）
├── overview.md # 立项说明
├── CLAUDE.md # AI 协作约定
├── .github/workflows/ # CI：GitHub Actions 自动跑 php artisan test
├── .vscode/ # 编辑器约定
├── docs/ # 从 0 开始的新手教程（含截图）
└── engine/ # ← Laravel 12 应用本体
（本机开发可能还有一个 CLAUDE.local.md，已被 gitignore，clone 不会带下来。）
推荐用网页引导器跟做（分步模式 + 准确恢复位置 + 代码一键复制 + 移动端章节抽屉，零依赖单文件）：
cd docs && php -S 127.0.0.1:9999，浏览器打开 http://127.0.0.1:9999仓库公开后可一键上线为网页版：Gitee 仓库 →「服务」→「Gitee Pages」→ 部署目录选
docs/→ 访问https://<你>.gitee.io/moo-engine-skeleton/（引导器全部用相对路径，子路径部署开箱即用）。
| 章节 | 内容 |
|---|---|
| 第 1 章 安装 Laravel 12 | 建项目、连 MariaDB、建库、真机访问 |
| 第 2 章 安装 moo-scaffold | 开源代码生成器接入、设计 foods 表、一键生成业务代码、两种方式调接口 |
| 第 3 章 JWT 登录认证（自建用户） | 零付费依赖：最简 User 实现 JWTSubject、双守卫、三中间件、登录全链路 |
| 第 4 章 JWT 加固与生产化 | 生产踩坑回灌：persistent_claims、黑名单宽限、滑动续期、CORS、限流、生产 composer、接口测试 |
| 第 5 章 给 Food 上 JWT 与 ACL | 动作级授权完整闭环：401→403→授权→200（User actions 最小实现） |
| 第 6 章 移动端分片与 user 守卫 | 守卫隔离、无宽限 token 轮换 |
| 第 7 章 安装 moo-system（进阶） | 完整系统管理：host 契约、主体切换 User→Personnel、角色授权、操作日志、调试器联调 |
| 第 8 章 部署上线（可选） | Composer / Packagist 部署、Redis、nginx、supervisor、清缓存坑 |
| 第 9 章 日常增量开发：改表与加接口 | 加字段（增量迁移）、「自动覆盖 vs 手动补」边界、moo:adder 自定义 action、ACL/文档/测试同步、专属 Resource 链式字段控制 |
| 第 10 章 云端监控进阶 | 聚合告警、AI 辅助处理、MCP 与多项目管理 |
| 第 11 章 操作人身份契约 | host 单点身份来源、共享 HasOperator、null 语义与扩展包接入 |
| 第 12 章 从骨架起手新项目 | 方式 A 正式版：./init-project 自动完成改名、密钥、依赖、ACL、样例清理、验证与独立 Git 历史 |
| 第 13 章 moo-feedback 用例 | 匿名提交、host 分类目录、扩展包一致命名契约、独立后台认证组与 401/403 验收 |
| 第 14 章 扩展包与 Host Resolver | 包自持窄契约、moo-system 人员目录、Host 合一实现与兼容验证 |
教程目录页还附了一张**「踩过的坑」速查表**（31 条新手高频问题）：docs/README.md。
下列账号仅供本地教程和自动测试。生产环境不得运行通用
DatabaseSeeder，也不得保留这些凭据。
| 用途 | 账号 | 密码 | 创建方式 |
|---|---|---|---|
自建用户（User 守卫）：第 3~6 章作后台账号；第 7 章后台主体切到 Personnel 后它不再用于后台，但一直是移动端（/app 接口、user 守卫）的账号 |
admin@example.com |
password |
migrate --seed（UserSeeder） |
后台管理员（Personnel 守卫，第 7 章起，走 /api/admin 接口） |
13800000000 |
admin888 |
migrate --seed（PersonnelSeeder） |
root 超级管理员（固定 id=1） |
root 或 13300000001 |
初始化时随机生成 | moo-system reset-root-password（缺少时创建，存在时重置） |
| scaffold 调试台（http://127.0.0.1:8088/scaffold 的登录账号） | 自定 | 自定 | seed 不创建，需自行执行 php artisan moo:account:add <用户名> --password=<密码> --role=admin（快速开始 A/B 均已含此步） |
后台账号的使用方式：后台是纯 API（前缀
/api/admin，无网页界面），拿着上表账号在/scaffold接口调试器里调POST /api/admin/authenticate登录、再调业务接口。
- 每一步都有操作记录，最终沉淀成可开源的新手教程。
- 每一步都真机测试——不只是写代码，而是跑起来、用浏览器/接口真实请求验证。 （作者成稿时由 AI 经 MCP——Model Context Protocol，一种让 AI 驱动浏览器、调用接口的 协议——自动完成这些验证；读者跟做时手动点一遍即可，不需要了解 MCP。）
包自身的细节文档在对应仓库里；有仓库访问权限后可查看
moo-scaffold/docs/guide/ 与 moo-system/docs/INTEGRATION.md。Packagist/GitHub 同步后，
开源包文档也会随公开仓库发布。
给新手一套可用的教程，从 0 开始、零付费依赖地搭出带 JWT + ACL 的 Laravel 12 骨架； 进阶者再用 moo-system 一键升级成完整系统管理后端。