TREK 审计日志完全指南:实例级 Audit Log 与插件哈希链能力审计
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(审计) 标签页即可查看实例级审计日志。
面板默认每页加载 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
- Admin-Panel-Overview —— 管理面板整体介绍
- Security-Hardening —— 安全加固清单
- Environment-Variables ——
TRUST_PROXY、TREK_PLUGIN_AUDIT_MAX_ROWS等环境变量说明
