shaadcode/payload-auditor
GitHub: shaadcode/payload-auditor
Payload Auditor 是一个 Payload CMS 插件，提供集中化的事件追踪、操作审计和安全监控功能。
Stars: 70 | Forks: 6
[](https://bundlephobia.com/package/payload-auditor)
# 📦 Payload Auditor
**Payload Auditor** 是一个专为 [Payload CMS](https://payloadcms.com) 设计的强大插件，提供集中的**事件追踪、审计和安全增强**功能。该工具专为希望在其 Payload 项目中监控关键操作、分析用户行为并增强后端安全的开发者和团队而设计。
📊 体积仅为 **~3.4 kB**（压缩 + Gzip）且**无外部依赖**。
## ⚙️ 安装与使用
使用你偏好的包管理器进行安装：
```
npm install payload-auditor
# 或
pnpm add payload-auditor
# 或
yarn add payload-auditor
```
然后，在你的 Payload 配置中注册该插件：
```
import { auditorPlugin } from 'payload-auditor'
export default buildConfig({
plugins: [
auditorPlugin({
// your plugin config here
}),
],
})
```
## 🔧 插件选项
该插件的设计允许你进行深度自定义。当然，该项目拥有完整的文档，你可以在开发过程中很好地利用它。
使用以下配置自定义插件（示例）：
```
auditorPlugin({
automation: {
logCleanup: {
cronTime: '* * * * *', // every minute
queueName: 'john-doe-queue',
},
},
collection: {
trackCollections: [
{
slug: "media",
hooks: {
afterChange: {
update: {
enabled: true,
},
},
},
},
],
},
});
```
## ✨ **你可以自定义的内容：**
- 🔒 **你可以控制日志的访问权限。** 出于插件安全性的考虑，其他操作将不可用。
- 🛠️ **你可以管理日志注入到数据库的方式。**
- 🏷️ **你可以自定义插件所有内置集合的值。**
- 📊 **你可以指定想要追踪的集合。**
## ✨ **如何为每个集合自定义日志记录：**
在日志记录方面，我们已经为你允许追踪的每个集合将整个插件与 **Payload CMS hooks** 集成，因此你可以**追踪整个应用程序**。**payload-auditor** 进行日志记录**不是基于 hooks 本身，而是基于每个 hook 内部的操作**。阅读 collection hooks 文档可以让你更好地理解插件的工作原理。
🔍 **简而言之，对于每个集合，你可以进行以下更改：**
- 🏷️ **设置你想要的 collection slug。** 这是追踪的基础，使插件能够找到你的集合。
- ⚙️ **启用所需的 hooks。** 如前所述，该插件支持所有 Payload CMS hooks。
- 🔄 **在每个 hook 中启用自定义操作。** 也许你需要某个 hook，但不想使用该 hook 内部的所有操作进行日志记录。例如，在 `afterOperation` hook 内部，只有 `create` 操作会创建日志。
- ⏸️ **你可以暂时停止追踪该集合。**
## 🧠 何时使用它？
- 你需要追踪关键的集合更改（例如，用户登录、更新）
- 你想为你的 Payload 项目提供额外的后端安全
- 你在具有特定角色需求的多用户管理后台环境中工作
- 你正在构建 SaaS 或企业级的基于 Payload 的产品
## 📚 文档
使用该插件非常简单。只需指定你要追踪的 collection 或 global 的 slug，然后配置你需要监控的 hooks 和操作即可。
### `automation`
配置插件的自动化功能。
目前，该插件支持使用 Payload CMS 的 Jobs 系统进行**自动日志清理**。
### `collections` 和 `globals`
这些是插件的核心部分，用于管理操作追踪。它们共享几乎完全相同的 API。
每个部分都有一个 `track` 属性，该属性接受以下配置：
| 属性 | 描述 |
| ------------------------------------ | ------------------------------------------------------------------------------------------ |
| `hooks` | 定义要追踪的 hooks。 |
| `hooks["hookName"]` | 要追踪的 hook 名称。可以是 `true` 或配置对象。 |
| `hooks["hookName"]["operationName"]` | 在指定 hook 内要追踪的操作。可以是 `true` 或配置对象。 |
| `slug` | `collection` 或 `global` 的 slug。该值是类型安全的。 |
#### 重要提示：
- 在 **hook 级别**（`hooks["hookName"]`）和**操作级别**（`hooks["hookName"]["operationName"]`），以下属性始终可用：
| 属性 | 描述 |
| -------------- | ------------------------------------------------------------------------ |
| `customLogger` | 用于自定义日志输出的自定义函数。 |
| `debug` | 为 hook 或操作启用调试。可以是 `true` 或对象。 |
- 当为 hook 或操作启用 `debug: true` 时，默认情况下日志**不会保存到数据库**。要覆盖此行为，请设置 `debug.skipDatabaseSave: false`。日志仍将显示在控制台中。
- 如果你正在追踪的 hook 没有操作（例如，`afterRead` 或 `afterForgotPassword`），插件会将二级键视为操作名称。例如，`forgot-password` 或 `read`。
- 使用 `customLogger` 时，请确保在你的输出中包含必要的内部集合字段（或自定义字段）。`operation` 和 `hook` 的值始终由插件覆盖并且是必填的。该函数必须返回一个对象。
- 在 hook 和操作级别都提供了一个 `enabled` 属性。这允许你为特定的 hooks 或操作启用或禁用追踪。
- 将 hook 或操作设置为 `false` 将完全禁用它。
### `buffer`
配置日志刷新到数据库的方式。你可以基于**时间**或**日志数量**来控制刷新。
| 属性 | 描述 |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `flushStrategy` | 定义刷新策略。选项：
- `size`：当日志数量达到指定限制时刷新。
- `time`：在指定的时间间隔后刷新。
- `realTime`：创建日志后立即刷新。 |
| `size` | 数值。当日志数量达到此数字时，将刷新日志。与 `size` 策略配合使用。 |
| `time` | 以毫秒为单位的数值。日志将以此间隔刷新。与 `time` 策略配合使用。 |
### `configureRootCollection`
允许你自定义内部集合的函数。
该函数接收默认集合配置作为参数，并期望你返回修改后的配置。
## 📄 许可证
[MIT 许可证](./LICENSE)
标签：CSV输出, GNU通用公共许可证, MITM代理, Node.js, Payload CMS, 事件追踪, 审计日志, 插件, 自动化攻击