diff --git a/CHANGELOG.md b/CHANGELOG.md index c001cd2..8bed450 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,17 @@ # Changelog +## 开发快照(按版本恢复 + 作业续作) + +### Added + +- 迁移 000068:`library_jobs.kind` 允许 `restore`,与封存/同步分开。 +- `POST /api/v1/library/restores`:管理员按指定整库快照恢复;要求**针对该快照的恢复授权** + (同步授权不能顶替),闸口与恢复演练证据同样适用,缺项逐条拒绝且不建作业。 +- `POST /api/v1/library/jobs/{id}/resume`:失败/取消的同步或恢复作业按原参数重新排队, + 旧作业保留为审计记录;封存作业不走续作(由封存入口重发)。 +- worker 新增 `library.restore` 处理器,与同步共用"闸口 → 授权 → 预备份 → 四类写入 → 校验"链路; + 成功后登记 `production_effective` 版本(带预备份快照与字节数证据),失败/回滚失败分别留痕。 + ## 开发快照(资源范围修正 + 内容级校验 + 真实对象存储验收) ### Fixed diff --git a/api/openapi.yaml b/api/openapi.yaml index efa2f66..0ada5fe 100644 --- a/api/openapi.yaml +++ b/api/openapi.yaml @@ -1025,6 +1025,101 @@ } } }, + "/api/v1/library/restores": { + "post": { + "tags": [ + "Runtime" + ], + "operationId": "startLibraryRestore", + "summary": "按指定整库版本恢复生产(仅管理员;需要针对该快照的恢复授权,闸口与恢复演练证据同样适用)", + "responses": { + "202": { + "description": "已创建恢复作业并入队" + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "403": { + "description": "仅管理员可发起恢复" + }, + "409": { + "description": "该目标已有在飞作业,或同一恢复请求参数冲突" + }, + "500": { + "$ref": "#/components/responses/InternalError" + }, + "503": { + "description": "闸口关闭、缺恢复演练证据或缺该快照的授权,返回具体原因" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": false, + "required": [ + "scope", + "snapshot_id" + ], + "properties": { + "scope": { + "type": "string", + "enum": [ + "internal", + "external" + ] + }, + "snapshot_id": { + "type": "string" + } + } + } + } + } + } + } + }, + "/api/v1/library/jobs/{id}/resume": { + "post": { + "tags": [ + "Runtime" + ], + "operationId": "resumeLibraryJob", + "summary": "续作失败或已取消的同步/恢复作业:按原参数重新排队,旧作业保留为审计记录", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "202": { + "description": "已创建续作作业" + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "403": { + "description": "需要知识工程师及以上权限" + }, + "404": { + "description": "作业不存在" + }, + "409": { + "description": "作业状态不允许续作,或该目标已有在飞作业" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + } + }, "/api/v1/library/authorizations": { "get": { "tags": [ diff --git a/cmd/worker/library_handlers.go b/cmd/worker/library_handlers.go new file mode 100644 index 0000000..4348e85 --- /dev/null +++ b/cmd/worker/library_handlers.go @@ -0,0 +1,126 @@ +package main + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "log" + "strings" + "time" + + "knowledge-governance/internal/appconfig" + "knowledge-governance/internal/governance" + "knowledge-governance/internal/jobs" + "knowledge-governance/internal/libraryrelease" + postgresstore "knowledge-governance/internal/platform/postgres" +) + +// libraryReleasePayload 是同步与恢复共用的队列载荷形状。 +type libraryReleasePayload struct { + LibraryJobID string `json:"library_job_id"` + Scope string `json:"scope"` + TargetSnapshotID string `json:"target_snapshot_id"` +} + +// runLibraryRelease 执行"闸口 → 授权 → 预备份 → 四类写入 → 校验"的完整链路。 +// 同步与恢复只在作业类型、授权摘要与成功后登记的版本类型上不同。 +func runLibraryRelease(ctx context.Context, store *postgresstore.Store, config appconfig.Config, + job jobs.Job, kind governance.LibraryJobKind) error { + var payload libraryReleasePayload + if err := json.Unmarshal(job.Payload, &payload); err != nil || payload.LibraryJobID == "" || payload.TargetSnapshotID == "" { + return fmt.Errorf("invalid library %s payload", kind) + } + now := time.Now().UTC() + _ = store.AdvanceLibraryJob(ctx, payload.LibraryJobID, governance.LibraryJobRunning, "prebackup", "", "", "", "", now) + recorder := libraryStageRecorder{store: store, jobID: payload.LibraryJobID} + + gateReasons := make([]string, 0, 3) + if !config.ProductionReleaseRequestsEnabled { + gateReasons = append(gateReasons, "生产写入闸口关闭") + } + if !config.ProductionBackupRestoreVerified { + gateReasons = append(gateReasons, "没有已核验的生产恢复演练证据") + } + if len(gateReasons) > 0 { + message := "生产" + kindLabel(kind) + "被闸口拒绝:" + strings.Join(gateReasons, ";") + recorder.Stage(ctx, "prebackup", "failed", message) + _ = store.AdvanceLibraryJob(ctx, payload.LibraryJobID, governance.LibraryJobFailed, "prebackup", message, + "未对生产执行任何写入,无需恢复", "", "", time.Now().UTC()) + return errors.New(message) + } + + digest, err := governance.LibraryRequestDigest(payload.Scope, kind, map[string]any{digestKey(kind): payload.TargetSnapshotID}) + if err != nil { + return failLibraryJob(ctx, store, recorder, payload.LibraryJobID, "无法计算请求摘要", "prebackup") + } + grant, found, err := store.ActiveLibraryAuthorization(ctx, payload.Scope, payload.TargetSnapshotID, digest, now) + if err != nil || !found { + return failLibraryJob(ctx, store, recorder, payload.LibraryJobID, "没有与目标快照匹配的有效发布授权", "prebackup") + } + target, backups, wireErr := buildLibraryProductionStack(ctx, config, payload.Scope) + if wireErr != nil { + return failLibraryJob(ctx, store, recorder, payload.LibraryJobID, wireErr.Error(), "prebackup") + } + defer target.Close() + + request := libraryrelease.Request{Target: payload.Scope, SnapshotID: payload.TargetSnapshotID, + ParamsDigest: digest, Now: now, + Grant: libraryrelease.Grant{Target: payload.Scope, SnapshotID: grant.SnapshotID, + ParamsDigest: grant.ParamsDigest, ExpiresAt: grant.ExpiresAt, AuthorizedBy: grant.AuthorizedBy}} + outcome := libraryrelease.Run(ctx, request, target, backups, recorder) + finishedAt := time.Now().UTC() + switch outcome.State { + case "succeeded": + // 成功后登记"生产生效版本":这是生产当前的权威依据,只有真的验证通过才写。 + versionErr := store.RecordLibraryVersion(ctx, governance.LibraryVersion{ + ID: "libver-prod-" + payload.Scope + "-" + outcome.Backup.SnapshotID, Scope: payload.Scope, + Kind: governance.LibraryVersionProductionEffective, SnapshotID: payload.TargetSnapshotID, + SourceJobID: payload.LibraryJobID, CreatedBy: grant.AuthorizedBy, + Evidence: map[string]any{"backup_snapshot": outcome.Backup.SnapshotID, + "backup_bytes": outcome.Backup.Bytes, "action": string(kind)}, + CreatedAt: finishedAt, + }) + if versionErr != nil { + log.Printf("library %s recorded but version registration failed: %v", kind, versionErr) + } + _ = store.AdvanceLibraryJob(ctx, payload.LibraryJobID, governance.LibraryJobSucceeded, "verify", "", "", + outcome.Backup.SnapshotID, payload.TargetSnapshotID, finishedAt) + log.Printf("library %s succeeded job=%s scope=%s snapshot=%s backup=%s", kind, + payload.LibraryJobID, payload.Scope, payload.TargetSnapshotID, outcome.Backup.SnapshotID) + return nil + case "rolled_back": + _ = store.AdvanceLibraryJob(ctx, payload.LibraryJobID, governance.LibraryJobFailed, "rollback", + outcome.Error, outcome.Rollback, "", "", finishedAt) + return errors.New(outcome.Error) + case "rollback_failed": + _ = store.AdvanceLibraryJob(ctx, payload.LibraryJobID, governance.LibraryJobFailed, "rollback", + outcome.Error, outcome.Rollback, "", "", finishedAt) + return fmt.Errorf("%s(%s)", outcome.Error, outcome.Rollback) + default: + _ = store.AdvanceLibraryJob(ctx, payload.LibraryJobID, governance.LibraryJobFailed, "prebackup", + outcome.Error, "未对生产执行任何写入,无需恢复", "", "", finishedAt) + return errors.New(outcome.Error) + } +} + +func failLibraryJob(ctx context.Context, store *postgresstore.Store, recorder libraryStageRecorder, jobID, message, stage string) error { + recorder.Stage(ctx, stage, "failed", message) + _ = store.AdvanceLibraryJob(ctx, jobID, governance.LibraryJobFailed, stage, message, + "未对生产执行任何写入,无需恢复", "", "", time.Now().UTC()) + return errors.New(message) +} + +func kindLabel(kind governance.LibraryJobKind) string { + if kind == governance.LibraryJobRestore { + return "恢复" + } + return "同步" +} + +func digestKey(kind governance.LibraryJobKind) string { + if kind == governance.LibraryJobRestore { + return "restore_snapshot_id" + } + return "target_snapshot_id" +} diff --git a/cmd/worker/main.go b/cmd/worker/main.go index 2ccca13..56ca4b9 100644 --- a/cmd/worker/main.go +++ b/cmd/worker/main.go @@ -3,13 +3,11 @@ package main import ( "context" "encoding/json" - "errors" "fmt" "log" "os" "os/signal" "path/filepath" - "strings" "syscall" "time" @@ -19,7 +17,6 @@ import ( "knowledge-governance/internal/governance" "knowledge-governance/internal/jobs" "knowledge-governance/internal/libraryagent" - "knowledge-governance/internal/libraryrelease" postgresstore "knowledge-governance/internal/platform/postgres" "knowledge-governance/internal/platform/weknora" "knowledge-governance/internal/versionhistory" @@ -48,6 +45,9 @@ const libraryCaptureJobType = "library.capture" // librarySyncJobType 是生产同步作业的队列类型;与封存严格分开,状态不共用。 const librarySyncJobType = "library.sync" +// libraryRestoreJobType 是按指定整库版本恢复的队列类型;与同步分开、授权也分开。 +const libraryRestoreJobType = "library.restore" + func main() { ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM) defer stop() @@ -212,90 +212,10 @@ func workerHandlers(store *postgresstore.Store, config appconfig.Config) (map[st // 生产同步:唯一入口在 API(闸口未齐不建作业)。这里仍实现执行器, // 但默认 fail-closed:没有闸口证据就明确失败,绝不向生产写入半个字节。 handlers[librarySyncJobType] = func(ctx context.Context, job jobs.Job) error { - var payload struct { - LibraryJobID string `json:"library_job_id"` - Scope string `json:"scope"` - TargetSnapshotID string `json:"target_snapshot_id"` - } - if err := json.Unmarshal(job.Payload, &payload); err != nil || payload.LibraryJobID == "" { - return fmt.Errorf("invalid library sync payload") - } - now := time.Now().UTC() - _ = store.AdvanceLibraryJob(ctx, payload.LibraryJobID, governance.LibraryJobRunning, "prebackup", "", "", "", "", now) - recorder := libraryStageRecorder{store: store, jobID: payload.LibraryJobID, scope: payload.Scope} - - // 闸口本身关闭时不必进入执行编排:先给出可操作的缺项。 - gateReasons := make([]string, 0, 3) - if !config.ProductionReleaseRequestsEnabled { - gateReasons = append(gateReasons, "生产写入闸口关闭") - } - if !config.ProductionBackupRestoreVerified { - gateReasons = append(gateReasons, "没有已核验的生产恢复演练证据") - } - if len(gateReasons) > 0 { - message := "生产同步被闸口拒绝:" + strings.Join(gateReasons, ";") - recorder.Stage(ctx, "prebackup", "failed", message) - _ = store.AdvanceLibraryJob(ctx, payload.LibraryJobID, governance.LibraryJobFailed, "prebackup", message, - "未对生产执行任何写入,无需恢复", "", "", time.Now().UTC()) - return errors.New(message) - } - - digest, digestErr := governance.LibraryRequestDigest(payload.Scope, governance.LibraryJobSync, - map[string]any{"target_snapshot_id": payload.TargetSnapshotID}) - if digestErr != nil { - message := "无法计算请求摘要" - recorder.Stage(ctx, "prebackup", "failed", message) - _ = store.AdvanceLibraryJob(ctx, payload.LibraryJobID, governance.LibraryJobFailed, "prebackup", message, "", "", "", time.Now().UTC()) - return errors.New(message) - } - grant, found, grantErr := store.ActiveLibraryAuthorization(ctx, payload.Scope, payload.TargetSnapshotID, digest, now) - if grantErr != nil || !found { - // 授权缺失/过期/参数不符都会走到这里:不能写生产。 - message := "没有与目标快照匹配的有效发布授权" - recorder.Stage(ctx, "prebackup", "failed", message) - _ = store.AdvanceLibraryJob(ctx, payload.LibraryJobID, governance.LibraryJobFailed, "prebackup", message, - "未对生产执行任何写入,无需恢复", "", "", time.Now().UTC()) - return errors.New(message) - } - - request := libraryrelease.Request{ - Target: payload.Scope, SnapshotID: payload.TargetSnapshotID, ParamsDigest: digest, Now: now, - Grant: libraryrelease.Grant{Target: payload.Scope, SnapshotID: grant.SnapshotID, - ParamsDigest: grant.ParamsDigest, ExpiresAt: grant.ExpiresAt, AuthorizedBy: grant.AuthorizedBy}, - } - // 生产目标与预备份存储来自部署注入的真实连接;未配置就在第一步失败并写明缺项, - // 不会出现"写了一半没有回滚目标"的状态。 - target, backups, wireErr := buildLibraryProductionStack(ctx, config, payload.Scope) - if wireErr != nil { - message := wireErr.Error() - recorder.Stage(ctx, "prebackup", "failed", message) - _ = store.AdvanceLibraryJob(ctx, payload.LibraryJobID, governance.LibraryJobFailed, "prebackup", message, - "未对生产执行任何写入,无需恢复", "", "", time.Now().UTC()) - return errors.New(message) - } - defer target.Close() - outcome := libraryrelease.Run(ctx, request, target, backups, recorder) - finishedAt := time.Now().UTC() - switch outcome.State { - case "succeeded": - _ = store.AdvanceLibraryJob(ctx, payload.LibraryJobID, governance.LibraryJobSucceeded, "verify", "", "", - "", payload.TargetSnapshotID, finishedAt) - log.Printf("library sync succeeded job=%s scope=%s snapshot=%s backup=%s", - payload.LibraryJobID, payload.Scope, payload.TargetSnapshotID, outcome.Backup.ID) - return nil - case "rolled_back": - _ = store.AdvanceLibraryJob(ctx, payload.LibraryJobID, governance.LibraryJobFailed, "rollback", outcome.Error, - outcome.Rollback, "", "", finishedAt) - return errors.New(outcome.Error) - case "rollback_failed": - _ = store.AdvanceLibraryJob(ctx, payload.LibraryJobID, governance.LibraryJobFailed, "rollback", outcome.Error, - outcome.Rollback, "", "", finishedAt) - return fmt.Errorf("%s(%s)", outcome.Error, outcome.Rollback) - default: - _ = store.AdvanceLibraryJob(ctx, payload.LibraryJobID, governance.LibraryJobFailed, "prebackup", outcome.Error, - "未对生产执行任何写入,无需恢复", "", "", finishedAt) - return errors.New(outcome.Error) - } + return runLibraryRelease(ctx, store, config, job, governance.LibraryJobSync) + } + handlers[libraryRestoreJobType] = func(ctx context.Context, job jobs.Job) error { + return runLibraryRelease(ctx, store, config, job, governance.LibraryJobRestore) } // A crash can leave the source writer stopped: recover before taking work, // and keep the failure visible instead of pretending the worker is ready. diff --git a/internal/governance/library_flow.go b/internal/governance/library_flow.go index ce04fcf..6c0a1ab 100644 --- a/internal/governance/library_flow.go +++ b/internal/governance/library_flow.go @@ -29,6 +29,8 @@ type LibraryJobKind string const ( LibraryJobSeal LibraryJobKind = "seal" LibraryJobSync LibraryJobKind = "sync" + // LibraryJobRestore 是按指定整库版本恢复:与同步分开,授权与阶段也独立。 + LibraryJobRestore LibraryJobKind = "restore" ) type LibraryJobState string diff --git a/internal/httpapi/library_restore.go b/internal/httpapi/library_restore.go new file mode 100644 index 0000000..cac7bd5 --- /dev/null +++ b/internal/httpapi/library_restore.go @@ -0,0 +1,192 @@ +package httpapi + +import ( + "context" + "encoding/json" + "errors" + "net/http" + "strings" + "time" + + "knowledge-governance/internal/governance" + "knowledge-governance/internal/jobs" +) + +// 按指定整库版本恢复:与同步分开的作业类型,需要**单独的管理员授权**, +// 授权摘要绑定"恢复到这个快照"这一件事,不能拿同步授权顶替。 +const libraryRestoreJobType = "library.restore" + +func libraryRestoreParamsDigest(scope, snapshotID string) (string, error) { + return governance.LibraryRequestDigest(scope, governance.LibraryJobRestore, + map[string]any{"restore_snapshot_id": snapshotID}) +} + +type libraryRestoreRequest struct { + Scope string `json:"scope"` + SnapshotID string `json:"snapshot_id"` +} + +func libraryRestoreEnqueue(w http.ResponseWriter, r *http.Request, config Config) { + if r.Method != http.MethodPost { + writeJSON(w, http.StatusMethodNotAllowed, map[string]string{"error": "method not allowed"}) + return + } + identity, ok := sessionFrom(r.Context()) + if !ok || roleRank(identity.Role) < roleRank(roleAdmin) { + writeJSON(w, http.StatusForbidden, map[string]any{"error": "按版本恢复仅管理员可发起"}) + return + } + store, ok := libraryStore(config) + if !ok { + writeJSON(w, http.StatusServiceUnavailable, map[string]any{"code": "library_restore_unavailable"}) + return + } + var request libraryRestoreRequest + if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 4096)).Decode(&request); err != nil { + writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid request body"}) + return + } + if request.Scope != "internal" && request.Scope != "external" { + writeJSON(w, http.StatusBadRequest, map[string]string{"error": "scope must be internal or external"}) + return + } + if strings.TrimSpace(request.SnapshotID) == "" { + writeJSON(w, http.StatusBadRequest, map[string]string{"error": "snapshot_id required"}) + return + } + digest, err := libraryRestoreParamsDigest(request.Scope, request.SnapshotID) + if err != nil { + writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot digest params"}) + return + } + // 双闸与恢复演练证据同样适用于恢复:恢复也是写生产。 + reasons := make([]string, 0, 4) + if !config.ProductionReleaseRequestsEnabled { + reasons = append(reasons, "生产写入闸口关闭") + } + if !config.ProductionBackupRestoreVerified { + reasons = append(reasons, "没有已核验的生产恢复演练证据") + } + authorizationOK := false + if storeWithAuth, ok := config.Store.(interface { + ActiveLibraryAuthorization(ctx context.Context, scope, snapshotID, digest string, now time.Time) (governance.LibraryReleaseAuthorization, bool, error) + }); ok { + _, found, authErr := storeWithAuth.ActiveLibraryAuthorization(r.Context(), request.Scope, request.SnapshotID, digest, time.Now().UTC()) + authorizationOK = authErr == nil && found + } + if !authorizationOK { + reasons = append(reasons, "没有针对该快照的恢复授权") + } + if len(reasons) > 0 { + writeJSON(w, http.StatusServiceUnavailable, map[string]any{"code": "library_restore_blocked", "reasons": reasons}) + return + } + now := time.Now().UTC() + jobID := "librestore-" + request.Scope + "-" + now.Format("20060102T150405.000000") + job, reused, err := store.CreateLibraryJob(r.Context(), governance.LibraryJob{ + ID: jobID, Scope: request.Scope, Kind: governance.LibraryJobRestore, + IdempotencyKey: "library.restore:" + request.Scope + ":" + request.SnapshotID, + RequestDigest: digest, TargetSnapshotID: request.SnapshotID, Actor: identity.Username, + }, governance.SyncStages(), now) + if errors.Is(err, governance.ErrLibraryJobActive) { + writeJSON(w, http.StatusConflict, map[string]any{"code": "library_restore_active", "error": "该目标已有在飞作业"}) + return + } + if errors.Is(err, governance.ErrLibraryJobIdempotencyConflict) { + writeJSON(w, http.StatusConflict, map[string]any{"code": "library_restore_conflict", "error": "同一恢复请求参数不一致"}) + return + } + if err != nil { + writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot create restore job"}) + return + } + if reused { + writeJSON(w, http.StatusAccepted, map[string]any{"job": job, "reused": true}) + return + } + payload, err := json.Marshal(map[string]string{ + "library_job_id": job.ID, "scope": request.Scope, "target_snapshot_id": request.SnapshotID, + }) + if err != nil { + writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot build restore payload"}) + return + } + queueJob, err := config.Store.Enqueue(r.Context(), jobs.EnqueueRequest{ + ID: job.ID + "-queue", Type: libraryRestoreJobType, Payload: payload, AvailableAt: now, + MaxAttempts: 1, IdempotencyKey: "library.restore.queue:" + job.ID, + }, now) + if err != nil || queueJob == nil { + _ = store.CancelLibraryJob(r.Context(), job.ID, "队列投递失败,未开始恢复", now) + writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot enqueue restore job"}) + return + } + if attachErr := store.AttachLibraryQueueJob(r.Context(), job.ID, queueJob.ID, now); attachErr != nil { + writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot attach restore job"}) + return + } + writeJSON(w, http.StatusAccepted, map[string]any{"job": job, "reused": false}) +} + +// 崩溃续作:失败作业可以按原参数重新排队,生成新作业(旧作业保留为审计记录)。 +func libraryJobResume(w http.ResponseWriter, r *http.Request, config Config) { + identity, ok := sessionFrom(r.Context()) + if !ok || roleRank(identity.Role) < roleRank(roleEngineer) { + writeJSON(w, http.StatusForbidden, map[string]any{"error": "续作需要知识工程师及以上权限"}) + return + } + store, ok := libraryStore(config) + if !ok { + writeJSON(w, http.StatusServiceUnavailable, map[string]any{"error": "作业存储不可用"}) + return + } + sourceID := strings.TrimSpace(r.PathValue("id")) + source, err := store.LibraryJob(r.Context(), sourceID) + if err != nil { + writeJSON(w, http.StatusNotFound, map[string]any{"error": "作业不存在"}) + return + } + if source.State != governance.LibraryJobFailed && source.State != governance.LibraryJobCancelled { + writeJSON(w, http.StatusConflict, map[string]any{"error": "只有失败或已取消的作业可以续作"}) + return + } + now := time.Now().UTC() + jobID := sourceID + "-r" + now.Format("150405") + var kind governance.LibraryJobKind + queueType := "" + switch source.Kind { + case governance.LibraryJobSync: + kind, queueType = governance.LibraryJobSync, librarySyncJobType + case governance.LibraryJobRestore: + kind, queueType = governance.LibraryJobRestore, libraryRestoreJobType + default: + writeJSON(w, http.StatusConflict, map[string]any{"error": "封存作业由封存入口重发,不走续作"}) + return + } + digest := source.RequestDigest + job, _, err := store.CreateLibraryJob(r.Context(), governance.LibraryJob{ + ID: jobID, Scope: source.Scope, Kind: kind, + IdempotencyKey: "library.resume:" + sourceID + ":" + now.Format("150405"), + RequestDigest: digest, TargetSnapshotID: source.TargetSnapshotID, Actor: identity.Username, + }, governance.SyncStages(), now) + if errors.Is(err, governance.ErrLibraryJobActive) { + writeJSON(w, http.StatusConflict, map[string]any{"error": "该目标已有在飞作业"}) + return + } + if err != nil { + writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot create resumed job"}) + return + } + payload, _ := json.Marshal(map[string]string{"library_job_id": job.ID, "scope": source.Scope, + "target_snapshot_id": source.TargetSnapshotID}) + queueJob, err := config.Store.Enqueue(r.Context(), jobs.EnqueueRequest{ + ID: job.ID + "-queue", Type: queueType, Payload: payload, AvailableAt: now, + MaxAttempts: 1, IdempotencyKey: "library.resume.queue:" + job.ID, + }, now) + if err != nil || queueJob == nil { + _ = store.CancelLibraryJob(r.Context(), job.ID, "队列投递失败", now) + writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot enqueue resumed job"}) + return + } + _ = store.AttachLibraryQueueJob(r.Context(), job.ID, queueJob.ID, now) + writeJSON(w, http.StatusAccepted, map[string]any{"job": job, "resumed_from": sourceID}) +} diff --git a/internal/httpapi/library_restore_test.go b/internal/httpapi/library_restore_test.go new file mode 100644 index 0000000..838e683 --- /dev/null +++ b/internal/httpapi/library_restore_test.go @@ -0,0 +1,87 @@ +package httpapi + +import ( + "context" + "net/http" + "net/http/httptest" + "strings" + "testing" + "time" + + "knowledge-governance/internal/governance" +) + +func restoreRequest(body, role string) *http.Request { + request := httptest.NewRequest(http.MethodPost, "/api/v1/library/restores", strings.NewReader(body)) + request.Header.Set("Content-Type", "application/json") + ctx := context.WithValue(request.Context(), sessionKey{}, sessionIdentity{Username: "tester", Role: role}) + return request.WithContext(ctx) +} + +// 恢复是写生产:非管理员直接拒绝,任何授权都不会被创建。 +func TestLibraryRestoreRequiresAdmin(t *testing.T) { + store := &fakeLibraryStore{} + recorder := httptest.NewRecorder() + libraryRestoreEnqueue(recorder, restoreRequest(`{"scope":"internal","snapshot_id":"snap-1"}`, roleEngineer), Config{Store: store}) + if recorder.Code != http.StatusForbidden { + t.Fatalf("status=%d body=%s", recorder.Code, recorder.Body.String()) + } + if store.createN != 0 { + t.Fatal("non-admin must not create a restore job") + } +} + +// 闸口关闭 / 缺恢复演练证据 / 缺该快照授权:逐条拒绝且不建作业。 +func TestLibraryRestoreRefusesWithoutGatesAndAuthorization(t *testing.T) { + store := &fakeLibraryStore{} + recorder := httptest.NewRecorder() + libraryRestoreEnqueue(recorder, restoreRequest(`{"scope":"internal","snapshot_id":"snap-1"}`, roleAdmin), Config{Store: store}) + if recorder.Code != http.StatusServiceUnavailable { + t.Fatalf("status=%d body=%s", recorder.Code, recorder.Body.String()) + } + body := recorder.Body.String() + for _, want := range []string{"生产写入闸口关闭", "恢复演练证据", "恢复授权"} { + if !strings.Contains(body, want) { + t.Fatalf("refusal must name %q: %s", want, body) + } + } + if store.createN != 0 { + t.Fatal("must not create a restore job while blocked") + } +} + +// 授权必须绑定"恢复到这个快照":同步授权不能顶替。 +func TestLibraryRestoreRequiresSnapshotBoundGrant(t *testing.T) { + store := &fakeLibraryStore{} + syncDigest, err := librarySyncParamsDigest("internal", "snap-1") + if err != nil { + t.Fatal(err) + } + now := time.Now().UTC() + store.grant = &governance.LibraryReleaseAuthorization{ID: "a", Scope: "internal", SnapshotID: "snap-1", + ParamsDigest: syncDigest, ExpiresAt: now.Add(time.Hour), CreatedAt: now} + config := Config{Store: store, ProductionReleaseRequestsEnabled: true, ProductionBackupRestoreVerified: true} + recorder := httptest.NewRecorder() + libraryRestoreEnqueue(recorder, restoreRequest(`{"scope":"internal","snapshot_id":"snap-1"}`, roleAdmin), config) + if recorder.Code != http.StatusServiceUnavailable || !strings.Contains(recorder.Body.String(), "恢复授权") { + t.Fatalf("sync grant must not authorize a restore: %d %s", recorder.Code, recorder.Body.String()) + } + if store.createN != 0 { + t.Fatal("must not create a restore job with a sync-only grant") + } +} + +// 续作只对失败/取消的同步与恢复作业开放;封存作业走封存入口。 +func TestLibraryJobResumeRejectsNonFailedJobs(t *testing.T) { + store := &fakeLibraryStore{jobs: []governance.LibraryJob{{ID: "job-1", Scope: "internal", + Kind: governance.LibraryJobSync, State: governance.LibraryJobSucceeded}}} + request := httptest.NewRequest(http.MethodPost, "/api/v1/library/jobs/job-1/resume", nil) + request.SetPathValue("id", "job-1") + request = request.WithContext(context.WithValue(request.Context(), sessionKey{}, + sessionIdentity{Username: "eng", Role: roleEngineer})) + recorder := httptest.NewRecorder() + libraryJobResume(recorder, request, Config{Store: store}) + if recorder.Code != http.StatusConflict { + t.Fatalf("status=%d body=%s", recorder.Code, recorder.Body.String()) + } +} diff --git a/internal/httpapi/server.go b/internal/httpapi/server.go index c246f3f..7972df3 100644 --- a/internal/httpapi/server.go +++ b/internal/httpapi/server.go @@ -434,6 +434,14 @@ func NewHandler(config Config) (http.Handler, error) { mux.HandleFunc("POST /api/v1/library/authorizations/{id}/revoke", func(w http.ResponseWriter, r *http.Request) { libraryAuthorizationRevoke(w, r, config) }) + // 按指定整库版本恢复(管理员 + 该快照的恢复授权)。 + mux.HandleFunc("POST /api/v1/library/restores", func(w http.ResponseWriter, r *http.Request) { + libraryRestoreEnqueue(w, r, config) + }) + // 失败/取消作业续作:按原参数重新排队,旧作业保留审计。 + mux.HandleFunc("POST /api/v1/library/jobs/{id}/resume", func(w http.ResponseWriter, r *http.Request) { + libraryJobResume(w, r, config) + }) // 生产同步唯一入口:闸口未齐不建作业,返回缺项而不是假 Accepted。 mux.HandleFunc("POST /api/v1/library/syncs", func(w http.ResponseWriter, r *http.Request) { librarySyncEnqueue(w, r, config) diff --git a/internal/platform/postgres/migrations/000068_library_restore_kind.down.sql b/internal/platform/postgres/migrations/000068_library_restore_kind.down.sql new file mode 100644 index 0000000..7a25464 --- /dev/null +++ b/internal/platform/postgres/migrations/000068_library_restore_kind.down.sql @@ -0,0 +1,3 @@ +DELETE FROM library_jobs WHERE kind='restore'; +ALTER TABLE library_jobs DROP CONSTRAINT IF EXISTS library_jobs_kind_check; +ALTER TABLE library_jobs ADD CONSTRAINT library_jobs_kind_check CHECK (kind IN ('seal','sync')); diff --git a/internal/platform/postgres/migrations/000068_library_restore_kind.up.sql b/internal/platform/postgres/migrations/000068_library_restore_kind.up.sql new file mode 100644 index 0000000..857d2bb --- /dev/null +++ b/internal/platform/postgres/migrations/000068_library_restore_kind.up.sql @@ -0,0 +1,4 @@ +-- 允许"按版本恢复"作为一种独立业务作业:与封存/同步分开,状态不共用。 +ALTER TABLE library_jobs DROP CONSTRAINT IF EXISTS library_jobs_kind_check; +ALTER TABLE library_jobs ADD CONSTRAINT library_jobs_kind_check + CHECK (kind IN ('seal','sync','restore')); diff --git a/internal/platform/postgres/migrations_test.go b/internal/platform/postgres/migrations_test.go index 69160c2..9e9234d 100644 --- a/internal/platform/postgres/migrations_test.go +++ b/internal/platform/postgres/migrations_test.go @@ -11,19 +11,27 @@ func TestEmbeddedMigrationsAreVersionSorted(t *testing.T) { if err != nil { t.Fatalf("loadMigrations() error = %v", err) } - if len(migrations) != 67 { - t.Fatalf("migration count = %d, want 67", len(migrations)) + if len(migrations) != 68 { + t.Fatalf("migration count = %d, want 68", len(migrations)) } - if last := migrations[len(migrations)-1]; last.Version != 67 || + if tail := migrations[len(migrations)-1]; tail.Version != 68 || + !strings.Contains(tail.UpSQL, "restore") { + t.Fatalf("migration 68 = %#v", tail) + } + if last := migrations[len(migrations)-2]; last.Version != 67 || !strings.Contains(last.UpSQL, "library_release_authorizations") || !strings.Contains(last.UpSQL, "params_digest") { t.Fatalf("migration 67 = %#v", last) } - if prev := migrations[len(migrations)-2]; prev.Version != 66 || + if prev := migrations[len(migrations)-3]; prev.Version != 66 || !strings.Contains(prev.UpSQL, "CREATE TABLE library_versions") || !strings.Contains(prev.UpSQL, "library_jobs_active") { t.Fatalf("migration 66 = %#v", prev) } + if auth := migrations[len(migrations)-2]; auth.Version != 67 || + !strings.Contains(auth.UpSQL, "library_release_authorizations") { + t.Fatalf("migration 67 = %#v", auth) + } if migrations[0].Version != 1 || !strings.Contains(migrations[0].UpSQL, "CREATE TABLE IF NOT EXISTS jobs") { t.Fatalf("migration 1 = %#v", migrations[0]) }