package handler import ( "context" "encoding/json" "errors" "fmt" "net" "net/http" "net/url" "os" "regexp" "strconv" "strings" "time" "unicode/utf8" "github.com/Tencent/WeKnora/internal/application/repository" "github.com/Tencent/WeKnora/internal/application/service" "github.com/Tencent/WeKnora/internal/application/service/file" "github.com/Tencent/WeKnora/internal/config" "github.com/Tencent/WeKnora/internal/database" apperrors "github.com/Tencent/WeKnora/internal/errors" "github.com/Tencent/WeKnora/internal/infrastructure/docparser" "github.com/Tencent/WeKnora/internal/logger" modellimiter "github.com/Tencent/WeKnora/internal/models/limiter" "github.com/Tencent/WeKnora/internal/runtime" "github.com/Tencent/WeKnora/internal/types" "github.com/Tencent/WeKnora/internal/types/interfaces" secutils "github.com/Tencent/WeKnora/internal/utils" "github.com/gin-gonic/gin" "github.com/neo4j/neo4j-go-driver/v6/neo4j" ) type runtimeKnowledgeCanceller interface { CancelKnowledgeParse(ctx context.Context, knowledgeID string) (*types.Knowledge, error) } // SystemHandler handles system-related requests type SystemHandler struct { cfg *config.Config neo4jDriver neo4j.Driver documentReader interfaces.DocumentReader tenantSvc interfaces.TenantService userSvc interfaces.UserService systemSettingSvc interfaces.SystemSettingService apiKeySvc interfaces.TenantAPIKeyService // auditSvc is optional — when nil, emitAdminAudit no-ops so unit // tests that wire a partial container still compile. In production // the dig graph always provides one. auditSvc interfaces.AuditLogService // taskInspector backs the SystemAdmin runtime queue dashboard. Always // provided by the container (asynq-backed in Redis mode, a no-op in // Lite mode), so GetRuntimeQueues can distinguish "no queues in this // deployment" from "queues are empty". taskInspector interfaces.TaskInspector // knowledgeSvc supplies the domain-level cancellation path used by the // runtime task console. It updates business state and tracing before queue // records are removed, unlike a raw Redis deletion. knowledgeSvc runtimeKnowledgeCanceller // storageBackendRepo lets GetStorageEngineStatus report multi-instance // storage backends (Settings → Storage) as "available", not just the legacy // singleton tenant.StorageEngineConfig. Optional — nil in partially-wired // unit tests, in which case only the legacy config is consulted. storageBackendRepo interfaces.StorageBackendRepository sandboxConfigSvc sandboxConfigService // startup snapshot for GET /system/capabilities; bound in router.NewRouter. deploymentCapabilities DeploymentCapabilitiesData } // NewSystemHandler creates a new system handler func NewSystemHandler(cfg *config.Config, neo4jDriver neo4j.Driver, documentReader interfaces.DocumentReader, tenantSvc interfaces.TenantService, userSvc interfaces.UserService, systemSettingSvc interfaces.SystemSettingService, apiKeySvc interfaces.TenantAPIKeyService, auditSvc interfaces.AuditLogService, taskInspector interfaces.TaskInspector, knowledgeSvc interfaces.KnowledgeService, storageBackendRepo interfaces.StorageBackendRepository, sandboxConfigSvc *service.TenantSandboxConfigService, ) *SystemHandler { return &SystemHandler{ cfg: cfg, neo4jDriver: neo4jDriver, documentReader: documentReader, tenantSvc: tenantSvc, userSvc: userSvc, systemSettingSvc: systemSettingSvc, apiKeySvc: apiKeySvc, auditSvc: auditSvc, taskInspector: taskInspector, knowledgeSvc: knowledgeSvc, storageBackendRepo: storageBackendRepo, sandboxConfigSvc: sandboxConfigSvc, } } type platformAPIKeyCreateRequest struct { Name string `json:"name"` Capabilities []string `json:"capabilities"` ExpiresAt *int64 `json:"expires_at_unix"` } // ListPlatformAPIKeys godoc // @Summary List platform API keys // @Description Lists non-workspace API keys. Full tokens are always masked. Human SystemAdmin only. // @Tags System Admin // @Produce json // @Success 200 {object} map[string]interface{} // @Security Bearer // @Router /system/admin/api-keys [get] func (h *SystemHandler) ListPlatformAPIKeys(c *gin.Context) { keys, err := h.apiKeySvc.ListPlatformAPIKeys(c.Request.Context()) if err != nil { c.Error(apperrors.NewInternalServerError("Failed to list platform API keys").WithDetails(err.Error())) return } response := make([]tenantAPIKeyResponse, 0, len(keys)) for _, key := range keys { item := tenantAPIKeyForResponse(key) item.APIKey = maskManagedAPIKey(key.APIKey) response = append(response, item) } c.JSON(http.StatusOK, gin.H{"success": true, "data": response}) } // CreatePlatformAPIKey godoc // @Summary Create a platform API key // @Description Creates a capability-scoped key that may target any workspace through X-Tenant-ID. The plaintext token is returned once. Human SystemAdmin only. // @Tags System Admin // @Accept json // @Produce json // @Param request body platformAPIKeyCreateRequest true "Platform API key" // @Success 201 {object} map[string]interface{} // @Security Bearer // @Router /system/admin/api-keys [post] func (h *SystemHandler) CreatePlatformAPIKey(c *gin.Context) { var req platformAPIKeyCreateRequest if err := c.ShouldBindJSON(&req); err != nil { c.Error(apperrors.NewValidationError("Invalid request data").WithDetails(err.Error())) return } if strings.TrimSpace(req.Name) == "" { c.Error(apperrors.NewValidationError("name is required")) return } capabilities := types.NormalizeAPIKeyCapabilities(types.StringArray(req.Capabilities)) if len(capabilities) == 0 || len(capabilities) != len(req.Capabilities) { c.Error(apperrors.NewValidationError("valid capabilities are required")) return } var expiresAt *time.Time if req.ExpiresAt != nil { value := time.Unix(*req.ExpiresAt, 0).UTC() if !value.After(time.Now().UTC()) { c.Error(apperrors.NewValidationError("expires_at_unix must be in the future")) return } expiresAt = &value } result, err := h.apiKeySvc.CreateAPIKey(c.Request.Context(), interfaces.TenantAPIKeyCreateRequest{ ScopeType: types.APIKeyScopePlatform, Name: req.Name, Capabilities: []string(capabilities), ExpiresAt: expiresAt, }) if err != nil { c.Error(apperrors.NewInternalServerError("Failed to create platform API key").WithDetails(err.Error())) return } item := tenantAPIKeyForResponse(result.APIKey) item.APIKey = maskManagedAPIKey(result.Token) h.emitAPIKeyAudit(c.Request.Context(), types.AuditActionSystemAPIKeyCreated, result.APIKey) c.JSON(http.StatusCreated, gin.H{ "success": true, "data": tenantAPIKeyCreateResponse{tenantAPIKeyResponse: item, Token: result.Token}, }) } // DeletePlatformAPIKey godoc // @Summary Revoke a platform API key // @Description Immediately revokes a platform API key. Human SystemAdmin only. // @Tags System Admin // @Produce json // @Param key_id path int true "API key ID" // @Success 200 {object} map[string]interface{} // @Security Bearer // @Router /system/admin/api-keys/{key_id} [delete] func (h *SystemHandler) DeletePlatformAPIKey(c *gin.Context) { id, err := strconv.ParseUint(c.Param("key_id"), 10, 64) if err != nil || id == 0 { c.Error(apperrors.NewBadRequestError("Invalid API key ID")) return } if err := h.apiKeySvc.RevokePlatformAPIKey(c.Request.Context(), id); err != nil { c.Error(apperrors.NewNotFoundError("Platform API key not found")) return } h.emitAPIKeyAudit(c.Request.Context(), types.AuditActionSystemAPIKeyRevoked, &types.TenantAPIKey{ID: id}) c.JSON(http.StatusOK, gin.H{"success": true}) } func maskManagedAPIKey(token string) string { token = strings.TrimSpace(token) if len(token) <= 12 { return "***" } return token[:7] + "..." + token[len(token)-4:] } func (h *SystemHandler) emitAPIKeyAudit(ctx context.Context, action types.AuditAction, key *types.TenantAPIKey) { if h.auditSvc == nil || key == nil { return } actorID, _ := types.UserIDFromContext(ctx) details, _ := json.Marshal(map[string]any{ "scope_type": types.APIKeyScopePlatform, "capabilities": key.Capabilities, }) _ = h.auditSvc.Log(ctx, &types.AuditLog{ TenantID: 0, ActorUserID: actorID, ActorRole: systemAuditActorRole(ctx), Action: action, TargetType: "api_key", TargetID: strconv.FormatUint(key.ID, 10), Outcome: types.AuditOutcomeSuccess, Details: types.JSON(details), }) } func systemAuditActorRole(ctx context.Context) string { if scope, ok := types.TenantAPIKeyScopeFromContext(ctx); ok && scope.IsPlatform() { return "platform_api_key" } return "system_admin" } // emitAdminAudit writes one audit row for a system-admin lifecycle event // (promote / revoke). Best-effort — a nil audit service or a write // failure does not bubble up to the caller. Mirrors the failure // semantics of tenantMemberService.emitAudit and the system settings // audit hook. // // `details` may be nil; the JSON `{}` default applies. func (h *SystemHandler) emitAdminAudit( ctx context.Context, action types.AuditAction, target *types.User, details map[string]any, ) { if h.auditSvc == nil { return } actorID, _ := types.UserIDFromContext(ctx) var detailsJSON types.JSON if details != nil { if b, err := json.Marshal(details); err == nil { detailsJSON = types.JSON(b) } } entry := &types.AuditLog{ // tenant_id=0 marks the row as system-scope. The audit_logs // table is tenant-scoped; 0 is the convention for platform-wide // events (matches AuditActionSystemSettingChanged). TenantID: 0, ActorUserID: actorID, ActorRole: systemAuditActorRole(ctx), Action: action, TargetType: "user", Outcome: types.AuditOutcomeSuccess, Details: detailsJSON, } if target != nil { entry.TargetID = target.ID entry.TargetUserID = target.ID } _ = h.auditSvc.Log(ctx, entry) } // GetSystemInfoResponse defines the response structure for system info type GetSystemInfoResponse struct { Version string `json:"version"` Edition string `json:"edition"` CommitID string `json:"commit_id,omitempty"` BuildTime string `json:"build_time,omitempty"` GoVersion string `json:"go_version,omitempty"` KeywordIndexEngine string `json:"keyword_index_engine,omitempty"` VectorStoreEngine string `json:"vector_store_engine,omitempty"` GraphDatabaseEngine string `json:"graph_database_engine,omitempty"` MinioEnabled bool `json:"minio_enabled,omitempty"` DBVersion string `json:"db_version,omitempty"` // DBMigrationError carries the human-readable error message recorded when // the most recent startup migration attempt failed. Empty when migrations // succeeded; non-empty values let the frontend surface a troubleshooting // banner instead of silently hiding the DB version row (see issue #1319). DBMigrationError string `json:"db_migration_error,omitempty"` // StartedAt is the server process boot time (RFC3339, UTC). StartedAt string `json:"started_at,omitempty"` // UptimeSeconds is seconds elapsed since process start. UptimeSeconds int64 `json:"uptime_seconds,omitempty"` } // 编译时注入的版本信息 var ( Version = "unknown" Edition = "standard" CommitID = "unknown" BuildTime = "unknown" GoVersion = "unknown" ) // GetSystemInfo godoc // @Summary 获取系统信息 // @Description 获取系统版本、构建信息和引擎配置 // @Tags 系统 // @Accept json // @Produce json // @Success 200 {object} GetSystemInfoResponse "系统信息" // @Router /system/info [get] func (h *SystemHandler) GetSystemInfo(c *gin.Context) { ctx := logger.CloneContext(c.Request.Context()) // Get keyword index engine from RETRIEVE_DRIVER keywordIndexEngine := h.getKeywordIndexEngine() // Get vector store engine from config or RETRIEVE_DRIVER vectorStoreEngine := h.getVectorStoreEngine() // Get graph database engine from NEO4J_ENABLE graphDatabaseEngine := h.getGraphDatabaseEngine() // Get MinIO enabled status minioEnabled := h.isMinioConfigured(c) dbMigrationErr := database.CachedMigrationError() var dbVersion string if ver, dirty, ok := database.CachedMigrationVersion(); ok { dbVersion = fmt.Sprintf("%d", ver) if dirty { dbVersion += " (dirty)" } if dbMigrationErr != "" { dbVersion += " (failed)" } } else if dbMigrationErr != "" { // Failure happened before m.Version() could be read (e.g. could not // open the database). Still emit a placeholder so the frontend renders // the row and shows the troubleshooting banner. dbVersion = "unknown" } var startedAt string var uptimeSec int64 if boot := runtime.ServerStartedAt(); !boot.IsZero() { startedAt = boot.UTC().Format(time.RFC3339) uptimeSec = int64(runtime.ServerUptime().Seconds()) } response := GetSystemInfoResponse{ Version: Version, Edition: Edition, CommitID: CommitID, BuildTime: BuildTime, GoVersion: GoVersion, KeywordIndexEngine: keywordIndexEngine, VectorStoreEngine: vectorStoreEngine, GraphDatabaseEngine: graphDatabaseEngine, MinioEnabled: minioEnabled, DBVersion: dbVersion, DBMigrationError: dbMigrationErr, StartedAt: startedAt, UptimeSeconds: uptimeSec, } logger.Info(ctx, "System info retrieved successfully") c.JSON(200, gin.H{ "code": 0, "msg": "success", "data": response, }) } func (h *SystemHandler) getDocReaderConnInfo() (addr, transport string) { addr = strings.TrimSpace(os.Getenv("DOCREADER_ADDR")) transport = strings.TrimSpace(os.Getenv("DOCREADER_TRANSPORT")) if transport == "" { transport = "grpc" } transport = strings.ToLower(transport) return addr, transport } // ListParserEngines returns available document parser engines. // Merges Go-native static engines with engines discovered from the remote // docreader service, so newly added Python engines are auto-discovered. // @Summary 列出可用的文档解析引擎 // @Tags 系统 // @Produce json // @Success 200 {object} map[string]interface{} "解析引擎列表" // @Router /system/parser-engines [get] func (h *SystemHandler) ListParserEngines(c *gin.Context) { var overrides map[string]string if v, exists := c.Get(types.TenantInfoContextKey.String()); exists { if tenant, ok := v.(*types.Tenant); ok && tenant != nil { if tenant.ParserEngineConfig != nil { overrides = tenant.ParserEngineConfig.ToOverridesMap() } if creds := tenant.Credentials.GetWeKnoraCloud(); creds != nil { if overrides == nil { overrides = make(map[string]string) } overrides["weknoracloud_app_id"] = creds.AppID } } } reader, docreaderAddr, docreaderTransport := h.resolveDocReader(c.Request.Context(), overrides) connected := reader != nil && reader.IsConnected() remoteEngines := h.fetchRemoteEngines(c.Request.Context(), reader, overrides) engines := docparser.ListAllEngines(connected, overrides, remoteEngines) c.JSON(200, gin.H{"code": 0, "msg": "success", "data": engines, "docreader_addr": docreaderAddr, "docreader_transport": docreaderTransport, "connected": connected}) } // ReconnectDocReader reconnects the document converter to a new (or same) DocReader address. // @Summary 重连文档解析服务 // @Tags 系统 // @Accept json // @Produce json // @Param request body object{addr string} true "DocReader 地址" // @Success 200 // @Router /system/docreader/reconnect [post] func (h *SystemHandler) ReconnectDocReader(c *gin.Context) { var req struct { Addr string `json:"addr" binding:"required"` } if err := c.ShouldBindJSON(&req); err != nil { c.JSON(400, gin.H{"code": 1, "msg": "请提供 addr 参数"}) return } addr := strings.TrimSpace(req.Addr) if addr == "" { c.JSON(400, gin.H{"code": 1, "msg": "addr 不能为空"}) return } // SSRF validation for docreader address if err := secutils.ValidateURLForSSRF(addr); err != nil { logger.Warnf(c.Request.Context(), "SSRF validation failed for docreader addr: %v", err) c.JSON(400, gin.H{"code": 1, "msg": secutils.FormatSSRFError("DocReader 地址", addr, err)}) return } if h.documentReader == nil { c.JSON(500, gin.H{"code": 1, "msg": "document converter not initialized"}) return } if err := h.documentReader.Reconnect(addr); err != nil { logger.Errorf(c.Request.Context(), "Failed to reconnect docreader to %s: %v", addr, err) c.JSON(200, gin.H{"code": 1, "msg": fmt.Sprintf("连接失败: %v", err)}) return } var overrides map[string]string if v, exists := c.Get(types.TenantInfoContextKey.String()); exists { if tenant, ok := v.(*types.Tenant); ok && tenant != nil { if tenant.ParserEngineConfig != nil { overrides = tenant.ParserEngineConfig.ToOverridesMap() } if creds := tenant.Credentials.GetWeKnoraCloud(); creds != nil { if overrides == nil { overrides = make(map[string]string) } overrides["weknoracloud_app_id"] = creds.AppID } } } remoteEngines := h.fetchRemoteEngines(c.Request.Context(), h.documentReader, overrides) engines := docparser.ListAllEngines(true, overrides, remoteEngines) _, docreaderTransport := h.getDocReaderConnInfo() c.JSON(200, gin.H{"code": 0, "msg": "连接成功", "data": engines, "docreader_addr": addr, "docreader_transport": docreaderTransport, "connected": true}) } // CheckParserEngines runs availability check with the given config overrides (e.g. current form values). // Used to test engine availability without saving; body shape matches ParserEngineConfig. // @Summary 使用当前参数检测解析引擎可用性 // @Tags 系统 // @Accept json // @Produce json // @Param body body object true "解析引擎配置（与保存接口同结构）" // @Success 200 // @Router /system/parser-engines/check [post] func (h *SystemHandler) CheckParserEngines(c *gin.Context) { var body types.ParserEngineConfig if err := c.ShouldBindJSON(&body); err != nil { c.JSON(400, gin.H{"code": 1, "msg": "请求体格式错误"}) return } var existing *types.ParserEngineConfig var tenant *types.Tenant if v, exists := c.Get(types.TenantInfoContextKey.String()); exists { if t, ok := v.(*types.Tenant); ok && t != nil { tenant = t existing = t.ParserEngineConfig } } merged := types.MergeParserEngineConfigForUpdate(&body, existing) overrides := merged.ToOverridesMap() if tenant != nil { if creds := tenant.Credentials.GetWeKnoraCloud(); creds != nil { if overrides == nil { overrides = make(map[string]string) } overrides["weknoracloud_app_id"] = creds.AppID } } reader, docreaderAddr, docreaderTransport := h.resolveDocReader(c.Request.Context(), overrides) connected := reader != nil && reader.IsConnected() remoteEngines := h.fetchRemoteEngines(c.Request.Context(), reader, overrides) engines := docparser.ListAllEngines(connected, overrides, remoteEngines) c.JSON(200, gin.H{"code": 0, "msg": "success", "data": engines, "docreader_addr": docreaderAddr, "docreader_transport": docreaderTransport, "connected": connected}) } func (h *SystemHandler) resolveDocReader(ctx context.Context, overrides map[string]string) (interfaces.DocumentReader, string, string) { if len(overrides) > 0 { if addr := strings.TrimSpace(overrides["docreader_addr"]); addr != "" && service.IsWeKnoraCloudDocReaderAddr(addr) { reader := h.ResolveDocumentReader(ctx, addr) return reader, addr, transportFromDocReaderAddr(addr) } } addr, transport := h.getDocReaderConnInfo() return h.documentReader, addr, transport } func transportFromDocReaderAddr(addr string) string { if strings.HasPrefix(strings.ToLower(strings.TrimSpace(addr)), "https://") { return "https" } return "http" } // fetchRemoteEngines queries the remote docreader for its engine list. // Returns nil on any error (e.g. not connected), letting the caller // fall back to Go's static registry only. func (h *SystemHandler) fetchRemoteEngines(ctx context.Context, reader interfaces.DocumentReader, overrides map[string]string) []types.ParserEngineInfo { if reader == nil || !reader.IsConnected() { return nil } engines, err := reader.ListEngines(ctx, overrides) if err != nil { logger.Warnf(ctx, "Failed to fetch remote engines from docreader: %v", err) return nil } return engines } // getKeywordIndexEngine returns the keyword index engine name func (h *SystemHandler) getKeywordIndexEngine() string { retrieveDriver := os.Getenv("RETRIEVE_DRIVER") if retrieveDriver == "" { return "未配置" } drivers := strings.Split(retrieveDriver, ",") // Filter out engines that support keyword retrieval keywordEngines := []string{} for _, driver := range drivers { driver = strings.TrimSpace(driver) if h.supportsRetrieverType(driver, types.KeywordsRetrieverType) { keywordEngines = append(keywordEngines, driver) } } if len(keywordEngines) == 0 { return "未配置" } return strings.Join(keywordEngines, ", ") } // getVectorStoreEngine returns the vector store engine name func (h *SystemHandler) getVectorStoreEngine() string { // First check config.yaml if h.cfg != nil && h.cfg.VectorDatabase != nil && h.cfg.VectorDatabase.Driver != "" { return h.cfg.VectorDatabase.Driver } // Fallback to RETRIEVE_DRIVER for vector support retrieveDriver := os.Getenv("RETRIEVE_DRIVER") if retrieveDriver == "" { return "未配置" } drivers := strings.Split(retrieveDriver, ",") // Filter out engines that support vector retrieval vectorEngines := []string{} for _, driver := range drivers { driver = strings.TrimSpace(driver) if h.supportsRetrieverType(driver, types.VectorRetrieverType) { vectorEngines = append(vectorEngines, driver) } } if len(vectorEngines) == 0 { return "未配置" } return strings.Join(vectorEngines, ", ") } // getGraphDatabaseEngine returns the graph database engine name func (h *SystemHandler) getGraphDatabaseEngine() string { if h.neo4jDriver == nil { return "Not Enabled" } return "Neo4j" } // supportsRetrieverType checks if a driver supports a specific retriever type // by looking up the retrieverEngineMapping from types package func (h *SystemHandler) supportsRetrieverType(driver string, retrieverType types.RetrieverType) bool { // Get the mapping of all supported drivers and their capabilities mapping := types.GetRetrieverEngineMapping() // Check if the driver exists in the mapping engines, exists := mapping[driver] if !exists { return false } // Check if any of the engine configurations support the requested retriever type for _, engine := range engines { if engine.RetrieverType == retrieverType { return true } } return false } // getMinioConfig resolves MinIO connection parameters from tenant config (if mode=remote) or env vars (mode=docker/default). func (h *SystemHandler) getMinioConfig(c *gin.Context) (endpoint, accessKeyID, secretAccessKey string) { if v, exists := c.Get(types.TenantInfoContextKey.String()); exists { if tenant, ok := v.(*types.Tenant); ok && tenant != nil && tenant.StorageEngineConfig != nil && tenant.StorageEngineConfig.MinIO != nil { m := tenant.StorageEngineConfig.MinIO if m.Mode == "remote" { return m.Endpoint, m.AccessKeyID, m.SecretAccessKey } } } endpoint = os.Getenv("MINIO_ENDPOINT") accessKeyID = os.Getenv("MINIO_ACCESS_KEY_ID") secretAccessKey = os.Getenv("MINIO_SECRET_ACCESS_KEY") return } // activeBackendProviders returns the set of storage providers that have at // least one active multi-instance backend registered for the caller's // workspace. Used to keep GetStorageEngineStatus in sync with the new Storage // settings UI, which writes to storage_backends rather than the legacy // tenant.StorageEngineConfig singleton. Best-effort and nil-safe: a missing // repo, missing tenant, or query error yields an empty set so callers fall // back to the legacy config checks. func (h *SystemHandler) activeBackendProviders(c *gin.Context) map[string]bool { result := map[string]bool{} if h.storageBackendRepo == nil { return result } v, exists := c.Get(types.TenantInfoContextKey.String()) if !exists { return result } tenant, ok := v.(*types.Tenant) if !ok || tenant == nil { return result } backends, err := h.storageBackendRepo.List(c.Request.Context(), tenant.ID) if err != nil { logger.Warnf(c.Request.Context(), "[storage] list backends for status failed: tenant=%d err=%v", tenant.ID, err) return result } for _, backend := range backends { if backend == nil || backend.Status != types.StorageBackendStatusActive { continue } result[strings.ToLower(strings.TrimSpace(backend.Provider))] = true } return result } // isMinioConfigured checks whether MinIO connection info is available (from tenant config or env). func (h *SystemHandler) isMinioConfigured(c *gin.Context) bool { endpoint, accessKeyID, secretAccessKey := h.getMinioConfig(c) return endpoint != "" && accessKeyID != "" && secretAccessKey != "" } // isMinioEnvAvailable checks whether MinIO env vars (MINIO_ENDPOINT etc.) are set. func (h *SystemHandler) isMinioEnvAvailable() bool { return os.Getenv("MINIO_ENDPOINT") != "" && os.Getenv("MINIO_ACCESS_KEY_ID") != "" && os.Getenv("MINIO_SECRET_ACCESS_KEY") != "" } // isCOSConfigured checks whether COS connection info is available from tenant config. func (h *SystemHandler) isCOSConfigured(c *gin.Context) bool { if v, exists := c.Get(types.TenantInfoContextKey.String()); exists { if tenant, ok := v.(*types.Tenant); ok && tenant != nil && tenant.StorageEngineConfig != nil && tenant.StorageEngineConfig.COS != nil { cosConf := tenant.StorageEngineConfig.COS return cosConf.SecretID != "" && cosConf.SecretKey != "" && cosConf.Region != "" && cosConf.BucketName != "" } } return false } // isTOSConfigured checks whether TOS connection info is available from tenant config or env. func (h *SystemHandler) isTOSConfigured(c *gin.Context) bool { if v, exists := c.Get(types.TenantInfoContextKey.String()); exists { if tenant, ok := v.(*types.Tenant); ok && tenant != nil && tenant.StorageEngineConfig != nil && tenant.StorageEngineConfig.TOS != nil { tosConf := tenant.StorageEngineConfig.TOS return tosConf.Endpoint != "" && tosConf.Region != "" && tosConf.AccessKey != "" && tosConf.SecretKey != "" && tosConf.BucketName != "" } } return h.isTOSEnvAvailable() } // isOSSConfigured checks whether OSS connection info is available from tenant config. func (h *SystemHandler) isOSSConfigured(c *gin.Context) bool { if v, exists := c.Get(types.TenantInfoContextKey.String()); exists { if tenant, ok := v.(*types.Tenant); ok && tenant != nil && tenant.StorageEngineConfig != nil && tenant.StorageEngineConfig.OSS != nil { ossConf := tenant.StorageEngineConfig.OSS return ossConf.Endpoint != "" && ossConf.Region != "" && ossConf.AccessKey != "" && ossConf.SecretKey != "" && ossConf.BucketName != "" } } return false } // isKS3Configured checks whether KS3 connection info is available from tenant config. func (h *SystemHandler) isKS3Configured(c *gin.Context) bool { if v, exists := c.Get(types.TenantInfoContextKey.String()); exists { if tenant, ok := v.(*types.Tenant); ok && tenant != nil && tenant.StorageEngineConfig != nil && tenant.StorageEngineConfig.KS3 != nil { ks3Conf := tenant.StorageEngineConfig.KS3 return ks3Conf.Endpoint != "" && ks3Conf.Region != "" && ks3Conf.AccessKey != "" && ks3Conf.SecretKey != "" && ks3Conf.BucketName != "" } } return false } // isOBSConfigured checks whether OBS connection info is available from tenant config or env. func (h *SystemHandler) isOBSConfigured(c *gin.Context) bool { if v, exists := c.Get(types.TenantInfoContextKey.String()); exists { if tenant, ok := v.(*types.Tenant); ok && tenant != nil && tenant.StorageEngineConfig != nil && tenant.StorageEngineConfig.OBS != nil { obsConf := tenant.StorageEngineConfig.OBS return obsConf.Endpoint != "" && obsConf.Region != "" && obsConf.AccessKey != "" && obsConf.SecretKey != "" && obsConf.BucketName != "" } } return h.isOBSEnvAvailable() } // isTOSEnvAvailable checks whether TOS env vars are set. func (h *SystemHandler) isTOSEnvAvailable() bool { return os.Getenv("TOS_ENDPOINT") != "" && os.Getenv("TOS_REGION") != "" && os.Getenv("TOS_ACCESS_KEY") != "" && os.Getenv("TOS_SECRET_KEY") != "" && os.Getenv("TOS_BUCKET_NAME") != "" } // isOBSEnvAvailable checks whether OBS env vars are set. func (h *SystemHandler) isOBSEnvAvailable() bool { return os.Getenv("OBS_ENDPOINT") != "" && os.Getenv("OBS_REGION") != "" && os.Getenv("OBS_ACCESS_KEY") != "" && os.Getenv("OBS_SECRET_KEY") != "" && os.Getenv("OBS_BUCKET_NAME") != "" } // StorageEngineStatusItem describes one storage engine's availability and description. type StorageEngineStatusItem struct { Name string `json:"name"` // "local", "minio", "cos", "tos", "s3", "oss", "ks3", "obs" Allowed bool `json:"allowed"` Available bool `json:"available"` // whether the engine can be used Description string `json:"description"` // short description for UI } // GetStorageEngineStatusResponse is the response for GET /system/storage-engine-status. type GetStorageEngineStatusResponse struct { Engines []StorageEngineStatusItem `json:"engines"` AllowedProviders []string `json:"allowed_providers"` MinioEnvAvailable bool `json:"minio_env_available"` } // GetStorageEngineStatus godoc // @Summary 获取存储引擎状态 // @Description 返回 Local、MinIO、COS 各存储引擎的可用状态及说明，供全局设置与知识库选择使用 // @Tags 系统 // @Produce json // @Success 200 {object} GetStorageEngineStatusResponse // @Router /system/storage-engine-status [get] func (h *SystemHandler) GetStorageEngineStatus(c *gin.Context) { // Providers that already have an active multi-instance backend registered // (Settings → Storage). These are authoritative and independent of the // legacy singleton tenant.StorageEngineConfig, so a workspace that only // configured storage through the new UI is still reported as available. activeBackend := h.activeBackendProviders(c) minioConfigured := h.isMinioConfigured(c) || activeBackend["minio"] minioEnvAvailable := h.isMinioEnvAvailable() cosConfigured := h.isCOSConfigured(c) || activeBackend["cos"] tosConfigured := h.isTOSConfigured(c) || activeBackend["tos"] s3Configured := h.isS3Configured(c) || activeBackend["s3"] ossConfigured := h.isOSSConfigured(c) || activeBackend["oss"] ks3Configured := h.isKS3Configured(c) || activeBackend["ks3"] obsConfigured := h.isOBSConfigured(c) || activeBackend["obs"] allowed := getAllowedStorageProviders() allowedProviders := make([]string, 0, len(getSupportedStorageProviders())) for _, provider := range getSupportedStorageProviders() { if allowed[provider] { allowedProviders = append(allowedProviders, provider) } } engines := []StorageEngineStatusItem{ {Name: "local", Allowed: allowed["local"], Available: true, Description: "本地文件系统存储，仅适合单机部署"}, {Name: "minio", Allowed: allowed["minio"], Available: minioConfigured || minioEnvAvailable, Description: "S3 兼容的自托管对象存储，适合内网和私有云部署"}, {Name: "cos", Allowed: allowed["cos"], Available: cosConfigured, Description: "腾讯云对象存储服务，适合公有云部署，支持 CDN 加速"}, {Name: "tos", Allowed: allowed["tos"], Available: tosConfigured, Description: "火山引擎对象存储服务，适合公有云部署"}, {Name: "s3", Allowed: allowed["s3"], Available: s3Configured, Description: "AWS S3 与兼容对象存储服务，适合公有云与混合云部署"}, {Name: "oss", Allowed: allowed["oss"], Available: ossConfigured, Description: "阿里云对象存储服务，适合公有云部署，支持 S3 兼容协议"}, {Name: "ks3", Allowed: allowed["ks3"], Available: ks3Configured, Description: "金山云对象存储服务，适合公有云部署"}, {Name: "obs", Allowed: allowed["obs"], Available: obsConfigured, Description: "华为云对象存储服务，适合公有云部署"}, } c.JSON(200, gin.H{ "code": 0, "msg": "success", "data": GetStorageEngineStatusResponse{Engines: engines, AllowedProviders: allowedProviders, MinioEnvAvailable: minioEnvAvailable}, }) } // --- Storage engine helpers --- // cosFieldPattern validates COS region and bucket name format to prevent URL injection. var cosFieldPattern = regexp.MustCompile(`^[a-zA-Z0-9][a-zA-Z0-9._-]{0,62}$`) // ossFieldPattern validates OSS region and bucket name format to prevent URL injection. var ossFieldPattern = regexp.MustCompile(`^[a-zA-Z0-9][a-zA-Z0-9._-]{0,62}$`) // sanitizeStorageCheckError converts a raw storage connectivity error into a safe // user-facing message that does not leak internal network details (hostnames, IPs, ports). // The concrete mapping lives in internal/utils so the service layer can share it. func sanitizeStorageCheckError(err error) string { return secutils.SanitizeStorageConnectivityError(err) } // storageEndpointHost extracts the hostname from a storage endpoint string. // Endpoints may be bare host:port, hostnames, or full URLs with a scheme // (e.g. "http://127.0.0.1:9000" for S3-compatible stores). func storageEndpointHost(endpoint string) string { endpoint = strings.TrimSpace(endpoint) if endpoint == "" { return "" } if strings.Contains(endpoint, "://") { if u, err := url.Parse(endpoint); err == nil { if h := u.Hostname(); h != "" { return h } } } if host, _, err := net.SplitHostPort(endpoint); err == nil { return host } return endpoint } // isBlockedStorageEndpoint keeps the legacy handler contract while delegating // to the same fail-closed SSRF policy used by the storage clients themselves. // Private storage endpoints must be explicitly whitelisted by an operator. func isBlockedStorageEndpoint(endpoint string) (bool, string) { endpoint = strings.TrimSpace(endpoint) if endpoint == "" { return true, "无效的地址" } if err := secutils.ValidateURLForSSRF(endpoint); err != nil { return true, secutils.FormatSSRFError("存储 Endpoint", endpoint, err) } return false, "" } // --- Storage engine connectivity check --- // StorageCheckRequest is the body for POST /system/storage-engine-check. type StorageCheckRequest struct { Provider string `json:"provider"` // "minio", "cos", "tos", "s3", "oss", "ks3", "obs" MinIO *types.MinIOEngineConfig `json:"minio,omitempty"` COS *types.COSEngineConfig `json:"cos,omitempty"` TOS *types.TOSEngineConfig `json:"tos,omitempty"` S3 *types.S3EngineConfig `json:"s3,omitempty"` OSS *types.OSSEngineConfig `json:"oss,omitempty"` KS3 *types.KS3EngineConfig `json:"ks3,omitempty"` OBS *types.OBSEngineConfig `json:"obs,omitempty"` } // StorageCheckResponse is the response for a single-engine connectivity check. type StorageCheckResponse struct { OK bool `json:"ok"` Message string `json:"message"` BucketCreated bool `json:"bucket_created,omitempty"` } // CheckStorageEngine tests connectivity for a single storage engine using the provided config. // @Summary 测试存储引擎连通性 // @Description 使用当前填写的参数测试 MinIO/COS 连通性，不保存配置 // @Tags 系统 // @Accept json // @Produce json // @Param body body StorageCheckRequest true "存储引擎配置" // @Success 200 {object} StorageCheckResponse // @Router /system/storage-engine-check [post] func (h *SystemHandler) CheckStorageEngine(c *gin.Context) { ctx := logger.CloneContext(c.Request.Context()) var req StorageCheckRequest if err := c.ShouldBindJSON(&req); err != nil { c.JSON(400, gin.H{"code": 1, "msg": "请求体格式错误"}) return } if !isStorageProviderAllowed(req.Provider) { c.JSON(403, gin.H{"code": 1, "msg": "该存储引擎已被禁用"}) return } switch req.Provider { case "minio": h.checkMinio(c, ctx, req.MinIO) case "cos": h.checkCOS(c, ctx, req.COS) case "tos": h.checkTOS(c, ctx, req.TOS) case "s3": h.checkS3(c, ctx, req.S3) case "oss": h.checkOSS(c, ctx, req.OSS) case "ks3": h.checkKS3(c, ctx, req.KS3) case "obs": h.checkOBS(c, ctx, req.OBS) default: c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: true, Message: "本地存储无需检测"}}) } } func (h *SystemHandler) isS3Configured(c *gin.Context) bool { if v, exists := c.Get(types.TenantInfoContextKey.String()); exists { if tenant, ok := v.(*types.Tenant); ok && tenant != nil && tenant.StorageEngineConfig != nil && tenant.StorageEngineConfig.S3 != nil { s3Conf := tenant.StorageEngineConfig.S3 return s3Conf.Region != "" && s3Conf.BucketName != "" && (s3Conf.AccessKey == "") == (s3Conf.SecretKey == "") } } return false } func (h *SystemHandler) checkMinio(c *gin.Context, ctx context.Context, cfg *types.MinIOEngineConfig) { if cfg == nil { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "未提供 MinIO 配置"}}) return } if cfg.BucketName != "" && !cosFieldPattern.MatchString(cfg.BucketName) { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Bucket 名称格式不正确，仅允许字母、数字、点、连字符"}}) return } endpoint, accessKeyID, secretAccessKey := cfg.Endpoint, cfg.AccessKeyID, cfg.SecretAccessKey if cfg.Mode != "remote" { endpoint = os.Getenv("MINIO_ENDPOINT") accessKeyID = os.Getenv("MINIO_ACCESS_KEY_ID") secretAccessKey = os.Getenv("MINIO_SECRET_ACCESS_KEY") } if endpoint == "" || accessKeyID == "" || secretAccessKey == "" { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Endpoint、Access Key、Secret Key 不能为空"}}) return } if cfg.Mode == "remote" { if blocked, reason := isBlockedStorageEndpoint(endpoint); blocked { logger.Warnf(ctx, "Storage check: MinIO endpoint blocked by SSRF protection, endpoint: %s", endpoint) c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: reason}}) return } } err := file.CheckMinioConnectivity(ctx, endpoint, accessKeyID, secretAccessKey, cfg.BucketName, cfg.UseSSL) if err != nil { errMsg := err.Error() // If bucket does not exist, auto-create it if strings.Contains(errMsg, "does not exist") && cfg.BucketName != "" { logger.Info(ctx, "Storage check: bucket does not exist, attempting auto-creation", "bucket", cfg.BucketName) if _, mkErr := file.NewMinioFileService(endpoint, accessKeyID, secretAccessKey, cfg.BucketName, cfg.UseSSL); mkErr != nil { logger.Error(ctx, "Storage check: failed to create bucket", "bucket", cfg.BucketName, "error", mkErr) c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: fmt.Sprintf("Failed to auto-create Bucket '%s': %s", cfg.BucketName, sanitizeStorageCheckError(mkErr))}}) return } logger.Info(ctx, "Storage check: bucket created", "bucket", cfg.BucketName) c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: true, BucketCreated: true, Message: fmt.Sprintf("Bucket '%s' does not exist, and has been automatically created", cfg.BucketName)}}) return } logger.Error(ctx, "Storage check: MinIO connectivity failed", "error", err) c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: sanitizeStorageCheckError(err)}}) return } msg := "连接成功" if cfg.BucketName != "" { msg = fmt.Sprintf("连接成功，Bucket「%s」已确认存在", cfg.BucketName) } c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: true, Message: msg}}) } func (h *SystemHandler) checkCOS(c *gin.Context, ctx context.Context, cfg *types.COSEngineConfig) { if cfg == nil { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "未提供 COS 配置"}}) return } if cfg.SecretID == "" || cfg.SecretKey == "" || cfg.Region == "" || cfg.BucketName == "" { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Secret ID、Secret Key、Region、Bucket 名称不能为空"}}) return } if !cosFieldPattern.MatchString(cfg.Region) { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Region 格式不正确，仅允许字母、数字、点、连字符"}}) return } if !cosFieldPattern.MatchString(cfg.BucketName) { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Bucket 名称格式不正确，仅允许字母、数字、点、连字符"}}) return } err := file.CheckCosConnectivity(ctx, cfg.BucketName, cfg.Region, cfg.SecretID, cfg.SecretKey) if err != nil { logger.Errorf(ctx, "Storage check: COS connectivity failed, bucket: %s, error: %v", cfg.BucketName, err) errMsg := err.Error() if strings.Contains(errMsg, "403") { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "认证失败，请检查 Secret ID / Secret Key 是否正确"}}) return } if strings.Contains(errMsg, "404") || strings.Contains(errMsg, "NoSuchBucket") { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: fmt.Sprintf("Bucket「%s」不存在，请检查名称和 Region", cfg.BucketName)}}) return } c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: sanitizeStorageCheckError(err)}}) return } c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: true, Message: fmt.Sprintf("连接成功，Bucket「%s」已确认存在", cfg.BucketName)}}) } func (h *SystemHandler) checkTOS(c *gin.Context, ctx context.Context, cfg *types.TOSEngineConfig) { if cfg == nil { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "未提供 TOS 配置"}}) return } if cfg.Endpoint == "" || cfg.Region == "" || cfg.AccessKey == "" || cfg.SecretKey == "" || cfg.BucketName == "" { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Endpoint、Region、Access Key、Secret Key、Bucket 名称不能为空"}}) return } if blocked, reason := isBlockedStorageEndpoint(cfg.Endpoint); blocked { logger.Warnf(ctx, "Storage check: TOS endpoint blocked by SSRF protection, endpoint: %s", cfg.Endpoint) c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: reason}}) return } err := file.CheckTosConnectivity(ctx, cfg.Endpoint, cfg.Region, cfg.AccessKey, cfg.SecretKey, cfg.BucketName) if err != nil { logger.Errorf(ctx, "Storage check: TOS connectivity failed, bucket: %s, error: %v", cfg.BucketName, err) errMsg := err.Error() if strings.Contains(errMsg, "403") { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "认证失败，请检查 Access Key / Secret Key 是否正确"}}) return } if strings.Contains(errMsg, "404") { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: fmt.Sprintf("Bucket「%s」不存在，请检查名称和 Region", cfg.BucketName)}}) return } c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: sanitizeStorageCheckError(err)}}) return } c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: true, Message: fmt.Sprintf("连接成功，Bucket「%s」已确认存在", cfg.BucketName)}}) } func (h *SystemHandler) checkS3(c *gin.Context, ctx context.Context, cfg *types.S3EngineConfig) { if cfg == nil { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "未提供 S3 配置"}}) return } if cfg.Region == "" || cfg.BucketName == "" { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Region、Bucket 名称不能为空"}}) return } if (cfg.AccessKey == "") != (cfg.SecretKey == "") { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Access Key 与 Secret Key 必须同时填写或同时留空（使用 AWS 默认凭证链）"}}) return } if cfg.Endpoint != "" { if blocked, reason := isBlockedStorageEndpoint(cfg.Endpoint); blocked { logger.Warnf(ctx, "Storage check: S3 endpoint blocked by SSRF protection, endpoint: %s", cfg.Endpoint) c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: reason}}) return } } err := file.CheckS3Connectivity(ctx, cfg.Endpoint, cfg.AccessKey, cfg.SecretKey, cfg.BucketName, cfg.Region) if err != nil { logger.Errorf(ctx, "Storage check: S3 connectivity failed, bucket: %s, error: %v", cfg.BucketName, err) errMsg := err.Error() if strings.Contains(errMsg, "403") { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "认证失败，请检查静态密钥或 AWS IAM Role / 默认凭证链权限"}}) return } if strings.Contains(errMsg, "404") || strings.Contains(errMsg, "NotFound") { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: fmt.Sprintf("Bucket「%s」不存在，请检查名称和 Region", cfg.BucketName)}}) return } c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: sanitizeStorageCheckError(err)}}) return } c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: true, Message: fmt.Sprintf("连接成功，Bucket「%s」已确认存在", cfg.BucketName)}}) } func (h *SystemHandler) checkOSS(c *gin.Context, ctx context.Context, cfg *types.OSSEngineConfig) { if cfg == nil { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "未提供 OSS 配置"}}) return } endpoint, accessKey, secretKey := cfg.Endpoint, cfg.AccessKey, cfg.SecretKey if endpoint == "" || accessKey == "" || secretKey == "" || cfg.BucketName == "" { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Endpoint、Access Key、Secret Key、Bucket Name 不能为空"}}) return } // Strip URL scheme before SSRF check — OSS endpoint may include http:// or https:// ssrfEndpoint := strings.TrimPrefix(strings.TrimPrefix(endpoint, "https://"), "http://") if blocked, reason := isBlockedStorageEndpoint(ssrfEndpoint); blocked { logger.Warnf(ctx, "Storage check: OSS endpoint blocked by SSRF protection, endpoint: %s", endpoint) c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: reason}}) return } if !ossFieldPattern.MatchString(cfg.Region) { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Region 格式不正确，仅允许字母、数字、点、连字符"}}) return } if !ossFieldPattern.MatchString(cfg.BucketName) { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Bucket 名称格式不正确，仅允许字母、数字、点、连字符"}}) return } err := file.CheckOssConnectivity(ctx, endpoint, cfg.Region, accessKey, secretKey, cfg.BucketName) if err != nil { errMsg := err.Error() if strings.Contains(errMsg, "403") || strings.Contains(errMsg, "AccessDenied") { logger.Errorf(ctx, "Storage check: OSS auth failed, endpoint: %s, bucket: %s", endpoint, cfg.BucketName) c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "认证失败，请检查 Access Key / Secret Key 是否正确"}}) return } if strings.Contains(errMsg, "404") || strings.Contains(errMsg, "NoSuchBucket") { logger.Errorf(ctx, "Storage check: OSS bucket not found, bucket: %s", cfg.BucketName) c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: fmt.Sprintf("Bucket「%s」不存在", cfg.BucketName)}}) return } logger.Errorf(ctx, "Storage check: OSS connectivity failed, endpoint: %s, bucket: %s, error: %v", endpoint, cfg.BucketName, err) c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: fmt.Sprintf("OSS 连通性检测失败: %s", sanitizeStorageCheckError(err))}}) return } c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: true, Message: fmt.Sprintf("连接成功，Bucket「%s」已确认存在", cfg.BucketName)}}) } func (h *SystemHandler) checkKS3(c *gin.Context, ctx context.Context, cfg *types.KS3EngineConfig) { if cfg == nil { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "未提供 KS3 配置"}}) return } endpoint, region, accessKey, secretKey := cfg.Endpoint, cfg.Region, cfg.AccessKey, cfg.SecretKey if endpoint == "" || region == "" || accessKey == "" || secretKey == "" || cfg.BucketName == "" { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Endpoint、Region、Access Key、Secret Key、Bucket 名称不能为空"}}) return } if blocked, reason := isBlockedStorageEndpoint(endpoint); blocked { logger.Warnf(ctx, "Storage check: KS3 endpoint blocked by SSRF protection, endpoint: %s", endpoint) c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: reason}}) return } err := file.CheckKS3Connectivity(ctx, endpoint, region, accessKey, secretKey, cfg.BucketName) if err != nil { logger.Errorf(ctx, "Storage check: KS3 connectivity failed, bucket: %s, error: %v", cfg.BucketName, err) errMsg := err.Error() if strings.Contains(errMsg, "403") || strings.Contains(errMsg, "AccessDenied") { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "认证失败，请检查 Access Key / Secret Key 是否正确"}}) return } if strings.Contains(errMsg, "404") || strings.Contains(errMsg, "NoSuchBucket") { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: fmt.Sprintf("Bucket「%s」不存在，请检查名称和 Region", cfg.BucketName)}}) return } c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: sanitizeStorageCheckError(err)}}) return } c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: true, Message: fmt.Sprintf("连接成功，Bucket「%s」已确认存在", cfg.BucketName)}}) } func (h *SystemHandler) checkOBS(c *gin.Context, ctx context.Context, cfg *types.OBSEngineConfig) { if cfg == nil { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "未提供 OBS 配置"}}) return } endpoint, region, accessKey, secretKey := cfg.Endpoint, cfg.Region, cfg.AccessKey, cfg.SecretKey if endpoint == "" || region == "" || accessKey == "" || secretKey == "" || cfg.BucketName == "" { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Endpoint、Region、Access Key、Secret Key、Bucket 名称不能为空"}}) return } ssrfEndpoint := strings.TrimPrefix(strings.TrimPrefix(endpoint, "https://"), "http://") if blocked, reason := isBlockedStorageEndpoint(ssrfEndpoint); blocked { logger.Warnf(ctx, "Storage check: OBS endpoint blocked by SSRF protection, endpoint: %s", endpoint) c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: reason}}) return } if !ossFieldPattern.MatchString(cfg.Region) { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Region 格式不正确，仅允许字母、数字、点、连字符"}}) return } if !ossFieldPattern.MatchString(cfg.BucketName) { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Bucket 名称格式不正确，仅允许字母、数字、点、连字符"}}) return } err := file.CheckObsConnectivity(ctx, endpoint, region, accessKey, secretKey, cfg.BucketName) if err != nil { logger.Errorf(ctx, "Storage check: OBS connectivity failed, bucket: %s, error: %v", cfg.BucketName, err) errMsg := err.Error() if strings.Contains(errMsg, "403") || strings.Contains(errMsg, "AccessDenied") { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "认证失败，请检查 Access Key / Secret Key 是否正确"}}) return } if strings.Contains(errMsg, "404") || strings.Contains(errMsg, "NoSuchBucket") { c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: fmt.Sprintf("Bucket「%s」不存在，请检查名称和 Region", cfg.BucketName)}}) return } c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: sanitizeStorageCheckError(err)}}) return } c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: true, Message: fmt.Sprintf("连接成功，Bucket「%s」已确认存在", cfg.BucketName)}}) } func (h *SystemHandler) ResolveDocumentReader(ctx context.Context, addr string) interfaces.DocumentReader { if addr == "" { return h.documentReader } if service.IsWeKnoraCloudDocReaderAddr(addr) { creds := h.tenantSvc.GetWeKnoraCloudCredentials(ctx) if creds == nil { return nil } reader, err := docparser.NewWeKnoraCloudSignedDocumentReader(creds.AppID, creds.AppSecret) if err != nil { return nil } return reader } reader, err := docparser.NewHTTPDocumentReader(addr) if err != nil || reader == nil { return reader } return reader } // PromoteUserToSystemAdminRequest defines the request for promoting a user to system admin. // // Either user_id (UUID) or email must be supplied. When both are present // user_id wins — explicit IDs are unambiguous, an email collision (extremely // rare in practice but possible during a tenant merge) would otherwise // silently target the wrong row. // // We don't expose a `binding:"required"` tag on either field because gin's // validator can't express the OR constraint; the handler does the check // manually and returns 400 with a specific message for each branch. type PromoteUserToSystemAdminRequest struct { UserID string `json:"user_id"` Email string `json:"email"` } // PromoteUserToSystemAdmin godoc // @Summary Promote a user to system administrator // @Description Grant system administrator privileges to a user (SystemAdmin only). // @Description Idempotent: re-promoting an existing system admin returns 200 with no DB write. // @Description Identify the user by email (preferred for human operators) or user_id (UUID, for API clients). // @Tags System Admin // @Accept json // @Produce json // @Param request body PromoteUserToSystemAdminRequest true "User promotion request" // @Success 200 {object} types.UserInfo "User promoted successfully" // @Failure 400 {object} map[string]interface{} "Bad request" // @Failure 403 {object} map[string]interface{} "Forbidden: not a system admin" // @Failure 404 {object} map[string]interface{} "User not found" // @Router /system/admin/promote [post] func (h *SystemHandler) PromoteUserToSystemAdmin(c *gin.Context) { ctx := logger.CloneContext(c.Request.Context()) var req PromoteUserToSystemAdminRequest if err := c.ShouldBindJSON(&req); err != nil { c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid request: " + err.Error()}) return } userID := strings.TrimSpace(req.UserID) email := strings.TrimSpace(req.Email) if userID == "" && email == "" { c.JSON(http.StatusBadRequest, gin.H{"error": "Either user_id or email is required"}) return } // Resolve user. user_id takes priority when both are sent (see request // struct doc); otherwise we look up by email. Both branches funnel // into the same {nil-user / error} 404 so we don't leak whether a // given email exists in the system to non-admins — though SystemAdmin // is already a high-trust role, the parity keeps the surface clean. var ( user *types.User err error ) switch { case userID != "": user, err = h.userSvc.GetUserByID(ctx, userID) default: user, err = h.userSvc.GetUserByEmail(ctx, email) } if err != nil { logger.Errorf(ctx, "Error fetching user (id=%q email=%q): %v", userID, email, err) c.JSON(http.StatusNotFound, gin.H{"error": "User not found"}) return } if user == nil { c.JSON(http.StatusNotFound, gin.H{"error": "User not found"}) return } if user.IsSystemAdmin { // Idempotent: re-promoting an existing system admin is a no-op // success. We still emit an audit row so probing the endpoint // leaves a forensic trail (idempotent=true marks it as noop). h.emitAdminAudit(ctx, types.AuditActionSystemAdminPromoted, user, map[string]any{ "target_email": user.Email, "target_username": user.Username, "idempotent": true, }) c.JSON(http.StatusOK, user.ToUserInfo()) return } user.IsSystemAdmin = true if err := h.userSvc.UpdateUser(ctx, user); err != nil { logger.Errorf(ctx, "Error promoting user %s to system admin: %v", req.UserID, err) c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to promote user"}) return } logger.Infof(ctx, "User %s (ID: %s) promoted to system admin", user.Username, user.ID) h.emitAdminAudit(ctx, types.AuditActionSystemAdminPromoted, user, map[string]any{ "target_email": user.Email, "target_username": user.Username, "idempotent": false, }) c.JSON(http.StatusOK, user.ToUserInfo()) } // RevokeSystemAdminRequest defines the request for revoking system admin privileges type RevokeSystemAdminRequest struct { UserID string `json:"user_id" binding:"required"` } // RevokeSystemAdmin godoc // @Summary Revoke system administrator privileges from a user // @Description Remove system administrator privileges from a user (SystemAdmin only). // @Description Two safety guards: the caller cannot revoke their own privileges, // @Description and revoking the last remaining system admin is rejected — both // @Description prevent a SystemAdmin from accidentally locking the platform out // @Description of system-level administration. Idempotent on already-non-admin users. // @Tags System Admin // @Accept json // @Produce json // @Param request body RevokeSystemAdminRequest true "User revocation request" // @Success 200 {object} types.UserInfo "Privileges revoked successfully" // @Failure 400 {object} map[string]interface{} "Bad request / would remove last admin / self-revoke" // @Failure 403 {object} map[string]interface{} "Forbidden: not a system admin" // @Failure 404 {object} map[string]interface{} "User not found" // @Router /system/admin/revoke [post] func (h *SystemHandler) RevokeSystemAdmin(c *gin.Context) { ctx := logger.CloneContext(c.Request.Context()) var req RevokeSystemAdminRequest if err := c.ShouldBindJSON(&req); err != nil { c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid request: " + err.Error()}) return } callerID, _ := types.UserIDFromContext(ctx) user, err := h.userSvc.RevokeSystemAdmin(ctx, req.UserID, callerID) switch { case err == nil: // Real revoke — privileges were actually removed. logger.Infof(ctx, "System admin privileges revoked from user %s (ID: %s)", user.Username, user.ID) h.emitAdminAudit(ctx, types.AuditActionSystemAdminRevoked, user, map[string]any{ "target_email": user.Email, "target_username": user.Username, "changed": true, }) c.JSON(http.StatusOK, user.ToUserInfo()) return case errors.Is(err, repository.ErrUserNotSystemAdmin): // Idempotent: target was already not an admin. Return 200 so // callers that re-issue the request after a partial failure // don't get a confusing 4xx, but mark `changed=false` in the // audit row so a forensic reader can tell a real revoke from a // noop probe. if user == nil { logger.Errorf(ctx, "RevokeSystemAdmin returned nil user with ErrUserNotSystemAdmin for %s", req.UserID) c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to revoke system admin privileges"}) return } logger.Infof(ctx, "Revoke noop (user %s was not a system admin)", user.ID) h.emitAdminAudit(ctx, types.AuditActionSystemAdminRevoked, user, map[string]any{ "target_email": user.Email, "target_username": user.Username, "changed": false, }) c.JSON(http.StatusOK, user.ToUserInfo()) return case errors.Is(err, repository.ErrCannotRevokeSelf): c.JSON(http.StatusBadRequest, gin.H{ "error": "Cannot revoke your own system admin privileges", }) return case errors.Is(err, repository.ErrLastSystemAdmin): c.JSON(http.StatusBadRequest, gin.H{ "error": "Cannot revoke the last remaining system administrator", }) return case errors.Is(err, repository.ErrUserNotFound): c.JSON(http.StatusNotFound, gin.H{"error": "User not found"}) return default: logger.Errorf(ctx, "Error revoking system admin from user %s: %v", req.UserID, err) c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to revoke system admin privileges"}) return } } // ListSystemAdminsResponse defines the response structure for listing system admins. // Total reflects the underlying COUNT(*), not just the page size, so the front // end can render pagination metadata without a follow-up call. type ListSystemAdminsResponse struct { Total int64 `json:"total"` Admins []*types.UserInfo `json:"admins"` } // ListSystemAdmins godoc // @Summary List all system administrators // @Description Retrieve a paginated list of users with system administrator // @Description privileges (SystemAdmin only). Supports `offset` (default 0) // @Description and `limit` (default 50, max 200) query parameters. Walks the // @Description partial-friendly idx_users_is_system_admin index. // @Tags System Admin // @Produce json // @Param offset query int false "Page offset" default(0) // @Param limit query int false "Page size (max 200)" default(50) // @Success 200 {object} ListSystemAdminsResponse "System admins retrieved successfully" // @Failure 403 {object} map[string]interface{} "Forbidden: not a system admin" // @Router /system/admin/list [get] func (h *SystemHandler) ListSystemAdmins(c *gin.Context) { ctx := logger.CloneContext(c.Request.Context()) // Best-effort pagination parsing — a malformed `limit=foo` falls back // to defaults rather than 400-ing, since the call is still safe and a // failed-page is more user-hostile than a soft default. offset := 0 limit := 50 if v := c.Query("offset"); v != "" { if n, err := strconv.Atoi(v); err == nil && n >= 0 { offset = n } } if v := c.Query("limit"); v != "" { if n, err := strconv.Atoi(v); err == nil && n > 0 { limit = n } } // Cap so a client can't ask for the entire table. if limit > 200 { limit = 200 } users, total, err := h.userSvc.ListSystemAdmins(ctx, offset, limit) if err != nil { logger.Errorf(ctx, "Error listing system admins: %v", err) c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to list system admins"}) return } // Always emit a non-nil slice so the JSON serialises to `[]` rather // than `null` for an empty page — front-end iteration is safer. infos := make([]*types.UserInfo, 0, len(users)) for _, u := range users { infos = append(infos, u.ToUserInfo()) } c.JSON(http.StatusOK, ListSystemAdminsResponse{ Total: total, Admins: infos, }) } // ResetUserPasswordRequest defines the system-administrator password-reset // payload. Email is intentionally the only user-facing identifier: the UI is // an operator tool and emails are easier to verify than UUIDs. The password is // never written to logs or audit details. type ResetUserPasswordRequest struct { Email string `json:"email" binding:"required,email"` NewPassword string `json:"new_password" binding:"required"` } // ResetUserPassword godoc // @Summary Reset another user's password // @Description Replace another user's local password and revoke all of their existing sessions (SystemAdmin only). // @Description A system administrator cannot reset their own password through this endpoint; self-service password change still requires the old password. // @Tags System Admin // @Accept json // @Produce json // @Param request body ResetUserPasswordRequest true "Password reset request" // @Success 200 {object} map[string]interface{} "Password reset successfully" // @Failure 400 {object} map[string]interface{} "Invalid request, weak password, or self reset" // @Failure 403 {object} map[string]interface{} "Forbidden: not a system admin" // @Failure 404 {object} map[string]interface{} "User not found" // @Router /system/admin/users/reset-password [post] func (h *SystemHandler) ResetUserPassword(c *gin.Context) { ctx := logger.CloneContext(c.Request.Context()) var req ResetUserPasswordRequest if err := c.ShouldBindJSON(&req); err != nil { c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid password reset request"}) return } req.Email = strings.TrimSpace(req.Email) if err := service.ValidatePasswordPolicy(req.NewPassword, h.complexPasswordEnabled(ctx)); err != nil { c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()}) return } user, err := h.userSvc.GetUserByEmail(ctx, req.Email) if err != nil || user == nil { c.JSON(http.StatusNotFound, gin.H{"error": "User not found"}) return } callerID, _ := types.UserIDFromContext(ctx) if callerID == user.ID { c.JSON(http.StatusBadRequest, gin.H{"error": "Cannot reset your own password here"}) return } if err := h.userSvc.AdminResetPassword(ctx, user.ID, req.NewPassword); err != nil { if service.IsPasswordPolicyError(err) { c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()}) return } logger.Errorf(ctx, "Failed to reset password for user %s: %v", user.ID, err) c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to reset user password"}) return } logger.Infof(ctx, "Password reset by system administrator for user ID: %s", user.ID) h.emitAdminAudit(ctx, types.AuditActionSystemUserPasswordReset, user, map[string]any{ "target_email": user.Email, "target_username": user.Username, "sessions_revoked": true, }) c.JSON(http.StatusOK, gin.H{"message": "Password reset successfully"}) } // CreateSystemUserResponse is the payload returned by // POST /api/v1/system/admin/users/create. GeneratedPassword is populated // exactly once, only when the server minted a random password (`password` // omitted or null), and is never logged, audited, or retrievable again. type CreateSystemUserResponse struct { User *types.UserInfo `json:"user"` // GeneratedPassword is the plaintext password when the server // auto-generated one. Absent when the caller supplied the password. GeneratedPassword string `json:"generated_password,omitempty"` } // CreateSystemUser godoc // @Summary Create a new user (SystemAdmin) // @Description Provision a new local user account (SystemAdmin only). // @Description When `password` is omitted or null, a cryptographically random // @Description password is generated (OIDC-style crypto/rand + base64url) // @Description and returned once in the response body. Any provided value, // @Description including empty string, is policy-checked. Tenant provisioning // @Description follows the shared auth.default_tenant_mode policy. // @Tags System Admin // @Accept json // @Produce json // @Param request body types.AdminCreateUserRequest true "User creation request" // @Success 201 {object} CreateSystemUserResponse "User created successfully" // @Success 200 {object} CreateSystemUserResponse "Identity already exists, returns the existing user" // @Failure 400 {object} map[string]interface{} "Invalid request or weak password" // @Failure 403 {object} map[string]interface{} "Forbidden: not a system admin" // @Failure 409 {object} map[string]interface{} "Email and username refer to conflicting identities" // @Failure 500 {object} map[string]interface{} "Internal error" // @Router /system/admin/users/create [post] func (h *SystemHandler) CreateSystemUser(c *gin.Context) { ctx := logger.CloneContext(c.Request.Context()) var req types.AdminCreateUserRequest if err := c.ShouldBindJSON(&req); err != nil { c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid user creation request"}) return } req.Username = secutils.SanitizeForLog(strings.TrimSpace(req.Username)) req.Email = secutils.SanitizeForLog(strings.TrimSpace(req.Email)) // Password is intentionally NOT trimmed or sanitized. if req.Username == "" || req.Email == "" { c.JSON(http.StatusBadRequest, gin.H{"error": "Username and email are required"}) return } // Binding's min=2/max=50 ran on the raw JSON, re-check the trimmed value. if n := utf8.RuneCountInString(req.Username); n < 2 || n > 50 { c.JSON(http.StatusBadRequest, gin.H{"error": "Username must be 2-50 characters"}) return } user, generatedPassword, err := h.userSvc.AdminCreateUser(ctx, &req, h.resolveDefaultTenantMode(ctx)) if err != nil { switch { case errors.Is(err, service.ErrUserEmailExists) || errors.Is(err, service.ErrUserUsernameExists): if user == nil { logger.Errorf(ctx, "Duplicate identity error without a resolved user: %v", err) c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to create user"}) return } logger.Infof(ctx, "Create user noop (identity already exists, ID: %s)", user.ID) h.emitAdminAudit(ctx, types.AuditActionSystemUserCreated, user, map[string]any{ "target_email": user.Email, "target_username": user.Username, "password_generated": false, "idempotent": true, }) c.JSON(http.StatusOK, CreateSystemUserResponse{User: user.ToUserInfo()}) case errors.Is(err, service.ErrPasswordPolicy): c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()}) case errors.Is(err, service.ErrUserIdentityConflict): c.JSON(http.StatusConflict, gin.H{"error": err.Error()}) default: logger.Errorf(ctx, "Failed to create user: %v", err) c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to create user"}) } return } logger.Infof(ctx, "System admin created user %s (ID: %s)", user.Username, user.ID) h.emitAdminAudit(ctx, types.AuditActionSystemUserCreated, user, map[string]any{ "target_email": user.Email, "target_username": user.Username, "password_generated": generatedPassword != "", "idempotent": false, }) c.JSON(http.StatusCreated, CreateSystemUserResponse{ User: user.ToUserInfo(), GeneratedPassword: generatedPassword, }) } // ============================================================================ // System Settings (P1) // ---------------------------------------------------------------------------- // Endpoints below are mounted under /api/v1/system/admin/settings*, all // gated to SystemAdmin via the route group's middleware. Every response // is the raw model — no `gin.H{"data": ...}` wrapping — to match the // project's axios interceptor contract (response.data is unwrapped at the // HTTP layer; see frontend/src/utils/request.ts:97). The P0 ListSystemAdmins // already follows this; do not break the convention. // ============================================================================ // ListSystemSettings godoc // @Summary List all system settings // @Description Return every row in the system_settings table (system-scope, // @Description not workspace-scoped). SystemAdmin only. // @Tags System Admin // @Produce json // @Success 200 {array} types.SystemSetting "list of settings" // @Failure 403 {object} map[string]interface{} "Forbidden: not a system admin" // @Router /system/admin/settings [get] // RuntimeQueuesResponse is the payload for the SystemAdmin runtime queue // dashboard. `available` is false in Lite mode (no Redis/asynq) so the // UI can render an "unavailable in this deployment" state instead of an // empty table. Each pool reports configured per-process concurrency plus live // cluster capacity/active workers aggregated from asynq server heartbeats. type RuntimeWorkerPool struct { Name string `json:"name"` Concurrency int `json:"concurrency"` // configured per instance QueueCount int `json:"queue_count"` Instances int `json:"instances"` // live asynq server heartbeats ClusterCapacity int `json:"cluster_capacity"` // sum of live server concurrency Active int `json:"active"` // live workers assigned to this pool Utilization float64 `json:"utilization"` // Active / ClusterCapacity } type RuntimeQueuesResponse struct { Available bool `json:"available"` UpstreamConcurrency int `json:"upstream_concurrency"` ParseConcurrency int `json:"parse_concurrency"` // compatibility alias for upstream_concurrency WikiConcurrency int `json:"wiki_concurrency"` // compatibility field Pools []RuntimeWorkerPool `json:"pools"` Queues []types.QueueStat `json:"queues"` ModelLimiterAvailable bool `json:"model_limiter_available"` Models []modellimiter.RuntimeStat `json:"models"` Timestamp int64 `json:"timestamp"` } func aggregateRuntimeWorkerPools(pools []RuntimeWorkerPool, servers []types.WorkerServerStat) { queueConfigs := map[string]map[string]int{ types.WorkerPoolCore: types.QueueWeightsForPool(types.WorkerPoolCore), types.WorkerPoolPostProcess: types.QueueWeightsForPool(types.WorkerPoolPostProcess), types.WorkerPoolEnrichment: types.QueueWeightsForPool(types.WorkerPoolEnrichment), types.WorkerPoolMaintenance: types.QueueWeightsForPool(types.WorkerPoolMaintenance), types.WorkerPoolShared: types.QueueWeightsForSharedPool(), types.WorkerPoolWiki: types.QueueWeightsForPool(types.WorkerPoolWiki), } indexes := make(map[string]int, len(pools)) for i := range pools { indexes[pools[i].Name] = i } for _, server := range servers { if server.Status != "active" { continue } for poolName, expectedQueues := range queueConfigs { if !sameQueueWeights(server.Queues, expectedQueues) { continue } idx, ok := indexes[poolName] if !ok { break } pools[idx].Instances++ pools[idx].ClusterCapacity += server.Concurrency pools[idx].Active += server.Active break } } for i := range pools { if pools[i].ClusterCapacity > 0 { pools[i].Utilization = float64(pools[i].Active) / float64(pools[i].ClusterCapacity) } } } func sameQueueWeights(left, right map[string]int) bool { if len(left) != len(right) { return false } for name, weight := range left { if right[name] != weight { return false } } return true } // GetRuntimeQueues godoc // @Summary 获取解析任务队列运行时状态 // @Description 返回各 asynq 队列的实时深度（pending/active/scheduled/retry 等）与 worker 并发配置，仅系统管理员可见 // @Tags 系统管理 // @Produce json // @Success 200 {object} RuntimeQueuesResponse // @Router /system/admin/runtime/queues [get] func (h *SystemHandler) GetRuntimeQueues(c *gin.Context) { ctx := logger.CloneContext(c.Request.Context()) var allocation types.WorkerPoolConcurrency if h.systemSettingSvc != nil { allocation = types.ResolveWorkerPoolConcurrency(func(key, env string, fallback int) int { configured := h.systemSettingSvc.GetInt(ctx, key, env, int64(fallback)) return int(configured) }) } else { allocation = types.DefaultWorkerPoolConcurrency() } queueCounts := make(map[string]int) for _, definition := range types.QueueDefinitions() { queueCounts[definition.Pool]++ } resp := RuntimeQueuesResponse{ UpstreamConcurrency: allocation.UpstreamTotal(), ParseConcurrency: allocation.UpstreamTotal(), WikiConcurrency: allocation.Wiki, Pools: []RuntimeWorkerPool{ {Name: types.WorkerPoolCore, Concurrency: allocation.Core, QueueCount: queueCounts[types.WorkerPoolCore]}, {Name: types.WorkerPoolPostProcess, Concurrency: allocation.PostProcess, QueueCount: queueCounts[types.WorkerPoolPostProcess]}, {Name: types.WorkerPoolEnrichment, Concurrency: allocation.Enrichment, QueueCount: queueCounts[types.WorkerPoolEnrichment]}, {Name: types.WorkerPoolMaintenance, Concurrency: allocation.Maintenance, QueueCount: queueCounts[types.WorkerPoolMaintenance]}, {Name: types.WorkerPoolShared, Concurrency: allocation.Shared, QueueCount: len(types.QueueWeightsForSharedPool())}, {Name: types.WorkerPoolWiki, Concurrency: allocation.Wiki, QueueCount: queueCounts[types.WorkerPoolWiki]}, }, Timestamp: time.Now().Unix(), } if h.taskInspector != nil { stats, supported, err := h.taskInspector.QueueStats(ctx) if err != nil { logger.Errorf(ctx, "get queue stats failed: %v", err) } resp.Available = supported if stats != nil { resp.Queues = stats } serverStats, _, serverErr := h.taskInspector.WorkerServerStats(ctx) if serverErr != nil { logger.Errorf(ctx, "get worker server stats failed: %v", serverErr) } else { aggregateRuntimeWorkerPools(resp.Pools, serverStats) } } // Always emit a non-nil array so the JSON serialises to `[]` rather // than `null`, keeping the frontend iteration simple. if resp.Queues == nil { resp.Queues = []types.QueueStat{} } modelStats, modelSupported, modelErr := modellimiter.RuntimeStats(ctx) if modelErr != nil { logger.Errorf(ctx, "get model concurrency stats failed: %v", modelErr) } resp.ModelLimiterAvailable = modelSupported resp.Models = modelStats c.JSON(http.StatusOK, resp) } type RuntimeTasksResponse struct { Available bool `json:"available"` Tasks []types.RuntimeTaskInfo `json:"tasks"` PageSize int `json:"page_size"` HasMore bool `json:"has_more"` NextCursor string `json:"next_cursor,omitempty"` } func isKnownRuntimeQueue(name string) bool { for _, definition := range types.QueueDefinitions() { if definition.Name == name { return true } } return false } func runtimeTaskPageSize(c *gin.Context) int { pageSize, _ := strconv.Atoi(c.DefaultQuery("page_size", "20")) if pageSize < 1 { pageSize = 20 } if pageSize > 100 { pageSize = 100 } return pageSize } func (h *SystemHandler) listRuntimeTasks(c *gin.Context, state types.RuntimeTaskState) { queue := c.Param("queue") if !isKnownRuntimeQueue(queue) { c.JSON(http.StatusBadRequest, gin.H{"error": "Unknown task queue"}) return } if !state.Valid() { c.JSON(http.StatusBadRequest, gin.H{"error": "Unknown task state"}) return } pageSize := runtimeTaskPageSize(c) cursor := c.Query("cursor") inspector, ok := h.taskInspector.(interfaces.RuntimeTaskInspector) if !ok { c.JSON(http.StatusOK, RuntimeTasksResponse{ Available: false, Tasks: []types.RuntimeTaskInfo{}, PageSize: pageSize, }) return } page, supported, err := inspector.ListRuntimeTasks(c.Request.Context(), queue, state, cursor, pageSize) if err != nil { if errors.Is(err, types.ErrInvalidRuntimeTaskCursor) { c.JSON(http.StatusBadRequest, gin.H{ "error": "Invalid task list cursor", "code": "runtime_task_cursor_invalid", }) return } if errors.Is(err, types.ErrExpiredRuntimeTaskCursor) { c.JSON(http.StatusConflict, gin.H{ "error": "Task list changed; refresh from the beginning", "code": "runtime_task_cursor_expired", }) return } logger.Errorf(c.Request.Context(), "list runtime queue tasks queue=%s state=%s: %v", queue, state, err) c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to list queue tasks"}) return } if page.Tasks == nil { page.Tasks = []types.RuntimeTaskInfo{} } c.JSON(http.StatusOK, RuntimeTasksResponse{ Available: supported, Tasks: page.Tasks, PageSize: pageSize, HasMore: page.HasMore, NextCursor: page.NextCursor, }) } // ListRuntimeTasks returns one live task-state page for the unified operator // drawer. Raw task payloads are never included. // @Summary List runtime queue tasks by state // @Tags System Admin // @Produce json // @Param queue path string true "Queue name" // @Param state query string true "Task state" Enums(pending,active,scheduled,retry,archived,completed) // @Param cursor query string false "Opaque continuation cursor" // @Param page_size query int false "Page size" default(20) // @Success 200 {object} RuntimeTasksResponse // @Router /system/admin/runtime/queues/{queue}/tasks [get] func (h *SystemHandler) ListRuntimeTasks(c *gin.Context) { h.listRuntimeTasks(c, types.RuntimeTaskState(c.Query("state"))) } func (h *SystemHandler) emitQueueTaskAudit( ctx context.Context, action types.AuditAction, queue, taskID string, extra map[string]string, ) { if h.auditSvc == nil { return } actorID, _ := types.UserIDFromContext(ctx) detailMap := map[string]string{"queue": queue, "task_id": taskID} for key, value := range extra { detailMap[key] = value } details, _ := json.Marshal(detailMap) targetType := "queue_task" targetID := taskID if targetID == "" { targetType = "task_queue" targetID = queue } _ = h.auditSvc.Log(ctx, &types.AuditLog{ TenantID: 0, ActorUserID: actorID, ActorRole: systemAuditActorRole(ctx), Action: action, TargetType: targetType, TargetID: targetID, Outcome: types.AuditOutcomeSuccess, Details: types.JSON(details), }) } func runtimeTaskParams(c *gin.Context) (string, string, bool) { queue := c.Param("queue") taskID := c.Param("task_id") if !isKnownRuntimeQueue(queue) || taskID == "" { c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid queue or task ID"}) return "", "", false } return queue, taskID, true } func (h *SystemHandler) mutateRuntimeTask(c *gin.Context, action types.RuntimeTaskAction) { queue, taskID, ok := runtimeTaskParams(c) if !ok { return } inspector, supported := h.taskInspector.(interfaces.RuntimeTaskInspector) if !supported { c.JSON(http.StatusServiceUnavailable, gin.H{"error": "Task queue is unavailable"}) return } task, available, err := inspector.GetRuntimeTask(c.Request.Context(), queue, taskID) if !available { c.JSON(http.StatusServiceUnavailable, gin.H{"error": "Task queue is unavailable"}) return } if err != nil || task == nil { c.JSON(http.StatusConflict, gin.H{"error": "Task is no longer available"}) return } if !task.Allows(action) { c.JSON(http.StatusConflict, gin.H{"error": "Action is not allowed for the current task state"}) return } var auditAction types.AuditAction auditDetails := map[string]string{ "task_type": task.Type, "from_state": string(task.State), "action": string(action), } switch action { case types.RuntimeTaskActionCancel: if h.knowledgeSvc == nil || task.TenantID == 0 || task.KnowledgeID == "" { c.JSON(http.StatusServiceUnavailable, gin.H{"error": "Business cancellation is unavailable"}) return } cancelCtx := context.WithValue(c.Request.Context(), types.TenantIDContextKey, task.TenantID) if _, err = h.knowledgeSvc.CancelKnowledgeParse(cancelCtx, task.KnowledgeID); err != nil { if isKnowledgeGone(err) { if h.purgeOrphanRuntimeTask(c.Request.Context(), inspector, queue, taskID, task.KnowledgeID) { logger.Warnf(c.Request.Context(), "cancel runtime queue task queue=%s task=%s: knowledge gone, purged queue record", queue, taskID) auditDetails["orphan_purge"] = "true" auditAction = types.AuditActionSystemQueueTaskCancelled break } } logger.Errorf(c.Request.Context(), "cancel runtime queue task queue=%s task=%s: %v", queue, taskID, err) c.JSON(http.StatusConflict, gin.H{"error": "Task can no longer be cancelled"}) return } auditAction = types.AuditActionSystemQueueTaskCancelled case types.RuntimeTaskActionRunNow: available, err = inspector.RunRuntimeTask(c.Request.Context(), queue, taskID) if !available { c.JSON(http.StatusServiceUnavailable, gin.H{"error": "Task queue is unavailable"}) return } if err != nil { logger.Errorf(c.Request.Context(), "run queue task now queue=%s task=%s: %v", queue, taskID, err) c.JSON(http.StatusConflict, gin.H{"error": "Task is no longer available to run"}) return } auditAction = types.AuditActionSystemQueueTaskRunNow case types.RuntimeTaskActionDelete: available, err = inspector.DeleteRuntimeTask(c.Request.Context(), queue, taskID) if !available { c.JSON(http.StatusServiceUnavailable, gin.H{"error": "Task queue is unavailable"}) return } if err != nil { logger.Errorf(c.Request.Context(), "delete queue task queue=%s task=%s: %v", queue, taskID, err) c.JSON(http.StatusConflict, gin.H{"error": "Task is no longer available for deletion"}) return } auditAction = types.AuditActionSystemQueueTaskDeleted default: c.JSON(http.StatusBadRequest, gin.H{"error": "Unknown task action"}) return } h.emitQueueTaskAudit(c.Request.Context(), auditAction, queue, taskID, auditDetails) c.JSON(http.StatusOK, gin.H{"success": true}) } func isKnowledgeGone(err error) bool { if errors.Is(err, repository.ErrKnowledgeNotFound) { return true } var appErr *apperrors.AppError return errors.As(err, &appErr) && appErr.Code == apperrors.ErrNotFound } // purgeOrphanRuntimeTask removes queue records for a task whose knowledge row // is already gone. CancelTasksForKnowledge sweeps sibling tasks best-effort; // success is reported only once the requested task ID is gone. func (h *SystemHandler) purgeOrphanRuntimeTask( ctx context.Context, inspector interfaces.RuntimeTaskInspector, queue, taskID, knowledgeID string, ) bool { if h.taskInspector != nil && knowledgeID != "" { if _, _, err := h.taskInspector.CancelTasksForKnowledge(ctx, knowledgeID); err != nil { logger.Warnf(ctx, "purge orphan tasks for knowledge %s: %v", knowledgeID, err) } } supported, err := inspector.ForceDeleteRuntimeTask(ctx, queue, taskID) if !supported { return false } if err == nil { return true } // The knowledge-wide sweep may have already removed this task ID. if _, available, getErr := inspector.GetRuntimeTask(ctx, queue, taskID); available && getErr != nil { return true } logger.Warnf(ctx, "force delete orphan task queue=%s task=%s: %v", queue, taskID, err) return false } // MutateRuntimeTask executes a backend-advertised action after re-reading the // current task state to close click/race windows. // @Summary Run a safe runtime task action // @Tags System Admin // @Produce json // @Param queue path string true "Queue name" // @Param task_id path string true "Task ID" // @Param action path string true "Action" Enums(cancel,run_now,delete) // @Success 200 {object} map[string]bool // @Router /system/admin/runtime/queues/{queue}/tasks/{task_id}/actions/{action} [post] func (h *SystemHandler) MutateRuntimeTask(c *gin.Context) { h.mutateRuntimeTask(c, types.RuntimeTaskAction(c.Param("action"))) } // PurgeArchivedRuntimeTasks clears every archived (finally-failed) task in one // queue. It only touches the archived dead-letter set — live pending/active/ // scheduled/retry tasks are untouched — and mirrors single-record delete // semantics by leaving business state as-is (archived tasks already had their // document status flipped to "failed" on their last retry). // @Summary Purge all archived tasks in a queue // @Tags System Admin // @Produce json // @Param queue path string true "Queue name" // @Success 200 {object} map[string]interface{} // @Router /system/admin/runtime/queues/{queue}/archived [delete] func (h *SystemHandler) PurgeArchivedRuntimeTasks(c *gin.Context) { queue := c.Param("queue") if !isKnownRuntimeQueue(queue) { c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid queue"}) return } inspector, supported := h.taskInspector.(interfaces.RuntimeTaskInspector) if !supported { c.JSON(http.StatusServiceUnavailable, gin.H{"error": "Task queue is unavailable"}) return } deleted, available, err := inspector.PurgeArchivedRuntimeTasks(c.Request.Context(), queue) if !available { c.JSON(http.StatusServiceUnavailable, gin.H{"error": "Task queue is unavailable"}) return } if err != nil { logger.Errorf(c.Request.Context(), "purge archived queue tasks queue=%s: %v", queue, err) c.JSON(http.StatusConflict, gin.H{"error": "Archived tasks could not be purged"}) return } h.emitQueueTaskAudit(c.Request.Context(), types.AuditActionSystemQueueArchivedPurged, queue, "", map[string]string{"deleted": strconv.Itoa(deleted)}) c.JSON(http.StatusOK, gin.H{"success": true, "deleted": deleted}) } func (h *SystemHandler) ListSystemSettings(c *gin.Context) { ctx := logger.CloneContext(c.Request.Context()) rows, err := h.systemSettingSvc.List(ctx) if err != nil { logger.Errorf(ctx, "list system settings failed: %v", err) c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to list system settings"}) return } if rows == nil { // Always emit a non-nil array so the JSON serialises to `[]` // rather than `null` on an empty table — front-end iteration // is safer. rows = []*types.SystemSetting{} } h.enrichSettingsModifiedBy(ctx, rows) c.JSON(http.StatusOK, rows) } // enrichSettingsModifiedBy resolves LastModifiedBy (UUID) → display name // in a single batch lookup. Failures degrade silently: the UI already // falls back to the UUID prefix when the name is empty, so a transient // userSvc error must not break the settings page entirely. func (h *SystemHandler) enrichSettingsModifiedBy(ctx context.Context, rows []*types.SystemSetting) { if len(rows) == 0 || h.userSvc == nil { return } idSet := make(map[string]struct{}, len(rows)) for _, r := range rows { if r != nil && strings.TrimSpace(r.LastModifiedBy) != "" { idSet[r.LastModifiedBy] = struct{}{} } } if len(idSet) == 0 { return } ids := make([]string, 0, len(idSet)) for id := range idSet { ids = append(ids, id) } users, err := h.userSvc.GetUsersByIDs(ctx, ids) if err != nil { logger.Warnf(ctx, "enrichSettingsModifiedBy: GetUsersByIDs failed: %v", err) return } for _, r := range rows { if r == nil { continue } u, ok := users[r.LastModifiedBy] if !ok || u == nil { continue } // Username is the canonical display label; fall back to email // for older rows where username may be empty (legacy seeded // admins). Both empty → leave LastModifiedByName empty so the // UI's UUID-prefix fallback kicks in. switch { case strings.TrimSpace(u.Username) != "": r.LastModifiedByName = u.Username case strings.TrimSpace(u.Email) != "": r.LastModifiedByName = u.Email } } } // GetSystemSetting godoc // @Summary Get a single system setting by key // @Description Returns the row matching :key. 404 when the key is unknown // @Description to the registry; 200 with the row when known. // @Tags System Admin // @Produce json // @Param key path string true "Setting key (e.g. file.max_size_mb)" // @Success 200 {object} types.SystemSetting "the setting row" // @Failure 400 {object} map[string]interface{} "Unknown key" // @Failure 404 {object} map[string]interface{} "Key registered but DB row absent" // @Router /system/admin/settings/{key} [get] func (h *SystemHandler) GetSystemSetting(c *gin.Context) { ctx := logger.CloneContext(c.Request.Context()) key := c.Param("key") row, err := h.systemSettingSvc.Get(ctx, key) if err != nil { // Service-layer "unknown key" surfaces as a generic error here; // distinguish via the error string rather than typed errors so // we don't grow a sentinel package for a single error class. c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()}) return } if row == nil { c.JSON(http.StatusNotFound, gin.H{"error": "setting not yet persisted"}) return } c.JSON(http.StatusOK, row) } // UpdateSystemSettingRequest is the body for PUT /system/admin/settings/:key. // `value` carries the new value as raw JSON — int / string / bool depending // on the registry-declared value_type. The service validates the type // strictly and rejects mismatches with 400. type UpdateSystemSettingRequest struct { // Value is intentionally `any` (decoded as float64 / string / bool / // etc. by the JSON unmarshaller). Service.encodeForType normalises // these against the registry's declared type and rejects mismatches. Value any `json:"value"` } // UpdateSystemSetting godoc // @Summary Update a system setting value // @Description Persist a new value for :key. Service validates the // @Description rawValue against the registry's declared value_type and // @Description rejects mismatches with 400. SystemAdmin only. Emits an // @Description audit row (action=system.setting_changed) on success. // @Tags System Admin // @Accept json // @Produce json // @Param key path string true "Setting key" // @Param request body UpdateSystemSettingRequest true "New value" // @Success 200 {object} types.SystemSetting "the updated row" // @Failure 400 {object} map[string]interface{} "Bad request / unknown key / type mismatch" // @Failure 403 {object} map[string]interface{} "Forbidden: not a system admin" // @Router /system/admin/settings/{key} [put] func (h *SystemHandler) UpdateSystemSetting(c *gin.Context) { ctx := logger.CloneContext(c.Request.Context()) key := c.Param("key") var req UpdateSystemSettingRequest if err := c.ShouldBindJSON(&req); err != nil { c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid request: " + err.Error()}) return } if req.Value == nil { c.JSON(http.StatusBadRequest, gin.H{"error": "value is required"}) return } row, err := h.systemSettingSvc.Update(ctx, key, req.Value) if err != nil { // Whether this is "unknown key" / "type mismatch" / "DB error" // is encoded in the error message at the service layer; surface // it verbatim. UI captures it as the toast text. c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()}) return } h.enrichSettingsModifiedBy(ctx, []*types.SystemSetting{row}) c.JSON(http.StatusOK, row) } // ApplyDefaultStorageQuotaToAllTenants godoc // @Summary Apply the default storage quota to every existing workspace // @Description Reads the current value of `tenant.default_storage_quota_gb` // @Description (3-tier resolver: DB > ENV > default) and writes that many // @Description GiB into storage_quota for every row in tenants. Bypasses // @Description the per-workspace PUT whitelist, which forbids storage_quota // @Description edits by Owners. SystemAdmin only. // @Description Idempotent — running twice with the same setting is a no-op. // @Tags System Admin // @Produce json // @Success 200 {object} map[string]interface{} "{ affected: int64, quota_bytes: int64 }" // @Failure 500 {object} map[string]interface{} "DB write failed" // @Router /system/admin/tenants/apply-default-storage-quota [post] func (h *SystemHandler) ApplyDefaultStorageQuotaToAllTenants(c *gin.Context) { ctx := logger.CloneContext(c.Request.Context()) // Resolve via the same 3-tier path the CreateTenant handler uses // so the action's effect mirrors what new tenants would receive. gb := h.systemSettingSvc.GetInt( ctx, "tenant.default_storage_quota_gb", "WEKNORA_TENANT_DEFAULT_STORAGE_QUOTA_GB", 10, ) if gb <= 0 { gb = 10 } quotaBytes := gb * 1024 * 1024 * 1024 affected, err := h.tenantSvc.BulkSetStorageQuota(ctx, quotaBytes) if err != nil { logger.Errorf(ctx, "BulkSetStorageQuota failed: %v", err) c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to apply storage quota"}) return } // Audit. We capture quota_bytes (the actual value written) rather // than the GB literal so the audit row is unambiguous if someone // later changes the setting's units. if h.auditSvc != nil { actorID, _ := types.UserIDFromContext(ctx) details, _ := json.Marshal(map[string]any{ "quota_bytes": quotaBytes, "quota_gb": gb, "affected": affected, }) _ = h.auditSvc.Log(ctx, &types.AuditLog{ TenantID: 0, ActorUserID: actorID, ActorRole: systemAuditActorRole(ctx), Action: types.AuditActionSystemSettingChanged, TargetType: "tenant_storage_quota", TargetID: "all", Outcome: types.AuditOutcomeSuccess, Details: types.JSON(details), }) } c.JSON(http.StatusOK, gin.H{ "affected": affected, "quota_bytes": quotaBytes, "quota_gb": gb, }) } // ResetSystemSetting godoc // @Summary Reset a system setting to ENV / built-in default // @Description Removes the DB override for :key so the 3-tier resolver // @Description falls back to the environment variable (when configured) // @Description or the in-code default. Idempotent — resetting a key // @Description that was never persisted returns 200. // @Tags System Admin // @Param key path string true "Setting key" // @Success 200 {object} map[string]interface{} "Reset acknowledged" // @Failure 400 {object} map[string]interface{} "Unknown key" // @Failure 500 {object} map[string]interface{} "DB write failed" // @Router /system/admin/settings/{key} [delete] func (h *SystemHandler) ResetSystemSetting(c *gin.Context) { ctx := logger.CloneContext(c.Request.Context()) key := c.Param("key") if err := h.systemSettingSvc.Reset(ctx, key); err != nil { // Service surfaces "unknown key" as a plain error string; treat // every error as 400 so the UI captures it as a toast. A real // DB failure here is rare and indistinguishable from "bad key" // at this layer — operators see the message either way. c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()}) return } c.JSON(http.StatusOK, gin.H{"success": true}) }