Files
knowledge-governance/internal/httpapi/production_bindings.go
T
姚章浩 5e1482e349
build / build (push) Successful in 1m40s
feat(library): 恢复验证成为可页面发起的真实作业
根因:生产可恢复性只有 PRODUCTION_BACKUP_RESTORE_VERIFIED 这个手填 env 开关,
页面没有任何入口去真跑一次恢复;CLI(librarydrill)又不是 worker 能复用的实现,
所以"已验证"既证明不了跑过、也证明不了跑的是当前目标。

改动:
- 共享实现 internal/libraryverify(维护隔离→捕获→基线校验→canary→恢复→复核→关窗口),
  cmd/librarydrill 改为薄封装,CLI 与 worker 只允许一份执行体。
- verify 成为独立业务作业:kind + VerifyStages(capture/verify/canary/restore/finalize),
  与 sync/restore/baseline 共用同一把写互斥;迁移 79 加 kind 约束、重建部分唯一索引、
  新建 library_restore_verifications(按 target_id 绑定,换库/索引/桶旧证据自动失效,
  同 target+scope+job 幂等)。
- worker:admitLibraryJob + runOwnedLibraryAttempt 之后调用共享实现,阶段实时写
  library_job_stages,结束后写真实终态;通过写 passed 证据,失败写 failed+原因(不伪成功);
  中断接管按同一作业 id 收掉维护窗口。
- API:POST/GET /api/v1/library/verifications(管理员;闸口关闭/维护中拒绝;返回完整
  整库目标、最近证据、失败原因),OpenAPI 同步。
- 闸口:同步/恢复/续作的证据判断改为读当前目标证据;历史 env 仅在证据缺失时兜底,
  证据存在时以证据为准。
- 页面:生产保护与恢复面板加「恢复验证」块(完整 KB/索引/桶、状态、最近证据、失败原因、
  管理员按钮、5s 轮询),作业类型补 verify 文案。

测试:make verify 16/16 全绿(go 1387 例 + web 454 例 + 契约/迁移/密钥/依赖锁定);
新增用例覆盖证据四条件、闸口证据优先、页面无证据/失败/通过三种呈现与管理员可见性。
2026-11-03 10:14:08 +08:00

223 lines
9.4 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
package httpapi
import (
"context"
"net/http"
"strings"
"time"
"knowledge-governance/internal/pgdsn"
"knowledge-governance/internal/platform/weknora"
)
// ProductionBindingStore persists the UI-managed 源库 → 目标库 mapping
// (migration 000044). An empty side means "unbound": the release then keeps the
// historical same-id semantics and fails closed at the contract check when no
// such base exists on the target.
type ProductionBindingStore interface {
LoadProductionKBBindings(context.Context) (string, string, string, error)
SaveProductionKBBindings(ctx context.Context, internalID, externalID, updatedBy string, now time.Time) error
}
// ProductionKnowledgeBaseLister enumerates the knowledge bases of the production
// WeKnora, resolved from the operator-managed service configuration.
type ProductionKnowledgeBaseLister interface {
ListProductionKnowledgeBases(ctx context.Context, baseURL string) ([]weknora.KnowledgeBase, error)
}
type productionBindingView struct {
InternalKBID string `json:"internal_kb_id"`
ExternalKBID string `json:"external_kb_id"`
InternalKBName string `json:"internal_kb_name"`
ExternalKBName string `json:"external_kb_name"`
UpdatedBy string `json:"updated_by"`
ProductionBaseURL string `json:"production_base_url"`
ProductionConnected bool `json:"production_connected"`
ProductionMessage string `json:"production_message"`
// LegacyScope 说明这条记录属于哪条发布路径。整库发布(封存/同步/恢复)不读它,
// 只读下面的 WholeTarget;页面必须把两者分开写,否则会把旧文档级目标当成整库目标。
LegacyScope string `json:"legacy_scope"`
// WholeTarget 是整库发布真正写入的目标(来自部署环境 LIBRARY_PRODUCTION_*),
// 与上面可编辑的文档级绑定是两条独立路径。
WholeTarget libraryPublishTargetView `json:"whole_target"`
}
// libraryPublishTargetView 是"整库发布到底写哪儿"的只读投影。
// 为什么由后端给出:页面上的 kb 名称/文档数来自生产端列表接口,而整库写入用的是
// 另一组环境配置;让页面自己拼会把两条路径混成一个。
type libraryPublishTargetView struct {
Configured bool `json:"configured"`
Source string `json:"source"`
TenantID uint64 `json:"tenant_id"`
InternalKBID string `json:"internal_kb_id"`
ExternalKBID string `json:"external_kb_id"`
Database string `json:"database"`
ElasticIndex string `json:"elastic_index"`
ObjectBucket string `json:"object_bucket"`
MissingReason string `json:"missing_reason"`
}
// libraryPublishTarget 从 config 派生整库目标;缺项照实说缺哪一项,不猜默认值。
func (config Config) libraryPublishTarget() libraryPublishTargetView {
view := libraryPublishTargetView{
Source: "部署环境 LIBRARY_PRODUCTION_*",
TenantID: config.LibraryProductionTenantID,
InternalKBID: config.LibraryProductionInternalKB,
ExternalKBID: config.LibraryProductionExternalKB,
Database: pgdsn.Endpoint(config.LibraryProductionDatabaseURL),
ElasticIndex: config.LibraryProductionIndex,
ObjectBucket: config.LibraryProductionS3Bucket,
}
missing := make([]string, 0, 4)
if config.LibraryProductionDatabaseURL == "" {
missing = append(missing, "LIBRARY_PRODUCTION_DATABASE_URL")
}
if view.InternalKBID == "" {
missing = append(missing, "LIBRARY_PRODUCTION_KB_INTERNAL")
}
if config.LibraryProductionIndex == "" {
missing = append(missing, "LIBRARY_PRODUCTION_INDEX")
}
view.Configured = len(missing) == 0
if len(missing) > 0 {
view.MissingReason = "未配置:" + strings.Join(missing, "、")
}
return view
}
// productionTargetBaseURL is the production endpoint the picker reads from: the
// operator-managed 「服务配置 · 生产地址」 first, the deployment default second.
func (config Config) productionTargetBaseURL(ctx context.Context) string {
if settings, err := config.Store.GetActiveUISettings(ctx); err == nil {
if resolved := strings.TrimSpace(settings.ProductionWeKnoraBaseURL); resolved != "" {
return resolved
}
}
return strings.TrimSpace(config.ProductionWeKnoraBaseURL)
}
// productionKnowledgeBases lists the production-side bases. The second return is
// the honest reason a listing was impossible, so the page can say why instead of
// pretending there are none.
func (config Config) productionKnowledgeBases(ctx context.Context) ([]weknora.KnowledgeBase, string) {
if config.ProductionKnowledgeBases == nil {
return nil, "生产知识库列表未接入(PRODUCTION_WEKNORA_BASE_URL / PRODUCTION_WEKNORA_API_KEY_FILE)"
}
baseURL := config.productionTargetBaseURL(ctx)
if baseURL == "" {
return nil, "未配置生产地址(系统设置 → 服务配置)"
}
bases, err := config.ProductionKnowledgeBases.ListProductionKnowledgeBases(ctx, baseURL)
if err != nil {
return nil, "生产 WeKnora 不可用:" + err.Error()
}
return bases, ""
}
func (config Config) productionBindingPayload(ctx context.Context) (productionBindingView, error) {
storedInternal, storedExternal, updatedBy, err := config.ProductionBindings.LoadProductionKBBindings(ctx)
if err != nil {
return productionBindingView{}, err
}
bases, message := config.productionKnowledgeBases(ctx)
names := make(map[string]string, len(bases))
for _, base := range bases {
names[base.ID] = base.Name
}
return productionBindingView{
InternalKBID: storedInternal, ExternalKBID: storedExternal,
InternalKBName: names[storedInternal], ExternalKBName: names[storedExternal],
UpdatedBy: updatedBy, ProductionBaseURL: config.productionTargetBaseURL(ctx),
ProductionConnected: message == "", ProductionMessage: message,
// 这张表服务的是"文档级发布"(单篇文档写生产)。整库发布读的是部署环境
// LIBRARY_PRODUCTION_*,两者不能互相顶替,所以页面必须分开显示。
LegacyScope: "文档级发布(单篇文档写生产)· 旧路径",
WholeTarget: config.libraryPublishTarget(),
}, nil
}
func (config Config) handleProductionBindings(w http.ResponseWriter, r *http.Request) {
if config.ProductionBindings == nil {
writeJSON(w, http.StatusServiceUnavailable, map[string]string{"error": "production bindings are not configured"})
return
}
view, err := config.productionBindingPayload(r.Context())
if err != nil {
writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "could not load production bindings"})
return
}
writeJSON(w, http.StatusOK, map[string]any{"data": view})
}
func (config Config) handleProductionKnowledgeBaseOptions(w http.ResponseWriter, r *http.Request) {
bases, message := config.productionKnowledgeBases(r.Context())
if message != "" {
writeJSON(w, http.StatusBadGateway, map[string]string{"error": message})
return
}
options := make([]routingKnowledgeBaseOption, 0, len(bases))
for _, base := range bases {
options = append(options, routingKnowledgeBaseOption{ID: base.ID, Name: base.Name, KnowledgeCount: base.KnowledgeCount})
}
writeJSON(w, http.StatusOK, map[string]any{"data": options})
}
// handleSaveProductionBindings stores the 源库 → 目标库 mapping. When the
// production endpoint answers, the chosen base must exist there; when it cannot
// be asked, the save still succeeds but the response says so honestly (a jittery
// production endpoint must not block the operator, a wrong ID must).
func (config Config) handleSaveProductionBindings(w http.ResponseWriter, r *http.Request) {
if config.ProductionBindings == nil {
writeJSON(w, http.StatusServiceUnavailable, map[string]string{"error": "production bindings are not configured"})
return
}
var input struct {
InternalKBID string `json:"internal_kb_id"`
ExternalKBID string `json:"external_kb_id"`
}
if err := decodeStrictJSON(r, &input); err != nil {
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid request body"})
return
}
internal := strings.TrimSpace(input.InternalKBID)
external := strings.TrimSpace(input.ExternalKBID)
for _, id := range []string{internal, external} {
if id != "" && !validCatalogID(id) {
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "knowledge base ID is invalid"})
return
}
}
if internal != "" && internal == external {
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "对内与对外必须绑定不同的生产知识库"})
return
}
if bases, message := config.productionKnowledgeBases(r.Context()); message == "" {
names := make(map[string]string, len(bases))
for _, base := range bases {
names[base.ID] = base.Name
}
if internal != "" {
if _, ok := names[internal]; !ok {
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "对内绑定的生产知识库在该 WeKnora 实例中不存在"})
return
}
}
if external != "" {
if _, ok := names[external]; !ok {
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "对外绑定的生产知识库在该 WeKnora 实例中不存在"})
return
}
}
}
if err := config.ProductionBindings.SaveProductionKBBindings(r.Context(), internal, external, actorFor(r), config.Now().UTC()); err != nil {
writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "could not save production bindings"})
return
}
view, err := config.productionBindingPayload(r.Context())
if err != nil {
writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "could not load production bindings"})
return
}
writeJSON(w, http.StatusOK, map[string]any{"data": view})
}