TREK 审计日志完全指南:实例级 Audit Log 与插件哈希链能力审计

原创2026-09-14 14:11:161,837 阅读
文章标签:后端前端移动开发MCP 服务插件系统AI 应用WebSocket微服务

TREK 审计日志完全指南:实例级 Audit Log 与插件哈希链能力审计

TREK 是自托管旅行规划器,内置一套双层次审计体系:实例级审计日志(Audit Log)记录登录、管理员操作、备份、OAuth 与集成配置等敏感动作,插件能力审计(Plugin Capability Audit)则用哈希链为每个插件的主机中介操作提供防篡改记录。本文以 wiki/Audit-Log.md 为主体,结合 server/src/services/auditLog.ts、server/src/nest/plugins/host/plugin-audit.ts 等源码,完整讲解两类日志的存储、读取、轮转、保留策略与反代 IP 配置,读完即可在自建实例上落地可追溯、可审计、可问责的安全基线。

一、审计日志是什么,为什么要看它

审计日志记录在 TREK 实例上发生的重要操作:登录尝试、密码修改、管理员对用户和权限的变更、OIDC/SSO 配置、备份与恢复、MCP 工具调用、OAuth 令牌签发、插件能力调用等。它回答三个问题:

  • 谁(User)在什么时间(Time)做了什么(Action);
  • 影响到了哪个资源(Resource,如文件名、行程 ID、工具名);
  • 来源 IP 是什么(IP),附带何种上下文(Details,JSON 格式)。

从源码看,实例级审计的落库实现集中在 server/src/services/auditLog.ts 的 writeAudit():它先把一条记录写入 audit_log 表,再同步写入纯文本日志文件,且所有写入都是 best-effort 设计——即使日志文件不可写或数据库异常,也只记录错误而不抛出、不打断业务主流程。

对应数据表定义位于 server/src/db/migrations.ts(及 server/src/db/schema.ts):

audit_log
├── id           INTEGER PRIMARY KEY AUTOINCREMENT
├── created_at   DATETIME DEFAULT CURRENT_TIMESTAMP
├── user_id      INTEGER REFERENCES users(id) ON DELETE SET NULL
├── action       TEXT NOT NULL   -- 动作键,如 user.login
├── resource     TEXT            -- 受影响资源
├── details      TEXT            -- 附加上下文(JSON 字符串)
└── ip           TEXT            -- 客户端 IP

配套索引 idx_audit_log_created ON audit_log(created_at DESC) 支撑按时间倒序分页查询。user_id 采用 ON DELETE SET NULL,用户被删除后审计记录仍保留、只是用户关联置空。

二、在哪里找到审计日志

打开 Admin Panel(管理面板)→ Audit(审计) 标签页即可查看实例级审计日志。

TREK 管理面板中的审计日志列表界面

面板默认每页加载 100 条,底部点击 Load more 拉取下一页,表格上方显示总条数。后端实现见 server/src/nest/admin/admin.controller.ts 的 GET /api/admin/audit-log,最终落到 server/src/services/adminService.ts 的 getAuditLog():

  • limit 默认 100,被钳制在 1~500 之间;
  • offset 默认 0,不允许负数;
  • SQL 用 LEFT JOIN users 关联出用户名与邮箱,按 id DESC 倒序;
  • 同时 SELECT COUNT(*) 返回总量用于显示;details 字段按 JSON 解析,解析失败时置 _parse_error: true 而非报错。

三、日志捕获的动作键(Action Key)全表

动作键(Action key)是日志中存储的原始值,按区域分组如下,面板中会用友好文案显示(映射见 server/src/services/auditLog.ts 的 ACTION_LABELS)。

3.1 认证(Authentication)

Action key Description
user.register 用户注册
user.login 用户登录
user.login_failed 登录尝试失败
user.password_change 用户修改密码
user.account_delete 用户删除自己的账号

3.2 MFA

Action key Description
user.mfa_enable 在账号上启用 MFA
user.mfa_disable 在账号上禁用 MFA

3.3 行程(Trips)

Action key Description
trip.create 创建行程(含标题)
trip.update 更新行程(含变更字段)
trip.copy 复制行程(含源行程与新行程 ID)
trip.delete 删除行程(含行程 ID 与标题)

3.4 管理员操作(Admin actions)

Action key Description
admin.user_create 管理员创建用户
admin.user_update 管理员编辑用户(角色、邮箱、用户名等)
admin.user_delete 管理员删除用户
admin.invite_create 创建邀请链接
admin.invite_delete 删除邀请链接
admin.permissions_update 更新实例权限
admin.oidc_update 更新 OIDC/SSO 设置
admin.addon_update 启用、禁用或配置 Addon
admin.oauth_session.revoke 管理员吊销 OAuth 会话
admin.rotate_jwt_secret 轮换 JWT 密钥
admin.bag_tracking 切换行李追踪功能开关
admin.places_photos 切换地点照片功能开关
admin.places_autocomplete 切换地点自动补全功能开关
admin.places_details 切换地点详情功能开关
admin.collab_features 更新协作功能
admin.packing_template_delete 删除打包清单模板
admin.default_user_settings_update 更新默认用户设置
admin.demo_baseline_save 保存 Demo 基线快照
settings.app_update 更新应用设置(SMTP、webhook、MFA 策略等)

3.5 备份(Backups)

Action key Description
backup.create 创建手动备份
backup.restore 从存储的备份恢复
backup.upload_restore 从上传的 ZIP 恢复
backup.delete 删除备份
backup.auto_settings 保存自动备份计划

3.6 MCP

Action key Description
mcp.tool_call 调用 MCP 工具(resource 为工具名)

3.7 OAuth

Action key Description
oauth.client.create 创建 OAuth 客户端应用
oauth.client.rotate_secret 轮换 OAuth 客户端密钥
oauth.client.delete 删除 OAuth 客户端应用
oauth.consent.grant 用户授予 OAuth 同意
oauth.token.issue 签发 OAuth 访问令牌
oauth.token.refresh 刷新 OAuth 访问令牌
oauth.token.revoke 吊销 OAuth 令牌
oauth.token.grant_failed OAuth 令牌授权尝试失败
oauth.token.client_auth_failed OAuth 客户端认证失败

3.8 集成(Integrations)

Action key Description
immich.private_ip_configured 保存了解析为私网 IP 的 Immich URL

3.9 动作键细节增强

writeAudit() 在写库之外,还会生成一行人类可读的 INFO 日志,细节格式见 buildInfoSummary()(server/src/services/auditLog.ts):

  • trip.create 附带 "<title>";trip.delete 附带 tripId=<id>;user.register 附带邮箱;
  • user.login_failed 附带失败原因 reason=...;
  • settings.app_update 会拼出变更明细,如 channel=...、smtp、events、webhook_url、file_types、registration=true/false、mfa=true/false;
  • immich.private_ip_configured 附带 url=... ip=<解析出的私网 IP>。

另外 server/src/services/auditLog.ts 中还能看到文档表未列出的动作键,如 admin.user_role_change(修改用户角色)、admin.plugin_retrust(重新信任插件作者签名密钥),说明该映射表会随版本持续扩充。

四、日志列含义

Column Description
Time 动作的时间戳
User 执行动作的用户名和邮箱(未认证事件显示 anonymous)
Action 动作键(见上文各表)
Resource 受影响的资源(文件名、行程 ID、工具名等,视场景而定)
IP 客户端 IP
Details 附加上下文,JSON 格式

未认证事件对应源码中 resolveUserEmail() 的兜底逻辑(server/src/services/auditLog.ts):userId 为空时返回 anonymous;用户已删除时返回 uid:<id>。

五、分页机制

面板默认按 100 条/页加载,底部 Load more 加载下一页,总条数显示在表格上方。这对应 getAuditLog() 的 LIMIT ? OFFSET ? 分页实现(server/src/services/adminService.ts):limit 上限 500,offset 从 0 开始,按 id DESC 倒序保证最新记录优先展示。

六、IP 地址与反向代理(重要)

客户端 IP 取自 X-Forwarded-For 请求头。当 TREK 部署在反向代理之后时,必须设置 TRUST_PROXY=1(其值表示代理跳数),代理头才会被信任,从而记录真实客户端 IP;否则记录的是代理自身的 IP。

源码印证:server/src/middleware/globalMiddleware.ts 在 NODE_ENV=production 或设置了 TRUST_PROXY 时执行 app.set('trust proxy', parseInt(process.env.TRUST_PROXY) || 1);server/src/services/auditLog.ts 的 getClientIp() 取 X-Forwarded-For 的首个 IP(跳过字符串或数组两种形态),无该头时才回退到 req.socket.remoteAddress。相关环境变量完整清单见 wiki/Environment-Variables.md。

七、日志文件与轮转

除数据库外,审计事件还会写入纯文本日志文件:

  • 路径: ./data/logs/trek.log(相对进程工作目录)
  • 轮转: 文件达到 10 MB 时轮转
  • 保留: 保留最近 4 个轮转文件(trek.log.1 至 trek.log.4)

实现见 server/src/services/auditLog.ts:rotateIfNeeded() 在写入前检查文件大小,超过 10 MB 时按 trek.log -> trek.log.1 -> ... 依次改名滚动(MAX_LOG_FILES = 5 即当前文件加 4 个历史文件);日志带 ANSI 彩色级别前缀(<a href="https://link.gitcode.com/i/ce87638b022d3c375a191a0d589975e8" target="_blank">INFO]/[DEBUG]/[WARN]/[ERROR]),时间戳受 TZ 环境变量控制,DEBUG 级别还额外写入 AUDIT <action> userId=<id> <detailsJson> 的调试行([server/src/services/auditLog.ts)。

八、数据库保留策略

数据库中的审计条目永远不会被自动删除,会持续累积并在 UI 中分页展示。换句话说,实例级审计是“只增不减”的完整流水账,配合上文表格可做长期回溯;磁盘占用完全由你的操作频率决定。

九、插件能力审计(哈希链防篡改)

与实例级审计日志分离,TREK 为已安装插件维护一套专用的 哈希链能力审计(hash-chained capability audit)。

9.1 记录什么、在哪里记录

插件执行的每一项主机中介动作——核心数据读取、WebSocket 广播、通知、AI 调用、跨插件调用——都在插件无法触及的 RPC 边界(主机侧)被记录,同时记录:

  • 执行用户:由主机绑定(acting user),绝不接受插件自行提供;
  • 接触的资源(resource);
  • 结果代码(outcome code)。

实现见 server/src/nest/plugins/host/plugin-audit.ts 的 isAuditable():凡是通过非 db:own 权限解锁的方法都属于核心表面并被自动审计;plugins.call 与 events.emit 虽不携带权限也显式列入审计。auditResource()(同文件 L32-L67)把方法名与参数映射为资源描述,例如 trips.listMine → trips:all、ws.broadcastToTrip → trip:<id>、ai.complete → ai:invoke、plugins.call → plugin:<id>#<fn>。

9.2 哈希链原理

每个插件各自的条目构成一条按插件隔离的哈希链:

hash = sha256(previous_hash + row)

其中 row 是 <a href="https://link.gitcode.com/i/0a64309f87285d88271d63b401772da2" target="_blank">pluginId, actingUserId, method, resource, code, ts] 的 JSON 序列化([server/src/nest/plugins/host/plugin-audit.ts 的 appendAudit())。因此日志是可察觉篡改的(tamper-evident):任何被修改或删除的条目都会破坏链条。表结构 plugin_capability_audit 见 server/src/db/migrations.ts,含 plugin_id、acting_user_id、method、resource、code、ts、prev_hash、hash 字段及 (plugin_id, id) 联合索引。

9.3 保留与裁剪

每个插件达到行数上限后,较早的行会被裁剪(默认 20,000 行/插件,可通过 TREK_PLUGIN_AUDIT_MAX_ROWS 调整;设为 0 则禁用裁剪)。裁剪在链上是安全的:保留窗口内每行 hash = sha256(其存储的 prev_hash + 自身内容) 依然成立,仅丢失到已被删除起源的连续性——这是任何保留策略固有的特性。实现见 server/src/nest/plugins/host/plugin-audit.ts:默认值 20_000 通过 envInt() 读取,裁剪按每 500 次追加摊销执行一次 COUNT/DELETE。

9.4 两个读取视图

View Who Where Shows
按插件审计(Per-plugin audit) 管理员 管理面板插件管理(GET /api/admin/plugins/:id/audit) 单个插件在所有用户下执行的全部动作
我的插件活动(My plugin activity) 任意用户 设置 → 插件(GET /api/plugin-activity) 任意插件以该用户名义执行的全部动作

用户侧视图由 server/src/nest/plugins/plugin-activity.controller.ts 提供,内部调用 readAuditForUser()(server/src/nest/plugins/host/plugin-audit.ts),按 acting_user_id 关联插件名倒序返回最近 200 条。它的意义在于:宽泛的数据读取授权对“数据被读取的那个人”可问责——任何用户都能看到插件以自己名义做了什么,而无需管理员权限。这正是 TREK 敢于向大型插件授予宽泛读取权限的底气所在。

十、See also

登录后查看全文
TREK