4. 对象存储元数据模型设计

对象存储的元数据模型是查询性能的基石。一个设计良好的元数据表，不仅需要完整表达对象的逻辑属性，还必须兼顾 PostgreSQL 的索引特性与查询模式。本章围绕对象 ID、桶（Bucket）、对象名、大小、ETag、存储类、时间戳等核心字段，给出专业、可落地的建模方案。

4.1 核心字段定义与数据类型选择

下表列出对象存储元数据最核心的字段及其 PostgreSQL 数据类型推荐。数据类型的选择直接影响存储效率、索引构建和查询性能。

4.2 元数据模型实体关系图

下图展示对象存储元数据核心实体之间的关系。桶（Bucket）作为逻辑容器，包含多个对象；对象通过 bucket_id 与桶关联，并通过 object_id 唯一标识。版本控制场景下，同一 object_id 可对应多个版本记录。

4.3 核心字段设计深度解析

4.3.1 对象 ID（object_id）

对象 ID 是全局唯一标识，建议使用 UUID v4 或 ULID。UUID 随机性高，避免自增 ID 在分布式环境下的冲突；ULID 在 UUID 基础上增加了时间戳前缀，支持按创建时间排序，对范围查询更友好。

4.3.2 桶 ID 与对象名（bucket_id + object_name）

桶 ID 与对象名共同构成对象的逻辑路径。在查询时，最常见的模式是：

• 精确查询： WHERE bucket_id = ? AND object_name = ? —— 返回单个对象。
• 前缀查询： WHERE bucket_id = ? AND object_name LIKE 'prefix/%' —— 列出桶内某个目录下的所有对象。
• 桶内全量查询： WHERE bucket_id = ? —— 列出桶内所有对象（需分页）。

针对这些模式，推荐创建复合索引：

CREATE INDEX idx_bucket_object ON objects (bucket_id, object_name);
-- 如果 object_name 需要前缀匹配，使用 text_pattern_ops
CREATE INDEX idx_bucket_object_pattern ON objects (bucket_id, object_name text_pattern_ops);

4.3.3 存储类（storage_class）

存储类通常是一个低基数字段（标准、低频、归档、冷归档等）。对于低基数索引，PostgreSQL 的 B-tree 索引效率不高，推荐使用 部分索引 或 位图索引 思路：

-- 部分索引：只索引归档类对象，用于快速统计
CREATE INDEX idx_archived_objects ON objects (created_at) WHERE storage_class = 2;

-- 或者使用 BRIN 索引（如果数据按时间顺序插入）
CREATE INDEX idx_storage_class_brin ON objects USING BRIN (storage_class) WITH (pages_per_range = 32);

4.3.4 时间戳字段（created_at / updated_at）

时间戳字段是范围查询和排序的常用条件。建议：

• 统一使用 TIMESTAMPTZ 类型，存储 UTC 时间，避免时区转换问题。
• 为 created_at 创建 B-tree 索引，支持 ORDER BY 和范围过滤。
• 如果表数据量极大（百亿级），考虑使用 BRIN 索引 替代 B-tree，因为时间戳天然有序，BRIN 索引体积更小。

-- B-tree 索引（默认）
CREATE INDEX idx_created_at ON objects (created_at);

-- BRIN 索引（适合时序插入场景）
CREATE INDEX idx_created_at_brin ON objects USING BRIN (created_at) WITH (pages_per_range = 64);

4.4 元数据表 DDL 示例

综合以上设计，给出一个完整的元数据表 DDL 示例：

CREATE TABLE objects (
    object_id       UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    bucket_id       INTEGER NOT NULL,
    object_name     TEXT NOT NULL,
    size            BIGINT NOT NULL DEFAULT 0,
    etag            VARCHAR(64) NOT NULL,
    storage_class   SMALLINT NOT NULL DEFAULT 0,  -- 0:标准, 1:低频, 2:归档
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    version_id      INTEGER NOT NULL DEFAULT 1,
    content_type    VARCHAR(255),
    metadata        JSONB DEFAULT '{}',
    
    -- 约束
    CONSTRAINT unique_bucket_object UNIQUE (bucket_id, object_name, version_id),
    CONSTRAINT chk_storage_class CHECK (storage_class IN (0, 1, 2))
);

-- 核心索引
CREATE INDEX idx_objects_bucket_name ON objects (bucket_id, object_name);
CREATE INDEX idx_objects_created_at ON objects (created_at);
CREATE INDEX idx_objects_storage_class ON objects (storage_class) WHERE storage_class = 2;

-- 可选：JSONB 索引（如果 metadata 经常被查询）
CREATE INDEX idx_objects_metadata ON objects USING GIN (metadata);

4.5 字段设计对查询性能的影响

下图展示不同查询模式下的索引选择路径，帮助理解字段设计如何影响执行计划。

4.6 字段设计避坑指南

• 避免过长的 object_name： 对象名最长可达 1024 字节，但索引键值过长会降低 B-tree 性能。建议限制在 256 字符以内，或使用哈希前缀索引。
• ETag 不要作为主键： ETag 是内容哈希，不同对象可能相同（如分片上传场景），且长度固定，不适合作为主键。
• 存储类枚举用 SMALLINT 而非 TEXT： TEXT 类型占用更多空间，且低基数场景下索引效率不如 SMALLINT + 部分索引。
• 时间戳默认使用 UTC： 避免因时区转换导致的查询条件不匹配，所有应用层统一使用 UTC 时间写入。
• JSONB 字段适度使用： 用户自定义元数据用 JSONB 存储灵活，但不要将高频查询字段放入 JSONB，否则无法利用原生索引。