跳转到内容
GitHub

日志与审计

系统留三种记录,回答三个问题:登录日志回答「谁、什么时候、从哪登录的,成没成功」,账号被锁、被强制下线这类安全事件也记在这里;操作日志回答「谁调了哪个接口、带了什么参数、结果如何、花了多久」,密码、令牌这类字段落库前就打码;数据变更记录回答「这条数据的哪个字段被谁从什么改成了什么」,和触发它的那次操作日志互相跳转。数据变更记录带一条签名链,记录被改、被删、被塞进来都能校验出来。三种记录默认都保留 180 天。

数据变更记录
入口路径权限码做什么
日志管理 → 登录日志/log/login查看 log:login:list · 导出 export · 清空 clear每次登录尝试和安全事件
日志管理 → 操作日志/log/opera查看 log:opera:list · 导出 export · 清空 clear每次接口调用;详情里有「这次改了什么」
日志管理 → 数据变更/log/change查看 log:change:list · 导出 log:change:export字段级的前后对比;超级管理员多一个「校验完整性」
用户、部门、角色、菜单、参数配置五个页面的行操作「变更记录」——log:change:list只看这一个对象的变更历史
  • 登录日志和操作日志页没有逐行删除,只有「清空」:整张表删掉、不管当前的筛选条件。数据变更记录不能删、也不能清空,只会按保留天数被清理。
  • ⚠️ 登录日志、操作日志两页的前端路由守卫目前认的是 log:login:del / log:opera:del,不是 list —— 只授了查看的角色打不开这两页。数据变更页认的是 log:change:list。
  • 数据变更记录不受数据范围约束:有 log:change:list 的人看得到所有对象的变更。

每一行:用户名、成功 / 失败、原因、IP 和归属地(国家 / 地区 / 城市)、浏览器、操作系统、设备、时间,以及事件类型:

事件什么时候记
登录每一次登录尝试,成功和失败都记
账号被锁密码连续输错到了阈值
IP 被锁同一个 IP 跨账号失败到了阈值
被强制下线被管理员踢、改了密码、账号被停用 —— 记的是被踢那台设备的 IP 和浏览器
  • 用户不存在和密码错,记的原因是同一句(和登录页上提示的一样);「账号已锁」只在密码输对之后才会说出来。
  • 开了二次验证的账号:密码对了、动态码还没输时不记,第二步通过时记一条「登录成功(二次验证)」,第二步失败也记。
  • 手机验证码登录失败时,用户名一栏是匹配到的账号名;没匹配到就是打码的手机号(138****1234)。
  • 第三方登录(GitHub / Google)只记成功。Swagger 调试口的登录不记。
  • 归属地默认用内置的离线 IP 库(ip2region)查,纯 IPv6 地址查不出归属地;也可以改成在线查询或关闭。结果在 Redis 里缓存一天。

操作日志记了什么?打码怎么做的?

Section titled “操作日志记了什么?打码怎么做的?”

/api/v1 下的每个请求都记一行(包括 GET):用户、方法、路径、接口说明、IP 与归属地、浏览器、请求参数、请求头、响应头、响应体、HTTP 状态、业务码、提示信息、耗时(毫秒)。

不记的:OPERA_LOG_PATH_EXCLUDE 里列的路径(接口文档、Swagger 登录口、第三方登录的跳转和回调)、OPTIONS 请求、请求还没处理完客户端就断开的(记成 499、不入库)。写日志走一个异步队列,队列满了(10 万条)新的会被丢弃并打警告。

截断:请求体超过 10 KB、或者没有声明长度的文件上传,记一个占位符;application/octet-stream 的请求体不读。响应体只记 JSON 和纯文本,超过 10 KB 截断,超过 5 MB 的 JSON 不解析。

打码在落库之前、截断之前做,不论嵌套多深(最多 20 层):

  • 按键名精确匹配:password · old_password · new_password · confirm_password · captcha · otp · totp_secret · otpauth_uri · recovery_codes · mfa_token · access_token · refresh_token · token · api_key · secret_key · access_key_secret · mcp_token · webhook_url · sign_secret · import_token(完整列表在 conf.py 的 OPERA_LOG_REDACT_KEYS)。
  • 「键 + 值」形状的数据(比如参数配置的一行):键名看起来像密钥(以 PASSWORD、SECRET、TOKEN、API_KEY、CREDENTIAL 等结尾,不分大小写)时,旁边的值打码。
  • 请求头:authorization、cookie、set-cookie、proxy-authorization、x-api-key、x-auth-token。
  • 宁可不记也不漏记:声明是 JSON 却解析不了的请求体不记;解析不了的 JSON 响应换成占位符。

有 log:change:list 的人打开一条写操作(GET 以外)的详情,能看到**「这次改了什么」**:这个请求引起的数据变更,最多列 50 条,更多的点「还有 N 条」跳到数据变更页按这次请求筛选。反过来,数据变更页的每一条也能跳回触发它的那条操作日志。两边靠请求的 trace_id 关联。

数据变更记录是怎么记下来的?

Section titled “数据变更记录是怎么记下来的?”

不是在每个接口里手写「记一笔」,而是挂在数据库会话上:事务提交前把这个事务里改了的对象逐个比对,生成「字段 · 旧值 · 新值」,和业务数据在同一个事务里写入 —— 业务回滚了,变更记录也不会留下。同一个事务里同一个对象改了多次,只记一行最终结果。

main 上已经接入的对象:

对象一起记在它名下的
用户角色、二次验证的开关和恢复码、第三方账号的绑定解绑
部门
角色功能权限(菜单)、数据范围
菜单
参数配置
  • 每一列都必须归类:普通字段、引用(同时记下被引用对象当时的名称,比如部门改名之后,老记录里仍是当时的名字)、敏感、忽略、软删除标记。漏归类的列让后端启动失败,而不是悄悄不记。
  • 敏感字段只记「改了」不记内容:密码、恢复码、键名像密钥的参数配置值,界面上显示「已修改(不记录内容)」,导出的文件里也一样。
  • 关联表记净变化:「先全删再全加回来」而实际没变的,不记。
  • 来源:网页、AI 助手、导入、第三方登录、后台任务、系统,一眼看出是不是人在界面上点出来的。
  • 一条语句改超过 500 行的批量操作,记成一行汇总。
  • 抽屉里点某个字段名,只看这个字段的历史;数据变更页把字段写进地址栏,刷新还在。

每一条数据变更记录写入时按顺序编号,并用 HMAC-SHA256 签名:签名覆盖这一行的内容和上一行的签名,连成一条链。改一行、删中间一行、删末尾几行、在中间塞一行、拿另一把密钥把整条链重签一遍,都会在校验时对不上。

三种方式校验,结果一样:

  • 数据变更页上的「校验完整性」(只给超级管理员)
  • 接口 GET /api/v1/logs/changes/integrity(只给超级管理员)
  • 命令行 fba data-change verify,有问题时退出码为 1,方便放进定时巡检

签名密钥是 .env 里的 DATA_CHANGE_CHAIN_KEY,只放环境变量、不进数据库:拿到数据库权限的人改了记录、重算签名也对不上。它留空时用空密钥签名,只能防「手滑直接改库」,校验结果会说明这一点。设了就别换 —— 换了之后,旧记录会被单独列成「换密钥之前签的」。同时拿到数据库和这把密钥的人,这条链挡不住。

记录默认在哪改
登录日志、操作日志(以及开放接口调用日志、短信发送日志)180 天「任务调度」里「清理历史日志」这条任务的参数 {"days": 180}
数据变更记录180 天参数配置 →「日志」→ DATA_CHANGE_RETENTION_DAYS(1–3650)
通知投递记录、Webhook 记录30 天各自在参数配置里的保留天数

清理任务 maintenance.prune_logs 每天 03:15 跑,按业务时间(登录时间、操作时间)每批 2000 行分批删。180 天来自《网络安全法》第二十一条「网络日志留存不少于六个月」;从 30 天改成 180 天的迁移只改还停在 30 天的那条任务,你自己改过的不动。清理数据变更记录时先挪动签名链的起点再删,所以清理之后校验仍然通过。

界面上改的:数据变更记录的保留天数(参数配置 →「日志」)、登录 / 操作日志的保留天数(任务调度里那条任务的参数),见上一节。

只能在 .env 改的,改完重启后端:

键默认值说明
DATA_CHANGE_CHAIN_KEY空防篡改链的签名密钥,64 位十六进制;生产环境建议设上,设了别换
IP_LOCATION_PARSEoffline归属地:offline 离线库 / online 在线查询 / false 不查
TRUSTED_PROXIES[]反代地址;不填的话,部署在反代后面时日志里的 IP 全是反代的
OPERA_LOG_PATH_EXCLUDE接口文档、第三方登录跳转等不记操作日志的路径(精确匹配)
OPERA_LOG_REDACT_KEYS · OPERA_LOG_REDACT_HEADERS见上文打码的键名和请求头
OPERA_LOG_BODY_MAX_SIZE · OPERA_LOG_RESPONSE_MAX_SIZE10240 · 10240请求体、响应体记多少字节
OPERA_LOG_RESPONSE_CONTENT_TYPESapplication/json · text/plain哪些类型的响应体会被记录
OPERA_LOG_QUEUE_MAXSIZE100000写日志队列的长度,满了丢弃
  1. 在模块或插件目录下放一个 data_change.py,启动时自动扫描。
  2. 调 register_audited(...) 登记模型,把每一列归类(字段 / 引用 / 敏感 / 忽略 / 软删除);关联表用 register_audited_set,一对一的子表用 register_audited_child,记在主对象名下。
  3. 每个字段的中文名、英文名进两份语言包和 server-data-keys.json(有测试核对)。
  4. 不经过网页请求的入口(后台任务、命令行)用 data_change_source(...) 标明来源。
  5. 别用会话看不见的写法:裸 SQL 的 text() 增删改、语句式的 insert(模型)、直接拿 connection() 写 —— 生产代码里出现这些写法,静态守卫测试会失败。

新增像凭据的请求字段时,记得加进 OPERA_LOG_REDACT_KEYS:有一条测试扫描所有接口的 schema,像凭据却没打码的字段会让它失败。逐条的说明和踩过的坑在 common/data_change/AGENTS.md。

  • 不记:个人偏好、密码历史、会话的建立与结束(这些在登录日志里);裸 SQL、迁移脚本、种子数据造成的改动。
  • 第三方登录失败、Swagger 调试口的登录不进登录日志。
  • 请求的 trace_id 可以由客户端通过 X-Request-ID 头指定,所以「这次改了什么」的关联不能当成不可伪造的证据;防篡改链保护的是数据变更记录本身。
  • 数据变更记录(含防篡改链)的测试在 CI 的 PostgreSQL、SQL Server 两个 job 上都跑,MySQL 上还没有验证过。
  • 登录日志、操作日志的保留天数不在参数配置页上,要去改定时任务的参数。

后端连真实的数据库和 Redis:

  • test_data_change.py(52 条):生产代码里没有捕获不到的写法(静态守卫)、角色菜单记净变化并带菜单标题、重置密码只记「改了」、中间和末尾的记录被删能校验出来、换一种方式重签整条链也能发现、校验接口只给超级管理员。
  • test_prune_logs.py(19 条):按业务时间而不是写入时间清理、默认保留天数各处一致且不低于六个月、迁移只改还停在 30 天的那条任务、清理带签名的数据变更后链仍然校验通过。
  • tests/test_opera_log_redaction.py(25 条):先打码再截断、客户端中途断开不记成成功、登录响应里的令牌被打码。
  • test_login_events.py:强制下线记下被踢的设备和是谁踢的。

浏览器端(Playwright):data-change.spec.ts(改部门名 → 行操作「变更记录」看到旧值 → 新值 → 数据变更页按对象筛 → 跳到这次请求的操作日志;操作日志详情「这次改了什么」→ 去数据变更看全部)、login-events.spec.ts(密码连续输错被锁 → 登录日志按「账号被锁」筛出来)。

在线演示(admin / 123456):到「系统管理 → 部门管理」改一个部门的名字,再点这一行的「变更记录」,能看到旧名字 → 新名字;点进去跳到触发它的那条操作日志,看请求参数和耗时。admin 是超级管理员,数据变更页上的「校验完整性」也能点。演示站是共用的,改完请改回去。