3. 交付物清单设计

验收交付最容易出现的争议，不是“数据库能不能跑”，而是“甲方拿到的资料能不能独立接手”。很多项目在验收时只交了一份 DDL 脚本和一个数据库账号，等到半年后出现故障，运维人员既不知道主从切换的判断依据，也找不到备份恢复的验证记录。因此，交付物清单设计的核心目标不是“凑齐文档数量”，而是让每一份交付物都能对应一个明确的接手场景：能看懂架构、能重建对象、能复现配置、能恢复数据、能判断异常、能按手册操作。

本节把交付物分为六类，并给出可直接套用的模板骨架。需要说明的是，下面出现的库名、IP、参数值均为教学示例，实际项目应替换为真实环境信息。

一、六类交付物与接手场景的对应关系

交付物不是孤立文档，它们之间存在引用关系：架构图确定拓扑与节点角色，ER 图确定逻辑模型，DDL 脚本落地物理对象，配置基线固化实例参数，备份策略与监控方案依赖架构图中的节点角色，运维手册则把前五者串成可执行动作。下图展示了这种依赖关系与各自的接手用途。

二、架构图与 ER 图：先讲清“画什么”

架构图不是网络拓扑的翻版，它必须回答三个问题：有哪些数据库节点、每个节点的角色是什么、数据在节点之间如何流动。建议至少标注节点主机名、IP、端口、角色（主库/备库/只读副本）、复制方式（流复制/逻辑复制）以及 VIP 或连接入口。例如示例环境可标注：pg-primary 10.20.1.11:5432 主库、pg-standby 10.20.1.12:5432 流复制备库、pg-ro 10.20.1.13:5432 只读副本，并注明应用通过 10.20.1.100:5432 的 VIP 接入。这样接手人一眼就能判断“写请求应该落在哪个节点、备库能否承担读流量”。

ER 图则聚焦逻辑模型，建议只画核心业务实体及其主外键关系，标注基数（1:1、1:N、M:N），并注明哪些表是大表、哪些字段有唯一约束。ER 图不必穷举所有字段，但必须与 DDL 脚本中的表名、主键、外键保持一致，否则验收时会出现“图与脚本对不上”的返工。

三、DDL 脚本：可重建、可核对、可追溯

DDL 脚本的验收标准是“在空库上执行后，对象结构与生产一致”。建议按 schema、表、索引、约束、注释、权限的顺序组织，并在脚本头部写明版本、生成时间、对应数据库版本。下面是一个可直接参考的片段：

-- 交付物：ddl_schema_v1.2.sql
-- 目标库：appdb    PostgreSQL 15.4
-- 生成时间：2025-03-18

CREATE SCHEMA IF NOT EXISTS app;

CREATE TABLE app.orders (
    order_id      bigserial PRIMARY KEY,
    customer_id   bigint NOT NULL REFERENCES app.customers(customer_id),
    order_no      varchar(32) NOT NULL UNIQUE,
    amount        numeric(14,2) NOT NULL CHECK (amount >= 0),
    status        varchar(16) NOT NULL DEFAULT 'created',
    created_at    timestamptz NOT NULL DEFAULT now()
);

CREATE INDEX idx_orders_customer ON app.orders (customer_id);
CREATE INDEX idx_orders_created  ON app.orders (created_at);

COMMENT ON TABLE  app.orders IS '订单主表';
COMMENT ON COLUMN app.orders.status IS 'created/paid/shipped/closed';

验收时应实际在测试库执行一次，并用 \d+ app.orders 或查询 information_schema 核对表、索引、约束数量是否与生产一致。若生产库存在手工创建的索引或临时表，必须一并纳入脚本，否则重建后会缺失。

四、配置基线：只固化“影响行为”的参数

配置基线不需要把整个 postgresql.conf 抄一遍，而应聚焦影响性能、复制与恢复的关键项，并记录默认值与当前值。建议用表格形式交付，便于逐项核对：

表中 archive_command 的路径必须与备份策略中的归档目录一致，否则 PITR 无法执行。验收时可执行 SHOW archive_mode; 与 SELECT * FROM pg_stat_archiver; 确认归档是否真正生效。

五、备份策略与监控方案：写清“多久、存哪、怎么判”

备份策略至少包含四要素：备份类型与频率、存放位置与保留周期、恢复目标（RPO/RTO）、验证方式。示例：每日 02:00 执行 pg_basebackup 全量备份，WAL 持续归档到 /pgbackup/wal，全量保留 14 天，WAL 保留 7 天，RPO ≤ 5 分钟，RTO ≤ 30 分钟；每月执行一次恢复到测试库的演练，并记录恢复耗时与数据校验结果。

监控方案应给出指标、阈值、采集方式与告警通道。例如：连接数使用率超过 80% 告警、主备复制延迟超过 30 秒告警、pg_stat_archiver 失败次数大于 0 告警、磁盘使用率超过 85% 告警。每条告警都要写明“收到后先看什么”，例如复制延迟告警先查 pg_stat_replication 的 replay_lag 与备库 IO 状态。

六、运维手册：把交付物变成动作

运维手册是总入口，建议包含日常巡检清单、启停步骤、主备切换步骤、备份恢复步骤、常见故障处理路径。巡检清单可直接给出可执行命令，例如：

-- 每日巡检示例
SELECT pg_is_in_recovery();                       -- 是否处于恢复状态
SELECT count(*) FROM pg_stat_activity;            -- 当前连接数
SELECT client_addr, state, replay_lag
  FROM pg_stat_replication;                       -- 复制延迟
SELECT last_archived_wal, last_failed_wal
  FROM pg_stat_archiver;                          -- 归档状态

最后提醒一点：交付物不是一次性文档。数据库版本升级、参数调整、表结构变更后，应同步更新架构图、DDL 脚本与配置基线，并在运维手册中记录变更时间与原因。只有保持交付物与生产环境一致，验收交付才真正具备长期可维护的价值。