README

ThinkAdmin 是一套基于 ThinkPHP 6 / 8 的开源后台开发框架。后端使用 ThinkLibrary 封装常用功能，通过 Composer 管理依赖和插件；前端搭配 Layui、jQuery 与 RequireJS，沿用 PHP 模板配合 JavaScript 的开发方式。

做后台，账号怎么分权限、列表怎么筛选、图片传到哪里，这些问题总会遇到。ThinkAdmin 已经有了对应的功能和页面，你可以接着写自己的客户管理、订单处理或运营工具，把重复搭建基础后台的时间，用在业务上。需要在多个项目里使用同一套模块时，再把它整理成 Composer 插件。

官方网站与开发文档 · 在线演示 · 版本发布 · 问题反馈

项目特点

基础管理不用从头搭。 用户、权限、菜单、配置、日志和文件管理都有现成页面。先把后台跑起来，就可以从自己的业务模块开始做。
列表和表单，有现成的写法。 ThinkLibrary 把筛选、分页、提交、校验和状态更新做了封装。熟悉一套流程后，后续页面可以继续沿用。
页面和接口能对着看。 控制器、模型、模板都在源码里。想知道某个筛选条件怎么生效、编辑弹窗怎么保存，顺着已有页面就能找到对应实现。
模块怎么拆，由业务决定。 只用于当前项目的代码，可以放在独立应用中；需要跨项目复用时，再用 Composer 管理插件的依赖和版本。
能自己改，也能用于商业项目。 项目采用 MIT 许可证，允许按许可条款修改、使用和分发。交付时保留版权与许可文本，并留意第三方组件各自的授权要求。

适用场景

如果你正在给团队做一个内部系统，或者为客户开发一套管理后台，ThinkAdmin 可以承担其中常见的基础工作：

做客户、订单或审批管理时，沿用已有的账号、权限、列表和表单，再编写具体的业务流程。
做内容运营后台时，接入图文编辑、图片上传和分类字典，把精力放在内容模型、审核和展示上。
做微信公众号业务时，在同一个后台处理粉丝、菜单、回复和支付相关操作，再对接自己的活动或订单。
做原型或定制项目时，先用已有界面把业务流程串起来，再逐步补充细节。

拿不准是否适合，可以先看看在线演示，挑一个熟悉的功能，再对照源码走一遍。对熟悉 PHP / ThinkPHP 的开发者，这也是了解项目开发方式的直接途径。

ThinkAdmin 做的是通用后台基础。客户怎么分配、订单如何流转、不同租户的数据怎样隔离，这些仍由你的业务模块来实现。

功能概览

能力	说明
后台管理	系统用户、权限、菜单、参数配置、数据字典、操作日志和文件管理
权限控制	基于控制器注解的登录与权限校验，配合菜单、角色授权控制后台访问
数据操作	查询筛选、分页、表单处理、输入校验、状态更新和删除等通用封装
文件存储	本地、Alist、七牛云、阿里云 OSS、腾讯云 COS、又拍云；支持文件哈希检查和图片处理
异步任务	任务登记、独立进程执行、进度展示和执行结果管理
微信管理	公众号配置、粉丝、图文、菜单、自动回复，以及微信支付记录和退款管理
前端组件	Layui、jQuery、RequireJS，以及按需使用的 ECharts、Vue 和富文本编辑器

账号、菜单与日常管理

新同事来了，给他开一个账号；岗位变了，调整可用权限；人员离职了，再停用账号。这些日常工作可以直接在系统用户管理中完成。菜单管理负责组织后台入口，站点名称、登录背景、主题和存储方式则在参数配置中调整。

分类、编码等经常变动的基础选项，可以放到数据字典中维护。想查某个账号最近做过哪些已记录的管理操作，可以按时间、账号或操作类型筛选日志；自己的业务模块也可以接入同一套日志记录方式。

权限配置，从页面入口到具体操作

比如，你希望运营人员能查看和编辑资料，但把删除和系统配置留给管理员。可以在控制器方法上标注登录或权限要求，再到后台配置相应授权。

页面上的按钮根据权限显示，接口请求也由服务端校验。新增业务时，按同样的方式接入，就可以把新页面和新操作放进现有的权限管理中。具体注解和数据权限的处理见开发与扩展。

列表与表单，沿用熟悉的开发方式

一个常见的管理页：上面按关键词、状态和时间筛选，下面是带分页的表格，点击“编辑”打开表单，保存后刷新列表。ThinkLibrary 和现有前端组件已经给这类页面准备了对应的写法。

可以从仓库的系统用户页面开始看：控制器怎样组织查询，模板怎样定义列和按钮，表单怎样提交。做自己的业务时，再换成对应的模型、字段和校验规则。许多页面虽然管理的数据不同，基本流程可以共用。

文件与图片，按需要选择存储方式

头像、封面、内容配图和附件，往往分散在不同表单里。ThinkAdmin 用一套上传组件处理这些需求，各页面通过参数指定文件类型、大小、存储方式和图片尺寸。

相同文件可以少传一次。 上传流程支持计算文件哈希，检查对应存储文件是否已存在；命中后直接复用结果。
图片按用途处理。 单图、多图、图片选择都有对应入口，压缩质量、最大宽高和裁切尺寸按页面需要设置。
上传记录集中管理。 后台可以查找文件记录，并在授权范围内编辑、删除或清理重复记录。
公开文件和安全文件分开存放。 例如支付证书可以使用安全模式，保存到本地 safefile/，读取权限由业务接口另行控制。

开发时可以先用本地存储，有需要再接入 Alist、七牛云、阿里云 OSS、腾讯云 COS 或又拍云。配置好对应账号和访问凭据后，业务页面仍可沿用上传组件；已有文件的搬迁和地址调整需要单独安排。

耗时工作，交给后台任务执行

同步一批粉丝、整理一批数据，可能比普通页面请求花更长时间。这类工作可以登记成任务，由队列监听进程安排执行，再到“系统任务管理”查看状态和结果。

任务代码可以报告“处理到第几条”“目前完成多少”等进度。延时执行、循环任务和后台重置重跑也有对应入口；仓库里的微信粉丝同步命令就是一个实际例子，可以参考它编写自己的任务。

先启动监听进程，任务才会被处理。部署方式见配置与部署，失败后的排查与重跑见下方常见问题。

微信管理，集中处理常见公众号操作

如果项目围绕微信公众号开展业务，可以把常见运营操作放到同一个后台：同步粉丝资料，查看关注状态和黑名单，维护图文内容、菜单、关键词与关注回复。

微信模块也包含商户参数配置、支付记录和退款相关操作，便于接入自己的订单或活动流程。它管理的是这些通用环节，具体订单怎样生成、付款后执行什么业务，仍由项目代码处理。

开始使用前，先填写自己的公众号或商户信息，按微信要求设置回调地址、域名和接口权限。公众号类型、认证情况和平台开放权限不同，可用功能也会有差别。

界面与交互，保留现成组件，也方便定制

想先换个站点名称、登录背景或主题，可以从后台配置开始。需要调整表格、表单、弹窗等细节时，再查看 Layui 组件、模板和项目级扩展文件。普通部署可直接使用已有静态资源，修改 Less 主题源码后再运行主题构建。

做图表或内容编辑页面时，也能用到项目中的 ECharts、Vue、CKEditor 与 wangEditor 相关资源。页面文字通过语言键组织，已有语言包可以作为业务翻译的参考。

技术与组件

找代码时，可以先按下面几部分定位。依赖声明见 composer.json：

组件	职责
`zoujingli/think-library`	核心工具库、控制器与模型辅助能力、存储和任务服务
`zoujingli/think-plugs-admin`	后台基础管理模块
`zoujingli/think-plugs-wechat`	微信管理模块，当前项目已直接依赖，无需重复安装
`topthink/think-orm`	数据访问层，根依赖约束支持 2.x / 3.x

静态资源随相关插件发布到 public/static/。安装时，Composer 按项目的版本约束选择依赖；实际的 PHP 与扩展要求见环境要求。

环境要求

本地体验可以先用 SQLite，不需要单独启动 MySQL；正式项目可以根据团队的数据库环境选择。无论采用哪一种方式，都要先准备 PHP、Composer 和对应扩展。

项目	要求与说明
PHP	根依赖声明为 `>=7.1`，实际最低版本还受 ThinkPHP、ThinkLibrary 及其他依赖版本约束；建议使用仍受维护且与依赖兼容的 PHP 8.x
Composer	建议使用 Composer 2，并允许项目配置中的 `zoujingli/think-install` 插件执行安装流程
数据库	默认 SQLite；仓库同时提供 MySQL 连接配置。其他数据库需自行验证驱动、迁移和业务兼容性
Web 服务	本地调试可用 PHP 内置服务器；正式部署使用 Nginx、Apache 等，站点根目录设为 `public/`
命令行	异步任务和数据库迁移需要 PHP CLI；队列运行还需要相应的进程执行权限

PHP 扩展按实际依赖及使用场景安装：

核心库涉及 curl、gd、iconv、json、mbstring、openssl、zlib 等扩展，框架还涉及 ctype。
数据库需要 pdo，并按选择启用 pdo_sqlite 或 pdo_mysql。
微信 SDK 涉及 bcmath、libxml、simplexml、xml 等扩展；文件类型检测需要 fileinfo。
zip 可用于依赖包解压，Redis 等驱动按需配置，不是默认 SQLite / 文件缓存方案的前提。

安装依赖后，在项目根目录检查实际运行要求：

php -v
php -m
composer --no-plugins check-platform-reqs

项目声明的 PHP >=7.1 只是最外层的依赖条件，不代表每一种依赖组合都能运行在 PHP 7.1 上。check-platform-reqs 会检查你实际安装的版本是否满足要求。也请确认命令行与网站使用的是同一套兼容的 PHP 环境，避免出现“命令能运行，网页却报错”的情况。

快速开始

以下安装方式二选一，建议使用不含中文和空格的项目路径。Composer 创建项目适合从发布版本开始；克隆源码适合需要查看 Git 历史、跟进 v6 分支或参与开发的情况。当前默认安装包含后台管理和微信管理模块。

Composer 安装器会发布插件文件，并尝试执行数据库迁移。使用 MySQL 时，应先准备数据库和连接配置；已有项目安装或更新依赖前，应先备份数据库并保存本地代码改动。

方式一：Composer 创建项目

默认使用 SQLite，需先启用 pdo_sqlite：

composer create-project zoujingli/thinkadmin thinkadmin "^6.0"
cd thinkadmin

方式二：从源码安装

git clone --branch v6 https://github.com/zoujingli/ThinkAdmin.git thinkadmin
cd thinkadmin

默认 SQLite 可直接安装。使用 MySQL 时，先按数据库配置创建项目根目录的 .env，再执行：

composer install

初始化与启动

完成上述任一安装方式后，在项目根目录执行：

# 检查已安装依赖的 PHP 版本与扩展要求
composer --no-plugins check-platform-reqs

# 执行尚未完成的数据库迁移；自动迁移成功后通常没有待执行项
php think migrate:run

# 启动本地调试服务器
php think run --host 127.0.0.1 --port 8000

访问 http://127.0.0.1:8000/admin。默认根路径 / 也会跳转到后台登录页，并非独立门户首页。

首次初始化空用户表时，默认管理员账号为 admin，密码为 admin。首次登录后立即修改密码；已有数据库不会因此重置账号。PHP 内置服务器仅用于本地调试，不用于正式部署。

首次配置

安装完成后，可以按下面的顺序熟悉后台：

先处理账号与权限。 修改管理员密码，为实际使用人员创建独立账号，再分配所需的访问权限。
设置站点信息。 在“系统参数配置”中调整站点名称、登录背景和主题。修改后台登录入口后，记下新的访问地址。
确认文件上传可用。 选择本地或云存储，配置允许的文件类型，再用测试文件确认上传、图片选择和访问地址正常。
按需配置微信与任务。 使用微信功能时，再填写自己的公众号或商户参数；需要同步或批量处理时，启动队列监听并查看任务记录。
从一个简单业务页开始。 先完成一个列表和编辑表单，再逐步加入菜单、权限和其他业务流程。开发入口见下文开发与扩展。

配置与部署

数据库配置

连接配置见 config/database.php。默认 SQLite 数据文件为项目根目录下的 database/sqlite.db，PHP 运行用户需对该文件及所在目录拥有必要的写权限。

使用 MySQL 时，先创建数据库及数据库账号，再在项目根目录的 .env 中配置：

DB_TYPE=mysql
DB_MYSQL_HOST=127.0.0.1
DB_MYSQL_PORT=3306
DB_MYSQL_DATABASE=thinkadmin
DB_MYSQL_USERNAME=thinkadmin
DB_MYSQL_PASSWORD=replace_with_your_password
DB_MYSQL_CHARSET=utf8mb4
DB_MYSQL_PREFIX=

请替换示例中的连接信息，并为迁移准备所需的建表、改表权限。.env.example 还提供缓存和会话配置项，其中的主机和账号只是示例，不应直接用于生产环境。

修改数据库连接不会自动迁移旧数据库中的业务数据；切换数据库时需要另行安排数据迁移与校验。

缓存、会话与运行模式

开发时通常先使用默认的文件缓存和会话配置即可。接入 Redis、调整会话时间或上线部署时，再按项目需求修改：

缓存默认为文件驱动，Redis 配置见 config/cache.php。
会话配置见 config/session.php，可通过 SESSION_* 环境变量调整。
超级管理员可在“系统参数配置”中切换开发 / 生产模式。运行模式及后台入口映射保存在 runtime/.env，与项目根目录的连接配置 .env 不同。

正式部署

将站点根目录指向 public/，配置入口转发规则；Apache 可参考 public/.htaccess。不要直接暴露项目根目录。
启用 HTTPS，修改默认账号密码，按需分配权限并切换为生产模式。
为 runtime/、safefile/、本地上传目录 public/upload/ 设置必要写权限；SQLite 还需数据库目录可写。修改站点图标时需允许写入 public/favicon.ico，不要将整个项目设为全员可写。
保护 .env、runtime/.env、数据库和安全文件，定期备份数据及上传文件。
使用队列时，可用 Supervisor、systemd 等管理前台 php think xadmin:queue listen 进程，并检查进程与任务日志。

依赖更新

Composer 插件可能将文件复制到 app/、config/、public/ 等目录。如果你直接修改过基础插件或静态资源，更新依赖时就需要留意这些改动是否会被覆盖。

建议把升级分成几步：先保存当前代码并备份数据库与上传文件，再在测试环境更新，随后查看文件差异、迁移结果和关键业务页面。确认登录、权限、上传以及实际使用的业务流程正常后，再部署到正式环境。

本仓库未跟踪 composer.lock。业务项目应保存经过验证的依赖锁定文件与部署版本，避免不同环境重新解析出不同的依赖组合。

项目结构

ThinkAdmin/
|-- app/
|   |-- admin/          后台管理模块
|   |-- index/          默认入口，跳转后台登录
|   `-- wechat/         微信管理模块
|-- config/             应用、数据库、缓存等配置
|-- database/           数据库迁移脚本及默认 SQLite 数据文件
|-- public/
|   |-- index.php       Web 入口
|   |-- static/         前端组件、主题及扩展资源
|   `-- upload/         本地公开上传文件
|-- runtime/            运行缓存、日志及运行模式配置
|-- safefile/           本地安全文件与相关缓存
|-- vendor/             Composer 依赖与生成配置
|-- composer.json       项目依赖及自动加载配置
`-- think               命令行入口

部分目录和文件由依赖安装或运行过程生成，不一定出现在初始源码中。

开发与扩展

后台业务开发

业务应用可按 controller、model、view、service 等目录组织。建议将自定义业务放在独立应用中，减少直接修改基础插件带来的升级冲突；需要跨项目复用时，再封装为 Composer 插件。

例如，要新增一个客户管理模块，可以按下面的顺序开展：

先定义数据。 确定客户记录有哪些字段、哪些字段必须唯一、有哪些状态，以及数据归属如何判断，再准备数据表和模型。
完成查询列表。 在控制器中组织关键词、状态和时间等筛选条件，使用查询封装处理列表和分页。
编写页面模板。 定义表格列、筛选表单、编辑弹窗和操作按钮，复用已有的后台布局与组件。
补齐保存规则。 处理必填项、格式校验、重复数据和状态限制。金额、库存、审批状态等重要规则放在服务端，确保通过接口提交时也会检查。
接入菜单与授权。 标注需要权限或登录的方法，配置菜单，再用普通账号检查可见内容和允许的操作是否符合预期。

后台控制器通常继承 think\admin\Controller，使用 ThinkLibrary 的查询、表单、校验与状态更新能力。参考仓库中的实际实现：

需求	参考入口
列表筛选、表单与状态操作	系统用户控制器及对应模板
权限与菜单配置	权限控制器、菜单控制器
文件上传与上传配置	上传接口、上传脚本模板
命令注册与任务处理	微信服务注册、粉丝同步命令

权限注解用于描述控制器方法的访问要求：

@auth true：需要权限校验。
@login true：需要登录。
@menu true：标记可用于菜单配置的节点，不会自动创建完整菜单或角色授权。

菜单和按钮决定页面上能看到什么，控制器的权限校验决定请求能否执行，两边需要配合配置。至于一个账号能查看哪个部门、哪些客户的数据，还要在业务查询和操作逻辑中处理。

核心 API 与扩展说明请参阅 ThinkLibrary 和官方文档。

插件开发

一个模块只在当前项目中使用，可以先放在独立应用里。当几个项目都需要它，或者它有自己的版本和依赖时，再整理成插件。

插件通过 Composer 管理依赖、安装路径和服务注册。应用服务类继承 think\admin\Plugin，定义插件信息与 menu()，按需使用 register()、boot() 注册服务、命令和事件。这样可以将一组相关的控制器、模板、配置和数据初始化安排在同一个模块中维护。

可参考后台模块服务与微信模块服务。安装、更新和卸载时会处理哪些文件或数据，由插件配置和安装器决定；操作前先读插件文档，并做好备份。

前端定制

项目已包含可运行的静态资源，正常部署不需要额外执行前端构建。默认开发方式是 PHP 输出模板，再由 JavaScript 处理表格加载、表单提交和弹窗等交互，不要求你先搭建一个独立的前端单页应用。

现有页面中有一些常用约定，可以结合源码直接学习：

页面约定	作用
`data-modal`	打开服务端页面作为弹窗内容，常用于新增、编辑表单
`data-action`	发起操作请求，可配合 `data-confirm` 显示确认提示
`data-table-id`	在支持该参数的操作中，指定成功后需要刷新的表格
`data-auto`	将表单接入已有的校验和提交处理流程
`data-file`	接入文件上传或图片选择，按属性指定类型和参数

这些约定用于复用页面交互，具体的权限、字段校验和业务处理仍写在服务端。调整样式和脚本时，可以先从以下位置入手：

项目级样式和脚本扩展入口为 public/static/extra/style.css 和 public/static/extra/script.js。
后台通用交互位于 public/static/admin.js，第三方组件位于 public/static/plugs/。
主题 Less 源文件及构建脚本位于 public/static/theme/css/，只在修改主题源码时需要 Node.js 与相关编译工具。

修改主题后可执行：

npm install --global less less-plugin-clean-css
cd public/static/theme/css
npm run build

提交主题修改时，应同步提交相关 Less 源文件、生成的 CSS 和 source map，避免源码与页面实际使用的资源不一致。

常用命令

除主题构建外，下列命令均在项目根目录执行：

命令	用途
`php think list`	查看当前安装版本支持的命令
`php think help xadmin:queue`	查看队列命令参数
`php think migrate:status`	查看数据库迁移状态
`php think migrate:run`	执行尚未完成的迁移，会修改数据库
`php think clear`	清理运行缓存
`php think xadmin:queue start`	在后台启动队列监听进程
`php think xadmin:queue listen`	在前台监听任务，适合交给进程管理器托管
`php think xadmin:queue status`	查看队列监听进程状态
`php think xadmin:queue query`	查看相关队列进程，并非查询任务记录
`php think xadmin:queue stop`	停止相关队列进程，执行前确认在途任务

后台的“系统任务管理”用于查看任务记录、执行状态和进度。start 只负责启动后台进程，不等同于配置了开机启动或进程崩溃后的自动恢复。

常见问题

可以用于商业项目吗

不使用微信功能，可以只做普通后台吗

可以。当前依赖包含微信管理模块，但普通后台业务不要求先开通公众号或商户。你可以先使用账号、权限、菜单、列表和文件管理等功能，需要微信业务时再配置相关模块。

Composer 安装或 PHP 命令无法启动，先看哪里

先看错误信息指向的是 PHP 版本、缺少扩展，还是依赖下载失败。安装依赖后，可以用 composer --no-plugins check-platform-reqs 核对版本和扩展；命令行环境正常而网页报错时，还要检查 Web 服务实际使用的 PHP 配置。

如果依赖已下载，但资源发布或数据库迁移失败，应先解决后续步骤的报错，再完成安装流程。跳过平台检查或安装脚本可能让问题留到首次打开页面时才暴露。

后台出现 404 或无法登录，怎么检查

先确认站点根目录是 public/，再检查入口转发规则。新安装可访问 /admin 或 /admin/login/index.html；如果已经修改了后台入口，应使用新的地址。本仓库没有预置独立的 /api 应用入口。

如果能打开登录页但登录失败，还应确认当前数据库和账号信息。admin / admin 是首次初始化空用户表时的默认账号，不会在每次启动或升级后重新设置。

数据库连接或迁移失败，怎么处理

检查项目根目录 .env 与 config/database.php，确认实际选用的数据库、驱动和连接信息。SQLite 需要数据文件及所在目录可写；MySQL 需要先建库，并给执行迁移的账号配置必要权限。

涉及已有业务数据时，先备份再排查，不要通过删除数据库来解决迁移报错。切换到另一台数据库服务器，也需要同时确认原有数据是否已经迁移。

文件上传失败，应该检查哪些设置

文件类型和大小是否符合页面及后台存储配置的限制。
PHP 的 upload_max_filesize、post_max_size 以及 Web 服务的请求大小限制是否足够。
本地目录是否可写，云存储的账号、访问凭据和相关域名是否配置正确。
上传成功但图片无法显示时，继续检查返回地址、公开访问策略和域名，而不只是上传接口本身。

任务一直等待，或者失败后需要重跑怎么办

先确认队列监听进程是否在运行，再检查 PHP CLI 环境和进程执行权限。后台任务记录可以帮助区分“尚未开始”和“已经执行但失败”，任务代码报告的进度消息也能提供排查线索。

排除失败原因后，可按权限使用后台的重置入口重新排队。涉及支付、通知或其他有外部影响的任务，应先确认是否已经部分执行，再决定如何重跑。

排查错误时，可结合 runtime/ 下的应用日志、日志配置以及 Web 服务 / PHP 错误日志；公开反馈前请移除密码、密钥、令牌及用户数据。

交流与贡献

用下来有什么问题、有哪些地方值得改，欢迎带着具体的场景来交流。修复一个问题、补充一个例子，或者把不清楚的说明改明白，都是参与项目的方式。

源码仓库：GitHub、Gitee。
使用说明、插件文档和技术交流群入口：官方网站。
反馈问题时，附上版本、运行环境、复现步骤和脱敏后的错误信息，便于其他人定位。
提交 Pull Request 时，说明为什么改、怎样验证。不同功能尽量分开提交，前端源码与构建产物保持同步。
安全问题请按安全政策联系维护者，不要在公开 Issue 中披露敏感信息或未修复漏洞细节。

赞助支持

感谢以下支持方为 ThinkAdmin 的开发与维护提供支持：

JetBrains - 通过开源项目支持计划，为项目活跃贡献者提供一份 PhpStorm 使用许可，用于 ThinkAdmin 的非商业开源开发与维护。

工具推荐

狗狗加速 - 网络加速服务，帮助改善 ChatGPT 等在线工具的访问体验。（邀请注册链接）

支持项目

如果 ThinkAdmin 帮你省下了一些开发时间，欢迎 Star、分享给同样做 PHP 开发的朋友，或者 Fork 后参与改进。开发赞助方式可以在官方网站了解。

zoujingli / thinkadmin

Package info

Security

Statistics