简介：这份压缩包提供基于 layui 2.5.6 与 ThinkPHP 6.0.2 搭建的权限管理后台源码，面向希望快速理解管理系统前后端协同、RBAC 权限控制及 PHP 框架工程化实践的开发者，也适合初学者对照学习与二次开发。资源共 1098 个文件，以 PHP 后端代码、JavaScript 脚本、HTML 页面和 CSS 样式为主，并包含图标图片、字体、SQL 初始化数据及项目说明文档，压缩包约 6.1MB，目录组织覆盖公共入口、应用模块、前端静态资源与依赖配置等部分。已有 2285 人学习下载，说明该模板在权限后台入门场景中具有一定参考价值。读者可从中了解用户角色分配、菜单与权限校验的实现思路，观察环境配置、Composer 依赖管理、持续集成配置和较清晰的项目分层，并借助现成页面与后端结构完成登录、权限管理等模块的改造练习，从而提升前后端协同开发和 PHP 框架应用能力。

1. 版本选错，后台三天没跑起来

上周帮一个做外包的朋友收拾环境，他卡在一个权限管理后台的登录页上：接口报 500，前端表格一片空白。翻了半天日志才发现，他把 TP6 装成了最新小版本，layui 又拉了 2.9 的包，两者对不上——项目本身锁的是 layui 2.5.6 + tp6.0.2。这种组合在中小型后台系统里太常见了：thinkphp 6.0.2 负责权限、菜单、角色这一套后端逻辑，layui 2.5.6 负责表格、表单、弹层这套前端皮。版本看着都很老，但恰恰是稳的组合，乱升一个点就会翻车。这篇我按自己装这套环境的顺序写一遍：PHP 版本怎么定、Composer 怎么拉、数据库怎么配、伪静态和入口文件怎么改、跑不起来时从哪儿查。适合刚接手老后台项目的开发者，也适合想复现一套能用的权限管理底子的人。

2. 环境准备：PHP 版本与扩展清单先定死

tp6.0.2 这个版本对 PHP 的要求是 7.1 起步，官方推荐 7.2～7.4。我这里选 7.4，因为 8.0 之后有几处函数行为和类型判断变了，老项目里的权限判断逻辑容易出问题。数据库用 MySQL 5.7，字符集统一 utf8mb4。Web 服务用 Nginx，这是这套后台最常见的部署组合。

2.1 PHP 扩展清单与版本对照

先列清楚要装什么，别等跑起来才发现缺扩展。tp6.0.2 常用到的是这几个：

扩展缺失的典型表现是：页面能打开，但一登录就白屏，或者报Call to undefined function。我一般先装完扩展再谈其他，因为排查顺序上，扩展问题是最好排除的。

2.2 安装 PHP 7.4 与补齐扩展

以 Ubuntu 20.04 为例，用系统源加第三方源装 7.4。如果系统自带版本低于 7.1，必须先加源，不能直接apt install php碰运气。

# 添加 PHP 源（Ubuntu） sudo apt update sudo apt install -y software-properties-common sudo add-apt-repository -y ppa:ondrej/php sudo apt update # 安装 PHP 7.4 及扩展 sudo apt install -y php7.4 php7.4-fpm php7.4-mysql php7.4-mbstring \ php7.4-json php7.4-xml php7.4-curl php7.4-zip php7.4-gd php7.4-bcmath # 查看版本确认 php -v

第一段加源是为了保证能拿到 7.4 的包；第二段一次装齐 fpm 和扩展，其中php7.4-fpm是给 Nginx 用的进程管理器，不是 CLI 那一套。php7.4-mysql里就包含 pdo_mysql，别单独去找。装完用php -m看一眼扩展列表，把上面表格里标「必须」的对一遍，缺哪个补哪个。

Redis 如果要用，再补一条sudo apt install -y php7.4-redis。这里有个血泪经验：装完扩展一定要重启 php-fpm，不然 Nginx 那边还是老进程，扩展生效不了。

sudo systemctl restart php7.4-fpm sudo systemctl status php7.4-fpm

status 显示 active (running) 才算过。如果显示 failed，基本是配置语法错或者端口被占，看/var/log/php7.4-fpm.log。

2.3 安装 Composer 并切换国内镜像

tp6.0.2 的依赖全靠 Composer 拉。不装镜像的话，拉 thinkphp 框架本体加一堆依赖，中间断一次就得重来。

# 下载 composer 安装脚本 curl -sS https://getcomposer.org/installer -o composer-setup.php # 校验并安装到全局 php composer-setup.php --install-dir=/usr/local/bin --filename=composer # 删除安装脚本 rm -f composer-setup.php # 切换镜像加速 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ # 确认版本 composer -V

--install-dir指定全局位置，放/usr/local/bin是为了命令行任意目录能直接敲composer。切镜像是全局配置（-g），写进用户目录的 composer 配置里。完成后composer -V能输出版本号即可，这一步不过后面全卡。

3. 拉取项目：用 Composer 装 tp6.0.2 与目录结构确认

框架本体我不建议直接下压缩包，用 Composer 建骨架再锁版本，依赖关系才干净。

3.1 创建项目并锁定 6.0.2

# 创建 tp6 项目骨架 composer create-project topthink/think tpadmin # 进入目录 cd tpadmin # 锁定框架版本到 6.0.2 composer require topthink/framework:6.0.2 --no-update composer update topthink/framework

create-project会拉最新的 think 骨架，所以第二段必须把topthink/framework锁到 6.0.2，否则装出来是 6.1 或更高，路由和中间件行为有差异，老项目的代码可能直接报错。--no-update是只改 composer.json 不动依赖，再单独 update，这样只动框架一个包，速度也快。

装完确认版本：

php think version

输出6.0.2就对了。如果是别的版本，检查 composer.json 里那一行有没有写死。

3.2 目录结构逐项过一遍

tp6 的目录结构和 tp5 差别不小，尤其是app和public的关系：

tpadmin/ ├── app/ # 应用目录，控制器、模型、中间件都在这里 │ ├── controller/ # 控制器，权限后台的登录、菜单、角色都放这 │ ├── model/ # 模型 │ ├── middleware/ # 中间件，登录校验一般写这里 │ └── common.php # 公共函数 ├── config/ # 配置目录，数据库、session、缓存 ├── public/ # 唯一对外暴露的目录，入口 index.php 在这 ├── route/ # 路由定义 ├── runtime/ # 运行时缓存日志，需要可写 ├── vendor/ # Composer 依赖 ├── .env.example # 环境变量样例 └── composer.json

关键点：public才是站点根目录，Nginx 的 root 要指向它，不是项目根。这点错了，配置文件、.env全暴露在公网，属于典型翻车现场。runtime目录要给写权限，否则日志和缓存写不进去，页面会莫名 500。

# runtime 可写 chmod -R 755 runtime chown -R www-data:www-data runtime

权限给 755 就够，别图省事上 777。www-data是 Ubuntu 下 Nginx 和 php-fpm 的默认运行用户，用其他用户装的要对应改。

3.3 layui 2.5.6 前端资源的放置位置

layui 不走 Composer，是纯静态资源。从官方包拿到 2.5.6 后，放到public/static/layui/下：

# 假设解压出来的 layui 目录在当前路径 mkdir -p public/static cp -r layui public/static/layui # 检查关键文件 ls public/static/layui/

目录里应该有layui.js、css/layui.css、font/这几样。版本务必确认是 2.5.6，layui 2.6 之后的表单渲染和弹层参数有小改动，老页面引用的写法可能不起作用。判断方法：打开layui.js顶部注释，或者页面控制台敲layui.v，返回2.5.6就是对的。

4. 配置数据库与 .env：连接串、前缀、时区三处最容易写错

tp6 用.env管环境变量，数据库信息全放这，比改 config 文件干净。但这也是最容易出问题的一环，写错一处就是连接失败。

4.1 从样例复制并填写数据库信息

# 复制环境变量样例 cp .env.example .env # 编辑 vim .env

.tp6.0.2 的.env关键段是这些：

APP_DEBUG = true [APP] DEFAULT_TIMEZONE = Asia/Shanghai [DATABASE] TYPE = mysql HOSTNAME = 127.0.0.1 DATABASE = tpadmin USERNAME = tpadmin_user PASSWORD = 你的密码 HOSTPORT = 3306 CHARSET = utf8mb4 PREFIX = tp_ [LANG] default_lang = zh-cn

APP_DEBUG = true只在开发机开，线上必须关，否则报错页面会把数据库账号密码打出来。DEFAULT_TIMEZONE不写默认是 UTC，后台的创建时间会差 8 小时，这是权限后台里最常见的「时间不对」投诉来源。PREFIX是表前缀，要和导入的 SQL 文件一致，后台项目一般用tp_或类似前缀，导入前先看 SQL 里的建表语句。

4.2 建库导表与权限账号

# 登录 mysql mysql -u root -p # 建库，字符集必须是 utf8mb4 CREATE DATABASE tpadmin DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; # 建专用账号，别用 root 跑应用 CREATE USER 'tpadmin_user'@'127.0.0.1' IDENTIFIED BY '你的密码'; GRANT ALL PRIVILEGES ON tpadmin.* TO 'tpadmin_user'@'127.0.0.1'; FLUSH PRIVILEGES;

建库时字符集写utf8mb4，别用utf8，后者在 MySQL 里是三字节的，遇到特殊字符和 emoji 会截断报错。账号限定@'127.0.0.1'而不是%，减少暴露面。导表用mysql -u tpadmin_user -p tpadmin < admin.sql，导之前先确认 SQL 里的表前缀和.env里的PREFIX对得上，不一致就改一边。

导完检查表数量：

SHOW TABLES;

权限后台通常是十几到二十几张表：用户、角色、权限节点、菜单、日志这类。数量差太多说明 SQL 没导全，或者中途报错被忽略了。

4.3 数据库配置的三种写法与取舍

tp6 的数据库配置可以在config/database.php写死，也可以走.env。我一般用.env，原因很实际：同一份代码要上测试机和正式机，改.env不用碰代码库，也不容易误提交。

config/database.php里对应的读取方式是env('database.hostname', '127.0.0.1')这种，第二个参数是默认值。如果你在.env里改了但没生效，先确认.env文件是不是在项目根、文件名有没有多余后缀（比如.env.txt），这是新手最常见的坑。另外 tp6 有个规则：.env里的段名要和配置文件的键对应，[DATABASE]里写HOSTNAME，对应就是database.hostname，大小写不敏感但拼写不能错。

5. Nginx 伪静态与入口文件：URL 重写和 public 指向

这一步弄错，表现是首页能开、点菜单全 404。原因是 tp6 默认走 PATH_INFO 形式的路由，Nginx 不做重写就找不到对应控制器。

5.1 Nginx 站点配置

server { listen 80; server_name admin.local; # 根目录必须指向 public root /var/www/tpadmin/public; index index.php index.html; location / { # 先找文件，找不到交给入口文件 try_files $uri $uri/ /index.php$is_args$args; } location ~ \.php$ { include snippets/fastcgi-php.conf; fastcgi_pass unix:/run/php/php7.4-fpm.sock; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; include fastcgi_params; } # 禁止访问隐藏文件 location ~ /\. { deny all; } }

root指向public是这套项目能否跑通的第一道关。try_files那一行是关键：请求先按真实文件找，找不到转给index.php，参数原样带上，tp6 的路由才能解析出控制器和方法。fastcgi_pass的 socket 路径要和实际 php-fpm 版本对应，装的是 7.4 就是php7.4-fpm.sock，写成 7.2 的会报 502。

改完配置必须测试再 reload：

sudo nginx -t sudo systemctl reload nginx

nginx -t输出 syntax is ok 才能 reload，直接 reload 一个语法错的配置会让整个站点挂掉，线上尤其不能省这一步。

5.2 入口文件与调试开关

public/index.php一般不用改，但调试阶段可以确认下它有没有绑定应用目录。tp6 的多应用模式需要在这文件里指定，单应用则不用。如果访问首页报「控制器不存在」，先看这个文件是不是被改过。

调试开关在.env的APP_DEBUG，开发期开 true，能看到详细报错栈，定位问题快很多。线上切 false，页面只显示「页面出错」，详细信息进日志。日志在runtime/log/按日期分文件，报错先翻这里，比在页面上猜快。

5.3 静态资源与 layui 路径对齐

layui 放在public/static/layui/，页面里引用路径要写/static/layui/layui.js这种根路径形式。如果写成相对路径，在深层路由页面里会 404，因为相对路径是相对于当前 URL 而不是文件位置。这个坑我在两个项目里都踩过，表现是列表页正常、详情页样式全丢。

<!-- 正确写法：根路径引用 --> <link rel="stylesheet" href="/static/layui/css/layui.css"> <script src="/static/layui/layui.js"></script>

引用完在浏览器控制台看 Network，layui.css和layui.js是不是 200。有一个 404 就回头查文件位置和 Nginx 的 root 配置。

6. 常见问题排查：五条踩坑记录

6.1 登录后白屏，接口 500

现象：登录页正常，提交账号密码后白屏，浏览器 Network 里登录接口返回 500。

原因：多半是数据库连不上，或者runtime目录不可写导致日志和缓存初始化失败。tp6 连不上库时抛的异常如果APP_DEBUG关着，页面上什么都看不到。

解决：先把APP_DEBUG开 true 复现一次，看报错内容；同时tail -f runtime/log/下最新日志。连库问题就核对.env的账号、库名、端口；目录问题就chmod -R 755 runtime && chown -R www-data:www-data runtime。

6.2 所有菜单点进去都是 404

现象：登录进后台了，左侧菜单能显示，但点任何一个都 404。

原因：Nginx 没配try_files，或者配了但 root 指到了项目根目录而不是public。也可能伪静态规则被注释掉了。

解决：确认root是/var/www/tpadmin/public，location /里有try_files $uri $uri/ /index.php$is_args$args;，改完nginx -t再 reload。还有一种少见情况：路由定义在route/app.php里写死了后缀，请求必须带.html，检查路由文件。

6.3 页面样式全丢，控制台一堆 404

现象：功能能用，但表格没边框、按钮没样式。

原因：layui 静态资源路径写错，或者 Nginx 对静态文件没权限读取。相对路径引用是高频原因。

解决：页面里改成/static/layui/...根路径引用；确认public/static/layui/下文件齐全；检查 Nginx 用户对public目录有读权限。

6.4 创建时间差 8 小时

现象：新建用户或角色，列表里的创建时间比实际早 8 小时（或晚 8 小时）。

原因：.env里没配DEFAULT_TIMEZONE = Asia/Shanghai，PHP 用 UTC，写库时按 UTC 存；展示层如果又按本地时间格式化，就对不上。

解决：.env里补上时区；同时确认 MySQL 的time_zone设置；已有数据如果已经按错误时区写入，需要单独修正，不能只改配置。

6.5 Composer 拉依赖卡住或报 memory 错误

现象：composer update跑到一半卡死，或报内存超限直接退出。

原因：没切镜像导致网络慢；或者 composer 默认内存限制不够，依赖多时爆掉。

解决：切国内镜像（第 2 章那条命令）；临时提高内存上限COMPOSER_MEMORY_LIMIT=-1 composer update。另外别用 root 跑 composer，生成的 vendor 目录属主会是 root，后面 php-fpm 读不了，这条是真血泪经验。

7. 验证跑通：从登录到权限节点的一条完整链路

环境装完不等于跑通，我习惯按一条完整业务链路去验，而不是只看首页出来没有。这套后台的验证顺序是：登录 → 菜单加载 → 角色分配 → 权限节点生效。四步过完，才算这套 layui 2.5.6 + tp6.0.2 真装好了。

第一步验登录。用初始化 SQL 里的管理员账号登录，Network 里看登录接口返回的 code 是不是 0，有没有拿到 token 或 session。如果返回 200 但前端没跳转，问题在前端回调，不在后端。

第二步验菜单。登录后左侧菜单是否按数据库里的节点渲染出来。这一步能过，说明数据库连接、模型查询、模板渲染都通了。菜单空的话查tp_auth_rule这类权限表有没有数据，以及当前角色有没有关联。

第三步验角色。新建一个角色，给它分配两三个菜单权限，再用一个普通账号登录，看菜单是不是只剩分配的那几个。这一步验的是权限判断逻辑，也是这套项目最核心的部分。

第四步验节点级权限。直接拼 URL 访问一个没分配的控制器方法，正常应该被拦下或跳提示，而不是能进去。能进去说明中间件没生效，回头查app/middleware/下的登录与权限校验中间件有没有在middleware.php里注册。

附一个快速自检清单，装完照着过一遍：

这套验证走完，环境才算落地。我现在的习惯是每次部署完都强制过一遍这个清单，尤其是伪静态和时区两项——它们不会让页面立刻报错，但会在上线后以「菜单点不开」「时间不对」的形式回来找你，那时候排查成本比装的时候高得多。从那以后我每次配新环境，宁可多花十分钟走完这四步验证，也不愿意事后翻日志找黑匣子。希望帮到你。

本文还有配套的精品资源，点击获取