SonnetDB 3.1.0 正式发布。本次版本覆盖自 v3.0.1 以来、截至 2026 年 8 月 24 日合入的 200+ 次提交，重点完成了多模型管理工作台、工业协议接入、关系 SQL 与查询规划、Document 易用性、语义内容、存储可靠性和可观测性的系统升级。

• 3.1.0 继续坚持“八种数据模型，一套引擎”： 时序、关系表、键值、JSON 文档、全文检索、向量检索、对象存储和消息队列共享同一个数据库目录、权限边界、备份恢复体系和管理工具。

版本亮点

• 多模型工作台形成完整闭环：Web Admin、SonnetDB Studio 和 VS Code 扩展共享统一 Explorer、结果视图、写入审批、历史与导出能力，覆盖八种正式数据模型。

• 工业接入能力显著扩展：新增 CoAP/CoAPS、Sparkplug B、Line Protocol UDP，以及内建 Modbus TCP master/client、slave/server、映射表、质量标记、审批和审计链路。

• 关系 SQL 从“可用”走向“可治理”：新增逻辑视图、物化视图、SQL 存储过程、关系表触发器、自增列、INSERT RETURNING、ALTER COLUMN、CHECK 约束和更完整的 EF Core 翻译。

• 查询执行器与规划器升级：关系查询获得 EXISTS/IN 快速路径、有界索引并集、倒序索引游标、输入下推、流式算子、index-only scan、持久统计、成本选择和 EXPLAIN ANALYZE 执行证据。

• 可靠性边界继续收紧：加固 KV/WAL/checkpoint、关系索引恢复、对象存储发布与删除、SonnetMQ 尾部恢复、批量导入原子性、命令取消和 HTTP/2 帧传输。

• 语义内容能力落地：新增通用 Semantic Content 合同和基于 SigLIP2 的文搜图、图搜图工作流，原始对象、向量 profile 和派生索引保持明确隔离。

多模型管理与开发工具

3.1.0 对管理界面进行了范围较大的重构。统一 Explorer 现在可以从 Connection、Database 一直浏览到 measurement、table、collection、KV keyspace、全文/向量索引、MQ topic、object bucket、backup，以及开发中的 graph 对象。

关系工作台新增数据网格、类型化行内编辑、表设计器、索引管理、CSV/JSON/JSONL 导入、结果导出、ER 关系图、DDL 导出和可视化执行计划。KV、SonnetMQ、Document、全文、向量、对象存储和时序数据也获得各自的浏览、诊断或操作入口。写操作统一进入 staged preview 和确认流程，执行结果可写入共享历史并导出为 CSV/JSON。

SonnetDB Studio 补齐桌面桥接、文件选择和原生菜单；VS Code 扩展补齐连接管理、Schema Explorer、SQL 语言服务、多结果页签、多模型只读预览和 Copilot 入口。管理端首次安装流程也得到修复：默认服务器标识、组织、管理员用户名和初始 Bearer Token 会写入真实表单值，服务不可达时不再误导用户提交。

工业协议与边缘接入

CoAP、Sparkplug B 与 UDP

• CoAP/CoAPS 支持通过 POST/PUT db/{db}/m/{measurement} 写入，复用现有批量摄取、Token 和权限模型；支持 blockwise payload、PSK DTLS，以及通过 Observe 订阅 SonnetMQ topic。

• MQTT 接入补齐 Sparkplug B payload 映射与生命周期处理，用于工业设备状态和遥测接入。

• 新增 Line Protocol UDP listener，用于可信内网中的低开销、fire-and-forget 时序写入；非法 UTF-8、超限和错误数据报不会终止监听循环。

• Parity 场景可以使用同一 Line Protocol payload 对拍 HTTP、UDP、MQTT 和 CoAP 的落库结果。
  CoAP、Line Protocol UDP 和相关工业协议监听器均默认关闭，必须由管理员显式配置。UDP 没有鉴权、确认和应用层背压，不应暴露到不可信网络。

Modbus TCP

• SonnetDB 现在可以把 Modbus TCP 数据映射到关系表，而不需要另建旁路存储：

• TCP master/client 支持轮询采集、受限控制写、超时、退避、重连、质量标记和失败策略。

• TCP slave/server 支持寄存器映射、连接限制、allowlist，以及 0x05、0x06、0x0F、0x10 写请求。

• 外部写默认进入持久 staging 队列，经预览、审批、重新校验后再更新关系表；拒绝、过期、约束失败和持久化失败均有终态审计。

• Web Admin、REST、SQL metadata 和指标端点提供 runtime、binding、pending、audit 和健康状态视图。
  Modbus runtime 全局默认关闭；创建 source、endpoint 或映射表不会自动建立外部网络连接。

关系 SQL、EF Core 与查询性能

新增 SQL 能力

• 关系表支持 CHECK 约束、自增列、数据库生成键和 INSERT ... RETURNING。

• ALTER TABLE 支持列默认值、NULL 约束、重命名与受预算约束的类型迁移。

• 新增持久化逻辑视图和显式刷新的物化视图，并跟踪基础对象依赖，阻止产生悬空引用的 DROP/ALTER。

• 新增 LANGUAGE SQL 存储过程，以及关系表 AFTER INSERT、AFTER UPDATE、AFTER DELETE FOR EACH ROW 触发器。

• UPDATE/DELETE 支持非相关 IN (SELECT ...)；关系表 JSON 导入复用标准约束、默认值、ROWVERSION 和触发器语义，并保持整条语句原子性。

• EF Core provider 新增自增键回填、DateTime/DateTimeOffset 日期运算与 Unix 时间翻译、字符串拼接，以及事务外 migration DDL。

• SQL 与 Document validator 共用有超时、输入预算和有界缓存的正则执行器；新增 regexp_like(...)、REGEXP/RLIKE 与 EF Core Regex.IsMatch 翻译，并在 EXPLAIN 中如实标为 residual scan filter。

查询规划与执行

• 关系执行器新增以下路径：

• EXISTS、字面量 IN 和可证明非相关的 IN (SELECT ...) 可以使用主键、二级索引或批量 MultiGet，并在首个有效结果处停止。

• 顶层 OR 可以对有界的主键、索引等值/范围和 IS NULL 分支做候选集合并；超出预算时完整回退，不静默截断。

• 双向 KV/index cursor 支持 ORDER BY ... DESC LIMIT/OFFSET 早停。

• JOIN 输入可以安全下推单表谓词、投影和部分分页窗口；scan/filter/project 改为惰性消费，排序分页使用有界 Top-N。

• covering index 在谓词和所需列均被覆盖时走 secondary_index_only，避免读取和解码基表行。

• ANALYZE TABLE 持久化有预算的表与索引统计；有限成本模型依据选择率、行宽和逻辑读取选择 point/range/index-union/full scan。

• EXPLAIN ANALYZE 可报告估算/实际行数、访问路径、候选与移除行数、循环、耗时、分配、锁等待、WAL fsync、内存行为和 fallback reason。
  时序查询同步补齐字符串/布尔类型选择与聚合语义、共享字段多聚合单次扫描、残差与跨字段 Geo 聚合流式化、count(*) 专用路径、raw LIMIT/OFFSET 下推，以及 ORDER BY time DESC LIMIT N 的 latest-N 倒序读取。
  仓库内开发机基准中，30,000 task/128 device 的关系 JOIN 样例均值由 128.44 ms 降至 61.61 ms，托管分配由 30.18 MB 降至 17.94 MB。该数据用于说明本次优化方向，不替代固定 ARM64/x64 硬件或生产负载报告。

Document、搜索与语义内容

Document SDK 增加更接近常见文档数据库使用习惯的 typed filter、projection、sort、cursor、update operator、aggregate、索引管理和 change feed API。更新能力新增 $mul、$pop 和原子 findOneAndUpdate；查询增加 $elemMatch、$regex、$type、$size、$all、递归 $not 与数组 path fan-out；索引增加 multikey/wildcard、typed key、EXPLAIN 和崩溃后修复；aggregation 增加 computed project/group、push/addToSet 和完整 unwind。

批处理现在支持 mixed ordered/unordered 操作、逐项结果、有界请求和 24 小时 requestId 重放。新增 sndb document import，可以从 JSON array、严格 UTF-8 NDJSON、常用 Extended JSON 和 mongodump BSON 子集执行 dry-run、checkpoint/resume 与错误报告。管理端同步完善文档浏览、校验、导入导出和变更订阅。SonnetDB 仍不提供 MongoDB wire protocol 或官方 MongoDB Driver 直连兼容；相关 parity 只用于验证公开的 MongoDB-like 语义。

• 对象存储与向量检索之上新增语义图片工作流： 部署者可以显式配置 SigLIP2 模型，以同一向量空间完成文搜图和图搜图。Embedding profile 会隔离不同模型、量化和预处理语义，避免不兼容向量混入同一索引；服务端不会自动下载模型，能力默认关闭。
  新增的 Semantic Content 合同统一描述内容清单、稳定 chunk/segment、对象引用、命名向量绑定、Embedding profile、内容外发策略和派生索引状态。原始内容继续由 Object Bucket 唯一持有，Core 不直接调用 embedding provider，也不在元数据中内嵌大对象。

可观测性与 Copilot

• Health 与 readiness 探针现在分别反映进程存活和服务可用性。

• Server 统一结构化日志字段，并增加慢查询、Top-N 指纹聚合、访问路径、行数放大、锁/队列等待、分配/GC、逻辑/物理 I/O 等诊断证据。

• 新增诊断转储采集流程，便于在不泄露业务行内容和参数值的前提下定位线上问题。

• Copilot 会话与用量摘要可持久化，模型按 provider-neutral 能力分组；知识召回指标和 Agent trace 得到补充。

• AI 边界保持不变： 当前仍是 Microsoft.Extensions.AI 抽象加自研 CopilotAgent，不是 Microsoft Agent Framework 的正式集成；本地 ONNX provider 尚未执行真实模型，不应在 3.1.0 公告中描述为已接通能力。

存储、传输与恢复

• 本次版本修复和加固了多条关键可靠性路径：

• KV checkpoint/WAL 轮换增加 sealed log 校验、状态 CRC、目录项落盘、写入预算和生命周期租约，避免延迟 checkpoint 与同目录重开的竞态。

• KV/关系大批量删除新增 generation 快速路径和带 commit record 的分块删除；TRUNCATE TABLE、DELETE WHERE TRUE 与后台 cleanup 不再要求逐行生成普通删除记录，异常恢复也不会让旧 generation 重新可见。

• 关系索引恢复改为分页核对并只修复 missing/stale/orphan 项，避免异常退出后无条件删除并重建全部索引。

• 对象 PUT 的正文、版本、latest 指针和审计按可恢复顺序发布；bucket 删除、并发 PUT、multipart complete/abort 和生命周期清理按 bucket 版本线性化。

• 对象 GET 支持 suffix Range，越界范围返回标准 416，完整和范围读取都可以取得对象总长度。

• SonnetMQ 可以修复最后活动段的全零或截断尾部，同时继续严格拒绝历史段和中间位置的非零损坏；冷读定位 offset 时不再读取此前的大 payload。

• ADO.NET 的 CommandTimeout、DbCommand.Cancel() 和 DataReader 逐行读取共享真实取消链路，并保持调用方取消、手动取消和超时可区分。

• Protocol=frame-http2 现在对 ADO.NET、MQ 和对象客户端真正要求 exact HTTP/2，不再在控制面或 REST fallback 中静默协商到 HTTP/1.1。

• Parity 工作流恢复失败汇总、宿主 readiness、真实当前提交镜像和多参考数据库适配，CI 门禁不再因第三方镜像缺少 shell 工具而卡在启动阶段。

开发中的原生图能力

• 3.1.0 的程序集包含原生属性图的开发中实现，供 API 联调和后续发布门禁使用：

• Graph catalog、事务、statement snapshot、分页 cursor、label/property/unique 派生索引与备份恢复合同。

• 嵌入式、HTTP 和 typed .NET SDK 的顶点/边读写、Expand、BFS/DFS、无权/加权最短路径和批量路径执行。

• SQL/PGQ 风格 GRAPH_TABLE、关系表映射 property graph、跨 Graph/Table/Document/FullText/Vector 的标准派生表组合，以及显式 opt-in 的受限 GQL 查询入口。

• Degree、弱连通分量、PageRank、label-propagation community 等可恢复离线算法。

• 知识图谱/GraphRAG 上层合同，以及 CLI、Web/Studio Graph Workbench、导入导出和两阶段维护审批。
  这些能力仍受固定结果数、frontier、内存、文件、导入字节和执行时间预算约束。完整 Cypher、完整 GQL、Neo4j Bolt、PostgreSQL wire 和无界遍历不在 3.1.0 的兼容承诺内。

兼容性与升级注意事项

• 目标框架保持 .NET 10 / net10.0；SonnetDB.Core 继续保持零第三方运行时依赖和 Safe-only 实现。

• 本次没有修改既有时序 .SDBSEG 与 WAL 二进制布局；新增 Graph、Modbus、视图、过程等能力使用独立 catalog/state，已有数据库可继续打开。KV state 当前写格式为 v5，并继续读取 v1-v4；较新 state 被写出后，不保证旧版 SonnetDB 二进制可以直接回滚读取，降级前应使用当前版本导出/备份并由目标版本重新导入。

• 既有 REST/JSON 端点继续保留，Frame v1 布局未改变。Graph 带目标属性过滤的请求在 Frame v1 配置下会显式回退到 source-generated HTTP 流。

• 显式轻事务只覆盖关系表 DML。DDL、measurement/document 写入和 IMPORT JSON 现在会在事务内明确拒绝，避免出现无法回滚的“假事务”；EF Core migration 已自动在事务外执行 DDL。

• 使用 Protocol=frame-http2 时必须连接支持 HTTP/2 或 h2c 的端口。需要允许 HTTP/1.1 fallback 的部署应继续使用 Protocol=auto 或 Protocol=rest。

• CoAP、Line Protocol UDP、Modbus runtime 和语义图片模型均默认关闭，升级后不会自动监听新端口、连接 PLC 或下载模型。
  升级生产环境前，建议先备份数据库目录，在预发布环境验证 SQL/EF migration、Frame endpoint、对象 Range、Document change feed 和启用中的工业协议。应用依赖 DDL-in-transaction 或 HTTP/2 强制模式静默降级的，需要先调整调用方式或连接串。

获取 3.1.0

• 安装 NuGet 包：

dotnet add package SonnetDB.Core --version 3.1.0
dotnet add package SonnetDB --version 3.1.0
dotnet add package SonnetDB.EntityFrameworkCore --version 3.1.0
dotnet tool install --global SonnetDB.Cli --version 3.1.0

• 拉取服务端镜像：

docker pull iotsharp/sonnetdb:3.1.0

完整历史和逐项工程记录见 CHANGELOG，部署和安装方式见 发布与打包。

感谢所有参与代码、测试、文档和问题反馈的贡献者。