docs(readme): 优化技术定位与项目介绍文案

围绕技术方向与开发价值介绍项目,用具体场景说明账号权限、表单、上传和异步任务,减少机械句式与重复提醒。

保留安装配置、代码示例、许可和工具推荐内容,补充数据权限及业务校验说明。
This commit is contained in:
Anyon 2026-09-08 13:36:36 +08:00
parent 91fefbeeb3
commit 88890c2155

111
readme.md
View File

@ -6,11 +6,9 @@
[![PHP Version](https://img.shields.io/badge/php-%3E%3D7.1-blue.svg)](composer.json)
[![ThinkPHP](https://img.shields.io/badge/ThinkPHP-6%20%7C%208-brightgreen.svg)](https://www.thinkphp.cn/)
ThinkAdmin 是一套面向 **PHP 开发者**的开源后台开发框架,基于 **ThinkPHP**,提供用户、权限、菜单、表单、文件上传、异步任务和微信管理等常用功能
ThinkAdmin 是一套基于 **ThinkPHP 6 / 8** 的开源后台开发框架。后端使用 **ThinkLibrary** 封装常用功能,通过 **Composer** 管理依赖和插件;前端搭配 **Layui、jQuery 与 RequireJS**,沿用 PHP 模板配合 JavaScript 的开发方式
开发业务后台时许多基础工作总会反复出现给同事开账号、限制操作权限、做带筛选的列表、上传图片、处理耗时任务。ThinkAdmin 把这些常用能力和对应的管理页面放在一起,让你从一个可以运行、可以继续扩展的后台开始,把更多时间用在业务规则和功能交付上。
当前 v6 系列使用 **ThinkLibrary** 提供通用开发能力,通过 **Composer** 管理依赖和插件。默认页面采用 PHP 模板配合 JavaScript 交互的方式组织,熟悉 ThinkPHP 的开发者可以从现有控制器、模型和模板入手,逐步加入自己的业务。
做后台账号怎么分权限、列表怎么筛选、图片传到哪里这些问题总会遇到。ThinkAdmin 已经有了对应的功能和页面,你可以接着写自己的客户管理、订单处理或运营工具,**把重复搭建基础后台的时间,用在业务上**。需要在多个项目里使用同一套模块时,再把它整理成 Composer 插件。
[官方网站与开发文档](https://thinkadmin.top) · [在线演示](https://v6.thinkadmin.top) · [版本发布](https://github.com/zoujingli/ThinkAdmin/releases) · [问题反馈](https://github.com/zoujingli/ThinkAdmin/issues)
@ -35,26 +33,24 @@ ThinkAdmin 是一套面向 **PHP 开发者**的开源后台开发框架,基于
## 项目特点
- **常用管理功能已经具备。** 系统用户、权限、菜单、参数配置、日志和文件管理都有对应页面,可以作为业务后台的基础部分继续使用
- **列表和表单有一致的开发方式。** 查询筛选、分页、表单提交、数据校验和状态更新都有现成封装,做不同业务页面时可以沿用同一套写法
- **前后端代码便于对照。** 仓库同时包含控制器和页面模板,遇到筛选、弹窗、上传等需求,可以从一个完整功能中找到服务端和页面端的实现。
- **按项目需要扩展。** 可以在独立应用中编写业务,也可以把需要重复使用的模块整理成 Composer 插件。是否拆成插件,由项目的复用和维护需要决定
- **支持基于源码继续开发和交付。** 项目采用 MIT 许可证,可在遵守许可证的前提下用于个人或商业项目,修改界面与业务代码;第三方组件仍按各自的许可使用
- **基础管理不用从头搭。** 用户、权限、菜单、配置、日志和文件管理都有现成页面。先把后台跑起来,就可以从自己的业务模块开始做
- **列表和表单,有现成的写法。** ThinkLibrary 把筛选、分页、提交、校验和状态更新做了封装。熟悉一套流程后,后续页面可以继续沿用
- **页面和接口能对着看。** 控制器、模型、模板都在源码里。想知道某个筛选条件怎么生效、编辑弹窗怎么保存,顺着已有页面就能找到对应实现。
- **模块怎么拆,由业务决定。** 只用于当前项目的代码,可以放在独立应用中;需要跨项目复用时,再用 Composer 管理插件的依赖和版本
- **能自己改,也能用于商业项目。** 项目采用 MIT 许可证,允许按许可条款修改、使用和分发。交付时保留版权与许可文本,并留意第三方组件各自的授权要求
## 适用场景
ThinkAdmin 更适合需要自行开发业务、又希望复用通用后台能力的项目
如果你正在给团队做一个内部系统或者为客户开发一套管理后台ThinkAdmin 可以承担其中常见的基础工作
| 项目场景 | 可以复用的部分 | 需要补充的业务 |
| --- | --- | --- |
| 企业内部管理 | 账号、权限、菜单、列表、表单和日志 | 客户、订单、审批等具体流程 |
| 内容与运营后台 | 图文编辑、文件上传、分类字典和状态管理 | 内容模型、审核规则、展示页面 |
| 微信公众号相关业务 | 粉丝、菜单、图文、回复规则及支付管理基础 | 自己的账号配置、活动逻辑和业务订单 |
| 项目原型与定制开发 | 已有后台界面、数据操作方式和基础组件 | 行业数据模型、业务规则及交付细节 |
- 做客户、订单或审批管理时,沿用已有的账号、权限、列表和表单,再编写具体的业务流程。
- 做内容运营后台时,接入图文编辑、图片上传和分类字典,把精力放在内容模型、审核和展示上。
- 做微信公众号业务时,在同一个后台处理粉丝、菜单、回复和支付相关操作,再对接自己的活动或订单。
- 做原型或定制项目时,先用已有界面把业务流程串起来,再逐步补充细节。
如果你熟悉 PHP / ThinkPHP希望在已有后台上持续开发自己的系统可以先通过[在线演示](https://v6.thinkadmin.top)了解操作方式,再结合源码评估是否适合项目
拿不准是否适合,可以先看看[在线演示](https://v6.thinkadmin.top),挑一个熟悉的功能,再对照源码走一遍。对熟悉 PHP / ThinkPHP 的开发者,这也是了解项目开发方式的直接途径。
CRM、ERP、OA、多租户或订阅系统都可以作为业务开发方向但它们的业务规则、数据隔离和计费逻辑仍需要按项目要求实现。
ThinkAdmin 做的是通用后台基础。客户怎么分配、订单如何流转、不同租户的数据怎样隔离,这些仍由你的业务模块来实现。
## 功能概览
@ -70,71 +66,58 @@ CRM、ERP、OA、多租户或订阅系统都可以作为业务开发方向
### 账号、菜单与日常管理
系统用户管理提供账号维护、密码修改、状态管理和权限分配等操作。系统菜单管理用来组织后台入口,参数配置用来调整站点名称、登录入口、主题和存储设置
新同事来了,给他开一个账号;岗位变了,调整可用权限;人员离职了,再停用账号。这些日常工作可以直接在系统用户管理中完成。菜单管理负责组织后台入口,站点名称、登录背景、主题和存储方式则在参数配置中调整
对实际项目来说,这些功能可以承接常见的管理工作:为新同事创建账号、调整可访问的模块、停用离职人员账号,或者修改网站显示信息。你可以在此基础上增加业务页面,不必为每个项目重新设计一套管理入口。
数据字典可统一维护分类、编码等基础选项;操作日志可查看已记录的管理行为,并按账号、操作类型、时间等条件查找。自定义业务需要记录的关键操作,可以继续接入这套日志能力。
分类、编码等经常变动的基础选项,可以放到数据字典中维护。想查某个账号最近做过哪些已记录的管理操作,可以按时间、账号或操作类型筛选日志;自己的业务模块也可以接入同一套日志记录方式。
### 权限配置,从页面入口到具体操作
ThinkAdmin 通过控制器方法上的注解描述登录和权限要求,再结合后台授权配置决定哪些账号可以访问哪些功能。模板中的权限判断可以控制按钮显示,服务端同时负责对应接口的访问校验
比如,你希望运营人员能查看和编辑资料,但把删除和系统配置留给管理员。可以在控制器方法上标注登录或权限要求,再到后台配置相应授权
例如,一个运营账号可以查看和编辑指定资料,但没有删除或修改系统配置的权限。开发新功能时,按同样的方式标注方法、配置菜单和授权,就能将业务功能纳入现有权限管理。
这套机制主要解决功能访问权限。部门数据范围、订单归属、多租户隔离等业务规则,需要在自己的查询和操作逻辑中继续处理。
页面上的按钮根据权限显示,接口请求也由服务端校验。新增业务时,按同样的方式接入,就可以把新页面和新操作放进现有的权限管理中。具体注解和数据权限的处理见[开发与扩展](#开发与扩展)。
### 列表与表单,沿用熟悉的开发方式
后台页面经常需要按关键词、状态、时间范围筛选数据也需要分页、编辑弹窗、保存提示和状态开关。ThinkLibrary 的数据操作封装与项目的前端组件共同处理这些重复工作
一个常见的管理页上面按关键词、状态和时间筛选下面是带分页的表格点击“编辑”打开表单保存后刷新列表。ThinkLibrary 和现有前端组件已经给这类页面准备了对应的写法
仓库中的系统用户页面就是一个完整参考:控制器组织筛选条件,模板定义表格列和操作按钮,表单负责输入与提交。新业务可以参照这条流程,替换为自己的模型、字段和校验规则。
通用封装负责处理常见流程,业务逻辑仍由你掌握。涉及金额、库存、审批状态等操作时,应在服务端明确校验规则和允许的状态变化。
可以从仓库的系统用户页面开始看:控制器怎样组织查询,模板怎样定义列和按钮,表单怎样提交。做自己的业务时,再换成对应的模型、字段和校验规则。许多页面虽然管理的数据不同,基本流程可以共用。
### 文件与图片,按需要选择存储方式
开发阶段可以使用本地存储;业务需要时,也可以配置 Alist、七牛云、阿里云 OSS、腾讯云 COS 或又拍云。上传组件读取统一的文件类型、大小、存储方式和图片处理参数,业务页面可以复用同一套上传交互
头像、封面、内容配图和附件往往分散在不同表单里。ThinkAdmin 用一套上传组件处理这些需求,各页面通过参数指定文件类型、大小、存储方式和图片尺寸
- **文件复用:** 上传流程支持计算文件哈希并检查对应存储文件,已存在时可以复用结果,避免再次传输相同文件内容
- **图片处理:** 支持单图、多图上传与图片选择,以及按参数进行图片压缩、尺寸限制和裁切,适合头像、封面和内容配图等场景
- **文件管理:** 后台可查看文件记录、按条件查找文件,并在授权范围内编辑、删除或清理重复记录。
- **安全文件:** 安全模式文件使用本地 `safefile/` 目录,与公开上传目录分开保存;业务中谁能读取这些文件,仍应由相应接口控制。
- **相同文件可以少传一次。** 上传流程支持计算文件哈希,检查对应存储文件是否已存在;命中后直接复用结果
- **图片按用途处理。** 单图、多图、图片选择都有对应入口,压缩质量、最大宽高和裁切尺寸按页面需要设置
- **上传记录集中管理。** 后台可以查找文件记录,并在授权范围内编辑、删除或清理重复记录。
- **公开文件和安全文件分开存放。** 例如支付证书可以使用安全模式,保存到本地 `safefile/`,读取权限由业务接口另行控制。
各存储服务需要配置自己的连接信息或访问凭据。更换存储方式影响后续上传,已有文件的搬迁和地址调整需要另外处理
开发时可以先用本地存储,有需要再接入 Alist、七牛云、阿里云 OSS、腾讯云 COS 或又拍云。配置好对应账号和访问凭据后,业务页面仍可沿用上传组件;已有文件的搬迁和地址调整需要单独安排
### 耗时工作,交给后台任务执行
批量同步、数据整理或其他耗时操作不适合一直占用用户当前的页面请求。ThinkAdmin 提供任务登记、队列监听、独立进程执行和进度展示,页面可以发起任务,再从“系统任务管理”查看执行情况
同步一批粉丝、整理一批数据,可能比普通页面请求花更长时间。这类工作可以登记成任务,由队列监听进程安排执行,再到“系统任务管理”查看状态和结果
队列支持延时和循环任务,后台提供执行记录、进度和重跑入口。任务代码可以主动报告“已处理多少条”“进行到哪一步”等进度,方便使用者了解处理情况。仓库中的微信粉丝同步命令可以作为实际参考,自定义任务也可以沿用相同的任务管理方式
任务代码可以报告“处理到第几条”“目前完成多少”等进度。延时执行、循环任务和后台重置重跑也有对应入口;仓库里的微信粉丝同步命令就是一个实际例子,可以参考它编写自己的任务
使用时需要启动队列监听进程。重试规则以及重复执行时如何避免重复扣款、重复通知等问题,应由具体任务设计;生产环境的进程托管方式见[配置与部署](#配置与部署)。
先启动监听进程,任务才会被处理。部署方式见[配置与部署](#配置与部署),失败后的排查与重跑见下方[常见问题](#常见问题)。
### 微信管理,集中处理常见公众号操作
默认微信模块提供常见的公众号管理和微信支付管理功能,适合将微信运营与自己的业务后台放在一起:
如果项目围绕微信公众号开展业务,可以把常见运营操作放到同一个后台:同步粉丝资料,查看关注状态和黑名单,维护图文内容、菜单、关键词与关注回复。
- 配置公众号接口,同步和查看粉丝资料、关注状态及黑名单等信息。
- 维护图文素材、自定义菜单和回复规则。
- 配置关注回复与相关消息处理。
- 配置微信支付参数,查看支付记录并处理退款相关操作。
微信模块也包含商户参数配置、支付记录和退款相关操作,便于接入自己的订单或活动流程。它管理的是这些通用环节,具体订单怎样生成、付款后执行什么业务,仍由项目代码处理。
使用前需要准备自己的公众号或商户信息,按微信要求配置回调地址、域名和接口权限。具体能使用哪些能力,也取决于账号类型及微信平台开放的权限;业务订单和活动流程则需要与你自己的系统对接
开始使用前,先填写自己的公众号或商户信息,按微信要求设置回调地址、域名和接口权限。公众号类型、认证情况和平台开放权限不同,可用功能也会有差别。
### 界面与交互,保留现成组件,也方便定制
默认后台使用 Layui、jQuery 和 RequireJS提供表格、表单、弹窗、日期选择、文件上传等常见交互。项目还包含 ECharts、Vue、CKEditor 与 wangEditor 相关资源,可根据页面需求使用
想先换个站点名称、登录背景或主题,可以从后台配置开始。需要调整表格、表单、弹窗等细节时,再查看 Layui 组件、模板和项目级扩展文件。普通部署可直接使用已有静态资源,修改 Less 主题源码后再运行主题构建
普通部署可以直接使用仓库中的静态资源。调整站点名称、登录背景和主题可以从后台配置开始;需要更细的样式或交互时,可使用项目级扩展文件,也可以修改模板。修改 Less 主题源码时,再执行对应的主题构建。
项目使用语言键组织界面文字,并提供已有语言包作为参考。增加业务页面或补充其他语言时,需要同步维护相应文字与翻译。
做图表或内容编辑页面时,也能用到项目中的 ECharts、Vue、CKEditor 与 wangEditor 相关资源。页面文字通过语言键组织,已有语言包可以作为业务翻译的参考。
## 技术与组件
ThinkAdmin 项目、核心库和应用插件各有职责。了解这些部分,更容易判断一个改动应该放在哪里:
默认依赖见 [composer.json](composer.json)
找代码时,可以先按下面几部分定位。依赖声明见 [composer.json](composer.json)
| 组件 | 职责 |
| --- | --- |
@ -143,9 +126,7 @@ ThinkAdmin 项目、核心库和应用插件各有职责。了解这些部分,
| `zoujingli/think-plugs-wechat` | 微信管理模块,当前项目已直接依赖,无需重复安装 |
| `topthink/think-orm` | 数据访问层,根依赖约束支持 2.x / 3.x |
后台页面的通用能力主要来自 ThinkLibrary后台管理和微信管理由对应插件提供。静态资源由相关插件引入并发布到 `public/static/`ThinkORM 负责数据访问。
当前项目面向 ThinkPHP 6 / 8 相关依赖组合,安装时由 Composer 根据版本约束选择依赖。更多组件、版本要求及适用范围以各插件文档和实际安装结果为准。
静态资源随相关插件发布到 `public/static/`。安装时Composer 按项目的版本约束选择依赖;实际的 PHP 与扩展要求见[环境要求](#环境要求)。
## 环境要求
@ -314,7 +295,7 @@ ThinkAdmin/
1. **先定义数据。** 确定客户记录有哪些字段、哪些字段必须唯一、有哪些状态,以及数据归属如何判断,再准备数据表和模型。
2. **完成查询列表。** 在控制器中组织关键词、状态和时间等筛选条件,使用查询封装处理列表和分页。
3. **编写页面模板。** 定义表格列、筛选表单、编辑弹窗和操作按钮,复用已有的后台布局与组件。
4. **补齐保存规则。** 处理必填项、格式校验、重复数据和状态限制重要规则放在服务端,确保通过接口提交时也会检查。
4. **补齐保存规则。** 处理必填项、格式校验、重复数据和状态限制。金额、库存、审批状态等重要规则放在服务端,确保通过接口提交时也会检查。
5. **接入菜单与授权。** 标注需要权限或登录的方法,配置菜单,再用普通账号检查可见内容和允许的操作是否符合预期。
后台控制器通常继承 `think\admin\Controller`,使用 ThinkLibrary 的查询、表单、校验与状态更新能力。参考仓库中的实际实现:
@ -332,15 +313,17 @@ ThinkAdmin/
- `@login true`:需要登录。
- `@menu true`:标记可用于菜单配置的节点,不会自动创建完整菜单或角色授权。
新增后台页面还需配置菜单与对应权限;不能把“菜单不可见”等同于接口已受保护。核心 API 与扩展说明请参阅 [ThinkLibrary](https://github.com/zoujingli/ThinkLibrary) 和[官方文档](https://thinkadmin.top)。
菜单和按钮决定页面上能看到什么,控制器的权限校验决定请求能否执行,两边需要配合配置。至于一个账号能查看哪个部门、哪些客户的数据,还要在业务查询和操作逻辑中处理。
核心 API 与扩展说明请参阅 [ThinkLibrary](https://github.com/zoujingli/ThinkLibrary) 和[官方文档](https://thinkadmin.top)。
### 插件开发
如果一个模块只服务于当前项目,先放在独立应用中通常更直接。如果它需要在多个项目间复用,或者需要单独维护版本和依赖,再整理成插件会更方便
一个模块只在当前项目中使用,可以先放在独立应用里。当几个项目都需要它,或者它有自己的版本和依赖时,再整理成插件
插件通过 Composer 管理依赖、安装路径和服务注册。应用服务类继承 `think\admin\Plugin`,定义插件信息与 `menu()`,按需使用 `register()``boot()` 注册服务、命令和事件。这样可以将一组相关的控制器、模板、配置和数据初始化安排在同一个模块中维护。
可参考 [后台模块服务](app/admin/Service.php)与[微信模块服务](app/wechat/Service.php)。安装、更新和卸载行为取决于插件包的配置及安装器逻辑,不能假定卸载一定保留或一定删除数据;操作前应阅读插件文档并备份。
可参考 [后台模块服务](app/admin/Service.php)与[微信模块服务](app/wechat/Service.php)。安装、更新和卸载时会处理哪些文件或数据,由插件配置和安装器决定;操作前先读插件文档,并做好备份。
### 前端定制
@ -436,14 +419,14 @@ npm run build
## 交流与贡献
用下来有什么问题、有哪些地方值得改,欢迎带着具体的场景来交流。修复一个问题、补充一个例子,或者把不清楚的说明改明白,都是参与项目的方式。
- 源码仓库:[GitHub](https://github.com/zoujingli/ThinkAdmin)、[Gitee](https://gitee.com/zoujingli/ThinkAdmin)。
- 使用说明、插件文档和技术交流群入口:[官方网站](https://thinkadmin.top)。
- 报告问题时,请提供版本、运行环境、复现步骤和脱敏后的错误信息。
- 提交 Pull Request 时,请说明修改目的和验证方式,不同功能尽量拆分提交;涉及前端源码与构建产物时保持同步。
- 反馈问题时,附上版本、运行环境、复现步骤和脱敏后的错误信息,便于其他人定位
- 提交 Pull Request 时,说明为什么改、怎样验证。不同功能尽量分开提交,前端源码与构建产物保持同步。
- 安全问题请按[安全政策](security.md)联系维护者,不要在公开 Issue 中披露敏感信息或未修复漏洞细节。
欢迎贡献代码、完善文档、提交可复现的问题以及分享实践经验。
## 赞助支持
感谢以下支持方为 ThinkAdmin 的开发与维护提供支持:
@ -456,7 +439,7 @@ npm run build
## 支持项目
如果 ThinkAdmin 对你有帮助,欢迎 Star、Fork、分享项目或参与代码和文档贡献。开发赞助方式请访问[官方网站](https://thinkadmin.top)了解。
如果 ThinkAdmin 帮你省下了一些开发时间,欢迎 Star、分享给同样做 PHP 开发的朋友,或者 Fork 后参与改进。开发赞助方式可以在[官方网站](https://thinkadmin.top)了解。
## 开源协议