GitLab项目审计事件开发指南：从原理到实践

最新推荐文章于 2025-06-18 22:30:30 发布

云忱川

最新推荐文章于 2025-06-18 22:30:30 发布

阅读量257

点赞数 5

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_01142/article/details/148392824

GitLab项目审计事件开发指南：从原理到实践

gitlabhq GitLab CE Mirror | Please open new issues in our issue tracker on GitLab.com 项目地址: https://gitcode.com/gh_mirrors/gi/gitlabhq

什么是审计事件？

审计事件是GitLab为项目所有者和系统管理员提供的重要功能，用于记录和查看应用程序中执行的关键操作。这些事件相当于系统的"操作日志"，帮助管理员追踪谁在什么时候对系统做了什么。

审计事件的适用场景

并非所有操作都适合记录为审计事件。以下是几种不适合作为审计事件的情况：

无法归属到特定用户的操作：如果操作无法明确关联到某个具体用户，则不适合作为审计事件。
对管理员无特别意义的操作：只有那些对系统管理有重要意义的事件才应被记录。
产品功能采用跟踪：用于统计产品功能使用情况的数据不属于审计事件范畴。
已明确排除的操作类型：某些操作类型已在项目规划中被明确排除。

审计事件的核心架构

每个审计事件应包含以下结构化属性：

| 属性名 | 类型 | 是否必填 | 说明 | |--------------|--------------------------|----------|----------------------------------------------------------------------| | name | 字符串 | 否 | 被审计的操作名称，代表事件类型 | | author | 用户对象 | 是 | 执行操作的用户，可以是内部用户 | | scope | 用户/项目/群组/实例 | 是 | 审计事件所属的作用域 | | target | 对象 | 是 | 被审计的目标对象 | | message | 字符串 | 是 | 描述操作的文字信息（注意不进行国际化处理） | | created_at | 日期时间 | 否 | 操作发生时间，默认为当前时间 |

如何实现新的审计事件

方法一：使用代码块记录多个事件

当需要在调用栈深处记录多个事件时，这种方法特别有用。以下是实现步骤：

在服务初始化时设置审计上下文
使用Gitlab::Audit::Auditor.audit包裹操作代码块
在相关模型中通过Auditable混入添加审计事件

# 服务初始化代码示例
audit_context = {
  name: 'update_merge_approval_rule',
  author: current_user,
  scope: project_alpha,
  target: merge_approval_rule,
  message: 'Attempted to update an approval rule'
}

::Gitlab::Audit::Auditor.audit(audit_context) do
  service.execute
end

# 模型代码示例
def audit_add(model)
  push_audit_event('Added an approver on Security rule')
end

方法二：标准方法调用记录单个事件

对于简单的单个事件记录，这种方法更为直接：

if merge_approval_rule.save
  audit_context = {
    name: 'create_merge_approval_rule',
    author: current_user,
    scope: project_alpha,
    target: merge_approval_rule,
    message: 'Created a new approval rule'
  }

  ::Gitlab::Audit::Auditor.audit(audit_context)
end