Files
knowledge-governance/internal/serviceverify/verifier.go
T
姚章浩 1db21fb899 feat(settings): 服务配置四项化并保存时真校验
- 生产/测试 WeKnora 地址、租户 ID、知识库 ID 由静态 env 收敛为版本化 UI 设置,保留修订号与操作人审计
- 新增 serviceverify:保存前真调目标端点探测,端点无效才拒绝;网络抖动或无凭据仅告警
- 迁移 000042(生产 WeKnora 端点)/000043(服务目标);补齐设置候选与校验契约用例
2026-09-30 10:54:07 +08:00

347 lines
14 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 serviceverify performs the real read behind 「服务配置」: the configured
// production endpoint is asked whether the saved knowledge base id exists and
// whether it really belongs to the saved production tenant. Two numbers stored in
// the database with nobody consuming them are decoration; this is the consumer.
//
// Blocking policy: only a definitive negative answer (HTTP 404/400 on the
// knowledge base, or a tenant that provably differs) rejects a save. Timeouts,
// 5xx, 401/403, a missing key file or a missing endpoint are reported as
// 「未核验」and let the save through — an operator must always be able to repair a
// broken configuration.
package serviceverify
import (
"context"
"errors"
"fmt"
"io"
"net/http"
"net/url"
"strconv"
"strings"
"time"
"knowledge-governance/internal/governance"
"knowledge-governance/internal/platform/weknora"
)
const (
defaultTimeout = 10 * time.Second
maxListedCandidates = 5
)
// Config wires the verifier to the same credential files the rest of the platform
// uses. Credentials stay file references (never values) and are read per call, so
// rotating a key file needs no restart.
type Config struct {
TestAPIKeyFile string
ProductionAPIKeyFile string
TestBaseURLFallback string
ProductionBaseURLFallback string
TestAllowDockerHTTP bool
ProductionAllowDockerHTTP bool
Timeout time.Duration
Now func() time.Time
}
// Verifier asks endpoints what they really hold. It is safe for concurrent use.
type Verifier struct {
config Config
httpClient *http.Client
}
func New(config Config) *Verifier {
if config.Timeout <= 0 {
config.Timeout = defaultTimeout
}
if config.Now == nil {
config.Now = time.Now
}
return &Verifier{
config: config,
httpClient: &http.Client{
Timeout: config.Timeout,
CheckRedirect: func(*http.Request, []*http.Request) error {
return http.ErrUseLastResponse
},
},
}
}
// VerifyServiceTarget probes both endpoints and, when it has a credential to ask
// with, checks the production knowledge base and tenant for real.
func (verifier *Verifier) VerifyServiceTarget(ctx context.Context, target governance.ServiceTarget) governance.ServiceTargetVerification {
productionBaseURL := firstNonEmpty(target.ProductionBaseURL, verifier.config.ProductionBaseURLFallback)
testBaseURL := firstNonEmpty(target.TestBaseURL, verifier.config.TestBaseURLFallback)
productionKey := verifier.apiKey(verifier.config.ProductionAPIKeyFile)
testKey := verifier.apiKey(verifier.config.TestAPIKeyFile)
verification := governance.ServiceTargetVerification{
Status: governance.ServiceTargetNotConfigured,
Message: "未配置:两项 ID 都留空,没有可核验的值",
TestEndpoint: verifier.probeEndpoint(ctx, testBaseURL, testKey, "测试地址", verifier.config.TestAllowDockerHTTP),
ProductionEndpoint: verifier.probeEndpoint(ctx, productionBaseURL, productionKey, "生产地址", verifier.config.ProductionAllowDockerHTTP),
CheckedAt: verifier.config.Now().UTC(),
}
if target.ProductionKnowledgeBaseID == "" && target.ProductionTenantID == "" {
return verification
}
if productionBaseURL == "" {
verification.Status = governance.ServiceTargetCannotVerify
verification.Message = "未核验:还没有生产地址可查,保存未被阻断"
return verification
}
if productionKey == "" {
verification.Status = governance.ServiceTargetCannotVerify
verification.Message = "未核验:没有可用的生产 API Key 文件(PRODUCTION_WEKNORA_API_KEY_FILE),保存未被阻断"
return verification
}
client, err := verifier.client(productionBaseURL, productionKey, verifier.config.ProductionAllowDockerHTTP)
if err != nil {
verification.Status = governance.ServiceTargetCannotVerify
verification.Message = "未核验:生产地址不能作为 WeKnora 端点(" + err.Error() + "),保存未被阻断"
return verification
}
if target.ProductionKnowledgeBaseID == "" {
return verifier.verifyTenantOnly(ctx, client, target, verification)
}
return verifier.verifyKnowledgeBase(ctx, client, target, verification)
}
// verifyKnowledgeBase is the strong check: the knowledge base must exist on the
// configured production endpoint, and (when a production ID is filled) its tenant
// must be that ID.
func (verifier *Verifier) verifyKnowledgeBase(ctx context.Context, client *weknora.Client, target governance.ServiceTarget, verification governance.ServiceTargetVerification) governance.ServiceTargetVerification {
base, err := client.GetKnowledgeBase(ctx, target.ProductionKnowledgeBaseID)
switch {
case err == nil:
observed := strconv.FormatUint(base.TenantID, 10)
name := base.Name
if name == "" {
name = base.ID
}
verification.KnowledgeBaseName = base.Name
verification.ObservedTenantID = observed
if target.ProductionTenantID != "" && target.ProductionTenantID != observed {
verification.Status = governance.ServiceTargetTenantMismatch
verification.Blocked = true
verification.Message = fmt.Sprintf("未通过:知识库「%s」属于租户 %s,与你填的生产 ID %s 不一致", name, observed, target.ProductionTenantID)
return verification
}
verification.Status = governance.ServiceTargetVerified
if target.ProductionTenantID == "" {
verification.Message = fmt.Sprintf("已核验:生产地址上存在知识库「%s」(租户 %s;未填生产 ID,没有比对租户)", name, observed)
return verification
}
verification.Message = fmt.Sprintf("已核验:生产地址上存在知识库「%s」,租户 %s 一致", name, observed)
return verification
case isStatus(err, http.StatusNotFound, http.StatusBadRequest):
verification.Status = governance.ServiceTargetMissing
verification.Blocked = true
verification.Message = fmt.Sprintf("未通过:生产地址上找不到知识库 ID「%s」%s", target.ProductionKnowledgeBaseID, verifier.candidateSuffix(ctx, client))
return verification
case isStatus(err, http.StatusUnauthorized, http.StatusForbidden):
verification.Status = governance.ServiceTargetUnauthorized
verification.Message = fmt.Sprintf("未核验:生产端点拒绝了这个 API Key(%s),保存未被阻断", describe(err))
return verification
default:
verification.Status = governance.ServiceTargetUnreachable
verification.Message = fmt.Sprintf("未核验:生产端点暂时不可用(%s),保存未被阻断", describe(err))
return verification
}
}
// verifyTenantOnly runs when only the production ID is filled: the tenant must own
// at least one knowledge base on the configured endpoint.
func (verifier *Verifier) verifyTenantOnly(ctx context.Context, client *weknora.Client, target governance.ServiceTarget, verification governance.ServiceTargetVerification) governance.ServiceTargetVerification {
tenant, err := strconv.ParseUint(target.ProductionTenantID, 10, 64)
if err != nil || tenant == 0 {
verification.Status = governance.ServiceTargetCannotVerify
verification.Message = "未核验:生产 ID 不是十进制租户号,没有可查的值"
return verification
}
bases, err := client.ListKnowledgeBases(ctx)
switch {
case err == nil:
owned, tenants := 0, []string{}
for _, base := range bases {
observed := strconv.FormatUint(base.TenantID, 10)
if base.TenantID == tenant {
owned++
}
if !contains(tenants, observed) {
tenants = append(tenants, observed)
}
}
if owned > 0 {
verification.Status = governance.ServiceTargetVerified
verification.ObservedTenantID = strconv.FormatUint(tenant, 10)
verification.Message = fmt.Sprintf("已核验:生产地址上有 %d 个知识库属于租户 %s", owned, target.ProductionTenantID)
return verification
}
verification.Status = governance.ServiceTargetMissing
verification.Blocked = true
verification.Message = fmt.Sprintf("未通过:生产地址上没有属于租户 %s 的知识库(该地址现有租户:%s)", target.ProductionTenantID, strings.Join(tenants, "、"))
return verification
case isStatus(err, http.StatusUnauthorized, http.StatusForbidden):
verification.Status = governance.ServiceTargetUnauthorized
verification.Message = fmt.Sprintf("未核验:生产端点拒绝了这个 API Key(%s),保存未被阻断", describe(err))
return verification
default:
verification.Status = governance.ServiceTargetUnreachable
verification.Message = fmt.Sprintf("未核验:生产端点暂时不可用(%s),保存未被阻断", describe(err))
return verification
}
}
// probeEndpoint reads the endpoint: a real knowledge-base list when a credential
// is available, otherwise a plain /health liveness call. Advisory — the caller
// only reports it.
func (verifier *Verifier) probeEndpoint(ctx context.Context, baseURL, apiKey, label string, allowDockerHTTP bool) governance.ServiceEndpointStatus {
if strings.TrimSpace(baseURL) == "" {
return governance.ServiceEndpointStatus{Status: governance.ServiceEndpointNotConfigured, Message: label + "未配置"}
}
if apiKey != "" {
if client, err := verifier.client(baseURL, apiKey, allowDockerHTTP); err == nil {
bases, listErr := client.ListKnowledgeBases(ctx)
switch {
case listErr == nil:
return governance.ServiceEndpointStatus{Status: governance.ServiceEndpointReachable, Message: fmt.Sprintf("%s可达(凭据有效,可列出 %d 个知识库)", label, len(bases))}
case isStatus(listErr, http.StatusUnauthorized, http.StatusForbidden):
return governance.ServiceEndpointStatus{Status: governance.ServiceEndpointUnauthorized, Message: fmt.Sprintf("%s拒绝了这个 API Key(%s)", label, describe(listErr))}
case !isStatus(listErr, http.StatusNotFound):
return governance.ServiceEndpointStatus{Status: governance.ServiceEndpointUnavailable, Message: fmt.Sprintf("%s不可用(%s)", label, describe(listErr))}
}
}
}
code, err := verifier.healthCode(ctx, baseURL)
switch {
case err != nil:
return governance.ServiceEndpointStatus{Status: governance.ServiceEndpointUnavailable, Message: fmt.Sprintf("%s不可达(%s)", label, describe(err))}
case code == http.StatusUnauthorized || code == http.StatusForbidden:
return governance.ServiceEndpointStatus{Status: governance.ServiceEndpointUnauthorized, Message: fmt.Sprintf("%s活着,但未带凭据的探活被拒(HTTP %d)", label, code)}
case code >= 200 && code < 300:
return governance.ServiceEndpointStatus{Status: governance.ServiceEndpointReachable, Message: fmt.Sprintf("%s /health 返回 HTTP %d", label, code)}
default:
return governance.ServiceEndpointStatus{Status: governance.ServiceEndpointUnavailable, Message: fmt.Sprintf("%s /health 返回 HTTP %d", label, code)}
}
}
func (verifier *Verifier) healthCode(ctx context.Context, baseURL string) (int, error) {
parsed, err := url.Parse(baseURL)
if err != nil || parsed.Host == "" || (parsed.Scheme != "http" && parsed.Scheme != "https") {
return 0, errors.New("endpoint is not an http(s) origin")
}
parsed.Path = strings.TrimSuffix(parsed.Path, "/") + "/health"
parsed.RawQuery, parsed.Fragment = "", ""
request, err := http.NewRequestWithContext(ctx, http.MethodGet, parsed.String(), nil)
if err != nil {
return 0, err
}
response, err := verifier.httpClient.Do(request)
if err != nil {
return 0, err
}
defer response.Body.Close()
_, _ = io.Copy(io.Discard, io.LimitReader(response.Body, 4096))
return response.StatusCode, nil
}
// candidateSuffix names what the endpoint actually holds, so a rejected save is
// fixable without a second trip to the WeKnora console.
func (verifier *Verifier) candidateSuffix(ctx context.Context, client *weknora.Client) string {
bases, err := client.ListKnowledgeBases(ctx)
if err != nil || len(bases) == 0 {
return ""
}
listed := make([]string, 0, maxListedCandidates)
for index, base := range bases {
if index == maxListedCandidates {
break
}
name := base.Name
if name == "" {
name = "无名"
}
listed = append(listed, name+"("+base.ID+")")
}
if len(bases) > len(listed) {
return fmt.Sprintf(";该地址现有 %d 个知识库,前 %d 个:%s", len(bases), len(listed), strings.Join(listed, "、"))
}
return fmt.Sprintf(";该地址现有 %d 个知识库:%s", len(bases), strings.Join(listed, "、"))
}
func (verifier *Verifier) client(baseURL, apiKey string, allowDockerHTTP bool) (*weknora.Client, error) {
return weknora.NewClient(weknora.ClientConfig{
BaseURL: baseURL,
APIKey: apiKey,
Timeout: verifier.config.Timeout,
AllowDockerHTTP: allowDockerHTTP,
})
}
// apiKey reads a credential file reference. An unset, unreadable or empty file is
// not an error here: it means "no credential to ask with" and is reported as
// 未核验 rather than failing the save.
func (verifier *Verifier) apiKey(path string) string {
path = strings.TrimSpace(path)
if path == "" || !strings.HasPrefix(path, "/") {
return ""
}
key, err := weknora.ReadAPIKeyFile(path)
if err != nil {
return ""
}
return key
}
func isStatus(err error, statuses ...int) bool {
var httpErr *weknora.HTTPError
if !errors.As(err, &httpErr) {
return false
}
for _, status := range statuses {
if httpErr.StatusCode == status {
return true
}
}
return false
}
// describe keeps a failed request readable without leaking internals: the class of
// failure and the HTTP status, nothing else.
func describe(err error) string {
var httpErr *weknora.HTTPError
if errors.As(err, &httpErr) {
return fmt.Sprintf("HTTP %d", httpErr.StatusCode)
}
switch {
case errors.Is(err, context.DeadlineExceeded):
return "超时"
case errors.Is(err, context.Canceled):
return "请求被取消"
case weknora.IsRetryable(err):
return "网络错误"
default:
return "请求失败"
}
}
func firstNonEmpty(values ...string) string {
for _, value := range values {
if trimmed := strings.TrimSpace(value); trimmed != "" {
return trimmed
}
}
return ""
}
func contains(values []string, wanted string) bool {
for _, value := range values {
if value == wanted {
return true
}
}
return false
}