PostgreSQL pgaudit连接

通过 pgAudit 观测 PostgreSQL 数据库访问的深入连接器指南——日志格式设置、流式摄取、归因和产生的访问映射边

pgAudit 连接器尾随 PostgreSQL 的结构化审计日志，每个被审计的数据访问发出一条访问映射边。读/写模式从 pgAudit 的类（READ、WRITE、DDL）逐字获取——绝不从 SQL 文本推断。连接器对日志文件是只读的，绝不打开到数据库的连接。

关于通用数据源模型和配置结构，从连接数据源开始。本页覆盖 PostgreSQL 端的先决条件、完整的配置界面、归因机制和生产资产的运营考虑。

PostgreSQL 先决条件

连接器读取 pgAudit 输出，因此 PostgreSQL 必须配置为产生它。安装扩展（在 Debian/Ubuntu 上 apt install postgresql-<version>-pgaudit），通过 shared_preload_libraries 加载，重启，然后在你要观测的每个数据库中 CREATE EXTENSION pgaudit。

有用输出的最低 postgresql.conf 设置：

shared_preload_libraries = 'pgaudit'
pgaudit.log = 'read, write'       # READ 和 WRITE 覆盖数据访问
log_destination = 'jsonlog'        # 推荐用于流式；csvlog 也可以
logging_collector = on
log_directory = '/var/log/postgresql'
log_filename = 'postgresql.json'

shared_preload_libraries 之后重启；其余之后重载（SELECT pg_reload_conf()）。通过运行查询并确认 pgAudit 条目出现在日志中来验证——条目的 message 字段包含 pgAudit 结构化行（类、命令、对象名称）。如果只出现标准 PostgreSQL 消息，扩展未加载或未配置。

配置

连接器通过 OLIVARES_SOURCES_CONFIG JSON 文件中的 kind: "pgaudit" 选择。完整示例：

{
  "sources": [
    {
      "name": "prod-postgres",
      "kind": "pgaudit",
      "tenant": "acme",
      "config": {
        "log_path": "/var/log/postgresql/postgresql.json",
        "format": "jsonlog",
        "follow": "true",
        "shared_accounts": "app_pool,reporting"
      }
    }
  ]
}

所有 config 值都是字符串。键由 pgAudit 连接器拥有：

log_path（必需）——PostgreSQL 日志文件的绝对路径。连接器读取此文件；它不按惯例发现日志文件。
format ——csvlog 或 jsonlog。默认为 csvlog。控制连接器使用的解析器；它必须匹配 PostgreSQL 实际写入的 log_destination。
follow ——当为 "true" 时，持续尾随文件（流式模式）。这仅适用于 jsonlog。csvlog 文件始终作为批处理读取，因为 CSV 记录可以跨行，使流式尾随不可靠。参见下面的批处理 vs 流式。
shared_accounts ——逗号分隔的 PostgreSQL 角色或 application_name 值列表，属于跨多个调用者池化或共享的。归因到其中任何一个的访问被有意标记为 approximate。参见归因和共享账户。

不要在这四个键之外发明配置键。连接器的配置界面有意很窄——它读取日志文件，不管理 PostgreSQL。

归因和共享账户

访问映射需要回答”哪个代理做了这件事。“pgAudit 日志条目携带 PostgreSQL 角色（用户），以及设置时会话的 application_name。连接器使用两者来构建边的来源。

按代理身份赢得确定边。 当每个代理在其连接上设置不同的 application_name（或使用专用角色）时，连接器明确归因每个访问，边为 firm。

共享角色折叠为近似。 当多个代理共享连接池、通用服务账户或通用 application_name 时，连接器无法分离调用者。通过该身份的每个访问被标记为 approximate，产品公开说明而非假装能区分它无法区分的代理。这就是 shared_accounts 存在的原因：预先声明池化身份告诉连接器立即将它们标记为 approximate。

治理含义是直接的：approximate 边无法支持确定的最小权限发现。如果你需要按代理治理数据库访问，分发按代理凭证或 application_name 值。参见保真度了解完整的归因模型。

覆盖范围层级

pgAudit 是 clean 覆盖范围。READ、WRITE 和 DDL 类是权威的——PostgreSQL 的审计子系统分类语句，连接器逐字采用该分类。没有推断、没有 SQL 解析、没有启发式。

边的 mode 是 R（读）、RW（读写，用于 WRITE 和 DDL 类）或按类指示保留。连接器绝不升级或降级 pgAudit 报告的内容。参见保真度——覆盖范围了解 clean 与 lossy 和 opaque 数据源的比较。

批处理 vs 流式

csvlog ——批处理。CSV 记录可以跨行（带有嵌入换行的查询产生多行行），因此流式尾随无法可靠地分割记录。连接器作为完整批处理读取文件；在数据源条目上设置 poll_seconds 按间隔控制重新读取。
jsonlog 带 follow: "true" ——流式。每个 JSON 条目是单行，因此尾随是安全的。连接器保持文件打开，PostgreSQL 写入时发出边。

对于近实时边，推荐 jsonlog 带 follow 的配置。对于定期审计或较低量的数据库，csvlog 批处理就够了。

边的样子

连接器解析的每个 pgAudit 日志条目产生一条具有以下字段的访问映射边：

来源 ——PostgreSQL 角色，当存在时以 application_name 限定。示例：reporting_agent 或 app_pool/invoice-service。
资源 ——完全限定的对象：database.schema.table。示例：prod.public.orders。
模式 ——R（来自 pgAudit 类 READ）或 RW（来自 pgAudit 类 WRITE 或 DDL）。
归因 ——如果来源解析到单个代理身份则为 firm，如果匹配 shared_accounts 条目或无法消歧则为 approximate。
数据源 ——按名称标识此连接器实例。

边不携带 SQL 文本、行数据或查询参数。它仅记录某个身份以给定模式访问了某个对象的结构性事实。

运营注意事项

日志轮换。 当 PostgreSQL 轮换其日志文件（通过 log_rotation_age 或 log_rotation_size）时，连接器必须指向当前文件。如果你的轮换重命名了活跃文件，follow 尾随将继续读取旧文件描述符直到耗尽然后停止。将 log_path 指向稳定的符号链接或使用连接器可以跟随的命名惯例。连接器本身不管理轮换。

高流量资产。 pgAudit 在繁忙数据库上可能产生大量日志，特别是使用 pgaudit.log = 'all' 时。将 pgaudit.log 限定到你需要的类（通常是 read, write），并考虑通过 pgaudit.log_relation 进行按数据库或按角色过滤以减少噪声而不丢失覆盖范围。

多个 PostgreSQL 实例。 每个实例需要在 OLIVARES_SOURCES_CONFIG 中有自己的数据源条目，具有不同的 name 和自己的 log_path。没有多实例发现——每个数据源恰好观察一个日志文件。

权限。 收集器进程需要对 PostgreSQL 日志文件的读取权限。它不需要数据库连接、PostgreSQL 角色或到数据库服务器的任何网络访问。文件系统读取权限是唯一要求。

连接 PostgreSQL (pgaudit)