Add PgAudit documentation.

CN/modules/ROOT/nav.adoc

@@ -19,6 +19,7 @@
 *** xref:master/5.4.adoc[pg_cron]
 *** xref:master/5.5.adoc[pgsql-http]
 *** xref:master/5.6.adoc[plpgsql_check]
+*** xref:master/5.7.adoc[PgAudit]
 ** IvorySQL架构设计
 *** 查询处理
 **** xref:master/6.1.1.adoc[双parser]

CN/modules/ROOT/pages/master/5.7.adoc

@@ -0,0 +1,110 @@
+
+:sectnums:
+:sectnumlevels: 5
+
+= PgAudit
+
+== 概述
+
+PgAudit 是一个审计扩展，可以为 DDL、DML、DCL 等关键操作生成可追溯的日志记录。通过审计日志，数据库管理员能够满足合规要求、及时发现异常行为，并在出现问题时快速定位责任主体与影响范围。
+
+== 功能特点
+
+* *全面审计能力*：记录 `SELECT`、`INSERT`、`UPDATE`、`DELETE`、DDL 命令以及权限变更等操作，帮助构建完整的操作轨迹。
+* *灵活的审计维度*：支持全局审计、角色审计与对象审计，可按用户、角色、模式或具体操作类型进行精细化配置。
+* *平滑集成*：复用 PostgreSQL 标准日志子系统，可与 `syslog`、`logrotate` 等工具联动，兼容现有日志采集与分析方案。
+* *合规支撑*：提供结构化审计日志，便于生成符合金融、政企等行业规范的审计报告。
+* *安全增强*：通过记录和分析数据库活动，及时发现未授权访问、异常 DML 或潜在数据泄露风险。
+* *运维优化*：辅助回放操作行为、定位性能瓶颈，支撑 SQL 优化与问题排查。
+
+== 安装部署
+
+=== 环境准备
+
+* 已安装的 IvorySQL 数据库。
+* 编译工具链：`gcc`、`make`、`tar` 等。
+* 数据库管理员权限，用于修改 `ivorysql.conf` 并重启数据库实例。
+
+=== 编译安装 PgAudit
+
+以 PgAudit 18.0 为例：
+
+[source,shell]
+----
+wget https://github.com/pgaudit/pgaudit/archive/refs/tags/18.0.tar.gz
+tar -xf 18.0.tar.gz
+cd pgaudit-18.0
+make install USE_PGXS=1 PG_CONFIG=$PGHOME/bin/pg_config
+----
+
+上述命令依赖环境变量 `PGHOME` 指向安装好的 IvorySQL 主目录。安装成功后，`pgaudit.so` 会被放置到 IvorySQL 的扩展目录中。
+
+=== 注册扩展前的基础配置
+
+1. 修改 `ivorysql.conf`，启用插件并设置常用参数：
+
+[source,conf]
+----
+shared_preload_libraries = 'pgaudit'   # 需实例重启生效
+pgaudit.log = 'read, write, ddl'       # 审计范围示例，可按需调整
+----
+
+2. 重启数据库实例，使共享库配置生效。
+
+=== 创建扩展并验证
+
+[source,sql]
+----
+CREATE EXTENSION IF NOT EXISTS pgaudit;
+SELECT name,
+       default_version,
+       installed_version,
+       comment
+  FROM pg_available_extensions
+ WHERE name = 'pgaudit';
+----
+
+若返回的 `installed_version` 与期望版本一致，说明扩展安装成功。
+
+== 使用
+
+1. 执行如下sql示例：
+
+[source,sql]
+----
+CREATE TABLE audit_demo(id serial PRIMARY KEY, info text);
+INSERT INTO audit_demo(info) VALUES ('pgaudit test');
+SELECT * FROM audit_demo;
+UPDATE audit_demo SET info = 'pgaudit update' WHERE id = 1;
+DELETE FROM audit_demo WHERE id = 1;
+----
+
+2. 在数据库服务器上查看审计日志：
+
+[source,shell]
+----
+tail -f $PGDATA/log/*.log | grep 'AUDIT:'
+----
+
+
+[source,text]
+----
+2025-10-31 15:56:32.113 CST [11451] LOG:  AUDIT: SESSION,1,1,DDL,CREATE SEQUENCE,SEQUENCE,public.audit_demo_id_seq,"CREATE TABLE audit_demo(id serial PRIMARY KEY, info text)",<not logged>
+2025-10-31 15:56:32.113 CST [11451] LOG:  AUDIT: SESSION,1,1,DDL,CREATE TABLE,TABLE,public.audit_demo,"CREATE TABLE audit_demo(id serial PRIMARY KEY, info text)",<not logged>
+2025-10-31 15:56:32.113 CST [11451] LOG:  AUDIT: SESSION,1,1,DDL,CREATE INDEX,INDEX,public.audit_demo_pkey,"CREATE TABLE audit_demo(id serial PRIMARY KEY, info text)",<not logged>
+2025-10-31 15:56:32.113 CST [11451] LOG:  AUDIT: SESSION,1,1,DDL,ALTER SEQUENCE,SEQUENCE,public.audit_demo_id_seq,"CREATE TABLE audit_demo(id serial PRIMARY KEY, info text)",<not logged>
+2025-10-31 15:56:32.117 CST [11451] LOG:  AUDIT: SESSION,2,1,WRITE,INSERT,,,INSERT INTO audit_demo(info) VALUES ('pgaudit test'),<not logged>
+2025-10-31 15:56:32.121 CST [11451] LOG:  AUDIT: SESSION,3,1,READ,SELECT,,,SELECT * FROM audit_demo,<not logged>
+2025-10-31 15:56:32.122 CST [11451] LOG:  AUDIT: SESSION,4,1,WRITE,UPDATE,,,UPDATE audit_demo SET info = 'pgaudit update' WHERE id = 1,<not logged>
+2025-10-31 15:56:32.127 CST [11451] LOG:  AUDIT: SESSION,5,1,WRITE,DELETE,,,DELETE FROM audit_demo WHERE id = 1,<not logged>
+----
+
+-- 若想记录参数的值，打开`pgaudit.log_parameter = 'on'`，效果如下：
+[source,text]
+----
+ivorysql=# SHOW pgaudit.log_parameter;
+pgaudit.log_parameter
+-----------------------
+off
+(1 row)
+----

EN/modules/ROOT/nav.adoc

@@ -18,6 +18,7 @@
 ** xref:master/5.4.adoc[pg_cron]
 ** xref:master/5.5.adoc[pgsql-http]
 ** xref:master/5.6.adoc[plpgsql_check]
+** xref:master/5.7.adoc[PgAudit]
 * IvorySQL Architecture Design
 ** Query Processing
 *** xref:master/6.1.1.adoc[Dual Parser]

EN/modules/ROOT/pages/master/5.7.adoc

@@ -0,0 +1,111 @@
+:sectnums:
+:sectnumlevels: 5
+
+= PgAudit
+
+== Overview
+
+PgAudit is an auditing extension for IvorySQL that produces traceable log records for critical operations such as DDL, DML, and DCL. With the audit trail, database administrators can meet compliance requirements, quickly detect abnormal behavior, and identify accountability and impact scope when incidents occur.
+
+== Key Features
+
+* *Comprehensive auditing*: Captures `SELECT`, `INSERT`, `UPDATE`, `DELETE`, DDL commands, privilege changes, and more to build a complete activity timeline.
+* *Flexible scope control*: Supports global, role-based, and object-level auditing, allowing fine-grained configuration by user, role, schema, or operation type.
+* *Seamless integration*: Reuses PostgreSQL's standard logging subsystem and works with tools like `syslog` and `logrotate`, aligning with existing log ingestion and analysis pipelines.
+* *Compliance ready*: Generates structured audit logs suitable for meeting regulatory requirements in finance, government, and other regulated industries.
+* *Security enhancement*: Records and inspects database activity to surface unauthorized access, anomalous DML, or potential data leakage risks in time.
+* *Operations insight*: Helps replay operational actions, locate performance bottlenecks, and support SQL tuning and incident troubleshooting.
+
+== Installation and Deployment
+
+=== Prerequisites
+
+* A IvorySQL installation (recommended version aligned with the targeted PgAudit release).
+* Build toolchain: `gcc`, `make`, `tar`, etc.
+* Database superuser privileges to modify `ivorysql.conf` and restart the instance.
+
+=== Compile and Install PgAudit
+
+Taking PgAudit 18.0 as an example:
+
+[source,shell]
+----
+wget https://github.com/pgaudit/pgaudit/archive/refs/tags/18.0.tar.gz
+tar -xf 18.0.tar.gz
+cd pgaudit-18.0
+make install USE_PGXS=1 PG_CONFIG=$PGHOME/bin/pg_config
+----
+
+The commands above expect the environment variable `PGHOME` to point to the installed IvorySQL home directory. After installation, `pgaudit.so` will be placed in IvorySQL's extension directory.
+
+=== Baseline Configuration Before Registering the Extension
+
+1. Modify `ivorysql.conf` to load the plugin and configure common parameters:
+
+   [source,conf]
+   ----
+   shared_preload_libraries = 'pgaudit'   # Requires an instance restart
+   pgaudit.log = 'read, write, ddl'       # Sample audit scope; adjust as needed
+   ----
+
+2. Restart or reload the database instance so the shared library configuration takes effect.
+
+=== Create the Extension and Verify
+
+[source,sql]
+----
+CREATE EXTENSION IF NOT EXISTS pgaudit;
+SELECT name,
+       default_version,
+       installed_version,
+       comment
+  FROM pg_available_extensions
+ WHERE name = 'pgaudit';
+----
+
+If the returned `installed_version` matches the expected release, the extension has been installed successfully.
+
+== Usage
+
+1. Execute the following SQL sample:
+
+   [source,sql]
+   ----
+   CREATE TABLE audit_demo(id serial PRIMARY KEY, info text);
+   INSERT INTO audit_demo(info) VALUES ('pgaudit test');
+   SELECT * FROM audit_demo;
+   UPDATE audit_demo SET info = 'pgaudit update' WHERE id = 1;
+   DELETE FROM audit_demo WHERE id = 1;
+   ----
+
+2. Check the audit logs on the database server:
+
+   [source,shell]
+   ----
+   tail -f $PGDATA/log/*.log | grep 'AUDIT:'
+   ----
+
+   Example output:
+
+   [source,text]
+   ----
+   2025-10-31 15:56:32.113 CST [11451] LOG:  AUDIT: SESSION,1,1,DDL,CREATE SEQUENCE,SEQUENCE,public.audit_demo_id_seq,"CREATE TABLE audit_demo(id serial PRIMARY KEY, info text)",<not logged>
+   2025-10-31 15:56:32.113 CST [11451] LOG:  AUDIT: SESSION,1,1,DDL,CREATE TABLE,TABLE,public.audit_demo,"CREATE TABLE audit_demo(id serial PRIMARY KEY, info text)",<not logged>
+   2025-10-31 15:56:32.113 CST [11451] LOG:  AUDIT: SESSION,1,1,DDL,CREATE INDEX,INDEX,public.audit_demo_pkey,"CREATE TABLE audit_demo(id serial PRIMARY KEY, info text)",<not logged>
+   2025-10-31 15:56:32.113 CST [11451] LOG:  AUDIT: SESSION,1,1,DDL,ALTER SEQUENCE,SEQUENCE,public.audit_demo_id_seq,"CREATE TABLE audit_demo(id serial PRIMARY KEY, info text)",<not logged>
+   2025-10-31 15:56:32.117 CST [11451] LOG:  AUDIT: SESSION,2,1,WRITE,INSERT,,,INSERT INTO audit_demo(info) VALUES ('pgaudit test'),<not logged>
+   2025-10-31 15:56:32.121 CST [11451] LOG:  AUDIT: SESSION,3,1,READ,SELECT,,,SELECT * FROM audit_demo,<not logged>
+   2025-10-31 15:56:32.122 CST [11451] LOG:  AUDIT: SESSION,4,1,WRITE,UPDATE,,,UPDATE audit_demo SET info = 'pgaudit update' WHERE id = 1,<not logged>
+   2025-10-31 15:56:32.127 CST [11451] LOG:  AUDIT: SESSION,5,1,WRITE,DELETE,,,DELETE FROM audit_demo WHERE id = 1,<not logged>
+   ----
+
+   To record parameter values as well, enable `pgaudit.log_parameter = 'on'`:
+
+   [source,text]
+   ----
+   ivorysql=# SHOW pgaudit.log_parameter;
+   pgaudit.log_parameter
+   -----------------------
+   off
+   (1 row)
+   ----