# hyperfAdmin

**Repository Path**: kamon/hyperf-admin

## Basic Information

- **Project Name**: hyperfAdmin
- **Description**: 一个基于Hyperf3.2+vue3的企业级后台基础框架
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-13
- **Last Updated**: 2026-07-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Base System Hyperf

基于 Hyperf 3.2 的通用基础系统框架，用于快速构建管理后台和业务系统。底座提供系统管理、认证权限、统一响应、文件上传、报表任务、异步队列、定时任务、WebSocket、JSON-RPC 和常用工具能力。

## 环境要求

- PHP >= 8.2
- Swoole >= 5.0，且 `swoole.use_shortname=Off`
- MySQL
- Redis
- Composer 2
- PHP 扩展：`curl`、`fileinfo`、`gd`、`openssl`、`pdo_mysql`、`redis`、`swoole`、`xml`、`xmlreader`、`xmlwriter`、`zip`
- Docker 与 Docker Compose（使用容器启动时需要）

## 快速启动

### 本地启动

```bash
composer install
cp .env.example .env
```

修改 `.env` 中的数据库、Redis、服务注册和密钥配置，然后启动：

```bash
composer start
```

也可以直接运行：

```bash
php bin/hyperf.php start
```

### Docker 启动

```bash
cp .env.example .env
docker compose up --build -d
docker compose logs -f base-system-hyperf
```

停止服务：

```bash
docker compose down
```

## 服务端口

```text
HTTP       9301
WebSocket  9302
JSON-RPC   9303
```

端口可通过 `.env` 中的 `HTTP_SERVER_PORT`、`WS_SERVER_PORT`、`RPC_SERVER_PORT` 调整。

## 默认账号

```text
账号：admin
密码：admin123456
```

## 认证入口

```text
POST /system/auth/login
GET  /system/auth/info
POST /system/auth/logout
POST /system/auth/change_password
GET  /system/auth/codes
```

登录态通过 Redis cache 保存。重复登录时只保留当前用户的最新 token。超级管理员调用 `/system/auth/codes` 返回 `['*']`，表示拥有全部前端按钮和组件显隐权限，不展开所有权限码。

## 核心配置

所有运行配置从 `.env` 读取，完整模板见 `.env.example`。首次运行至少需要检查：

```env
APP_NAME=base_system
APP_ENV=dev
APP_KEY=change-me
JWT_KEY=change-me

DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=base_system
DB_USERNAME=base_user
DB_PASSWORD=change-me
DB_PREFIX=base_

REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_DB=13
REDIS_AUTH=
```

生产环境必须修改 `APP_KEY`、`JWT_KEY`、数据库密码，并把 `APP_ENV` 设为 `prod`。生产环境的 `ALLOW_ORIGINS` 应填写明确域名列表，不能使用 `*`。

## 操作日志

管理端的 `POST`、`PUT`、`PATCH`、`DELETE` 操作请求会自动写入 `sys_log`，覆盖登录、退出、保存、删除、状态变更、排序和任务操作。无论操作成功、业务失败、参数验证失败或发生异常都会记录，并通过状态、业务响应码、HTTP 状态和响应消息标识结果。

相关环境变量：

```env
OPERATION_LOG_ENABLED=true
OPERATION_LOG_PATH_PREFIXES=/system
OPERATION_LOG_EXCLUDED_PATHS=
OPERATION_LOG_METHODS=POST,PUT,PATCH,DELETE
OPERATION_LOG_MAX_PAYLOAD_BYTES=32768
```

密码、密钥和认证信息会脱敏或排除，上传只记录文件元数据。明确不需要审计的接口仍可通过路由配置关闭日志。

业务节点日志使用独立表（逻辑表名 `operation_logs`），用于业务详情页时间线。首次使用前执行：

```bash
mysql -u 用户名 -p 数据库名 < docs/sql/operation_logs.sql
```

业务代码统一通过 `OperationLogService::addLog()` 埋点：

```php
$this->operationLogService->addLog(
    'order',
    $orderId,
    '订单审核通过',
    relatedId: $relatedId,
    targetStatus: '已审核'
);
```

计划任务、队列和外部回写等非人为操作传 `operatorId: 0`，系统会默认写 `operator_name=系统`。业务日志查询接口为 `GET /system/operation_log/list`，类型选项接口为 `GET /system/operation_log/types`。

账号组织层级启用前执行：

```bash
mysql -u 用户名 -p 数据库名 < docs/sql/user_manager.sql
```

地区能力使用默认库逻辑表 `region`，建表脚本见 `docs/sql/region.sql`。

## 文件上传

上传类型和大小通过 `.env` 配置，并由 `config/autoload/upload.php` 统一解析：

```env
UPLOAD_MAX_SIZE=134217728
UPLOAD_ALLOWED_EXTENSIONS=jpg,jpeg,png,gif,bmp,tiff,webp,mp4,avi,mov,wmv,mkv,flv,webm,pdf,doc,docx,xls,xlsx,zip,txt,csv,mp3,wav
```

上传同时校验扩展名和 `fileinfo` 检测到的真实 MIME。

## 队列与报表

队列配置在 `config/autoload/async_queue.php`，默认使用 Redis driver。队列 channel 默认跟随 `APP_NAME`，也可以通过 `.env` 中的 `QUEUE_DEFAULT_CHANNEL`、`QUEUE_REPORT_CHANNEL` 覆盖。

报表导出采用任务化流程：

```text
POST /system/report/task_add      创建任务
POST /system/report/task_execute  投递 report 队列
GET  /system/report/task_list     查看任务列表
GET  /system/report/task_info     查看任务详情
POST /system/report/task_reset    重置任务
```

报表任务超时和过期清理由 `REPORT_TASK_PROCESSING_TIMEOUT`、`REPORT_TASK_EXPIRED_DAYS` 控制；过期天数配置为 `0` 时不自动清理。

启用报表任务自动扫描时设置 `REPORT_TASK_JOB_ENABLED=true`。执行 `composer start` 或 `php bin/hyperf.php start` 后，Hyperf 会根据 `config/autoload/async_queue.php` 自动启动已启用的 `default` 和 `report` 消费进程；启用状态、进程数和并发数均在该配置文件中设置。

## RPC

JSON-RPC 配置集中在：

```text
config/autoload/rpc.php
config/autoload/services.php
config/autoload/service_consumers.php
```

RPC 服务名前缀默认为空，即不限制 Provider 服务名：

```env
RPC_SERVICE_PREFIX=
```

多个系统注册到同一个服务中心且需要统一命名空间时，可显式配置前缀，例如 `RPC_SERVICE_PREFIX=Base`。

不使用 Consul 服务发现时，可在 `.env` 中关闭注册与发现：

```env
RPC_DISCOVERY_ENABLE=false
RPC_REGISTER_ENABLE=false
```

## 常用校验

```bash
find app config test -name '*.php' -exec php -l {} +
composer validate --no-check-publish
composer test
composer analyse
php bin/hyperf.php describe:routes --disable-event-dispatcher
docker compose config --quiet
```

## 规范文档

项目架构、开发要求、代码边界、路由、权限、测试和文档维护规范统一见 [AGENTS.md](AGENTS.md)。