OpenMetadata Data Retention 应用配置指南：为每种实体精细化设置数据库保留策略-平芜编程栈

OpenMetadata Data Retention 应用配置指南：为每种实体精细化设置数据库保留策略

【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata

导读

Data Retention（数据保留）是 OpenMetadata 内置的自动化应用，负责按管理员定义的保留期限定期清理服务端内部数据库中的过期记录，防止变更事件、活动线程、测试结果、Profile 数据、审计日志等随时间持续膨胀拖垮数据库性能。本文以 DataRetentionApplication.md 中定义的 8 个配置字段为主线，结合 JSON Schema、应用注册配置与 Java 实现源码，完整讲解每个保留参数的语义、默认值、取值范围及其在底层清理流程中的实际作用，并给出可直接落地的配置建议。

Data Retention 应用在 OpenMetadata 中扮演什么角色

OpenMetadata 的服务端会持续产生大量"过程性"数据：每次元数据变更产生的 change event、用户对话产生的活动线程与评论、数据质量测试的运行结果、profiler 采集的 Profile 时间序列、审计日志，以及测试连接、查询运行器、反向摄取等自动化工作流留下的短期记录。这些数据若不清理，会随运行时间线性增长，拖慢查询、增加备份体积。

Data Retention 应用正是为此而生：它作为一个原生（internal）应用注册在 OpenMetadata 中，按固定调度周期运行，依据管理员配置的保留期限批量删除过期记录。其市场定义在 DataRetentionApplication.json 中明确说明："The Data Retention App automates the cleanup of OpenMetadata's internal database to maintain performance and efficiency... prevents data bloat by removing outdated records."（自动清理内部数据库以维持性能与效率，通过删除过期记录防止数据膨胀）。

应用的实际执行入口是org.openmetadata.service.apps.bundles.dataRetention.DataRetention类（见 DataRetention.java），它继承AbstractNativeApplication，在startApp中调用executeCleanup依次执行各类清理任务。

配置入口：在哪里填写保留期限

Data Retention 应用通过 OpenMetadata UI 的Settings → Applications（应用市场）安装/启用。在应用的配置面板中，表单的每个输入字段对应的就是本文档描述的各个保留参数。DataRetentionApplication.md正是这一配置表单的字段说明（locale 文案），每个字段以$$section包裹，并通过$(id="...")绑定到对应的 JSON 配置键名。

这些字段对应的配置结构体定义在 dataRetentionConfiguration.json，应用启动时由 DataRetention.java 通过JsonUtils.convertValue将 UI 提交的配置反序列化为DataRetentionConfiguration对象。若配置为空，应用会记录警告"No retention policy configuration provided. Cleanup tasks will not run."并跳过清理。

八个保留参数逐一详解

下表汇总了全部配置字段的键名、含义、Schema 默认值与取值范围，随后逐个展开。

配置键（id）	控制的数据	Schema 默认值	取值范围约束
`changeEventRetentionPeriod`	变更事件记录（含成功发送的事件、消费者 DLQ）	7 天	整数，最小 1，必填
`activityThreadsRetentionPeriod`	类型为`Conversation`的活动线程	60 天	整数，最小 0，必填
`activityCommentsRetentionPeriod`	活动事件上的评论	0 天（永久保留）	整数，最小 0，必填
`testCaseResultsRetentionPeriod`	测试用例结果时间序列	1440 天	整数，必填
`profileDataRetentionPeriod`	Profiler 采集的 Profile 数据时间序列	1440 天	整数，必填
`auditLogRetentionPeriod`	审计日志条目	90 天	整数，最小 1，必填
`workflowRetentionPeriod`	自动化工作流记录（测试连接、查询运行器、反向摄取）	30 天	整数，最小 0，非必填
`extensions`	基于 OpenMetadata 构建的分发版贡献的扩展清理保留期	`{}`（空 Map）	键为扩展名，值为天数

1. Change Event Retention Period (days)`$(id="changeEventRetentionPeriod")`

控制变更事件记录的保留天数，例如 7 代表保留一周、30 代表一个月。Schema 默认值为 7，最小值为 1（不允许设置为 0）。

在底层，这个参数一次驱动三类表的清理（见 DataRetention.java）：

successful_sent_change_events：已成功发送给订阅消费者的变更事件；
change_events：通用的变更事件记录；
consumers_dlq：投递失败进入死信队列（DLQ）的事件。

三者都通过eventSubscriptionDAO的delete*InBatches(cutoffMillis, BATCH_SIZE)以批量方式删除。

2. Activity Threads Retention Period (days)`$(id="activityThreadsRetentionPeriod")`

控制类型为Conversation的活动线程记录保留天数（如 30 对应一个月、60 对应两个月）。Schema 默认值 60，最小 0。底层由 cleanActivityThreads 调用ConversationRepository.deleteExpiredUserConversations实现，事务内批量执行。

3. Activity Comments Retention Period (days)`$(id="activityCommentsRetentionPeriod")`

控制活动事件上评论的保留天数。设置为 0 表示永久保留评论。Schema 默认值即为 0。底层由cleanActivityComments调用ConversationRepository.deleteExpiredActivityConversations实现（见 DataRetention.java）。

4. Test Case Results Retention Period (days)`$(id="testCaseResultsRetentionPeriod")`

控制数据质量测试用例结果（Test Case Results）的保留天数，默认值 1440（约 4 年）。底层由cleanTestCaseResults调用testCaseResultsDAO.deleteRecordsBeforeCutOff按时间序列时间戳批量清理（见 DataRetention.java）。该 DAO 在构造函数中通过collectionDAO.testCaseResultTimeSeriesDao()注入。

5. Profile Data Retention Period (days)`$(id="profileDataRetentionPeriod")`

控制 profiler 采集的列/表 Profile 数据时间序列的保留天数，默认值同样为 1440。底层由cleanProfileData调用profileDataDAO.deleteRecordsBeforeCutOff清理（见 DataRetention.java）。注意：它与测试结果共用 1440 天的默认值，若你的 profiler 调度频繁、采集量很大，可适当调低以控制存储。

6. Audit Log Retention Period (days)`$(id="auditLogRetentionPeriod")`

控制审计日志条目的保留天数，默认 90（约一个季度），最小 1。底层由cleanAuditLogs调用auditLogDAO.deleteInBatches清理（见 DataRetention.java）。审计日志用于安全合规追溯，设置过短可能导致无法回溯历史操作。

7. Automation Workflow Retention Period (days)`$(id="workflowRetentionPeriod")`

控制自动化工作流记录的保留天数。这些是测试连接（test connection）、查询运行器（query runner）和反向摄取（reverse ingestion）运行后留下的短期记录，默认保留 30 天，设置为 0 表示永久保留。

这是实现上最特殊的一个参数：工作流对象持有其运行所针对的服务连接信息，如果仅用批量 SQL 删除行，连接密钥会残留在外部密钥管理器中、所有者关系行也会遗留。因此底层不使用批量 SQL，而是逐个通过仓库层Entity.deleteEntity删除（见 DataRetention.java）。每次删除都是一次仓库往返外加一次deleteSecretsFromWorkflow调用（在 AWS/Azure 环境下会走网络访问外部密钥管理器），因此单次运行设置了 10 万条（MAX_WORKFLOW_DELETES_PER_RUN）的上限，首次运行积累的大量积压会被分摊到后续多次周任务中，避免长时间运行触发密钥服务商的限流。

8. Extension Retention Periods (days)`$(id="extensions")`

为基于 OpenMetadata 构建的分发版（如商业发行版、下游 fork）通过扩展机制贡献的清理任务设置保留期，键为扩展名。Schema 中明确指出："OpenMetadata never reads these values; it hands them to the registered DataRetentionExtension, which decides what a missing key means."—— OpenMetadata 本身不读取这些值，而是将它们交给注册的扩展，由扩展自行决定缺失某个键时的行为（通常回退到扩展自带的默认值）。

应用的默认配置与调度方式

应用的注册数据定义在 DataRetentionApplication.json，它同时给出了开箱即用的默认保留策略：

{ "name": "DataRetentionApplication", "displayName": "Data Retention", "appConfiguration": { "changeEventRetentionPeriod": 7, "activityThreadsRetentionPeriod": 60, "activityCommentsRetentionPeriod": 0, "profileDataRetentionPeriod": 1440, "testCaseResultsRetentionPeriod": 1440, "auditLogRetentionPeriod": 90, "workflowRetentionPeriod": 30 }, "appSchedule": { "scheduleTimeline": "Custom", "cronExpression": "0 0 * * 0" } }

调度上，应用使用Custom时间线，cron 表达式为0 0 * * 0，即每周日零点执行一次全量清理。市场定义（DataRetentionApplication.json）中scheduleType为ScheduledOrManual，permission为All，runtime.enabled为true，className指向org.openmetadata.service.apps.bundles.dataRetention.DataRetention—— 也就是说除了按计划自动运行，管理员也可以在 UI 中手动触发一次清理。

保留语义的两个关键细节

"0 或缺失 = 永久保留"

activityThreadsRetentionPeriod、activityCommentsRetentionPeriod、workflowRetentionPeriod三个字段的值为 0 或未配置（null）时，不执行对应清理，数据永久保留。实现中的判定函数位于 DataRetention.java：

static boolean isRetentionEnabled(Integer retentionPeriod) { return retentionPeriod != null && retentionPeriod > 0; }

这一语义在 DataRetentionTest.java 中被测试锁定：null和0均判定为不启用，1及以上才启用。而changeEventRetentionPeriod、auditLogRetentionPeriod在 Schema 中最小值为 1，因此不允许用 0 关闭清理。

字段的必填与向后兼容

Schema 的required列表包含除workflowRetentionPeriod和extensions外的全部字段。workflowRetentionPeriod故意不作为必填项，这样在它被引入之前保存的应用配置在反序列化时会回退到 Schema 默认值 30 而不是 null。对应的测试workflowRetentionFallsBackToDefaultForConfigsSavedWithoutIt（见 DataRetentionTest.java）验证了仅配置{"changeEventRetentionPeriod": 7}时getWorkflowRetentionPeriod()返回 30。

底层执行流程：一次运行做了什么

executeCleanup（见 DataRetention.java）定义了单次运行的完整清理顺序，分为两大部分：

第一阶段：数据一致性清理（与保留天数无关，每次必跑）

孤立关系与损坏的服务层级：通过EntityRelationshipCleanupUtil清理entity_relationship表中的孤立关系，并删除指向已删除服务的损坏实体（database、dashboard、api、messaging、pipeline、storage、mlmodel、search 等类型，删除数按服务类型分别统计）；
孤立标签使用（TagUsageCleanup）；
孤立测试用例：清理entityLink指向已删除实体的测试用例；
缺少关系的测试用例：清理缺少 testDefinition 关系（会破坏搜索索引）或缺少可执行测试套件的测试用例；
孤立的摄取管道：清理容器（服务/测试套件）CONTAINS 关系已消失、永远无法运行且会破坏搜索索引的摄取管道；
孤立的时序行：清理测试用例解析状态、Agent 执行记录、MCP 执行记录、孤立 Profile 数据与查询成本时序等孤儿行。

第二阶段：按保留期限的定时清理按顺序执行变更事件、活动线程、活动评论、测试用例结果、Profile 数据、审计日志、自动化工作流，最后运行扩展清理。所有清理都以 10,000 行（BATCH_SIZE）为一批次循环排空（drain），每批删除数不足一个批次即认为排空完成；自动化工作流清理则采用"零进度即停止"的判定，防止某条永远删不掉的数据阻塞整个排空（相关行为被aPoisonRowDoesNotStopTheWorkflowDrain测试固化，见 DataRetentionTest.java）。

每次清理的成功/失败行数都会通过updateStats记录到Stats结构（jobStats汇总 +entityStats按实体分类），运行结束后通过AppRunRecord持久化，并通过 WebSocket 向data_retention_app_channel广播，便于 UI 实时展示运行统计。

扩展机制：为自有表接入同一套清理管道

extensions参数配合DataRetentionExtensionSPI 使用。该接口定义在 DataRetentionExtension.java，基于 OpenMetadata 构建的分发版可注册实现（通过META-INF/services/...DataRetentionExtension），使其自有数据表也能被同一个调度任务、以同样的批处理、统计与失败上报方式清理，而 OpenMetadata 无需知道这些表的存在。

name()：扩展的稳定标识，同时作为extensionsMap 的键与日志标识，要求跨 provider 唯一且不可随意变更；
steps(configuration)：返回该扩展贡献的清理步骤（RetentionStep，每个步骤含统计键与批量删除函数），按顺序执行；
retentionPeriodDays(configuration, defaultDays)：读取管理员在extensions.<name>下配置的天数，未配置时回退到扩展自带默认值 —— 这正是文档中"Leave a key out to use whatever default that extension defines"（省略某个键即使用该扩展定义的默认值）的实现依据。

DataRetentionExtensionRegistry（见 DataRetentionExtensionRegistry.java）通过ServiceLoader发现 classpath 上的扩展，并对发现、实例化、贡献步骤三个阶段做了全面防御：单个损坏的注册/扩展会被跳过，内置清理与其余扩展照常运行，运行状态标记为ACTIVE_ERROR并记录首个失败详情。扩展清理始终在全部内置清理之后执行，因此即使某次运行中途失败，OpenMetadata 自身数据表的清理结果也已得到保证。

配置建议与注意事项

结合 Schema 约束与实现行为，给出以下实践要点：

变更事件建议保持较短周期：默认 7 天即适合多数场景，变更事件仅用于通知与审计追溯，长期积累收益有限；
测试结果与 Profile 数据按需裁剪：两者默认 1440 天（约 4 年），如果数据质量与 profiler 任务高频运行且存储紧张，可调低到 180～365 天；
审计日志兼顾合规：默认 90 天，若组织有更长的审计追溯要求应调大（注意最小值为 1，不可设为 0 关闭）；
0 值语义只对线程、评论、工作流三类生效：这三个字段为 0 时数据永久保留，其余字段最小值为 1；
首次启用注意工作流积压：自动化工作流清理单次有 10 万条上限，历史积压会跨多个周任务逐步消化，属预期行为，可在应用的运行统计（automation_workflows等实体统计键）中观察进度；
修改保留期限立即生效：配置在每次运行时读取（init阶段反序列化），调整参数后下一次调度即按新值执行，也可在 UI 中手动触发一次运行验证效果。

OpenMetadata Data Retention 应用配置指南：为每种实体精细化设置数据库保留策略