RavenDb @refresh标记文档未按指定时间触发刷新的问题排查

使用场景说明 #

区别于RavenDB内置的「文档过期」特性会直接删除符合条件文档的行为，计划通过@refresh刷新规则，在指定时间触发订阅流程，为文档计算并标记expired过期状态。当前已在服务端配置中开启文档刷新功能，为需要触发刷新的文档在元数据中添加UTC格式的@refresh时间字段，测试用文档示例如下：

{
    "Name": "My data",
    "@metadata": {
        "@collection": "Testing",
        "@refresh": "2021-04-30T07:41:35.4845961Z"
    }
}

异常表现 #

• 文档刷新触发行为不稳定：部分场景可正常执行刷新逻辑，部分场景完全无响应
• 已尝试调整@refresh时间值、分别通过代码接口和Raven Studio手动设置属性，问题仍可复现
• 服务端监控界面显示文档刷新间隔配置正常、服务处于运行状态，但始终提示文档将在「一分钟内」触发刷新，迟迟未实际执行

已完成的排查动作与环境信息 #

• 许可层面：使用Community社区版许可，许可权益说明中未明确标注文档刷新特性的适用范围，其他版本的许可权益文档中也未提及该特性的使用限制
• 版本层面：跨多个版本复现相同问题：Docker部署在Windows 10主机的4.2.111版本（含配套服务端、Studio）、独立部署的5.1.7版本（含配套服务端、Studio）均存在异常；其中5.1.7版本曾短暂恢复正常工作，后续又停止触发刷新逻辑
• 客户端层面：使用C#版本的RavenDB.Client 5.1.6
• 已检索公开问题跟踪库，未匹配到文档刷新相关的已知历史问题

已定位的异常线索 #

1. 控制台日志捕获到文档刷新流程抛出的空引用异常，日志片段如下：

RavendbProject, Raven.Server.Documents.Expiration.ExpiredDocumentsCleaner, Failed to refresh documents on RavendbProject which are older than 05/17/2021 09:48:47, EXCEPTION: System.NullReferenceException: Object reference not set to an instance of an object.

RavendbProject |    at Sparrow.Server.ByteStringContext`1.From(String value, ByteStringType type, ByteString& str) in C:\Builds\RavenDB-Stable-5.1\51024\src\Sparrow.Server\ByteString.cs:line 1297

RavendbProject |    at Raven.Server.Documents.DocumentPutAction.PutDocument(DocumentsOperationContext context, String id, String expectedChangeVector, BlittableJsonReaderObject document, Nullable`1 lastModifiedTicks, String changeVector, DocumentFlags flags, NonPersistentDocumentFlags nonPersistentFlags) in C:\Builds\RavenDB-Stable-5.1\51024\src\Raven.Server\Documents\DocumentPutAction.cs:line 190

2. 集群事务写入文档的关联影响观察：
   • 部分通过ClusterWide（集群级）事务写入的文档，元数据带有"@flags": "FromClusterTransaction"标记
   • 已观测到的关联现象：删除集合内带有上述集群事务标记的文档后，同集合内其余文档的刷新功能恢复正常，初步推断这类通过集群事务写入的文档可能阻塞了整个集合的文档刷新流程

待确认的核心问题 #

• 上述空引用异常的根本触发原因，是否与集群事务写入的文档元数据字段缺失、格式不兼容直接相关
• 文档刷新服务的批次执行逻辑，是否存在单条文档处理失败时未做故障隔离、直接中断整个批次刷新任务的设计缺陷
• 适配集群事务写入文档的文档刷新特性正确使用方案

内容的提问来源于stack exchange，提问作者Cabal