ToolJet 审计日志（Audit Logs）完整指南：记录、筛选、脱敏与文件导出-平芜编程栈

ToolJet 审计日志（Audit Logs）完整指南：记录、筛选、脱敏与文件导出

【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 🚀项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet

本文围绕 ToolJet 的审计日志（Audit Logs）功能展开，系统讲解如何通过日期范围与多维度筛选检索账户内全部操作记录、如何解读每条日志的完整字段结构，以及如何通过环境变量配置日志文件的生成路径、每日轮转与敏感信息脱敏。读完本文，你将能够在自托管部署中开启审计日志文件输出，并结合环境变量配置与 syslog 集成方案落地合规审计与安全追踪。

付费功能提示：Audit Logs 属于 ToolJet 的付费功能（Paid feature），需要对应的许可证支持。

什么是审计日志

审计日志是 ToolJet 账户内所有操作行为的自动记录报告。它自动捕获并展示事件，记录谁（who）在何时（when）、何地（where）执行了什么操作（what），同时附带 IP 地址等信息。简单来说，每一次登录、建应用、跑查询、改权限等动作，都会被记录成一条可检索、可追溯的事件。

在服务端，每条审计事件对应一张数据库表记录，其实体定义位于 server/src/entities/audit_log.entity.ts，对应数据库表audit_logs。核心字段包括：

id：UUID 主键，唯一事件 ID；
user_id/organization_id：执行者用户与所属组织；
resource_id/resource_name/resource_type：被操作资源的 ID、名称与类型（resource_type使用枚举，取值见 server/src/modules/app/constants/modules.ts，包含APP、USER、DataQueries、GroupPermissions等）；
action_type：动作类型（如APP_CREATE、USER_LOGIN）；
ip_address：来源 IP；
metadata：JSON 结构，包含tooljet_version与user_agent；
created_at：事件产生时间。

日志写入侧还使用了 winston 自定义格式auditLog（见 server/src/modules/audit-logs/constants/index.ts），把审计数据注入auditLog字段并提取resourceType作为日志label，这解释了下方示例日志文件中的结构。

在界面中查看与检索日志

打开账户的 Audit Logs 页面即可看到日志列表视图，默认展示最近 24 小时的日志，并提供日期范围选择、筛选与分页能力。

日期范围（Date Range）

使用范围选择器（range picker）检索指定日期与时间区间内发生的事件；
默认加载最近 24 小时的日志作为初始视图；
"from" 与 "to" 之间可指定的最大跨度是 30 天，超出范围无法检索；
页面底部提供分页导航，每页最多展示 7 条日志。

30 天最大查询跨度由许可证条款控制。前端通过getMaxDurationForAuditLogs()请求/license/audit-logs/max-duration接口获取上限（见 frontend/src/_services/auditLogsService.js），服务端对应控制器定义在 server/src/modules/licensing/controllers/audit-logs.controller.ts，其能力受许可证字段MAX_DURATION_FOR_AUDIT_LOGS（maxDaysForAuditLogs）约束（见 server/src/modules/licensing/constants/index.ts）。

筛选审计日志

Audit Logs 页面提供四组筛选条件，可组合使用以快速定位目标事件。

按用户筛选（Select Users）

从下拉列表中选择特定用户，即可查看该用户的所有活动记录。

按应用筛选（Select Apps）

下拉列表会展示当前账户关联的全部应用。选择某个应用后，日志将只保留与该应用相关的记录。

按资源筛选（Select Resources）

资源（Resources）	说明
User	过滤全部用户类事件，如`USER_LOGIN`、`USER_SIGNUP`、`USER_INVITE`、`USER_INVITE_REDEEM`。
App	过滤全部应用类事件，如`APP_CREATE`、`APP_UPDATE`、`APP_VIEW`、`APP_DELETE`、`APP_IMPORT`、`APP_EXPORT`、`APP_CLONE`。
Data Query	过滤与数据查询关联的事件，如`DATA_QUERY_RUN`。
Group Permission	过滤全部与用户组权限关联的事件，包括`GROUP_CREATE`、`GROUP_UPDATE`、`GROUP_DELETE`。
App Group Permission	每个用户组内可为应用设置只读或可编辑权限，这些变更会作为应用组权限事件被记录。

前端获取资源列表调用getResources()请求/audit-logs/resources接口（见 frontend/src/_services/auditLogsService.js）。需要说明的是，资源枚举在代码层面是可扩展的：除上表外，server/src/modules/app/constants/modules.ts 中还定义了Workflows、AppGit、AppHistory、DataQueryFolders等更多模块类型，界面中是否展示取决于当前版本与许可证能力。

按动作筛选（Select Actions）

动作（Actions）	说明
USER_LOGIN	每次用户登录时记录。
USER_SIGNUP	每次新用户注册时记录。
USER_INVITE	在`Manage Users`中邀请用户时，每次发送邀请都会记录一条事件。
USER_INVITE_REDEEM	邀请被兑换（接受）时记录。
APP_CREATE	用户创建新应用时记录。
APP_UPDATE	对应用重命名、设为公开、编辑分享链接或部署应用等操作时记录。
APP_VIEW	有人查看已发布应用时记录（公开应用不计入）。
APP_DELETE	用户从仪表盘删除应用时记录。
APP_IMPORT	用户导入应用时记录。
APP_EXPORT	应用被导出时记录。
APP_CLONE	复制现有应用生成克隆时记录。
DATA_QUERY_RUN	添加数据源、创建查询，或从查询编辑器/已发布应用中运行查询时记录。
GROUP_PERMISSION_CREATE	创建用户组时记录。
GROUP_PERMISSION_UPDATE	向组中添加/移除应用或用户，或更新组权限时记录。
GROUP_PERMISSION_DELETE	从账户中删除用户组时记录。
APP_GROUP_PERMISSION_UPDATE	为用户组中的应用设置`View`（查看）或`Edit`（编辑）权限，且权限被更新时记录；默认情况下，应用对用户组的权限为`View`。

理解日志信息

展开任一条日志，可以看到完整的结构化信息。下面对照 readinglogv2 截图逐字段解读。

属性（Property）	说明
action_type	该事件记录的动作类型，具体取值见上文按动作筛选一节。
created_at	事件被记录时的日期与时间。
id	每条事件被分配的唯一事件 ID。
ip_address	产生该事件来源的 IP 地址。
metadata	包含两个子属性：`tooljet_version`（事件发生时 ToolJet 的版本）与`user_agent`（使用的设备与浏览器信息）。
organization_id	ToolJet 中每个组织都有唯一 ID，事件发生时会被一并记录。
resource_id	不同资源在创建时被分配各自关联的 ID。
resource_name	参与事件记录的资源名称，例如创建或删除应用时会显示该应用的名称。
resource_type	指示参与事件的资源类型。
user_id	每个用户账户在 ToolJet 中有唯一 ID，事件发生时一并记录。

这些字段与数据库实体一一对应（见 server/src/entities/audit_log.entity.ts），其中resource_type是枚举列，取值源自MODULES常量（server/src/modules/app/constants/modules.ts），metadata以 JSON 存储。

日志文件：导出、轮转、脱敏与路径

除界面内查看外，审计日志还可以输出为本地文件，便于归档、投递到 syslog 或第三方分析平台。

日志文件（Log File）

日志文件会包含审计日志的全部数据。只要在环境变量中指定了路径，系统就会在该路径下生成日志文件，并且每生成一条新审计日志，文件都会被动态更新。

关于如何启用日志文件生成，可参考 syslog 集成指南：只需将环境变量LOG_FILE_PATH设为期望的路径（例如rsyslog）即可激活该功能。详细的启动与验证步骤（包括如何检查生成的目录结构）都在该文档中。

日志轮转（Log Rotation）

日志文件按每日轮转：每天都会创建一个新日志文件，从而高效地管理与组织审计数据。实现上，服务端基于winston-daily-rotate-file的DailyRotateFiletransport 完成轮转，目录名为{process_id}-%DATE%，文件名固定为audit.log，日期模式为YYYY-MM-DD；轮转时还会把旧文件的内容整理并写出为.json格式的归档文件，相关代码见 server/src/modules/log-to-file/constants/index.ts。

日志脱敏（Log Redaction）

ToolJet 实现了日志脱敏以保护敏感信息。默认情况下，以下请求/响应头在日志中被掩码：

authorization
cookie
set-cookie
x-api-key
proxy-authorization
www-authenticate
authentication-info
x-forwarded-for

在服务端，这些默认脱敏路径被硬编码在 pino logger 的redact.paths配置中，并统一使用[REDACTED]作为掩码内容；同时会把环境变量LOGGER_REDACT中的逗号分隔字段合并进脱敏路径列表（见 server/src/modules/app/loader.ts）。

此外，你还可以通过LOGGER_REDACT环境变量指定自定义脱敏字段：

变量	说明
LOGGER_REDACT	需要被掩码的额外字段的逗号分隔列表（例如`req.headers["x-session-id"],req.headers["x-device-fingerprint"]`）

例如：

LOGGER_REDACT=res.headers["x-rate-limit-remaining"],res.headers["x-request-id"]

注意：LOGGER_REDACT中的每个条目会被直接拼接到 pino 的redact.paths数组（server/src/modules/app/loader.ts），因此请使用与示例一致的 pino 路径语法（如req.headers["xxx"]、res.headers["xxx"]）。

日志文件路径（Log File Path）

日志文件的路径由环境变量LOG_FILE_PATH定义。该路径相对于机器的主目录（home directory）。例如，若LOG_FILE_PATH设为hsbc/dashboard/log，则最终生成的日志文件路径结构如下：

homepath/hsbc/dashboard/log/tooljet_log/{process_id}-{date}/audit.log

其中{process_id}是唯一进程标识符的占位符，{date}表示当前日期。这种结构化路径确保审计日志按进程与日期双重组织，便于追踪与分析。

变量	说明
LOG_FILE_PATH	日志文件将被创建的路径（例如`tooljet/log/tooljet-audit.log`）

该行为与代码实现一致：服务端使用path.join(os.homedir(), filePath, 'tooljet_log')计算绝对目录，目录不存在时会自动递归创建，再以{processId}-%DATE%作为子目录写入audit.log（见 server/src/modules/log-to-file/constants/index.ts）。

示例日志文件数据

以下是一条APP_CREATE事件的真实日志结构（展开查看）：

{ level: 'info', message: 'PERFORM APP_CREATE OF awdasdawdwd APP', timestamp: '2023-11-02 17:12:40', auditLog: { userId: '0ad48e21-e7a2-4597-9568-c4535aedf687', organizationId: 'cf8e132f-a68a-4c81-a0d4-3617b79e7b17', resourceId: 'eac02f79-b8e2-495a-bffe-82633416c829', resourceType: 'APP', actionType: 'APP_CREATE', resourceName: 'awdasdawdwd', ipAddress: '::1', metadata: { userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36', tooljetVersion: '2.22.2-ee2.8.3' } }, label: 'APP' }

可以看到，auditLog内的字段与界面展示的日志属性一一对应，且与数据库实体字段保持一致；顶层timestamp使用YYYY-MM-DD HH:mm:ss格式，label取自resourceType，二者均由 winston 日志格式在写入时注入（见 server/src/modules/log-to-file/constants/index.ts 与 server/src/modules/audit-logs/constants/index.ts）。

数据保留策略

审计日志在数据库中会按保留期自动清理。服务端通过AuditLogsClearScheduler定时任务（server/src/modules/audit-logs/scheduler.ts）实现：

任务每天凌晨 2:00（CronExpression.EVERY_DAY_AT_2AM）运行；
删除早于保留期截止日期的日志，截止日期 = 当前日期 - 保留天数；
保留天数由环境变量AUDIT_LOGS_RETENTION_PERIOD控制，默认 90 天；
将该变量设为0可跳过清理，永久保留审计日志。

# 默认保留 90 天（不设置时） # 自定义保留天数，例如 30 天 AUDIT_LOGS_RETENTION_PERIOD=30 # 禁用自动清理，永久保留 AUDIT_LOGS_RETENTION_PERIOD=0

权限与可用性说明

审计日志受许可证（license）控制，属于付费能力：

服务端通过FeatureAbilityGuard结合许可证字段LICENSE_FIELD.AUDIT_LOGS（auditLogsEnabled）进行能力校验，前端在无权限时仅渲染空页面（见 frontend/src/modules/auditLogs/pages/AuditLogsPage/AuditLogsPage.jsx）；
后端提供/audit-logs、/audit-logs/resources、/license/audit-logs/license-terms、/license/audit-logs/max-duration等接口（见 frontend/src/_services/auditLogsService.js 与 server/src/modules/licensing/controllers/audit-logs.controller.ts）；
在 server/src/modules/licensing/constants/index.ts 的计划定义中，Audit logs 属于 Team（business）及以上计划的功能。

最佳实践小结

按需设置保留期：默认 90 天的清理策略适合大多数场景；若有合规留存要求，可通过AUDIT_LOGS_RETENTION_PERIOD=0关闭清理，或设置更长天数。
开启日志文件输出：设置LOG_FILE_PATH（相对主目录）即可生成每日轮转的audit.log，轮转时自动产出 JSON 归档，方便投递 syslog 或导入分析平台。
主动脱敏敏感头：默认脱敏列表覆盖authorization、cookie、x-api-key等常见敏感头；自定义头（如会话 ID、设备指纹）务必通过LOGGER_REDACT补充掩码，避免敏感信息进入日志。
善用筛选组合：结合「用户 + 应用 + 资源 + 动作」四维筛选与 30 天范围查询，可快速定位安全事件（如异常的USER_LOGIN、越权的APP_GROUP_PERMISSION_UPDATE）。
留意许可证边界：审计日志是付费功能，查询最大时间跨度也受许可证maxDaysForAuditLogs约束，自托管部署前请确认许可证与版本支持情况。