ThinkAdmin

README

# ThinkAdmin

[![Latest Stable Version](https://poser.pugx.org/zoujingli/thinkadmin/v/stable)](https://packagist.org/packages/zoujingli/thinkadmin)
[![Total Downloads](https://poser.pugx.org/zoujingli/thinkadmin/downloads)](https://packagist.org/packages/zoujingli/thinkadmin)
[![License](https://poser.pugx.org/zoujingli/thinkadmin/license)](license)
[![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 是一套基于 **ThinkPHP 6 / 8** 的开源后台开发框架。后端使用 **ThinkLibrary** 封装常用功能，通过 **Composer** 管理依赖和插件；前端搭配 **Layui、jQuery 与 RequireJS**，沿用 PHP 模板配合 JavaScript 的开发方式。

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

[官方网站与开发文档](https://thinkadmin.top) · [在线演示](https://v6.thinkadmin.top) · [版本发布](https://github.com/zoujingli/ThinkAdmin/releases) · [问题反馈](https://github.com/zoujingli/ThinkAdmin/issues)

## 目录

- [✨ 项目特点](#项目特点)
- [🎯 适用场景](#适用场景)
- [🧩 功能概览](#功能概览)
- [🛠️ 技术与组件](#技术与组件)
- [📋 环境要求](#环境要求)
- [🚀 快速开始](#快速开始)
- [⚙️ 配置与部署](#配置与部署)
- [🗂️ 项目结构](#项目结构)
- [💻 开发与扩展](#开发与扩展)
- [⌨️ 常用命令](#常用命令)
- [❓ 常见问题](#常见问题)
- [💬 交流与贡献](#交流与贡献)
- [🤝 赞助支持](#赞助支持)
- [🧰 工具推荐](#工具推荐)
- [⭐ 支持项目](#支持项目)
- [📄 开源协议](#开源协议)

## 项目特点

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

## 适用场景

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

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

拿不准是否适合，可以先看看[在线演示](https://v6.thinkadmin.top)，挑一个熟悉的功能，再对照源码走一遍。对熟悉 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](https://gitee.com/zoujingli/ThinkAdmin/blob/v6/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 / 文件缓存方案的前提。

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

```bash
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`：

```bash
composer create-project zoujingli/thinkadmin thinkadmin "^6.0"
c