49 lines
2.8 KiB
Markdown
49 lines
2.8 KiB
Markdown
---
|
||
name: app_audit
|
||
description: 全局审计日志模块。append-only 审计，owner.audit 角色隔离，防自删。Use when 写入/查询/备份/删除审计日志，或为关键操作接入审计。
|
||
---
|
||
|
||
# app_audit — 审计日志全局模块
|
||
|
||
## 架构
|
||
|
||
独立仓库 + 独立 Python 包。其他模块通过 `from app_audit import audit_log` 在关键操作时写入审计。
|
||
|
||
```
|
||
app_audit/
|
||
├── app_audit/
|
||
│ ├── __init__.py # 导出 audit_log / is_audit_role / list/backup/delete
|
||
│ ├── audit_service.py # 核心逻辑（纯函数，只依赖 sqlor/appPublic）
|
||
│ └── init.py # load_app_audit：add_startup 建表 + owner.audit 角色
|
||
├── models/sd_audit_logs.json
|
||
├── wwwroot/index.ui # DataGrid 审计日志列表界面
|
||
├── wwwroot/api/audit.dspy # list/backup/delete
|
||
└── scripts/load_path.py # RBAC 权限注册（仅 owner.audit）
|
||
```
|
||
|
||
## 数据模型
|
||
|
||
`sd_audit_logs`：id, user_id, username, action, target, detail(text), result, client_ip, created_at。append-only（只 INSERT 不 UPDATE）。
|
||
|
||
## 关键端点
|
||
|
||
`/app_audit/api/audit.dspy`（action 参数）：
|
||
- `list`：分页查询，返回 `{rows, total}`（DataGrid 兼容）。过滤参数 user_id/username/act/from/to，分页 page/rows。
|
||
- `backup`：导出 JSON，支持过滤 + limit（上限 50000）。
|
||
- `delete`：按 `before` 时间戳删除（`audit_delete` 留痕永不删）。
|
||
|
||
## 审计事件清单（VALID_ACTIONS 白名单）
|
||
|
||
认证 login/login_fail/logout；权限 role_change/perm_change/user_role_change；工作环境 work_env_set/org_key_gen/remote_bwrap；部署账号 account_create/account_remove/sandbox_run；用户机构 user_create/user_disable/user_delete/org_change；财务 customer_recharge；审计自身 audit_delete/audit_backup。非白名单 action 归 `unknown`（detail 保留原始值）。
|
||
|
||
## Pitfalls
|
||
|
||
- **审计独立性**：owner.audit 与 owner.superuser 完全隔离，superuser 也无权看审计。双层校验（RBAC path 挂 owner.audit + audit.dspy 内 is_audit_role），应用层是兜底（独立 app 的 RBAC 对未注册路径可能放行）。
|
||
- **审计写入是旁路**：audit_log 内 try/except，失败不阻断主流程。
|
||
- **run 类接口 result 判断用 `rc == 0`**：run_in_sandbox/run_in_work_env 返回 `{rc, stdout, stderr}`，没有 `ok` 键，不能 `r.get('ok')`（会恒判 fail）。
|
||
- **sqlor `%` 是占位符**：LIKE 要写 `%%`。
|
||
- **INSERT IGNORE 在 aiomysql 打 Duplicate entry 警告**（无害噪音）。
|
||
- **RBAC 缓存 600s TTL**：注册新权限后要重启服务才生效。
|
||
- **审计员用户 user_status='0' 才是启用**：basic_auth 判断 `user_status != '0'` 为禁用。
|
||
- **owner.audit 角色的 role 表 id 是 'owner.audit' 字符串**（非随机 ID），userrole.roleid 直接存 'owner.audit'。
|