# Auditify — 适用于 Laravel 的高性能、解耦审计日志
[](https://packagist.org/packages/arpanihan/auditify)
[](https://packagist.org/packages/arpanihan/auditify)
[](LICENSE.md)
**Auditify** 是一个易于使用、高性能的审计日志和威胁检测 Laravel 扩展包。
🔗 **官方着陆页与演示：** [arpa12.github.io/laravel-auditify-landingPage](https://arpa12.github.io/laravel-auditify-landingPage/)
与标准的日志库不同，Auditify 采用**解耦的数据库设计**，将日志分离到三个独立的表中。这优化了数据库表索引，减少了写入拥堵，并保证了随着应用程序增长时的清晰扩展组织。
## 目录
* [环境要求](#-requirements)
* [功能特性](#-features)
* [仪表盘](#-dashboard)
* [报告与分析模块](#-reports--analytics-module)
* [解耦日志模块](#-decoupled-log-modules)
* [实时威胁引擎](#-real-time-threat-engine)
* [XSS 攻击防护](#-xss-attack-shield)
* [前端事件记录 API](#-frontend-event-logging-api-optional)
* [仅管理员访问与自定义授权门](#-admin-only-access--custom-authorization-gate)
* [安装说明](#-installation)
* [配置](#-configuration)
* [手动记录与辅助方法](#-manual-logging--helper-methods)
* [Artisan 命令](#%EF%B8%8F-artisan-commands)
* [路由参考](#-routes-reference)
* [测试](#-testing)
* [作者](#-author)
* [许可证](#-license)
## 🖥️ 环境要求
| Laravel | PHP |
|---|---|
| 13.x | 8.3 – 8.4 |
| 11.x, 12.x | 8.2 – 8.4 |
| 10.x | 8.2 – 8.3 |
## 🚀 功能特性
### 📊 仪表盘
URL: `/auditify`
主毛玻璃效果仪表盘将操作日志、页面访问和威胁警报聚合在一个交互式界面中：
* **指标计数器** — 包含未读指示器的操作日志、活动日志和安全日志总数。
* **日志摘要** — 操作（创建、更新、删除）和身份验证事件（登录、登出）的细分。
* **7 天趋势图** — 基于 Chart.js 绘制的操作与活动每日对比计数图。
* **活跃用户与常修改模块 Top 榜** — 最活跃的用户 ID 列表和频繁更改的模型列表。
* **实时最新日志** — 最新访客操作和安全警报列表。
### 📈 报告与分析模块
URL: `/auditify/reports`
一个综合性的报告面板，提供在自定义时间范围内（过去 7 天、过去 30 天或过去 90 天）详细的统计细分，并配有交互式的 Chart.js 图表：
* **概览分析：** 使用多折线图映射的系统日志活动趋势。
* **操作报告：** 按类型划分的操作（圆环图）和更改最多的模型（水平条形图），以及详细的数据库修改表和 CSV/Excel/PDF 下载选项。
* **活动报告：** 访问量最高的页面/URL（水平条形图）和活动高峰时段（条形图），以及详细的活动表和 CSV/Excel/PDF 下载选项。
* **安全报告：** 按严重程度划分的警报（圆环图）、主要威胁源 IP（条形图）和解决状态分布（饼图），以及详细的安全事件表和 CSV/Excel/PDF 下载选项。
* **格式导出：** 支持导出经过时间范围筛选的报告，格式包括 CSV、Excel (xlsx) 和整洁可打印的 PDF。
### 🗄️ 解耦日志模块
Auditify 将数据记录分为 `Auditify\Models` 下的三个目标模型，以避免写入瓶颈。以下是每种日志类型捕获的确切数据库 schema 和属性：
#### 操作日志 (`ActionLog`)
* **表名**: `audit_action_logs`
* **用途**: 追踪 Eloquent 数据库修改（插入、更新、删除和恢复）。
* **捕获属性 / 数据库列**：
* `id` (BigInt, 主键)
* `user_id` & `user_type` (可为空的 Morphs) — 与执行数据库修改的用户的多态关联。
* `subject_id` & `subject_type` (可为空的 Morphs) — 与实际被修改的模型的多态关联。
* `action` (String) — 查询事件（`created`、`updated`、`deleted`、`restored`）。
* `module` (String) — 受影响的模型模块/类名（例如 `Post`、`User`、`Role`）。
* `description` (Text, 可为空) — 友好可读的日志摘要描述。
* `old_values` (JSON, 可为空) — 操作前转换为数组的模型属性值。
* `new_values` (JSON, 可为空) — 操作后转换为数组的模型属性值。
* `ip_address` (String, 可为空) — 触发事件的客户端 IP 地址。
* `url` (Text, 可为空) — 发生更改的 HTTP Request URL。
* `user_agent` (Text, 可为空) — HTTP User-Agent 字符串。
* `created_at` & `updated_at` (时间戳)
#### 活动日志 (`ActivityLog`)
* **表名**: `audit_activity_logs`
* **用途**: 记录访客请求、导航、自定义应用程序操作和身份验证流程。
* **捕获属性 / 数据库列**：
* `id` (BigInt, 主键)
* `user_id` & `user_type` (可为空的 Morphs) — 与访客的多态关联（如果已通过身份验证）。
* `activity` (String) — 操作/活动的类型（例如 `Page Visit`、`Login`、`Logout`、`Failed Login` 或自定义事件）。
* `properties` (JSON, 可为空) — 存储上下文元数据或自定义事件 payload 的转换数组。
* `url` (Text, 可为空) — 请求的 URL 路径。
* `ip_address` (String, 可为空) — 访客 IP 地址。
* `user_agent` (Text, 可为空) — 访客 User-Agent 字符串。
* `created_at` & `updated_at` (时间戳)
#### 安全日志 (`SecurityLog`)
* **表名**: `audit_security_logs`
* **用途**: 记录由 XSS 保护 middleware、速率限制或自动化威胁规则生成的警报。
* **捕获属性 / 数据库列**：
* `id` (BigInt, 主键)
* `user_id` & `user_type` (可为空的 Morphs) — 与用户的多态关联（如果已通过身份验证）。
* `severity` (String) — 警报优先级（`low`、`medium`、`high`、`critical`）。
* `title` (String) — 事件的简短名称（例如 `XSS Attack Blocked`、`Failed Logins Peak`）。
* `description` (Text, 可为空) — 关于威胁被标记原因的深入细节。
* `is_read` (Boolean) — 用于管理员仪表盘警报的已读/未读切换标志。
* `status` (String) — 警报解决状态（`pending` 或 `resolved`）。
* `resolved_at` (DateTime, 可为空) — 事件被标记为已解决/已读时的时间戳。
* `resolution_notes` (Text, 可为空) — 解释解决策略的文本。
* `method` (String, 可为空) — 请求的 HTTP method（`GET`、`POST` 等）。
* `route_name` (String, 可为空) — 发生攻击/警报的命名路由。
* `payload` (JSON, 可为空) — 被安全防护扫描的请求体 payload 参数转换数组。
* `ip_address` (String, 可为空) — 事件的源 IP 地址。
* `user_agent` (Text, 可为空) — 事件客户端的 User-Agent。
* `created_at` & `updated_at` (时间戳)
### 📈 实时威胁引擎
Auditify 会自动监控活动日志，并在违反规则时记录高优先级的安全条目：
* **批量删除防护**：如果用户在 5 分钟内删除了单个模型中的 5 条或更多记录（默认），则触发 `critical` 安全日志。
* **批量更新防护**：如果用户在 5 分钟内更新了单个模型中的 10 条或更多记录（默认），则触发 `high` 安全日志。
* **登录失败监控器**：追踪失败的登录尝试。如果在 5 分钟内记录了 3 次或更多次失败登录尝试，则触发 `high` 安全日志。
* **敏感模块监控器**：每当修改了 `sensitive_modules`（例如 `User`、`Role`、`Permission`、`Setting`、`Config`）中列出的模型时，就会触发 `medium` 安全日志。
* **权限变更监控**：每当添加、修改或删除权限、角色或 gate 映射时，就会触发 `high` 安全日志。
### 🛡️ XSS 攻击防护
Auditify 内置了 XSS 保护。它会自动扫描所有传入的请求参数（例如 `$_GET` 或 `$_POST`）以及路由变量。
如果检测到常见的 XSS 模式（如 `
```
### 🔐 仅管理员访问与自定义授权门
默认情况下，如果在 `config/auditify.php` 中进行了配置，该扩展包会启用访问控制。**你应该在应用程序内注册一个授权回调**，这样开发者就可以精确定义谁被归类为授权管理员。
要将仪表盘视图和日志下载限制为仅限管理员访问，请在 `app/Providers/AppServiceProvider.php` 的 `boot` 方法中注册授权回调：
```
use Auditify\Facades\Auditify;
public function boot()
{
// Restrict all Auditify dashboard and API routes to Admin users
Auditify::auth(function ($request) {
// Option A: Check user role (e.g. if using Spatie Role package)
return $request->user() && $request->user()->hasRole('admin');
// Option B: Check simple is_admin database flag
// return $request->user() && $request->user()->is_admin;
// Option C: Check a specific company email domain
// return $request->user() && str_ends_with($request->user()->email, '@yourcompany.com');
});
}
```
## 📦 安装说明
### 1. 通过 Composer 安装
在你的项目根目录运行此命令：
```
composer require arpanihan/auditify
```
### 2. 运行安装程序
运行安装命令以发布配置文件、复制迁移文件并自动设置数据库：
```
php artisan auditify:install
```
### 3. 清除应用程序缓存
安装后，清除所有缓存的配置、路由、视图和其他缓存数据，以确保 Auditify 加载最新设置：
```
php artisan optimize:clear
```
### 4. 启动 Laravel 开发服务器
如果你的应用程序尚未运行，请启动 Laravel 开发服务器：
```
php artisan serve
```
### 5. 访问仪表盘
安装程序成功完成后，打开 Web 浏览器并导航到 Auditify 仪表盘 URL：
```
http://your-domain.local/auditify
```
*(注意：如果你更改了 `config/auditify.php` 中的 `'route_prefix'` 配置设置，此路由 URL 将相应更新)。*
### 4. (可选) 选择性模型审计
默认情况下，Auditify 会在全局范围内自动审计**所有 Eloquent 模型**，无需任何手动设置。
但是，如果你关闭了全局审计（`'auto_audit_models' => false`）并希望手动选择要审计的模型，请添加 `Auditable` trait：
```
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
use Auditify\Traits\Auditable;
class Product extends Model
{
use Auditable;
}
```
## ⚙️ 配置
发布后，在 `config/auditify.php` 中自定义你的设置：
```
return [
// Base URL route prefix: https://your-domain.com/auditify
'route_prefix' => 'auditify',
// Dashboard visual layout theme: 'dark' or 'light'
'theme' => 'dark',
// Middlewares applied to the dashboard routes
'middleware' => [
'web',
],
// Log entries shown per page
'pagination' => 20,
// Track details
'track_ip' => true,
'track_user_agent' => true,
'track_url' => true,
// Authorization configuration
'authorization' => [
'enabled' => false,
'gate' => 'view-auditify',
],
// Automatic tracking configurations
'track_auth_events' => true, // Login, Logout, Failed logins
'track_page_visits' => true, // Page visits
// Global model auditing
'auto_audit_models' => true, // Tracks all model lifecycle changes globally
'exclude_models' => [ // Model classes to exclude from global auditing
// App\Models\Session::class,
],
// Firewall scanning
'xss_protection' => [
'enabled' => true,
'block' => true, // Abort requests with HTTP 403 when script is found
'exclude_routes' => [
// 'admin/rich-text/*',
],
],
// Pruning configuration
'pruning' => [
'keep_days' => 90, // Default age in days for keeping historical log rows
],
];
```
## 🔌 手动记录与辅助方法
你可以使用 `Auditify` facade，在自己的 Laravel 控制器、后台任务或填充器中手动 Auditify 日志或暂时暂停审计。
### 1. 手动生成日志
在你的文件中引入该 facade：
```
use Auditify\Facades\Auditify;
```
#### 手动记录数据库/模块操作
```
Auditify::logAction(
action: 'PUBLISH',
module: 'Article',
description: 'User published a new article',
oldValues: ['status' => 'draft'],
newValues: ['status' => 'published'],
userId: auth()->id(), // optional, defaults to current authenticated user
subject: $article // optional, polymorphic eloquent model instance
);
```
#### 手动记录用户活动
```
Auditify::logActivity(
activity: 'Exported Reports (PDF)',
url: request()->fullUrl(), // optional, defaults to request URL
userId: auth()->id(), // optional
properties: ['timeframe' => '30_days'] // optional metadata payload
);
```
#### 手动记录安全警报
```
Auditify::logSecurity(
title: 'Suspicious Endpoint Access',
description: 'Blocked access attempt to restricted legacy endpoint',
severity: 'high', // options: low, medium, high, critical
payload: request()->all() // optional JSON request context
);
```
#### 真实的控制器示例
以下是在标准 Laravel 控制器中实现手动记录的实用示例，包含完整的代码注释：
```
namespace App\Http\Controllers;
use Illuminate\Http\Request;
use App\Models\Order;
use Auditify\Facades\Auditify; // Import the Auditify facade
class OrderController extends Controller
{
/**
* Cancel a customer order and log the audit trail.
*/
public function cancel(Request $request, $id)
{
// 1. Retrieve the order record from the database
$order = Order::findOrFail($id);
// Capture the original status for audit comparison
$oldStatus = $order->status;
// 2. Perform the cancellation business logic
$order->update([
'status' => 'cancelled',
'cancelled_at' => now(),
'cancellation_reason' => $request->input('reason')
]);
// 3. Manually Log a database Action showing the status transition
Auditify::logAction(
action: 'CANCEL_ORDER',
module: 'Order',
description: "Order #{$order->id} cancelled by user due to: " . $request->input('reason'),
oldValues: ['status' => $oldStatus],
newValues: ['status' => 'cancelled'],
userId: auth()->id(), // Associate log with the logged-in administrator
subject: $order // Link the polymorphic subject relation to this order model
);
// 4. Log a general user activity for dashboard stats tracking
Auditify::logActivity(
activity: 'Cancelled Order',
properties: [
'order_id' => $order->id,
'total_amount' => $order->total_price
]
);
// 5. Send a redirect response back to the admin portal
return redirect()->back()->with('success', 'Order cancelled and action audited.');
}
}
```
### 2. 暂停审计 (Seeders & 批量导入)
在运行数据迁移、数据库 seeders 或大型 CSV 导入时，你应该暂时禁用记录：
* **防止数据库拥堵（性能）：** 审计批量插入会使数据库查询量翻倍（10 万条记录 = 20 万次查询）。暂停日志可以防止数据库锁定并加快导入速度。
* **防止表膨胀（日志垃圾信息）：** Seeders 会生成虚假的模拟数据。暂停审计可以防止这些虚假记录填满你的审计日志表并减慢搜索速度。
#### 选项 A：运行闭包 (推荐用于 Seeders & Migrations)
**在哪里使用：** 在 **`database/seeders/DatabaseSeeder.php`** 或数据迁移文件中。
此辅助函数会在回调执行期间自动暂停审计，并安全地恢复之前的审计状态。
```
use Auditify\Facades\Auditify;
// Pauses auditing automatically for the duration of the callback function
Auditify::withoutAuditing(function () {
// Generate 1,000 dummy articles silently without log spam
Article::factory()->count(1000)->create();
});
```
#### 选项 B：手动切换审计 (推荐用于 Artisan 命令 & 测试套件)
**在哪里使用：** 在自定义的 Artisan 控制台命令 (`app/Console/Commands/ImportData.php`) 或 PHPUnit 测试设置 (`tests/TestCase.php`) 中。
直接打开或关闭审计标志。
```
use Auditify\Facades\Auditify;
// 1. Manually disable auditing
Auditify::disableAuditing();
// 2. Perform sequential operations...
User::insert($massiveCsvData);
// 3. Manually re-enable auditing
Auditify::enableAuditing();
```
## 🛠️ Artisan 命令
Auditify 提供了专用的命令，以自动完成安装和优化数据库大小的任务：
| Command | Description |
|---|---|
| `auditify:install` | 自动运行迁移并发布配置文件。 |
| `auditify:prune {--days=}` | 删除超过 N 天的旧审计日志记录（默认为 `keep_days` 配置值）。 |
### 1. 为什么要使用这些命令？
* **`auditify:install` (更简单的上手体验)：** 消除手动设置。它不需要开发者单独去复制配置、移动迁移文件和迁移数据表，而是通过一行终端命令即可完成整个扩展包的设置。
* **`auditify:prune` (优化数据库速度与存储)：** 高流量的生产系统会生成数百万条日志。无限期存储日志会减慢数据库查询速度、增加备份大小并增加存储成本。修剪操作可删除过时条目，确保仪表盘即时渲染并符合合规性保留要求（例如 GDPR、SOC2）。
### 2. 自动化数据库修剪设置
为了自动保持数据库表小巧且高性能，请在应用程序的任务调度器（`routes/console.php` 或 `app/Console/Kernel.php`）中调度修剪命令：
```
use Illuminate\Support\Facades\Schedule;
Schedule::command('auditify:prune --days=90')->daily();
```
## 🗺️ 路由参考
所有路由都分组在配置的 `route_prefix`（默认为：`auditify`）下，并应用了相应的 middleware。
| Method | URI | Controller Action | Description |
|---|---|---|---|
| GET | `/` | `DashboardController@index` | 主日志仪表盘索引 |
| GET | `/action-logs` | `ActionLogController@index` | 查看数据库操作日志列表 |
| GET | `/action-logs/{id}` | `ActionLogController@show` | 查看详情及并排属性差异 |
| GET | `/action-logs/export/csv` | `ActionLogController@exportCsv` | 以 CSV 格式导出操作日志 |
| GET | `/action-logs/export/excel` | `ActionLogController@exportExcel` | 以 Excel 格式导出操作日志 |
| GET | `/action-logs/export/pdf` | `ActionLogController@exportPdf` | 以 PDF 格式导出操作日志 |
| GET | `/activity-logs` | `ActivityLogController@index` | 查看活动日志列表 |
| GET | `/activity-logs/export/csv` | `ActivityLogController@exportCsv` | 以 CSV 格式导出活动日志 |
| GET | `/activity-logs/export/excel` | `ActivityLogController@exportExcel` | 以 Excel 格式导出活动日志 |
| GET | `/activity-logs/export/pdf` | `ActivityLogController@exportPdf` | 以 PDF 格式导出活动日志 |
| GET | `/security-logs` | `SecurityLogController@index` | 查看安全日志列表 |
| GET | `/security-logs/unread-check` | `SecurityLogController@checkUnreadAlerts` | 实时警报轮询检查 |
| GET | `/security-logs/{id}` | `SecurityLogController@show` | 查看安全日志详情 |
| POST | `/security-logs/{id}/read` | `SecurityLogController@markAsRead` | 切换日志读取状态 |
| GET | `/security-logs/export/csv` | `SecurityLogController@exportCsv` | 以 CSV 格式导出安全日志 |
| GET | `/security-logs/export/excel` | `SecurityLogController@exportExcel` | 以 Excel 格式导出安全日志 |
| GET | `/security-logs/export/pdf` | `SecurityLogController@exportPdf` | 以 PDF 格式导出安全日志 |
| POST | `/api/events` | `ActivityLogController@storeFrontendEvent` | 前端客户端交互记录 |
| GET | `/reports` | `ReportController@index` | 查看详细的日志分析和报告 |
## 🧪 测试
该扩展包包含一个全面的 PHPUnit 测试套件，涵盖模型、middlewares、控制器 endpoints 和 Artisan 命令。独立测试通过 `orchestra/testbench` 运行，无需父级 Laravel 安装。
克隆仓库并安装开发依赖：
```
git clone https://github.com/arpa12/laravel-auditify.git
cd laravel-auditify
composer install
```
运行所有测试：
```
./vendor/bin/phpunit
```
## 👤 作者
Arpa Nihan
全栈开发者
## 📄 许可证
在 [MIT 许可证](LICENSE.md) 下发布。
```
MIT License
Copyright (c) 2026 Arpa Nihan
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```
⭐ 如果 Auditify 为你节省了时间，请在 GitHub 上给它点个 Star！ ⭐
用 ❤️ 为 Laravel 社区打造
版权所有 © 2026 Arpa Nihan。保留所有权利。