blackteay/ThinkAdmin
1
0
Fork 0
mirror of https://gitee.com/zoujingli/ThinkAdmin.git synced 2026-09-18 05:15:40 +08:00
Code Issues Projects Releases Wiki Activity
ThinkAdmin/readme.md
Anyon 89f01d57fc docs(readme): 增加章节图标并保留目录锚点 
为二级标题添加适量 emoji，改善长文档的浏览体验。

保留原有章节名称锚点，确保目录及已有章节链接继续有效，不改动正文和示例。
2026-09-08 13:37:23 +08:00

483 lines
30 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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)
<a id="目录"></a>
## 📑 目录
- [项目特点](#项目特点)
- [适用场景](#适用场景)
- [功能概览](#功能概览)
- [技术与组件](#技术与组件)
- [环境要求](#环境要求)
- [快速开始](#快速开始)
- [配置与部署](#配置与部署)
- [项目结构](#项目结构)
- [开发与扩展](#开发与扩展)
- [常用命令](#常用命令)
- [常见问题](#常见问题)
- [交流与贡献](#交流与贡献)
- [赞助支持](#赞助支持)
- [工具推荐](#工具推荐)
- [支持项目](#支持项目)
- [开源协议](#开源协议)
<a id="项目特点"></a>
## ✨ 项目特点
- **基础管理不用从头搭。** 用户、权限、菜单、配置、日志和文件管理都有现成页面。先把后台跑起来，就可以从自己的业务模块开始做。
- **列表和表单，有现成的写法。** ThinkLibrary 把筛选、分页、提交、校验和状态更新做了封装。熟悉一套流程后，后续页面可以继续沿用。
- **页面和接口能对着看。** 控制器、模型、模板都在源码里。想知道某个筛选条件怎么生效、编辑弹窗怎么保存，顺着已有页面就能找到对应实现。
- **模块怎么拆，由业务决定。** 只用于当前项目的代码，可以放在独立应用中；需要跨项目复用时，再用 Composer 管理插件的依赖和版本。
- **能自己改，也能用于商业项目。** 项目采用 MIT 许可证，允许按许可条款修改、使用和分发。交付时保留版权与许可文本，并留意第三方组件各自的授权要求。
<a id="适用场景"></a>
## 🎯 适用场景
如果你正在给团队做一个内部系统，或者为客户开发一套管理后台，ThinkAdmin 可以承担其中常见的基础工作：
- 做客户、订单或审批管理时，沿用已有的账号、权限、列表和表单，再编写具体的业务流程。
- 做内容运营后台时，接入图文编辑、图片上传和分类字典，把精力放在内容模型、审核和展示上。
- 做微信公众号业务时，在同一个后台处理粉丝、菜单、回复和支付相关操作，再对接自己的活动或订单。
- 做原型或定制项目时，先用已有界面把业务流程串起来，再逐步补充细节。
拿不准是否适合，可以先看看[在线演示](https://v6.thinkadmin.top)，挑一个熟悉的功能，再对照源码走一遍。对熟悉 PHP / ThinkPHP 的开发者，这也是了解项目开发方式的直接途径。
ThinkAdmin 做的是通用后台基础。客户怎么分配、订单如何流转、不同租户的数据怎样隔离，这些仍由你的业务模块来实现。
<a id="功能概览"></a>
## 🧩 功能概览
| 能力 | 说明 |
| --- | --- |
| 后台管理 | 系统用户、权限、菜单、参数配置、数据字典、操作日志和文件管理 |
| 权限控制 | 基于控制器注解的登录与权限校验，配合菜单、角色授权控制后台访问 |
| 数据操作 | 查询筛选、分页、表单处理、输入校验、状态更新和删除等通用封装 |
| 文件存储 | 本地、Alist、七牛云、阿里云 OSS、腾讯云 COS、又拍云；支持文件哈希检查和图片处理 |
| 异步任务 | 任务登记、独立进程执行、进度展示和执行结果管理 |
| 微信管理 | 公众号配置、粉丝、图文、菜单、自动回复，以及微信支付记录和退款管理 |
| 前端组件 | Layui、jQuery、RequireJS，以及按需使用的 ECharts、Vue 和富文本编辑器 |
### 账号、菜单与日常管理
新同事来了，给他开一个账号；岗位变了，调整可用权限；人员离职了，再停用账号。这些日常工作可以直接在系统用户管理中完成。菜单管理负责组织后台入口，站点名称、登录背景、主题和存储方式则在参数配置中调整。
分类、编码等经常变动的基础选项，可以放到数据字典中维护。想查某个账号最近做过哪些已记录的管理操作，可以按时间、账号或操作类型筛选日志；自己的业务模块也可以接入同一套日志记录方式。
### 权限配置，从页面入口到具体操作
比如，你希望运营人员能查看和编辑资料，但把删除和系统配置留给管理员。可以在控制器方法上标注登录或权限要求，再到后台配置相应授权。
页面上的按钮根据权限显示，接口请求也由服务端校验。新增业务时，按同样的方式接入，就可以把新页面和新操作放进现有的权限管理中。具体注解和数据权限的处理见[开发与扩展](#开发与扩展)。
### 列表与表单，沿用熟悉的开发方式
一个常见的管理页：上面按关键词、状态和时间筛选，下面是带分页的表格，点击“编辑”打开表单，保存后刷新列表。ThinkLibrary 和现有前端组件已经给这类页面准备了对应的写法。
可以从仓库的系统用户页面开始看：控制器怎样组织查询，模板怎样定义列和按钮，表单怎样提交。做自己的业务时，再换成对应的模型、字段和校验规则。许多页面虽然管理的数据不同，基本流程可以共用。
### 文件与图片，按需要选择存储方式
头像、封面、内容配图和附件，往往分散在不同表单里。ThinkAdmin 用一套上传组件处理这些需求，各页面通过参数指定文件类型、大小、存储方式和图片尺寸。
- **相同文件可以少传一次。** 上传流程支持计算文件哈希，检查对应存储文件是否已存在；命中后直接复用结果。
- **图片按用途处理。** 单图、多图、图片选择都有对应入口，压缩质量、最大宽高和裁切尺寸按页面需要设置。
- **上传记录集中管理。** 后台可以查找文件记录，并在授权范围内编辑、删除或清理重复记录。
- **公开文件和安全文件分开存放。** 例如支付证书可以使用安全模式，保存到本地 `safefile/`，读取权限由业务接口另行控制。
开发时可以先用本地存储，有需要再接入 Alist、七牛云、阿里云 OSS、腾讯云 COS 或又拍云。配置好对应账号和访问凭据后，业务页面仍可沿用上传组件；已有文件的搬迁和地址调整需要单独安排。
### 耗时工作，交给后台任务执行
同步一批粉丝、整理一批数据，可能比普通页面请求花更长时间。这类工作可以登记成任务，由队列监听进程安排执行，再到“系统任务管理”查看状态和结果。
任务代码可以报告“处理到第几条”“目前完成多少”等进度。延时执行、循环任务和后台重置重跑也有对应入口；仓库里的微信粉丝同步命令就是一个实际例子，可以参考它编写自己的任务。
先启动监听进程，任务才会被处理。部署方式见[配置与部署](#配置与部署)，失败后的排查与重跑见下方[常见问题](#常见问题)。
### 微信管理，集中处理常见公众号操作
如果项目围绕微信公众号开展业务，可以把常见运营操作放到同一个后台：同步粉丝资料，查看关注状态和黑名单，维护图文内容、菜单、关键词与关注回复。
微信模块也包含商户参数配置、支付记录和退款相关操作，便于接入自己的订单或活动流程。它管理的是这些通用环节，具体订单怎样生成、付款后执行什么业务，仍由项目代码处理。
开始使用前，先填写自己的公众号或商户信息，按微信要求设置回调地址、域名和接口权限。公众号类型、认证情况和平台开放权限不同，可用功能也会有差别。
### 界面与交互，保留现成组件，也方便定制
想先换个站点名称、登录背景或主题，可以从后台配置开始。需要调整表格、表单、弹窗等细节时，再查看 Layui 组件、模板和项目级扩展文件。普通部署可直接使用已有静态资源，修改 Less 主题源码后再运行主题构建。
做图表或内容编辑页面时，也能用到项目中的 ECharts、Vue、CKEditor 与 wangEditor 相关资源。页面文字通过语言键组织，已有语言包可以作为业务翻译的参考。
<a id="技术与组件"></a>
## 🛠️ 技术与组件
找代码时，可以先按下面几部分定位。依赖声明见 [composer.json](composer.json)：
| 组件 | 职责 |
| --- | --- |
| `zoujingli/think-library` | 核心工具库、控制器与模型辅助能力、存储和任务服务 |
| `zoujingli/think-plugs-admin` | 后台基础管理模块 |
| `zoujingli/think-plugs-wechat` | 微信管理模块，当前项目已直接依赖，无需重复安装 |
| `topthink/think-orm` | 数据访问层，根依赖约束支持 2.x / 3.x |
静态资源随相关插件发布到 `public/static/`。安装时，Composer 按项目的版本约束选择依赖；实际的 PHP 与扩展要求见[环境要求](#环境要求)。
<a id="环境要求"></a>
## 📋 环境要求
本地体验可以先用 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 环境，避免出现“命令能运行，网页却报错”的情况。
<a id="快速开始"></a>
## 🚀 快速开始
以下安装方式二选一，建议使用不含中文和空格的项目路径。Composer 创建项目适合从发布版本开始；克隆源码适合需要查看 Git 历史、跟进 v6 分支或参与开发的情况。当前默认安装包含后台管理和微信管理模块。
> Composer 安装器会发布插件文件，并尝试执行数据库迁移。使用 MySQL 时，应先准备数据库和连接配置；已有项目安装或更新依赖前，应先备份数据库并保存本地代码改动。
### 方式一：Composer 创建项目
默认使用 SQLite，需先启用 `pdo_sqlite`：
```bash
composer create-project zoujingli/thinkadmin thinkadmin "^6.0"
cd thinkadmin
```
### 方式二：从源码安装
```bash
git clone --branch v6 https://github.com/zoujingli/ThinkAdmin.git thinkadmin
cd thinkadmin
```
默认 SQLite 可直接安装。使用 MySQL 时，先按[数据库配置](#数据库配置)创建项目根目录的 `.env`，再执行：
```bash
composer install
```
### 初始化与启动
完成上述任一安装方式后，在项目根目录执行：
```bash
# 检查已安装依赖的 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](http://127.0.0.1:8000/admin)。默认根路径 `/` 也会跳转到后台登录页，并非独立门户首页。
首次初始化空用户表时，默认管理员账号为 `admin`，密码为 `admin`。首次登录后立即修改密码；已有数据库不会因此重置账号。PHP 内置服务器仅用于本地调试，不用于正式部署。
### 首次配置
安装完成后，可以按下面的顺序熟悉后台：
1. **先处理账号与权限。** 修改管理员密码，为实际使用人员创建独立账号，再分配所需的访问权限。
2. **设置站点信息。** 在“系统参数配置”中调整站点名称、登录背景和主题。修改后台登录入口后，记下新的访问地址。
3. **确认文件上传可用。** 选择本地或云存储，配置允许的文件类型，再用测试文件确认上传、图片选择和访问地址正常。
4. **按需配置微信与任务。** 使用微信功能时，再填写自己的公众号或商户参数；需要同步或批量处理时，启动队列监听并查看任务记录。
5. **从一个简单业务页开始。** 先完成一个列表和编辑表单，再逐步加入菜单、权限和其他业务流程。开发入口见下文[开发与扩展](#开发与扩展)。
<a id="配置与部署"></a>
## ⚙️ 配置与部署
### 数据库配置
连接配置见 [config/database.php](config/database.php)。默认 SQLite 数据文件为项目根目录下的 `database/sqlite.db`，PHP 运行用户需对该文件及所在目录拥有必要的写权限。
使用 MySQL 时，先创建数据库及数据库账号，再在项目根目录的 `.env` 中配置：
```ini
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](.env.example) 还提供缓存和会话配置项，其中的主机和账号只是示例，不应直接用于生产环境。
修改数据库连接不会自动迁移旧数据库中的业务数据；切换数据库时需要另行安排数据迁移与校验。
### 缓存、会话与运行模式
开发时通常先使用默认的文件缓存和会话配置即可。接入 Redis、调整会话时间或上线部署时，再按项目需求修改：
- 缓存默认为文件驱动，Redis 配置见 [config/cache.php](config/cache.php)。
- 会话配置见 [config/session.php](config/session.php)，可通过 `SESSION_*` 环境变量调整。
- 超级管理员可在“系统参数配置”中切换开发 / 生产模式。运行模式及后台入口映射保存在 `runtime/.env`，与项目根目录的连接配置 `.env` 不同。
### 正式部署
- 将站点根目录指向 `public/`，配置入口转发规则；Apache 可参考 [public/.htaccess](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`。业务项目应保存经过验证的依赖锁定文件与部署版本，避免不同环境重新解析出不同的依赖组合。
<a id="项目结构"></a>
## 🗂️ 项目结构
```text
ThinkAdmin/
|-- app/
| |-- admin/ 后台管理模块
| |-- index/ 默认入口，跳转后台登录
| `-- wechat/ 微信管理模块
|-- config/ 应用、数据库、缓存等配置
|-- database/ 数据库迁移脚本及默认 SQLite 数据文件
|-- public/
| |-- index.php Web 入口
| |-- static/ 前端组件、主题及扩展资源
| `-- upload/ 本地公开上传文件
|-- runtime/ 运行缓存、日志及运行模式配置
|-- safefile/ 本地安全文件与相关缓存
|-- vendor/ Composer 依赖与生成配置
|-- composer.json 项目依赖及自动加载配置
`-- think 命令行入口
```
部分目录和文件由依赖安装或运行过程生成，不一定出现在初始源码中。
<a id="开发与扩展"></a>
## 💻 开发与扩展
### 后台业务开发
业务应用可按 `controller`、`model`、`view`、`service` 等目录组织。建议将自定义业务放在独立应用中，减少直接修改基础插件带来的升级冲突；需要跨项目复用时，再封装为 Composer 插件。
例如，要新增一个客户管理模块，可以按下面的顺序开展：
1. **先定义数据。** 确定客户记录有哪些字段、哪些字段必须唯一、有哪些状态，以及数据归属如何判断，再准备数据表和模型。
2. **完成查询列表。** 在控制器中组织关键词、状态和时间等筛选条件，使用查询封装处理列表和分页。
3. **编写页面模板。** 定义表格列、筛选表单、编辑弹窗和操作按钮，复用已有的后台布局与组件。
4. **补齐保存规则。** 处理必填项、格式校验、重复数据和状态限制。金额、库存、审批状态等重要规则放在服务端，确保通过接口提交时也会检查。
5. **接入菜单与授权。** 标注需要权限或登录的方法，配置菜单，再用普通账号检查可见内容和允许的操作是否符合预期。
后台控制器通常继承 `think\admin\Controller`，使用 ThinkLibrary 的查询、表单、校验与状态更新能力。参考仓库中的实际实现：
| 需求 | 参考入口 |
| --- | --- |
| 列表筛选、表单与状态操作 | [系统用户控制器](app/admin/controller/User.php)及[对应模板](app/admin/view/user/) |
| 权限与菜单配置 | [权限控制器](app/admin/controller/Auth.php)、[菜单控制器](app/admin/controller/Menu.php) |
| 文件上传与上传配置 | [上传接口](app/admin/controller/api/Upload.php)、[上传脚本模板](app/admin/view/api/upload.js) |
| 命令注册与任务处理 | [微信服务注册](app/wechat/Service.php)、[粉丝同步命令](app/wechat/command/Fans.php) |
权限注解用于描述控制器方法的访问要求：
- `@auth true`：需要权限校验。
- `@login true`：需要登录。
- `@menu true`：标记可用于菜单配置的节点，不会自动创建完整菜单或角色授权。
菜单和按钮决定页面上能看到什么，控制器的权限校验决定请求能否执行，两边需要配合配置。至于一个账号能查看哪个部门、哪些客户的数据，还要在业务查询和操作逻辑中处理。
核心 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)。安装、更新和卸载时会处理哪些文件或数据，由插件配置和安装器决定；操作前先读插件文档，并做好备份。
### 前端定制
项目已包含可运行的静态资源，正常部署不需要额外执行前端构建。默认开发方式是 PHP 输出模板，再由 JavaScript 处理表格加载、表单提交和弹窗等交互，不要求你先搭建一个独立的前端单页应用。
现有页面中有一些常用约定，可以结合源码直接学习：
| 页面约定 | 作用 |
| --- | --- |
| `data-modal` | 打开服务端页面作为弹窗内容，常用于新增、编辑表单 |
| `data-action` | 发起操作请求，可配合 `data-confirm` 显示确认提示 |
| `data-table-id` | 在支持该参数的操作中，指定成功后需要刷新的表格 |
| `data-auto` | 将表单接入已有的校验和提交处理流程 |
| `data-file` | 接入文件上传或图片选择，按属性指定类型和参数 |
这些约定用于复用页面交互，具体的权限、字段校验和业务处理仍写在服务端。调整样式和脚本时，可以先从以下位置入手：
- 项目级样式和脚本扩展入口为 [public/static/extra/style.css](public/static/extra/style.css) 和 [public/static/extra/script.js](public/static/extra/script.js)。
- 后台通用交互位于 [public/static/admin.js](public/static/admin.js)，第三方组件位于 `public/static/plugs/`。
- 主题 Less 源文件及构建脚本位于 [public/static/theme/css/](public/static/theme/css/)，只在修改主题源码时需要 Node.js 与相关编译工具。
修改主题后可执行：
```bash
npm install --global less less-plugin-clean-css
cd public/static/theme/css
npm run build
```
提交主题修改时，应同步提交相关 Less 源文件、生成的 CSS 和 source map，避免源码与页面实际使用的资源不一致。
<a id="常用命令"></a>
## ⌨️ 常用命令
除主题构建外，下列命令均在项目根目录执行：
| 命令 | 用途 |
| --- | --- |
| `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` 只负责启动后台进程，不等同于配置了开机启动或进程崩溃后的自动恢复。
<a id="常见问题"></a>
## ❓ 常见问题
### 可以用于商业项目吗
可以。ThinkAdmin 采用 MIT 许可证，允许按许可条款使用、修改和分发，包括商业用途。交付或分发时需要保留相应版权声明和许可文本；另外安装的组件、插件及第三方服务，要分别确认它们的许可和使用条件。
### 不使用微信功能，可以只做普通后台吗
可以。当前依赖包含微信管理模块，但普通后台业务不要求先开通公众号或商户。你可以先使用账号、权限、菜单、列表和文件管理等功能，需要微信业务时再配置相关模块。
### 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/` 下的应用日志、[日志配置](config/log.php)以及 Web 服务 / PHP 错误日志；公开反馈前请移除密码、密钥、令牌及用户数据。
<a id="交流与贡献"></a>
## 💬 交流与贡献
用下来有什么问题、有哪些地方值得改，欢迎带着具体的场景来交流。修复一个问题、补充一个例子，或者把不清楚的说明改明白，都是参与项目的方式。
- 源码仓库：[GitHub](https://github.com/zoujingli/ThinkAdmin)、[Gitee](https://gitee.com/zoujingli/ThinkAdmin)。
- 使用说明、插件文档和技术交流群入口：[官方网站](https://thinkadmin.top)。
- 反馈问题时，附上版本、运行环境、复现步骤和脱敏后的错误信息，便于其他人定位。
- 提交 Pull Request 时，说明为什么改、怎样验证。不同功能尽量分开提交，前端源码与构建产物保持同步。
- 安全问题请按[安全政策](security.md)联系维护者，不要在公开 Issue 中披露敏感信息或未修复漏洞细节。
<a id="赞助支持"></a>
## 🤝 赞助支持
感谢以下支持方为 ThinkAdmin 的开发与维护提供支持：
- **[JetBrains](https://www.jetbrains.com/)** - 通过[开源项目支持计划](https://www.jetbrains.com/community/opensource/)，为项目活跃贡献者提供一份 [PhpStorm](https://www.jetbrains.com/phpstorm/) 使用许可，用于 ThinkAdmin 的非商业开源开发与维护。
<a id="工具推荐"></a>
## 🧰 工具推荐
- **[狗狗加速](https://www.dginv.click/#/register?code=JLdSICSx)** - 网络加速服务，帮助改善 ChatGPT 等在线工具的访问体验。（邀请注册链接）
<a id="支持项目"></a>
## ⭐ 支持项目
如果 ThinkAdmin 帮你省下了一些开发时间，欢迎 Star、分享给同样做 PHP 开发的朋友，或者 Fork 后参与改进。开发赞助方式可以在[官方网站](https://thinkadmin.top)了解。
<a id="开源协议"></a>
## 📄 开源协议
本项目基于 [MIT License](license) 开源，可按许可证条款使用、修改和分发。使用或分发时应保留相应版权声明和许可文本；第三方依赖遵循各自的许可证。
版权信息以许可证文件中的声明为准。官方网站：[thinkadmin.top](https://thinkadmin.top)；备案信息：[粤ICP备16006642号](https://beian.miit.gov.cn)。
Reference in New Issue View Git Blame Copy Permalink