HHostingByteSoftware
Ctrl K
ComunidadGuías…

docs/UPGRADE_v0.9.3.md

Rama main · réplica de lectura del repositorio original.

Archivo original ↗Preguntar a KiBot
# Core v0.9.3 补丁升级指南

[English](UPGRADE_v0.9.3.en.md)

从公开 Core 0.9.2 升级到 0.9.3，修复有限收包、通知正常关闭与执行器死信重投，增加只读维护指标。本指南只涉及 Core；MCP / Agent Client SDK、DSH 仍为 0.7.0，ACC、客户端与独立 Host 按各自流程发行和部署。

## 保留数据并协调写入

备份目标数据库，保留配置与凭据、附件、原任务/请求、审批、死信、队列及旧制品。停止新工作并协调所有共用状态库的写入方，核对在途通知和已送达/未知送达记录，再排空关闭旧实例。

保留原 Job、request、operation、invocation、审批 decision 和死信 ID。新关闭保证需新代码参与；旧实例的关闭成功不证明尚未登记的通知已完成。关闭超时后保留同实例资源，等待后重试，不强制关库或盲目重发未知消息。

## 选择制品并显式迁移

选择正式 `v0.9.3` 源码、npm 包或镜像，核对 Tag/提交、版本和制品摘要。安装器、预构建镜像 Compose 默认版本同步为 0.9.3；已有 `.env` 保留，依赖版本不更新。

通过官方显式迁移器应用全部未执行文件。源码入口：

```bash
npm run db:init
```

嵌入式使用官方 `migrateBailingHubCoreSchema` 显式入口；核对完整 `BAILINGHUB_CORE_ARTIFACT_V1` 制品 manifest。启动不自动迁移，已记账 SQL 跳过，不手工编辑历史 SQL 或迁移账本。

| 相对 0.9.2 新增迁移 | 作用 |
| --- | --- |
| `067_delivery_dlq_replay.sql` | 在 `bz_delivery_dlq` 增加 `delivery_kind`、`notification_job_id`、`executor_replay_key`；在 `bz_jobs` 增加 `delivery_replay_keys`，保存通知原记录与永久入队标记 |

067 不清除旧数据，不批量猜测历史死信类型。旧死信重投时由 Core 核对原任务；绑定不明时明确拒绝。启动新 Core 的全部 MySQL DLQ 读写前必须应用 067，包括原生渠道 record/get；从更早版本升级还须补全部前序迁移，065/066 配套见 [0.9.2 指南](UPGRADE_v0.9.2.md)。

## 配套仓储与调用方

官方 MySQL/JSONL 状态仓储及 DLQ ledger 一起升级。自定义 ledger 提供可选 `ensureExecutorReplay`，自定义状态仓提供 `RuntimeStateStore.requeueDeliveryJobOnce`，并保证核对原绑定、原子入队和标记、标记不被普通更新清除。未配套时执行器重投返回 `delivery_dlq_replay_unavailable`，不改发同名原生渠道。JSONL 仍仅支持单 writer。

重投保留原通知子任务的完整输入、收件人和 request/job 标识；不使用业务父任务重跑来补发。返回 `queued` 是队列准入，实际送达另看执行状态/收件方证据。同一死信的永久标记阻止重复入队；再次失败形成的新死信属于新的运营处理记录。原生渠道不新增跨系统恰好一次保证，部分或未知送达仍需核对。

保持 managed 的既有 `tick()` 与 `close(drainMs)`；关闭按共同预算等待已接受通知及动态子工作。通知失败和超时应观察固定类别指标，不能用计数代替业务或接收方证据。

## 升级验收

1. 核对新制品身份、目标库迁移账本与 067 实际字段，检查 `/health`、控制台和既有 smoke。可显式运行只读诊断：

   ```bash
   npm run --silent doctor -- --deployment --url http://127.0.0.1:18900 --readiness --json
   ```

   它不执行迁移或确认镜像摘要、完整数据库身份。读取退出码及未检查范围，见[部署诊断](DEPLOYMENT_DIAGNOSTICS.md)。
2. 在隔离环境检查限额内/超限工具正文与附件，包含缺少/低报长度和多字节文本。已外发写操作超限后保留原调用未知结果，恢复不得出现第二次业务派发。
3. 核对执行器通知失败产生的死信：一次重投仅将原通知子任务入队；并发/确认丢失重试不重复入队，也不重跑业务父任务。实际收件方送达另行验收。
4. 核对延迟回调、通知派生和 DLQ 写入阻挡资源关闭，排空超时保留资源且同实例重试成功。这不验证 SIGKILL 后全量通知补投。
5. 若启用受保护的 `/metrics`，检查固定类别的后台在途、失败、运行年龄、排空超时和最近一页进度。抓取不触发维护或供应商请求；进程计数不是持久积压量。

合成测试及专用 MySQL 回归入口见 [Core 可靠性](CORE_RELIABILITY.md#core-v093-的-http-与通知修复)。跳过不计通过，发行验收不代替目标环境的部署验收。

## 回退边界

067 是增量结构；代码回退保留死信类型/绑定/重投标识、`delivery_replay_keys`、队列、原记录及迁移账本，不能删除标记后重投。先停止相关写入，核对已准入和在途通知、收件方证据，再决定回退。

**旧版本不自动兼容新迁移账本。** 旧制品的完整 schema manifest 或迁移器可能因未知的 067 记录失败关闭；字段增量不等于旧 readiness/迁移入口必然通过。必须在隔离副本验证目标旧制品与保留的新 schema/账本组合，明确恢复方式，不能靠删除迁移记录绕过检查。回退旧代码也会失去本版收包、通知关闭及重投去重保证。

若恢复旧备份，核对备份后已经发生的业务、消息送达和账务；数据库恢复不撤销这些外部效果。未知送达不能盲目补发，业务方保留自己的幂等与最终授权。

[版本说明](RELEASE_NOTES_v0.9.3.md) · [可靠性契约](CORE_RELIABILITY.md) · [兼容策略](兼容性与升级.md)