fix(library): 区分维护窗口指纹与恢复目标指纹

为什么:维护窗口记录的是部署/实例指纹(journal 与 library_instance_maintenance),
observeRestoreTarget 返回的是内容/索引/桶身份;两者本来不同层(r38 实测
dbe7… vs bb3f…)。v2 证据拆成 target_fingerprint 与 restore_target_fingerprint:
前者绑定窗口与治理行,后者绑定激活时的实时只读观察,避免用一个值冒充两层。
This commit is contained in:
姚章浩
2026-11-02 18:54:18 +08:00
parent 80254756f1
commit 24608e132b
6 changed files with 33 additions and 17 deletions
@@ -30,7 +30,9 @@ v2 证据文档(`protocol_version=2`)字段。注意:台账行 `library_in
| 字段 | 含义 |
|---|---|
| `target_identity` / `target_fingerprint` | 目标身份与现场指纹(64 位 sha256 hex) |
| `target_identity` | 目标身份 |
| `target_fingerprint` | 维护窗口/部署目标指纹(64 位 sha256 hex),必须等于 journal 与维护行 |
| `restore_target_fingerprint` | 激活时对恢复目标(库/索引/桶)的实时观察指纹 |
| `target_instance` | 治理库维护窗口的实例名,必须等于 journal 的 `source` |
| `governance_database` | 当前治理库名,与 `current_database()` 比对 |
| `protocol_build` | 必须是**运行中二进制**的 `version.DisplayVersion()` |
@@ -51,7 +53,9 @@ v2 证据文档(`protocol_version=2`)字段。注意:台账行 `library_in
- **A4 实例绑定**:journal `source` == 证据 `target_instance`,且 == 治理库
`library_instance_maintenance.instance`。
- **A5 作业绑定**:journal `job` == 证据 `maintenance_job` == 维护行 `owner_job_id`。
- **A6 目标绑定**:journal `target_fingerprint` == 证据指纹 == 维护行指纹 == 调用方现场观察值。
- **A6 目标绑定**:journal `target_fingerprint` == 证据 `target_fingerprint` == 维护行指纹;
证据 `restore_target_fingerprint` == 调用方激活时对恢复目标的只读观察值。两者是
不同层(实例/部署 vs 内容/索引/桶身份),不能用一个值互相顶替。
- **A7 入口排空**:`ingress_closed=true`、`drain_verified=true`、gate `closed && drained &&
active_at_close==0`。
- **A8 后台静默**:`quiesce` 存在且 depth/pending_ops/unsettled 全 0、有合法 digest、
@@ -40,9 +40,13 @@ type RestoreDispatchWriterDrain struct {
}
type RestoreDispatchActivationEvidence struct {
ProtocolVersion int `json:"protocol_version"`
TargetIdentity string `json:"target_identity"`
ProtocolVersion int `json:"protocol_version"`
TargetIdentity string `json:"target_identity"`
// TargetFingerprint 是维护窗口/部署目标指纹(journal 与治理库维护行记录的那一个);
// RestoreTargetFingerprint 是激活时对恢复目标内容/索引/桶的实时观察值。两者是不同层,
// 不能相互替代:前者绑定"动的是哪个实例",后者绑定"恢复要写的那个目标身份"。
TargetFingerprint string `json:"target_fingerprint"`
RestoreTargetFingerprint string `json:"restore_target_fingerprint"`
TargetInstance string `json:"target_instance"`
GovernanceDatabase string `json:"governance_database"`
ProtocolBuild string `json:"protocol_build"`
@@ -60,7 +64,8 @@ func (e RestoreDispatchActivationEvidence) Validate(now time.Time, maxAge time.D
}
for name, value := range map[string]string{
"target identity": e.TargetIdentity, "target fingerprint": e.TargetFingerprint,
"target instance": e.TargetInstance, "governance database": e.GovernanceDatabase,
"restore target fingerprint": e.RestoreTargetFingerprint,
"target instance": e.TargetInstance, "governance database": e.GovernanceDatabase,
"protocol build": e.ProtocolBuild, "attested by": e.AttestedBy,
"maintenance job": e.MaintenanceJob, "maintenance journal": e.MaintenanceJournal,
"maintenance journal digest": e.MaintenanceJournalSHA256,
@@ -69,8 +74,8 @@ func (e RestoreDispatchActivationEvidence) Validate(now time.Time, maxAge time.D
return fmt.Errorf("restore dispatch activation evidence lacks %s", name)
}
}
if !isHex64(e.TargetFingerprint) {
return errors.New("restore dispatch activation target fingerprint is not a sha256 hex string")
if !isHex64(e.TargetFingerprint) || !isHex64(e.RestoreTargetFingerprint) {
return errors.New("restore dispatch activation target fingerprints are not sha256 hex strings")
}
if !isHex64(e.MaintenanceJournalSHA256) {
return errors.New("restore dispatch activation maintenance journal digest is not a sha256 hex string")
@@ -37,6 +37,7 @@ type restoreDispatchVerifiedView struct {
MaintenanceState string `json:"maintenance_state"`
MaintenanceJournalSHA256 string `json:"maintenance_journal_sha256"`
TargetFingerprint string `json:"target_fingerprint"`
RestoreTargetFingerprint string `json:"restore_target_fingerprint"`
IngressGate restoreDispatchGateView `json:"ingress_gate"`
Quiesce restoreDispatchQuiesceView `json:"quiesce"`
Writers []restoreDispatchWriterView `json:"writers"`
@@ -143,8 +144,11 @@ func (s *Store) verifyRestoreDispatchEvidence(ctx context.Context, evidence libr
return verified, fmt.Errorf("restore dispatch activation evidence was produced by build %q, running build is %q",
evidence.ProtocolBuild, build)
}
if targetFingerprint != evidence.TargetFingerprint {
return verified, errors.New("restore dispatch activation evidence does not match the live target fingerprint")
// 维护窗口指纹与恢复目标指纹是两层:前者已与 journal/维护行比对,后者必须等于
// 激活方刚刚对恢复目标做的那次只读观察。用一个值同时顶替两者会掩盖"配置指向
// 另一个目标实例"的漂移。
if targetFingerprint != evidence.RestoreTargetFingerprint {
return verified, errors.New("restore dispatch activation evidence does not match the live restore target fingerprint")
}
// 治理库维护行由维护链在开窗口时写入,不是激活调用方写的:用它把作业/实例/
@@ -220,6 +224,7 @@ FROM library_instance_maintenance WHERE instance=$1`, evidence.TargetInstance).S
verified = restoreDispatchVerifiedView{
MaintenanceJob: journal.Job, MaintenanceSource: journal.Source, MaintenanceState: journal.State,
MaintenanceJournalSHA256: journal.Digest, TargetFingerprint: journal.TargetFingerprint,
RestoreTargetFingerprint: evidence.RestoreTargetFingerprint,
IngressGate: restoreDispatchGateView{Closed: journal.Gate.Closed, Drained: journal.Gate.Drained,
ActiveAtClose: journal.Gate.ActiveAtClose, Served: journal.Gate.Served, Detail: journal.Gate.Detail},
Quiesce: restoreDispatchQuiesceView{Depth: journal.Quiesce.Depth, PendingOps: journal.Quiesce.PendingOps,
@@ -442,7 +442,7 @@ func ds01ActivationEvidence(t *testing.T, store *Store, targetIdentity, fingerpr
}
return libraryrelease.RestoreDispatchActivationEvidence{
ProtocolVersion: 2, TargetIdentity: targetIdentity, TargetFingerprint: fingerprint,
TargetInstance: ds01TestInstance, GovernanceDatabase: database, ProtocolBuild: version.DisplayVersion(),
RestoreTargetFingerprint: fingerprint, TargetInstance: ds01TestInstance, GovernanceDatabase: database, ProtocolBuild: version.DisplayVersion(),
AttestedBy: "ds01-test", AttestedAt: time.Now().UTC(),
MaintenanceJob: job, MaintenanceJournal: job + ".json", MaintenanceJournalSHA256: journalDigest,
Writers: []libraryrelease.RestoreDispatchWriterDrain{{Name: ds01TestWriter, Kind: "worker", InstanceID: ds01TestWriter}},
@@ -426,8 +426,9 @@ FROM library_instance_maintenance WHERE instance=$1`, cfg.LibraryTargetInstance)
if observeErr != nil {
return "", nil, fmt.Errorf("observe live target: %w", observeErr)
}
if recorded, _ := journal["target_fingerprint"].(string); fingerprint != recorded {
return "", nil, fmt.Errorf("live target fingerprint %s != maintenance window %s", fingerprint, recorded)
windowFingerprint, _ := journal["target_fingerprint"].(string)
if windowFingerprint == "" {
return "", nil, errors.New("maintenance journal has no target fingerprint")
}
build := version.DisplayVersion()
if expected := os.Getenv("KG_R38_VERSION"); expected != "" && build != expected {
@@ -440,8 +441,8 @@ FROM library_instance_maintenance WHERE instance=$1`, cfg.LibraryTargetInstance)
journalSum := sha256.Sum256(rawJournal)
now := time.Now().UTC()
evidence := libraryrelease.RestoreDispatchActivationEvidence{
ProtocolVersion: 2, TargetIdentity: cfg.LibraryTargetIdentity(), TargetFingerprint: fingerprint,
TargetInstance: cfg.LibraryTargetInstance, GovernanceDatabase: database, ProtocolBuild: build,
ProtocolVersion: 2, TargetIdentity: cfg.LibraryTargetIdentity(), TargetFingerprint: windowFingerprint,
RestoreTargetFingerprint: fingerprint, TargetInstance: cfg.LibraryTargetInstance, GovernanceDatabase: database, ProtocolBuild: build,
AttestedBy: "r38-runner", AttestedAt: now,
MaintenanceJob: job.ID, MaintenanceJournal: job.ID + ".json",
MaintenanceJournalSHA256: hex.EncodeToString(journalSum[:]), Writers: writers,
@@ -471,8 +472,9 @@ FROM library_index_restore_dispatch_activation WHERE target_identity=$1`, cfg.Li
gate, _ := journal["gate"].(map[string]any)
quiesce, _ := journal["quiesce"].(map[string]any)
facts := map[string]any{
"target": target, "fingerprint": fingerprint, "governance_database": database,
"maintenance_job": job.ID, "protocol_build": build,
"target": target, "fingerprint": fingerprint, "window_fingerprint": windowFingerprint,
"governance_database": database,
"maintenance_job": job.ID, "protocol_build": build,
"journal_sha256": drainDigest, "activation_evidence_sha256": hex.EncodeToString(evidenceSum[:]),
"journal_state": journal["state"], "gate": gate, "quiesce": quiesce,
"writers": writers, "activated_at": activatedAt, "stored_evidence_bytes": len(stored),
@@ -600,7 +600,7 @@ WHERE instance=$1`, ds01TargetInstance, `["worker-ds01"]`, fingerprint); err !=
}
evidence := libraryrelease.RestoreDispatchActivationEvidence{
ProtocolVersion: 2, TargetIdentity: targetIdentity, TargetFingerprint: fingerprint,
TargetInstance: ds01TargetInstance, GovernanceDatabase: database, ProtocolBuild: version.DisplayVersion(),
RestoreTargetFingerprint: fingerprint, TargetInstance: ds01TargetInstance, GovernanceDatabase: database, ProtocolBuild: version.DisplayVersion(),
AttestedBy: "ds01-test", AttestedAt: now,
MaintenanceJob: job, MaintenanceJournal: job + ".json",
MaintenanceJournalSHA256: hex.EncodeToString(journalSum[:]),