ThinkPHP6.0.2+Layui2.5.6权限后台部署与鉴权避坑-平芜编程栈

简介：面向 PHP 后台开发初学者与二次开发者的权限管理项目模板，将 layui2.5.6 前端组件库与 ThinkPHP6.0.2 后端框架整合，重点解决登录鉴权、角色分配与菜单权限控制等需求，可用于快速搭建管理后台原型，也适合作为课程设计参考。压缩包共 1098 个文件、约 6.1MB，主体是 481 个 php 源码与 139 个 js 脚本，配合 30 个 css、36 个 html 页面构成前后端交互骨架，另有 gif、png、svg 等界面素材以及 md 使用说明、json 与 yml 配置、sql 建表文件；目录涵盖框架核心、公共静态资源与依赖描述等层次，并按 Composer 方式管理依赖，便于按模块阅读与调试。目前已有 2285 人学习下载。借助该案例可了解 RBAC 权限模型的落地方式、.env 环境配置的切换办法，以及 layui 组件与后端接口的对接思路，从而理清前后端协同开发的基本路径。

1. 装之前先定版本：PHP 7.4 与 Composer 2 是 tp6.0.2 的舒适区

把 layui2.5.6 + tp6.0.2 权限管理后台从压缩包跑到能正常登录，卡住人的从来不是权限逻辑，而是版本。我见过最典型的一次，是把项目丢进一台预装 PHP 8.1 的机器，php think run倒是起来了，一进登录页就白屏，runtime/log里只有一行看不懂的反射报错，排查了半天才发现是运行环境的问题，跟代码一行关系都没有。这套 tp6 layui 组合在后台管理场景里太常见了：左侧菜单、角色分配、节点鉴权、列表增删改查，一套骨架能撑起大半个中后台。但它对运行环境有自己的脾气，PHP 版本高了低了我都不建议，PHP 7.4 加 Composer 2.x 是踩过坑之后最省事的一档，数据库用 MySQL 5.7 或 8.0 都行。这套东西适合手上有后台需求、想拿一套能跑通的骨架改的人；如果你的目标是用 PHP 8.3 那一套，那这篇的路径不适用，别硬套。

2. 搭底座：PHP 7.4 扩展、Composer 2 与 tp6.0.2 骨架拉取

2.1 PHP 7.4 与六个必开扩展

tp6.0.2 的依赖声明里写的是 PHP >= 7.1，但真正让人翻车的往往不是版本号，而是扩展。我一般先跑两条命令把底摸清楚，而不是等页面报 500 再回头猜。

# 看大版本，以及实际加载的是哪一个 php.ini php -v php --ini # 一次性筛出 tp6 从启动到连库、渲染、写日志要用的扩展 php -m | grep -Ei 'openssl|mbstring|pdo|mysql|curl|fileinfo|tokenizer|xml|json'

php -v决定后面所有讨论的前提；php --ini拿到的才是真正生效的 ini 路径，很多「我明明改了 php.ini 却没反应」的问题，都是改到了另一个版本目录下的配置文件。php -m列的是已启用模块，上面这几个是必经之路：openssl 供 Composer 与加密函数使用，mbstring 处理中文字符串截断，pdo_mysql 负责连库，fileinfo 判断上传文件真实类型，tokenizer 供模板解析，xml 与 json 则是框架内部序列化的常客。

Linux 下补扩展最省事的是包管理器，把版本号换成你自己装的：

sudo apt install php7.4-mbstring php7.4-xml php7.4-curl php7.4-mysql php7.4-fileinfo -y sudo systemctl restart php7.4-fpm # 走 fpm 的必须重启才生效

Windows 下打开 php.ini，去掉对应行的分号，并把 extension_dir 指到 ext 目录：

extension_dir = "D:/php7.4/ext" extension=openssl extension=mbstring extension=pdo_mysql extension=fileinfo extension=curl

改完别只看 ini 里有没有那行，回到终端用php -m复查一遍——扩展加载失败时 PHP 只在启动日志里留一句警告，页面上是看不出来的。顺手再看一眼disable_functions，部分集成环境默认把putenv、proc_open关掉，Composer 装依赖时会直接中断，报错信息还挺隐晦。

2.2 Composer 2 安装与镜像配置

Composer 走的是 HTTPS 拉包，机器时间不准、CA 证书过期都会失败，先把这两样确认掉再装。

# 官方安装脚本，装到当前目录后移到全局 php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');" php composer-setup.php --install-dir=/usr/local/bin --filename=composer php -r "unlink('composer-setup.php');" composer -V # 确认是 2.x composer diagnose # 体检：网络、证书、缓存目录一次看全

--install-dir与--filename决定最终的可执行文件名，放在/usr/local/bin下可以直接用composer而不是./composer.phar。composer diagnose这一步我强烈建议每次都跑，它会把网络连通性、证书、代理设置、缓存目录权限全列出来，比出问题后一个个猜要快得多。

拉包慢是常态，配全局镜像，把地址换成你网络环境下实际可用的那个：

composer config -g repo.packagist composer https://mirrors.example.com/composer/ composer config -g --list | grep repos # 确认写进去了

这条命令改的是全局配置文件，不动项目里的 composer.json。好处是换机器、换项目都不用重复配；坏处是镜像偶尔同步滞后，装到一半提示某个包「not found」，先把镜像关掉再试一次，能立刻判断是源的问题还是包名写错了。

2.3 拉 tp6.0.2 骨架并跑起来

版本号一定要写死，create-project不带约束会给你拉最新的 6.x 小版本，跟 layui2.5.6 那套模板写法对不上。

# 目录名自定，版本号锁死在 6.0.2 composer create-project topthink/think tpadmin "6.0.2" cd tpadmin cp .example.env .env # 环境变量文件，后面连库要用 php think run -H 0.0.0.0 -p 8000

-H 0.0.0.0是为了让容器外或局域网内能访问，只在本机调试用127.0.0.1就行。启动后访问http://你的IP:8000，出现框架默认的欢迎页，说明骨架这一层是通的。如果这里就白屏，先看runtime/log下当天的日志文件，再看 PHP 错误日志，两边都没有就往扩展和disable_functions上查。

拉下来之后目录长这样，几个位置要提前记住：app/放业务代码，config/放配置，public/是唯一的 Web 入口，route/是路由定义，runtime/是缓存与日志。vendor/不提交版本库，换机器重新composer install即可。

2.4 public 入口与伪静态

新手最容易栽的一步：把站点根目录指到了项目根，而不是public。后果是.env、composer.json全暴露在浏览器里，属于安全事故级别的问题。

Nginx 的最小可用配置：

server { listen 80; server_name admin.local; root /data/www/tpadmin/public; # 必须指到 public index index.php; location / { try_files $uri $uri/ /index.php$is_args$args; # 去掉 index.php 的关键 } location ~ \.php$ { fastcgi_pass 127.0.0.1:9000; fastcgi_index index.php; include fastcgi_params; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; } location ~ /\.(env|git) { deny all; # 环境文件与版本库目录禁止访问 } }

try_files那行是伪静态的核心，找不到实体文件就统一交给index.php，路由才能接管。最后那段 deny 是兜底，就算根目录配错了，.env也读不到。

Apache 环境更简单，public目录下框架自带的.htaccess直接生效，只需要确认mod_rewrite已开、AllowOverride All已配。

3. 接前端：layui2.5.6 静态资源落位与后台布局模板

3.1 layui2.5.6 放哪：目录带版本号

静态资源我只认一种放法：public/static/下面按「库名/版本号」分层，把 2.5.6 写进路径里。

public/static/ └── layui/ └── 2.5.6/ ├── layui.js ├── css/layui.css ├── font/ └── modules/

这样做的好处很直接：以后要试 2.6 或更高版本，新开一个目录并行放，改模板里的引用路径就能灰度，不用覆盖旧文件。覆盖式升级在后台项目里是血泪教训，一旦新版本某个组件的默认样式变了，线上表格立刻变形，想回退还得翻备份。

模板里的引用保持相对路径，别写死域名：

<link rel="stylesheet" href="/static/layui/2.5.6/css/layui.css"> <script src="/static/layui/2.5.6/layui.js"></script>

modules/整个目录必须一起拷，layui 是按需异步加载模块的，少一个文件，页面只会在控制台报一句 404，界面上什么都不显示，属于典型的黑匣子问题。

3.2 多应用模式与模板引擎：两个包别忘

tp6 的骨架默认是单应用，也不带模板引擎，这两样都要额外装。这是我认为整套安装里最容易漏的一步。

composer require topthink/think-multi-app # 多应用：app/admin、app/index 这种结构 composer require topthink/think-view # 模板引擎：{extend}、{block} 才可用

装完think-multi-app之后，访问方式从/index/index变成/admin/index/index，app/admin/就是一个独立应用。think-view提供的是view()助手函数和模板继承能力，没有它，return view()会直接抛方法不存在的异常。

应用目录按这个结构铺：

app/ ├── admin/ │ ├── controller/ │ │ └── Index.php │ ├── middleware/ │ │ └── Auth.php │ ├── middleware.php # 应用级中间件注册 │ └── view/ │ ├── public/ │ │ └── layout.html # 公共骨架 │ └── index/ │ └── index.html └── common.php

控制器里渲染视图，只需要一句：

namespace app\admin\controller; class Index { // 对应 app/admin/view/index/index.html public function index() { return view(); } }

view()不带参数时，按「控制器名/方法名」自动找模板，规则是view/控制器/方法.html。想指定别的模板就传路径，view('public/main')这种写法我用得最多。

3.3 后台主框架：layout 继承与 iframe 菜单

后台布局有两种做法：iframe 版和单页版。前者菜单点击换 iframe 的 src，每个页面互相独立；后者用前端路由，整站一个 HTML。layui2.5.6 这套生态里，iframe 版落地最快，出问题也最好定位。

公共骨架layout.html：

<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>{block name="title"}后台管理{/block}</title> <link rel="stylesheet" href="/static/layui/2.5.6/css/layui.css"> </head> <body> {include file="public/header" /} <div class="layui-body"> {block name="content"}{/block} </div> <script src="/static/layui/2.5.6/layui.js"></script> {block name="script"}{/block} </body> </html>

子模板只需要三行：

{extend name="public/layout" /} {block name="title"}角色管理{/block} {block name="content"} <table id="roleTable" lay-filter="roleTable"></table> {/block}

{extend}必须写在第一行，前面连空行都不能有，否则模板解析会把它当普通文本输出到页面上。{block}的名字要和父模板一一对应，多写一个不会报错，只是永远不渲染——这类问题没有报错提示，只能靠肉眼比对。

3.4 接口返回格式：跟 layui table 对齐

前端表格直接决定了后端返回的数据结构，这一层不统一，后面每个列表页都要单独写一遍解析。

// app/common.php，全局可调 function json_table($list, $total, $code = 0, $msg = '') { // layui table 默认读 code / msg / count / data 四个字段 return json([ 'code' => $code, 'msg' => $msg, 'count' => $total, 'data' => $list, ]); }

code为 0 表示成功，非 0 时前端弹msg；count是总条数，分页组件靠它算页数；data是当前页数据。分页参数 layui 默认传page和limit，后端直接接：

$page = (int) $request->param('page', 1); $limit = (int) $request->param('limit', 10); $total = Db::name('role')->count(); $list = Db::name('role')->page($page, $limit)->select()->toArray(); return json_table($list, $total);

page($page, $limit)的两个参数顺序是页码在前、每页条数在后，写反了不会报错，只是数据错位。toArray()别漏，tp6 的查询结果默认是数据集对象，直接塞进 json 会变成嵌套结构，前端表格拿不到字段。

4. 落权限：TP6 的四张表、.env 连库与中间件鉴权

4.1 四张核心表：管理员、角色、节点、关联

权限后台的表结构不用复杂，四张够用。管理员挂角色，角色挂节点，节点就是「哪个控制器下的哪个方法」。

-- 管理员表 CREATE TABLE `admin` ( `id` int unsigned NOT NULL AUTO_INCREMENT, `username` varchar(32) NOT NULL COMMENT '登录名', `password` varchar(255) NOT NULL COMMENT 'password_hash 结果', `role_id` int unsigned NOT NULL DEFAULT '0' COMMENT '角色ID', `status` tinyint NOT NULL DEFAULT '1' COMMENT '1启用 0禁用', `create_time` int unsigned NOT NULL DEFAULT '0', PRIMARY KEY (`id`), UNIQUE KEY `uk_username` (`username`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; -- 角色表 CREATE TABLE `role` ( `id` int unsigned NOT NULL AUTO_INCREMENT, `name` varchar(32) NOT NULL, `status` tinyint NOT NULL DEFAULT '1', PRIMARY KEY (`id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; -- 节点表，pid 做无限级菜单 CREATE TABLE `node` ( `id` int unsigned NOT NULL AUTO_INCREMENT, `pid` int unsigned NOT NULL DEFAULT '0', `title` varchar(64) NOT NULL COMMENT '菜单名', `module` varchar(32) NOT NULL DEFAULT 'admin', `controller` varchar(64) NOT NULL, `action` varchar(64) NOT NULL, `sort` int NOT NULL DEFAULT '0', PRIMARY KEY (`id`), KEY `idx_pid` (`pid`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; -- 角色与节点多对多 CREATE TABLE `role_node` ( `role_id` int unsigned NOT NULL, `node_id` int unsigned NOT NULL, PRIMARY KEY (`role_id`,`node_id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

controller和action统一小写存，校验时也统一转小写比对，大小写混着存是权限「配了却不生效」的头号原因。role_node用联合主键，天然防重复授权，比加自增 id 再补唯一索引省事。

超级管理员我一般不走关联表，直接判role_id = 1放行。理由很实在：节点是动态增删的，超管每次加功能都要回来补授权，早晚会漏。

4.2 .env 与 config/database.php：两个入口别打架

tp6 的数据库配置有两处：.env和config/database.php。规则是配置文件里用env()取值，.env有就用.env的，没有就用第二个参数兜底。

[DATABASE] TYPE = mysql HOSTNAME = 127.0.0.1 DATABASE = tpadmin USERNAME = tpadmin PASSWORD = 换成你的密码 HOSTPORT = 3306 CHARSET = utf8mb4 DEBUG = true

对应的config/database.php关键几行：

return [ 'type' => env('database.type', 'mysql'), 'hostname' => env('database.hostname', '127.0.0.1'), 'database' => env('database.database', ''), 'username' => env('database.username', 'root'), 'password' => env('database.password', ''), 'hostport' => env('database.hostport', '3306'), 'charset' => env('database.charset', 'utf8mb4'), ];

env('database.hostname')里的点号对应.env中的[DATABASE]段和HOSTNAME键，大小写不敏感。改了.env之后如果没生效，多半是runtime/下留了旧缓存，php think clear清一次再刷新。生产环境记得把DEBUG关掉，APP_DEBUG = false，否则报错页会把连接信息直接打到浏览器上。

建库的时候字符集一步到位：

CREATE DATABASE `tpadmin` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

用utf8也能跑，但存 emoji 和部分生僻字会截断，后台里填个备注就莫名其妙少半截，返工成本比一开始就选对高得多。

4.3 登录与会话：密码哈希和 session 落点

密码不存明文，也不自己写 md5 加盐，用 PHP 自带的password_hash，验证用password_verify，将来换算法也不用改表结构。

public function login(Request $request) { $username = $request->param('username', ''); $password = $request->param('password', ''); $admin = Db::name('admin')->where('username', $username)->find(); // 用户不存在与密码错误返回同一句提示，避免被枚举账号 if (!$admin || !password_verify($password, $admin['password'])) { return json(['code' => 1, 'msg' => '账号或密码错误']); } if ((int) $admin['status'] !== 1) { return json(['code' => 1, 'msg' => '账号已禁用']); } // 只写必要字段进 session，别把整行数据丢进去 session('admin', [ 'id' => $admin['id'], 'username' => $admin['username'], 'role_id' => $admin['role_id'], ]); return json(['code' => 0, 'msg' => '登录成功']); }

session 驱动在config/session.php里改，单机部署用默认的文件驱动就够，多机才需要换到 redis 或数据库。文件驱动的 session 存runtime/session/，目录权限不对会表现为「登录成功但一刷新就掉」，这是权限问题的伪装，排查时先看目录属主。

退出登录把 session 清干净：

public function logout() { session(null); // 清空当前会话数据 return redirect('/admin/login/index'); }

4.4 中间件做鉴权：把判断收到一处

每个控制器方法里写一遍权限判断，是这套后台最常见的退化方式——加一个方法忘了加判断，就是一个越权入口。正确做法是应用级中间件统一拦。

namespace app\admin\middleware; use think\facade\Db; class Auth { public function handle($request, \Closure $next) { $admin = session('admin'); // 未登录直接跳登录页 if (!$admin) { return redirect('/admin/login/index'); } // 超管放行，不做节点比对 if ((int) $admin['role_id'] === 1) { return $next($request); } // 当前请求对应的节点标识，统一小写 $node = strtolower($request->controller() . '/' . $request->action()); $allow = Db::name('role_node') ->alias('rn') ->join('node n', 'n.id = rn.node_id') ->where('rn.role_id', $admin['role_id']) ->whereRaw('LOWER(CONCAT(n.controller, "/", n.action)) = :node', ['node' => $node]) ->count(); if (!$allow) { return json(['code' => 403, 'msg' => '无访问权限'], 403); } return $next($request); } }

注册在app/admin/middleware.php，登录接口本身要排除：

return [ // 除登录相关方法外，全部走鉴权 \app\admin\middleware\Auth::class => ['except' => ['login/index', 'login/check', 'login/logout']], ];

except里写的是「控制器/方法」的小写形式，写错大小写会导致该放行的方法被拦下来，表现是登录页一直跳回自己。whereRaw里的CONCAT是为了把两列拼成一个标识再比，避免先查出全部节点再在 PHP 里 foreach，节点上百条之后差异很明显。

鉴权中间件返回 JSON 还是跳转，取决于请求类型。我一般在这里判一下$request->isAjax()，接口请求返回 403 JSON，页面请求跳登录页，两套前端都能正常处理。

5. 避坑排查：这套组合最常翻车的五个点

5.1 页面白屏，日志里什么都没有

现象：访问后台任意页面返回 500，浏览器空白，runtime/log里当天的文件是空的或者只有框架启动那几行。

原因：tp6 的异常处理在调试模式下才把详细堆栈写进日志，APP_DEBUG为 false 时异常被吞成一句「页面错误」。另外 PHP 自己的display_errors关掉后，fatal error 也不会显示在页面上。

解决：临时把.env里的APP_DEBUG打开，同时确认log配置的level包含error。如果还是没内容，直接看 PHP-FPM 的 error log（/var/log/php7.4-fpm.log或 nginx 的 error_log），语法错误、内存超限这类问题只出现在那边。

5.2 layui 表格一直显示「请求异常」

现象：列表页加载后表格区域只显示「请求异常」四个字，Network 面板里接口是 200，返回的 JSON 看着也正常。

原因：layui table 默认解析code / msg / count / data，返回体里少一个字段或者code不是 0，前端就按失败处理。另一种情况是接口返回了 HTML（比如被中间件重定向到登录页），data解析不出来。

解决：先在 Network 里点开 Response 原样看，是 JSON 还是 HTML。是 HTML 就查中间件的except有没有放行这个方法；是 JSON 就核对四个字段是否齐全，count必须是数字不能是字符串，data必须是数组不能是对象。

5.3 权限配了不生效，改了菜单没反应

现象：后台给角色勾了新节点，保存成功，重新登录该角色还是看不到菜单，或者菜单出来了点进去 403。

原因：一是节点表里controller、action存了大小写混合，鉴权时统一转了小写比对不上；二是runtime/下有旧的缓存文件；三是菜单是登录时一次性写进 session 的，改了库但 session 里还是老数据。

解决：查库确认两列全小写；执行php think clear清缓存；菜单别存 session，每次渲染从库里读，量为几十条时这点开销可以忽略。

5.4 子目录部署后静态资源全 404

现象：项目放在https://域名/admin/这种子路径下，页面能打开但样式全丢，控制台一片 404，请求路径变成了/admin/static/...之外的位置。

原因：模板里写的是/static/...这种以根开头的绝对路径，浏览器会从域名根开始找，不认子目录。

解决：模板里改用{:static_path()}之类的助手函数拼前缀，或者在config/view.php里配一个tpl_replace_string，把占位符统一替换成带前缀的路径。散落在几十个模板里的硬编码路径，越早统一越省事。

5.5 iframe 里登录态丢失

现象：主框架登录正常，点左侧菜单进 iframe 页面，内容区跳回了登录页。

原因：session 的 cookie 作用域或 SameSite 属性配置不当，跨端口、跨子域时浏览器不带 cookie；也可能是 session 存储目录权限不对，写入失败后每次请求都是新会话。

解决：config/cookie.php里把domain配成实际域名（不要留空又跨子域访问），samesite设成lax；然后检查runtime/session/的属主是否与 PHP-FPM 运行用户一致。

6. 装完怎么验证：四条链路依次打通才算跑通

装完不等于跑通。我判断一套后台能不能交付，是按四条链路依次走的，前面不通就不往下走，避免问题叠在一起分不清是谁的锅。

第一条，静态链路。浏览器直接访问/static/layui/2.5.6/layui.js，返回 200 且 Content-Type 是application/javascript。返回 404 说明目录没放对，返回 HTML 说明伪静态把静态文件也接管了，try_files那行要检查。

第二条，模板链路。访问/admin/index/index，页面源码里能看到 layui 的样式引用和渲染出来的菜单结构，而不是一堆{block}原文。后者说明think-view没装或没生效。

第三条，数据链路。登录接口能返回code: 0，且admin表里能查到session写入对应的记录。这一步过了，说明.env、pdo_mysql、密码哈希三样都对。

第四条，权限链路。用两个角色对照，这是最容易被跳过也最该做的一步：

验证项	操作	期望结果
超管放行	用 role_id=1 的账号访问任意方法	全部 200
普通角色越权	用只授权了角色列表的账号访问`/admin/admin/index`	返回 403 JSON
菜单渲染	普通角色登录后的左侧菜单	只出现已授权节点
未登录拦截	清 cookie 后直接访问后台首页	跳转登录页