+ + 中文文档 | + English Docs +
+🚀 LaravelS 是 Laravel/Lumen 和 Swoole 之间开箱即用的适配器
+ +
+
+## 其他特性
+
+### 配置Swoole事件
+
+支持的事件列表：
+
+| 事件 | 需实现的接口 | 发生时机 |
+| -------- | -------- | -------- |
+| ServerStart | Hhxsv5\LaravelS\Swoole\Events\ServerStartInterface | 发生在Master进程启动时，`此事件中不应处理复杂的业务逻辑，只能做一些初始化的简单工作` |
+| ServerStop | Hhxsv5\LaravelS\Swoole\Events\ServerStopInterface | 发生在Server正常退出时，`此事件中不能使用异步或协程相关的API` |
+| WorkerStart | Hhxsv5\LaravelS\Swoole\Events\WorkerStartInterface | 发生在Worker/Task进程启动完成后 |
+| WorkerStop | Hhxsv5\LaravelS\Swoole\Events\WorkerStopInterface | 发生在Worker/Task进程正常退出后 |
+| WorkerError | Hhxsv5\LaravelS\Swoole\Events\WorkerErrorInterface | 发生在Worker/Task进程发生异常或致命错误时 |
+
+1.创建事件处理类，实现相应的接口。
+```php
+namespace App\Events;
+use Hhxsv5\LaravelS\Swoole\Events\ServerStartInterface;
+use Swoole\Atomic;
+use Swoole\Http\Server;
+class ServerStartEvent implements ServerStartInterface
+{
+ public function __construct()
+ {
+ }
+ public function handle(Server $server)
+ {
+ // 初始化一个全局计数器(跨进程的可用)
+ $server->atomicCount = new Atomic(2233);
+
+ // 控制器中调用：app('swoole')->atomicCount->get();
+ }
+}
+```
+
+```php
+namespace App\Events;
+use Hhxsv5\LaravelS\Swoole\Events\WorkerStartInterface;
+use Swoole\Http\Server;
+class WorkerStartEvent implements WorkerStartInterface
+{
+ public function __construct()
+ {
+ }
+ public function handle(Server $server, $workerId)
+ {
+ // 初始化一个数据库连接池对象
+ // DatabaseConnectionPool::init();
+ }
+}
+```
+
+2.配置。
+```php
+// 修改文件 config/laravels.php
+'event_handlers' => [
+ 'ServerStart' => [\App\Events\ServerStartEvent::class], // 按数组顺序触发事件
+ 'WorkerStart' => [\App\Events\WorkerStartEvent::class],
+],
+```
+
+### Serverless
+
+#### 阿里云函数计算
+> [函数计算官方文档](https://help.aliyun.com/product/50980.html)。
+
+1.修改`bootstrap/app.php`，设置storage目录。因为项目目录只读，`/tmp`目录才可读写。
+
+```php
+$app->useStoragePath(env('APP_STORAGE_PATH', '/tmp/storage'));
+```
+
+2.创建Shell脚本`laravels_bootstrap`，并赋予`可执行权限`。
+
+```bash
+#!/usr/bin/env bash
+set +e
+
+# 创建storage相关目录
+mkdir -p /tmp/storage/app/public
+mkdir -p /tmp/storage/framework/cache
+mkdir -p /tmp/storage/framework/sessions
+mkdir -p /tmp/storage/framework/testing
+mkdir -p /tmp/storage/framework/views
+mkdir -p /tmp/storage/logs
+
+# 设置环境变量APP_STORAGE_PATH，请确保与.env的APP_STORAGE_PATH一样
+export APP_STORAGE_PATH=/tmp/storage
+
+# Start LaravelS
+php bin/laravels start
+```
+
+3.配置`template.xml`。
+
+```xml
+ROSTemplateFormatVersion: '2015-09-01'
+Transform: 'Aliyun::Serverless-2018-04-03'
+Resources:
+ laravel-s-demo:
+ Type: 'Aliyun::Serverless::Service'
+ Properties:
+ Description: 'LaravelS Demo for Serverless'
+ fc-laravel-s:
+ Type: 'Aliyun::Serverless::Function'
+ Properties:
+ Handler: laravels.handler
+ Runtime: custom
+ MemorySize: 512
+ Timeout: 30
+ CodeUri: ./
+ InstanceConcurrency: 10
+ EnvironmentVariables:
+ BOOTSTRAP_FILE: laravels_bootstrap
+
+```
+
+## 注意事项
+
+### 单例问题
+
+- 传统FPM下，单例模式的对象的生命周期仅在每次请求中，请求开始=>实例化单例=>请求结束后=>单例对象资源回收。
+
+- Swoole Server下，所有单例对象会常驻于内存，这个时候单例对象的生命周期与FPM不同，请求开始=>实例化单例=>请求结束=>单例对象依旧保留，需要开发者自己维护单例的状态。
+
+- 常见的解决方案：
+
+ 1. 写一个`XxxCleaner`清理器类来清理单例对象状态，此类需实现接口`Hhxsv5\LaravelS\Illuminate\Cleaners\CleanerInterface`，然后注册到`laravels.php`的`cleaners`中。
+
+ 2. 用一个`中间件`来`重置`单例对象的状态。
+
+ 3. 如果是以`ServiceProvider`注册的单例对象，可添加该`ServiceProvider`到`laravels.php`的`register_providers`中，这样每次请求会重新注册该`ServiceProvider`，重新实例化单例对象，[参考](https://github.com/hhxsv5/laravel-s/blob/PHP-8.x/Settings-CN.md#register_providers)。
+
+### 清理器
+> [设置清理器](https://github.com/hhxsv5/laravel-s/blob/PHP-8.x/Settings-CN.md#cleaners)。
+
+### 常见问题
+> [常见问题](https://github.com/hhxsv5/laravel-s/blob/PHP-8.x/KnownIssues-CN.md)：一揽子的已知问题和解决方案。
+
+### 调试方式
+
+- 记录日志；如想要在控制台输出，可使用`stderr`，Log::channel('stderr')->debug('debug message')。
+
+- [Laravel Dump Server](https://github.com/beyondcode/laravel-dump-server)（Laravel 5.7已默认集成）。
+
+### 读取请求
+应通过`Illuminate\Http\Request`对象来读取请求信息，$_ENV是可读取的，$_SERVER是部分可读的，`不能使用`$_GET、$_POST、$_FILES、$_COOKIE、$_REQUEST、$_SESSION、$GLOBALS。
+
+```php
+public function form(\Illuminate\Http\Request $request)
+{
+ $name = $request->input('name');
+ $all = $request->all();
+ $sessionId = $request->cookie('sessionId');
+ $photo = $request->file('photo');
+ // 调用getContent()来获取原始的POST body，而不能用file_get_contents('php://input')
+ $rawContent = $request->getContent();
+ //...
+}
+```
+
+### 输出响应
+推荐通过返回`Illuminate\Http\Response`对象来响应请求，兼容echo、vardump()、print_r()，`不能使用`函数 dd()、exit()、die()、header()、setcookie()、http_response_code()。
+
+```php
+public function json()
+{
+ return response()->json(['time' => time()])->header('header1', 'value1')->withCookie('c1', 'v1');
+}
+```
+
+### 持久连接
+`单例的连接`将被常驻内存，建议开启`持久连接`，获得更好的性能。
+1. 数据库连接，连接断开后会自动重连
+
+```php
+// config/database.php
+'connections' => [
+ 'my_conn' => [
+ 'driver' => 'mysql',
+ 'host' => env('DB_MY_CONN_HOST', 'localhost'),
+ 'port' => env('DB_MY_CONN_PORT', 3306),
+ 'database' => env('DB_MY_CONN_DATABASE', 'forge'),
+ 'username' => env('DB_MY_CONN_USERNAME', 'forge'),
+ 'password' => env('DB_MY_CONN_PASSWORD', ''),
+ 'charset' => 'utf8mb4',
+ 'collation' => 'utf8mb4_unicode_ci',
+ 'prefix' => '',
+ 'strict' => false,
+ 'options' => [
+ // 开启持久连接
+ \PDO::ATTR_PERSISTENT => true,
+ ],
+ ],
+],
+```
+
+2. Redis连接，连接断开后`不会立即`自动重连，会抛出一个关于连接断开的异常，下次会自动重连。需确保每次操作Redis前正确的`SELECT DB`。
+
+```php
+// config/database.php
+'redis' => [
+ 'client' => env('REDIS_CLIENT', 'phpredis'), // 推荐使用phpredis，以获得更好的性能
+ 'default' => [
+ 'host' => env('REDIS_HOST', 'localhost'),
+ 'password' => env('REDIS_PASSWORD', null),
+ 'port' => env('REDIS_PORT', 6379),
+ 'database' => 0,
+ 'persistent' => true, // 开启持久连接
+ ],
+],
+```
+
+### 关于内存泄露
+
+- 避免使用全局变量，如一定要，请手动清理或重置。
+
+- 无限追加元素到全局变量、静态变量、单例，将导致内存溢出。
+
+ ```php
+ class Test
+ {
+ public static $array = [];
+ public static $string = '';
+ }
+
+ // 某控制器
+ public function test(Request $req)
+ {
+ // 内存溢出
+ Test::$array[] = $req->input('param1');
+ Test::$string .= $req->input('param2');
+ }
+ ```
+
+- 内存泄露的检测方法
+
+ 1. 修改`config/laravels.php`：`worker_num=1, max_request=1000000`，测试完成后记得改回去；
+
+ 2. 增加路由`/debug-memory-leak`，不设置任何`路由中间件`，用于观察`Worker`进程的内存变化情况；
+
+ ```php
+ Route::get('/debug-memory-leak', function () {
+ global $previous;
+ $current = memory_get_usage();
+ $stats = [
+ 'prev_mem' => $previous,
+ 'curr_mem' => $current,
+ 'diff_mem' => $current - $previous,
+ ];
+ $previous = $current;
+ return $stats;
+ });
+ ```
+
+ 3. 启动`LaravelS`，请求`/debug-memory-leak`，直到`diff_mem`小于或等于零；如果`diff_mem`一直大于零，说明`全局中间件`或`Laravel框架`可能存在内存泄露；
+
+ 4. 完成`步骤3`后，`交替`请求业务路由与`/debug-memory-leak`（建议使用`ab`/`wrk`对业务路由进行大量的请求），刚开始出现的内存增涨是正常现象。业务路由经过大量请求后，如果`diff_mem`一直大于零，并且`curr_mem`持续增大，则大概率存在内存泄露；如果`curr_mem`始终在一定范围内变化，没有持续变大，则大概率不存在内存泄露。
+
+ 5. 如果始终没法解决，[max_request](https://wiki.swoole.com/#/server/setting?id=max_request)是最后兜底的方案。
+
diff --git a/docs/README_LOG.md b/docs/README_LOG.md
deleted file mode 100644
index 5cb1ac7..0000000
--- a/docs/README_LOG.md
+++ /dev/null
@@ -1,608 +0,0 @@
-# 系统操作日志模块文档
-
-## 概述
-
-系统操作日志模块用于记录后台管理系统的所有操作请求，包括用户操作、API 调用、错误信息等，方便管理员进行系统监控、审计和问题排查。
-
-## 技术特性
-
-- **自动记录**: 通过中间件自动记录所有请求，无需手动调用
-- **详细信息**: 记录用户信息、请求参数、响应结果、执行时间等
-- **敏感信息保护**: 自动过滤密码等敏感信息
-- **性能优化**: 不影响业务响应速度
-- **多维度查询**: 支持按用户、模块、操作、状态、时间等多维度筛选
-- **数据导出**: 支持导出日志数据为 Excel 文件
-- **批量操作**: 支持批量删除和定期清理
-
-## 数据库表结构
-
-### system_logs 表
-
-| 字段名 | 类型 | 说明 |
-|--------|------|------|
-| id | bigint | 主键 ID |
-| user_id | bigint | 用户 ID |
-| username | varchar(100) | 用户名 |
-| module | varchar(50) | 模块名称 |
-| action | varchar(100) | 操作名称 |
-| method | varchar(10) | 请求方法 (GET/POST/PUT/DELETE) |
-| url | text | 请求 URL |
-| ip | varchar(45) | 客户端 IP 地址 |
-| user_agent | text | 用户代理 |
-| params | json | 请求参数 |
-| result | text | 响应结果（仅错误时记录） |
-| status_code | int | HTTP 状态码 |
-| status | varchar(20) | 状态 (success/error) |
-| error_message | text | 错误信息 |
-| execution_time | int | 执行时间（毫秒） |
-| created_at | timestamp | 创建时间 |
-| updated_at | timestamp | 更新时间 |
-
-## 核心组件
-
-### 1. 中间件 (Middleware)
-
-**LogRequestMiddleware**
-
-位置: `app/Http/Middleware/LogRequestMiddleware.php`
-
-功能:
-- 自动拦截所有经过的请求
-- 记录请求和响应信息
-- 计算请求执行时间
-- 提取用户信息和操作详情
-- 过滤敏感参数
-- 处理异常情况
-
-使用方式:
-```php
-// 在路由中应用
-Route::middleware(['log.request'])->group(function () {
- // 需要记录日志的路由
-});
-```
-
-### 2. 服务层 (Service)
-
-**LogService**
-
-位置: `app/Services/System/LogService.php`
-
-主要方法:
-- `create(array $data)`: 创建日志记录
-- `getList(array $params)`: 获取日志列表（分页）
-- `getListQuery(array $params)`: 获取日志查询构建器
-- `getById(int $id)`: 根据 ID 获取日志详情
-- `delete(int $id)`: 删除单条日志
-- `batchDelete(array $ids)`: 批量删除日志
-- `clearLogs(string $days)`: 清理指定天数前的日志
-- `getStatistics(array $params)`: 获取日志统计信息
-
-### 3. 控制器 (Controller)
-
-**Log Controller**
-
-位置: `app/Http/Controllers/System/Admin/Log.php`
-
-接口列表:
-- `GET /admin/logs`: 获取日志列表
-- `GET /admin/logs/{id}`: 获取日志详情
-- `GET /admin/logs/statistics`: 获取日志统计
-- `POST /admin/logs/export`: 导出日志
-- `DELETE /admin/logs/{id}`: 删除单条日志
-- `POST /admin/logs/batch-delete`: 批量删除日志
-- `POST /admin/logs/clear`: 清理历史日志
-
-### 4. 请求验证 (Request Validation)
-
-**LogRequest**
-
-位置: `app/Http/Requests/LogRequest.php`
-
-验证规则:
-- `user_id`: 用户 ID（可选）
-- `username`: 用户名（模糊查询，可选）
-- `module`: 模块名称（可选）
-- `action`: 操作名称（可选）
-- `status`: 状态（success/error，可选）
-- `start_date`: 开始日期（可选）
-- `end_date`: 结束日期（可选）
-- `ip`: IP 地址（可选）
-- `page`: 页码（默认 1）
-- `page_size`: 每页数量（默认 20，最大 100）
-
-## API 接口文档
-
-### 1. 获取日志列表
-
-**接口**: `GET /admin/logs`
-
-**请求参数**:
-```json
-{
- "user_id": 1,
- "username": "admin",
- "module": "users",
- "action": "创建 users",
- "status": "success",
- "start_date": "2024-01-01",
- "end_date": "2024-12-31",
- "ip": "192.168.1.1",
- "page": 1,
- "page_size": 20
-}
-```
-
-**响应示例**:
-```json
-{
- "code": 200,
- "message": "success",
- "data": {
- "list": [
- {
- "id": 1,
- "user_id": 1,
- "username": "admin",
- "module": "users",
- "action": "创建 users",
- "method": "POST",
- "url": "http://example.com/admin/users",
- "ip": "192.168.1.1",
- "user_agent": "Mozilla/5.0...",
- "params": {
- "name": "test",
- "email": "test@example.com"
- },
- "result": null,
- "status_code": 200,
- "status": "success",
- "error_message": null,
- "execution_time": 125,
- "created_at": "2024-01-01 12:00:00",
- "user": {
- "id": 1,
- "name": "管理员",
- "username": "admin"
- }
- }
- ],
- "total": 100,
- "page": 1,
- "page_size": 20
- }
-}
-```
-
-### 2. 获取日志详情
-
-**接口**: `GET /admin/logs/{id}`
-
-**响应示例**:
-```json
-{
- "code": 200,
- "message": "success",
- "data": {
- "id": 1,
- "user_id": 1,
- "username": "admin",
- "module": "users",
- "action": "创建 users",
- "method": "POST",
- "url": "http://example.com/admin/users",
- "ip": "192.168.1.1",
- "user_agent": "Mozilla/5.0...",
- "params": {
- "name": "test",
- "email": "test@example.com"
- },
- "result": null,
- "status_code": 200,
- "status": "success",
- "error_message": null,
- "execution_time": 125,
- "created_at": "2024-01-01 12:00:00",
- "user": {
- "id": 1,
- "name": "管理员",
- "username": "admin",
- "email": "admin@example.com",
- "created_at": "2024-01-01 10:00:00"
- }
- }
-}
-```
-
-### 3. 获取日志统计
-
-**接口**: `GET /admin/logs/statistics`
-
-**请求参数**:
-```json
-{
- "start_date": "2024-01-01",
- "end_date": "2024-12-31"
-}
-```
-
-**响应示例**:
-```json
-{
- "code": 200,
- "message": "success",
- "data": {
- "total": 1000,
- "success": 950,
- "error": 50
- }
-}
-```
-
-### 4. 导出日志
-
-**接口**: `POST /admin/logs/export`
-
-**请求参数**: 与获取日志列表相同的查询参数
-
-**响应**: Excel 文件下载
-
-文件名格式: `系统操作日志_YYYYMMDDHHmmss.xlsx`
-
-包含字段:
-- ID
-- 用户名
-- 模块
-- 操作
-- 请求方法
-- URL
-- IP 地址
-- 状态码
-- 状态
-- 错误信息
-- 执行时间(ms)
-- 创建时间
-
-### 5. 删除单条日志
-
-**接口**: `DELETE /admin/logs/{id}`
-
-**响应示例**:
-```json
-{
- "code": 200,
- "message": "删除成功",
- "data": null
-}
-```
-
-### 6. 批量删除日志
-
-**接口**: `POST /admin/logs/batch-delete`
-
-**请求参数**:
-```json
-{
- "ids": [1, 2, 3, 4, 5]
-}
-```
-
-**响应示例**:
-```json
-{
- "code": 200,
- "message": "批量删除成功",
- "data": null
-}
-```
-
-### 7. 清理历史日志
-
-**接口**: `POST /admin/logs/clear`
-
-**请求参数**:
-```json
-{
- "days": 30
-}
-```
-
-**说明**: 清理指定天数前的所有日志记录，默认清理 30 天前的数据。
-
-**响应示例**:
-```json
-{
- "code": 200,
- "message": "清理成功",
- "data": null
-}
-```
-
-## 日志记录规则
-
-### 1. 自动记录的请求
-
-所有经过 `log.request` 中间件的请求都会被自动记录，包括:
-- 用户管理操作
-- 角色管理操作
-- 权限管理操作
-- 部门管理操作
-- 系统配置操作
-- 其他所有后台管理操作
-
-### 2. 不记录的请求
-
-- 登录接口 (`POST /admin/auth/login`)
-- 健康检查接口 (`GET /up`)
-- 其他明确排除的路由
-
-### 3. 敏感信息过滤
-
-以下字段会被自动过滤，记录为 `******`:
-- `password`
-- `password_confirmation`
-- `token`
-- `secret`
-- `key`
-
-### 4. 错误日志处理
-
-- 成功请求 (HTTP 状态码 < 400): `status` = `success`
-- 失败请求 (HTTP 状态码 >= 400): `status` = `error`
-- 错误时记录响应内容和错误消息
-- 同时写入 Laravel 日志文件 (`storage/logs/laravel.log`)
-
-## 模块和操作名称解析
-
-### 模块名称
-
-从 URL 路径中解析，例如:
-- `/admin/users` → 模块: `users`
-- `/admin/roles` → 模块: `roles`
-- `/admin/configs` → 模块: `configs`
-
-### 操作名称
-
-根据 HTTP 方法和资源名称生成:
-- `GET /admin/users` → 操作: `查询 users`
-- `POST /admin/users` → 操作: `创建 users`
-- `PUT /admin/users/1` → 操作: `更新 users`
-- `DELETE /admin/users/1` → 操作: `删除 users`
-
-## 性能优化建议
-
-### 1. 定期清理日志
-
-建议使用 Laravel 任务调度器定期清理历史日志:
-
-```php
-// app/Console/Kernel.php
-
-protected function schedule(Schedule $schedule)
-{
- // 每天凌晨 2 点清理 90 天前的日志
- $schedule->call(function () {
- app(LogService::class)->clearLogs(90);
- })->dailyAt('02:00');
-}
-```
-
-### 2. 数据库索引
-
-确保以下字段有索引:
-- `user_id`
-- `username`
-- `module`
-- `status`
-- `created_at`
-
-### 3. 分页查询
-
-列表查询必须使用分页，避免一次加载过多数据。
-
-### 4. 异步记录
-
-日志记录操作应放在请求处理后，不影响响应速度。
-
-## 前端集成示例
-
-### Vue3 + Ant Design Vue
-
-```vue
-
- 
+
- {{ config.APP_NAME }}
+
+ {{
+ config.APP_NAME
+ }}
+
{{ config.APP_NAME }}
+ 
+ 
+ 
+ 
+ 
+ 
+