ThinkAdmin

ThinkAdmin

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 内置服务器仅用于本地调试，不用于正式部署。

首次配置

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

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

配置与部署

数据库配置

连接配置见 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 插件。

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

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

后台控制器通常继承 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 只负责启动后台进程，不等同于配置了开机启动或进程崩溃后的自动恢复。

常见问题

可以用于商业项目吗

可以。ThinkAdmin 采用 MIT 许可证，允许按许可条款使用、修改和分发，包括商业用途。交付或分发时需要保留相应版权声明和许可文本；另外安装的组件、插件及第三方服务，要分别确认它们的许可和使用条件。

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

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

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

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