核心端点
本页按领域列出常用 HTTP API 分组;完整的操作与 Schema 索引以生成 API 参考为准。
集群接口
GET /api/v1/clustersPOST /api/v1/clustersGET /api/v1/clusters/capabilitiesGET /api/v1/clusters/:clusterID/detailGET /api/v1/clusters/:clusterID/namespacesGET /api/v1/clusters/:clusterID/infrastructure/nodesGET /api/v1/clusters/:clusterID/workloads/pods?namespace=defaultGET /api/v1/clusters/:clusterID/workloads/deployments?namespace=defaultGET /api/v1/clusters/:clusterID/workloads/statefulsets?namespace=<optional>GET /api/v1/clusters/:clusterID/network/services?namespace=<optional>GET /api/v1/clusters/:clusterID/network/ingresses?namespace=<optional>GET /api/v1/clusters/:clusterID/events?namespace=<optional>&limit=20POST /api/v1/clusters/:clusterID/workloads/deployments/restartPOST /api/v1/clusters/:clusterID/workloads/deployments/scale
/clusters/capabilities 返回供控制台、CLI、Skills 与外部集成统一消费的直连(Direct)与 Agent 运行时能力矩阵。每条记录包含能力键、所属分类、所需权限范围、风险等级、审批要求、文档链接,以及分别针对直连模式和 Agent 模式的支持状态与 partial 或 unsupported 降级原因说明。
审计接口
GET /api/v1/audit/logs
监控与告警接口
POST /api/v1/integrations/alerts/webhookGET /api/v1/monitoring/summaryGET /api/v1/alerts?status=<optional>&clusterId=<optional>&limit=50GET /api/v1/notification-channelsPOST /api/v1/notification-channelsPUT /api/v1/notification-channels/:channelID
AI 设置接口
GET /api/v1/settings/aiPUT /api/v1/settings/ai/workbench-modelPUT /api/v1/settings/ai/skills
虚拟化接口
公开契约覆盖连接、虚拟机、镜像、规格、操作、指标、控制台、同步、取消和重试接口。完整真实源路由与 Schema 请查阅生成 API 参考。
PVE 凭据仅在创建或更新请求载荷中接收,API 响应绝不回传明文凭据,仅暴露 credentialConfigured 布尔标识。
KubeVirt 虚拟化当前要求直连 Kubernetes 客户端,明确不支持 Agent 连接模式;客户端必须读取实时能力矩阵与虚拟机 allowedActions,不能假设其操作集与 PVE 完全等价。
计算资源接口
GET /api/v1/compute/capabilitiesGET /api/v1/compute/overviewGET /api/v1/compute/access-sourcesGET /api/v1/compute/providersGET /api/v1/compute/provider-instancesGET /api/v1/compute/provider-instances/:domain/:providerKey/:instanceRefPOST /api/v1/compute/provider-instances/:domain/:providerKey/:instanceRef/health-checksPOST /api/v1/compute/provider-instances/:domain/:providerKey/:instanceRef/discoveriesGET /api/v1/compute/resources/:domain/:kind/:idGET /api/v1/compute/resources/:domain/:kind/:id/relationsPOST /api/v1/compute/resources/:domain/:kind/:id/actions/:actionGET /api/v1/compute/tasksGET /api/v1/compute/tasks/:domain/:idGET /api/v1/compute/tasks/:domain/:id/logsPOST /api/v1/compute/tasks/:domain/:id/cancelPOST /api/v1/compute/tasks/:domain/:id/retry
这些路由均已在 Core 中上线,并委托给已启用的虚拟化或容器运行时后端执行。实际可用性仍取决于模块启用状态、后端能力与调用方权限。
应用与交付接口
GET /api/v1/applications?search=<optional>&limit=100POST /api/v1/applicationsGET /api/v1/applications/:applicationIDGET /api/v1/applications/:applicationID/detailGET /api/v1/applications/:applicationID/runtimeGET /api/v1/applications/:applicationID/servicesPOST /api/v1/applications/:applicationID/servicesGET /api/v1/applications/:applicationID/services/:serviceIDPUT /api/v1/applications/:applicationID/services/:serviceIDDELETE /api/v1/applications/:applicationID/services/:serviceIDPOST /api/v1/applications/:applicationID/delivery-actionsPUT /api/v1/applications/:applicationIDDELETE /api/v1/applications/:applicationIDGET /api/v1/build-templatesPOST /api/v1/build-templatesPUT /api/v1/build-templates/:buildTemplateIDDELETE /api/v1/build-templates/:buildTemplateIDGET /api/v1/delivery/environmentsGET /api/v1/application-environmentsPOST /api/v1/application-environmentsGET /api/v1/application-environments/:applicationEnvironmentIDPUT /api/v1/application-environments/:applicationEnvironmentIDDELETE /api/v1/application-environments/:applicationEnvironmentIDGET /api/v1/application-environments/:applicationEnvironmentID/detailGET /api/v1/application-environments/target-candidates?clusterId=<required>&namespace=<required>&search=<optional>GET /api/v1/workflow-templatesPOST /api/v1/workflow-templatesPUT /api/v1/workflow-templates/:workflowTemplateIDDELETE /api/v1/workflow-templates/:workflowTemplateIDPOST /api/v1/delivery/plansGET /api/v1/delivery/plans/:planIDPOST /api/v1/delivery/plans/:planID/confirmGET /api/v1/delivery/release-boardGET /api/v1/delivery/release-bundles?applicationId=<optional>&applicationEnvironmentId=<optional>&limit=50GET /api/v1/delivery/release-bundles/:bundleIDGET /api/v1/delivery/release-bundles/:bundleID/artifactsGET /api/v1/delivery/execution-tasks?applicationId=<optional>&applicationEnvironmentId=<optional>&releaseBundleId=<optional>&status=<optional>&providerKind=<optional>&limit=50GET /api/v1/delivery/execution-tasks/:taskIDGET /api/v1/delivery/execution-tasks/:taskID/artifactsGET /api/v1/delivery/artifactsPOST /api/v1/delivery/execution-tasks/:taskID/cancelPOST /api/v1/delivery/execution-tasks/:taskID/retryPOST /api/v1/delivery/execution-callbacksGET /api/v1/delivery/execution-tasks/:taskID/runner-statusGET /api/v1/builds?applicationId=<optional>&limit=50POST /api/v1/builds/triggerGET /api/v1/workflows?applicationId=<optional>&limit=50POST /api/v1/workflows/triggerPOST /api/v1/workflows/:workflowRunID/approvePOST /api/v1/workflows/:workflowRunID/rejectGET /api/v1/releases?applicationId=<optional>&clusterId=<optional>&limit=50POST /api/v1/releases/triggerGET /api/v1/integrations/gitlab/projects?search=<optional>&limit=50GET /api/v1/integrations/gitlab/branches?projectId=<required>&search=<optional>&limit=50GET /api/v1/integrations/gitlab/tags?projectId=<required>&search=<optional>&limit=50
控制台以创建并确认 DeliveryPlan 作为唯一交付写入口;直接触发构建、工作流和发布的端点继续作为兼容 API 保留。
Copilot 接口
GET /api/v1/copilot/insightsGET /api/v1/copilot/sessionsGET /api/v1/copilot/sessions/:sessionIDPOST /api/v1/copilot/sessionsPATCH /api/v1/copilot/sessions/:sessionIDDELETE /api/v1/copilot/sessions/:sessionIDGET /api/v1/copilot/sessions/:sessionID/messagesPOST /api/v1/copilot/sessions/:sessionID/messagesPOST /api/v1/copilot/sessions/:sessionID/messages/streamPOST /api/v1/copilot/global-assistant/eventsPOST /api/v1/copilot/sessions/:sessionID/analyzeGET /api/v1/copilot/root-cause/runsPOST /api/v1/copilot/root-cause/runsGET /api/v1/copilot/root-cause/runs/:runIDGET /api/v1/copilot/agent-providersGET /api/v1/copilot/agent-runsGET /api/v1/copilot/data-source-capabilitiesGET /api/v1/copilot/data-sourcesPOST /api/v1/copilot/data-sourcesPUT /api/v1/copilot/data-sources/:dataSourceIDPOST /api/v1/copilot/data-sources/:dataSourceID/validateGET /api/v1/copilot/analysis-profilesPOST /api/v1/copilot/analysis-profilesPUT /api/v1/copilot/analysis-profiles/:profileIDGET /api/v1/copilot/automation-policiesPOST /api/v1/copilot/automation-policiesPUT /api/v1/copilot/automation-policies/:policyIDGET /api/v1/copilot/inspection-tasksPOST /api/v1/copilot/inspection-tasksPUT /api/v1/copilot/inspection-tasks/:taskIDGET /api/v1/copilot/inspection-runsPOST /api/v1/copilot/inspection-tasks/:taskID/executePOST /api/v1/copilot/agent-runs/claimPOST /api/v1/copilot/agent-runs/callbackPOST /api/v1/copilot/agent-runs/tool-call
/copilot/agent-runs/claim、/copilot/agent-runs/callback 与 /copilot/agent-runs/tool-call 是面向运行器的接口,要求携带 Authorization: Bearer <runtime.execution_runner_token>(或具备对应权限的服务账号令牌)。工具调用还必须附带当次运行的专属 callbackToken;控制平面仅执行 AgentRun.toolBindings 快照中允许的工具,并将执行结果记录为 ToolExecution。
POST /copilot/root-cause/runs 接收 agentProviderId、analysisProfileId 与 triggerType。当 agentProviderId=internal 时会同步运行内置分析流程;选择 hermes 等外部执行器时,服务端会先创建排队状态的根因分析业务运行单及关联的 AgentRun,随后由运行器回调写回最终分析结果。
AI 平台接口
GET /api/v1/ai/agent-providers/catalogGET /api/v1/ai/agent-providers/runtime-statusGET /api/v1/ai/agent-providers/registry-snapshotPOST /api/v1/ai/agent-providers/registry-acksGET /api/v1/ai/agent-providers/rolloutsPOST /api/v1/ai/agent-providers/rolloutsPOST /api/v1/ai/agent-providers/rollouts/:rolloutID/:rolloutActionGET /api/v1/ai/agent-providers/conformance-runsPOST /api/v1/ai/agent-providers/conformance-runsGET /api/v1/ai/agent-runs/multi-agentPOST /api/v1/ai/agent-runs/multi-agentPOST /api/v1/ai/agent-runs/multi-agent/:planID/subtasks/:subtaskID/completePOST /api/v1/ai/agent-runs/multi-agent/:planID/cancelGET /api/v1/ai/knowledge-basesPOST /api/v1/ai/knowledge-basesGET /api/v1/ai/knowledge-bases/:baseIDPATCH /api/v1/ai/knowledge-bases/:baseIDDELETE /api/v1/ai/knowledge-bases/:baseIDGET /api/v1/ai/knowledge-bases/:baseID/sourcesPOST /api/v1/ai/knowledge-bases/:baseID/sourcesPOST /api/v1/ai/knowledge-bases/:baseID/sources/:sourceID/syncGET /api/v1/ai/knowledge-bases/:baseID/documentsGET /api/v1/ai/knowledge-bases/:baseID/sync-runsGET /api/v1/ai/knowledge-bases/:baseID/index-revisionsGET /api/v1/ai/knowledge-bases/:baseID/graph-revisionsPOST /api/v1/ai/knowledge-bases/:baseID/graph-revisionsPOST /api/v1/ai/knowledge-bases/:baseID/graph-revisions/:revisionID/publishPOST /api/v1/ai/knowledge-bases/:baseID/graph-revisions/:revisionID/queryPOST /api/v1/ai/knowledge-bases/:baseID/rebuildPOST /api/v1/ai/knowledge/searchPOST /api/v1/ai/context/inspectGET /api/v1/ai/knowledge/connectorsPOST /api/v1/ai/knowledge/connectorsPOST /api/v1/ai/knowledge/connectors/:connectorID/validatePOST /api/v1/ai/knowledge-bases/:baseID/sync-jobsGET /api/v1/ai/knowledge/sync-jobs/:jobIDPOST /api/v1/ai/knowledge/sync-jobs/:jobID/cancelPOST /api/v1/ai/knowledge/sync-jobs/:jobID/retryGET /api/v1/ai/evaluations/datasetsPOST /api/v1/ai/evaluations/datasetsGET /api/v1/ai/evaluations/runsPOST /api/v1/ai/evaluations/runsGET /api/v1/ai/evaluations/runs/:runIDGET /api/v1/ai/evaluations/runs/:runID/resultsPOST /api/v1/ai/evaluations/runs/:runID/completeGET /api/v1/ai/evaluations/executor-profilesPOST /api/v1/ai/evaluations/executor-profilesPOST /api/v1/ai/evaluations/runs/:runID/executeGET /api/v1/ai/evaluations/runs/:runID/attemptsGET /api/v1/ai/evaluations/replaysPOST /api/v1/ai/evaluations/replaysGET /api/v1/ai/evaluations/gate-policiesPOST /api/v1/ai/evaluations/gate-policiesGET /api/v1/ai/evaluations/gate-decisionsPOST /api/v1/ai/evaluations/gates/evaluateGET /api/v1/ai/evaluations/feedbackPOST /api/v1/ai/evaluations/feedbackGET /api/v1/ai/memory/policiesPOST /api/v1/ai/memory/policiesGET /api/v1/ai/memoryPOST /api/v1/ai/memoryDELETE /api/v1/ai/memory/:memoryIDGET /api/v1/ai/environments/templatesPOST /api/v1/ai/environments/templatesGET /api/v1/ai/environments/leasesPOST /api/v1/ai/environments/leases/:leaseID/releasePOST /api/v1/ai/environments/gcGET /api/v1/ai/operationsPOST /api/v1/ai/operationsGET /api/v1/ai/operations/runbook-evidence
AI Gateway 接口
公开契约 ../soha/contracts/openapi/soha-api.yaml 当前覆盖以下 AI Gateway、访问令牌、审计、审批、治理状态、模型中继与 MCP 能力边界:
GET /api/v1/ai-gateway/capabilitiesPOST /api/v1/ai-gateway/plans/validatePOST /api/v1/ai-gateway/tasksGET /api/v1/ai-gateway/tasksGET /api/v1/ai-gateway/tasks/:taskIdPOST /api/v1/ai-gateway/tasks/:taskId/resumePOST /api/v1/ai-gateway/tasks/:taskId/cancelPOST /api/v1/ai-gateway/tools/:toolName/invokePOST /api/v1/ai-gateway/resources/readPOST /api/v1/ai-gateway/prompts/getGET /api/v1/ai-gateway/personal-access-tokensPOST /api/v1/ai-gateway/personal-access-tokensPOST /api/v1/ai-gateway/personal-access-tokens/:tokenID/revokePOST /api/v1/ai-gateway/personal-access-tokens/:tokenID/rotateGET /api/v1/ai-gateway/service-accountsPOST /api/v1/ai-gateway/service-accountsGET /api/v1/ai-gateway/service-account-tokensPOST /api/v1/ai-gateway/service-accounts/:serviceAccountID/tokensPOST /api/v1/ai-gateway/service-account-tokens/:tokenID/revokePOST /api/v1/ai-gateway/service-account-tokens/:tokenID/rotatePOST /api/v1/ai-gateway/governed-credentials/personal-access-tokensPOST /api/v1/ai-gateway/governed-credentials/personal-access-tokens/:tokenID/rotatePOST /api/v1/ai-gateway/governed-credentials/service-accounts/:serviceAccountID/tokensPOST /api/v1/ai-gateway/governed-credentials/service-account-tokens/:tokenID/rotateGET /api/v1/ai-gateway/audit-logsGET /api/v1/ai-gateway/approval-requestsGET /api/v1/ai-gateway/approval-requests/:requestID/timelinePOST /api/v1/ai-gateway/approval-requests/:requestID/:actionPOST /api/v1/ai-gateway/approval-requests/:requestID/approvePOST /api/v1/ai-gateway/approval-requests/:requestID/rejectPOST /api/v1/ai-gateway/approval-requests/:requestID/cancelGET /api/v1/ai-gateway/governance/statusGET /api/v1/ai-gateway/relay/upstreamsPOST /api/v1/ai-gateway/relay/upstreamsPUT /api/v1/ai-gateway/relay/upstreams/:upstreamIDPOST /api/v1/ai-gateway/relay/upstreams/testPOST /api/v1/ai-gateway/relay/upstreams/health-checks/runPOST /api/v1/ai-gateway/relay/upstreams/:upstreamID/testGET /api/v1/ai-gateway/relay/model-routesPOST /api/v1/ai-gateway/relay/model-routesPUT /api/v1/ai-gateway/relay/model-routes/:routeIDDELETE /api/v1/ai-gateway/relay/model-routes/:routeIDGET /api/v1/ai-gateway/relay/model-callsGET /api/v1/ai-gateway/relay/metricsGET /api/v1/ai-gateway/llm/openai/v1/modelsPOST /api/v1/ai-gateway/llm/openai/v1/chat/completionsPOST /api/v1/ai-gateway/llm/openai/v1/responsesPOST /api/v1/ai-gateway/llm/openai/v1/embeddingsPOST /api/v1/ai-gateway/llm/openai/v1/images/generationsPOST /api/v1/ai-gateway/llm/openai/v1/images/editsPOST /api/v1/ai-gateway/llm/openai/v1/images/variationsPOST /api/v1/ai-gateway/llm/openai/v1/audio/speechPOST /api/v1/ai-gateway/llm/openai/v1/audio/transcriptionsPOST /api/v1/ai-gateway/llm/openai/v1/audio/translationsGET /api/v1/ai-gateway/llm/openai/v1/realtimeGET /api/v1/ai-gateway/llm/:openaiCompatibleProvider/v1/modelsPOST /api/v1/ai-gateway/llm/:openaiCompatibleProvider/v1/chat/completionsPOST /api/v1/ai-gateway/llm/:openaiCompatibleProvider/v1/responsesPOST /api/v1/ai-gateway/llm/:openaiCompatibleProvider/v1/embeddingsPOST /api/v1/ai-gateway/llm/:openaiCompatibleProvider/v1/images/generationsPOST /api/v1/ai-gateway/llm/:openaiCompatibleProvider/v1/images/editsPOST /api/v1/ai-gateway/llm/:openaiCompatibleProvider/v1/images/variationsPOST /api/v1/ai-gateway/llm/:openaiCompatibleProvider/v1/audio/speechPOST /api/v1/ai-gateway/llm/:openaiCompatibleProvider/v1/audio/transcriptionsPOST /api/v1/ai-gateway/llm/:openaiCompatibleProvider/v1/audio/translationsGET /api/v1/ai-gateway/llm/gemini/v1beta/modelsPOST /api/v1/ai-gateway/llm/gemini/v1beta/modelsPOST /api/v1/ai-gateway/llm/gemini/v1beta/models/:geminiModel:generateContentPOST /api/v1/ai-gateway/llm/gemini/v1beta/models/:geminiModel:streamGenerateContentPOST /api/v1/ai-gateway/llm/gemini/v1beta/interactionsPOST /api/v1/ai-gateway/llm/cohere/v2/rerankGET /api/v1/ai-gateway/llm/anthropic/v1/modelsPOST /api/v1/ai-gateway/llm/anthropic/v1/messagesGET /api/v1/mcp/capabilities
插件市场接口
GET /api/v1/marketplace/index.jsonGET /api/v1/marketplace/plugins/:pluginID/:version/plugin.manifest.json
同一 OpenAPI 工件中已预留、但当前后端尚未挂载路由的中继缓存契约端点:
GET /api/v1/ai-gateway/relay/cache/statsPOST /api/v1/ai-gateway/relay/cache/purge
/ai-gateway/capabilities 返回经后端权限过滤后对当前调用主体可见的 AI 原生工具、资源、提示词和技能清单。建议 AI 客户端在可用时附带 X-Soha-AI-Client-ID、X-Soha-AI-Client 与 X-Soha-Skill-ID 请求头,以便审计记录清晰区分人类用户、服务账号、客户端应用、技能与具体工具调用上下文。
/ai-gateway/plans/validate 在执行前校验能力计划;/ai-gateway/tasks 创建和列出持久化任务,每一步执行时都会重新检查权限和当前条件。恢复任务会创建新的计划版本;取消任务不会回滚已完成步骤的副作用。
/ai-gateway/tools/:toolName/invoke 是 MCP、CLI 与 AI 智能体共用的统一工具调用入口。该接口必须逐次复核 Gateway 权限、领域权限、资源范围(Scope)、工具授权(Grant)及风险策略,随后委托给所属业务应用服务执行,不得绕过 soha 控制平面逻辑。
/ai-gateway/resources/read 与 /ai-gateway/prompts/get 是完全收敛在后端的 MCP 资源读取与提示词获取边界。本地 soha mcp 进程仅代理转发这些请求,不在客户端本地拼装受权限保护的资源文档或提示词内容。
/ai-gateway/governance/status 是只读的 Gateway 治理运营概览端点,用于汇总近期审计统计、待处理审批、令牌与客户端风险发现、策略覆盖率、高风险护栏巡检结果、敏感字段脱敏覆盖率以及资源范围绑定覆盖率。
/ai-gateway/approval-requests/:requestID/:action 支持 approve、reject 与 cancel 三种动作;上方同时列出了展开后的具体动作路径,供 CLI 与运维手册直接调用。审批通过后的重放执行仍在 Gateway 应用服务内完成,并会重新校验原始工具授权、访问策略、技能绑定、当前有效权限与目标业务服务的授权规则。
/ai-gateway/relay/* 用于管理模型中继上游(Upstream)、模型路由规则、模型调用日志与运行指标;响应缓存统计与清理契约预留给后续响应缓存阶段。管理类接口统一采用 OpenSoha 标准响应信封,并要求具备中继查看或管理权限。
/ai-gateway/llm/* 面向标准模型 SDK 暴露 OpenAI、Anthropic、Gemini、Cohere 以及 OpenAI 兼容提供商接口,覆盖模型发现、对话与 Responses、向量嵌入(Embeddings)、图像与音频处理、实时流(Realtime)以及重排序(Rerank)等上游支持的能力。这些端点通过 Authorization: Bearer 或 x-api-key 接收既有的 soha_pat_ 与 soha_sat_ 凭据,要求令牌显式包含中继授权元数据,并直接返回原生提供商格式的 JSON 或流式响应,不额外包裹 OpenSoha 响应信封。
公开契约状态(Public OpenAPI contract status)
-
已纳入公开契约的 Gateway 运行时、令牌、审计、审批、治理与 MCP 能力端点均已列于上方,并由测试脚本自动核对
../soha/contracts/openapi/soha-api.yaml。 -
待纳入契约(Pending contracts addition — not yet included in the public OpenAPI artifact):以下控制台管理端点已在 Core 与 Web 的 Gateway 工作台中实现,但尚未写入公开 OpenAPI 契约工件:
-
GET /api/v1/ai-gateway/ai-clients -
POST /api/v1/ai-gateway/ai-clients -
PUT /api/v1/ai-gateway/ai-clients/:clientID -
GET /api/v1/ai-gateway/tool-grants -
POST /api/v1/ai-gateway/tool-grants -
DELETE /api/v1/ai-gateway/tool-grants/:grantID -
GET /api/v1/ai-gateway/access-policies -
POST /api/v1/ai-gateway/access-policies -
PUT /api/v1/ai-gateway/access-policies/:policyID -
DELETE /api/v1/ai-gateway/access-policies/:policyID -
GET /api/v1/ai-gateway/skill-bindings -
POST /api/v1/ai-gateway/skill-bindings -
PUT /api/v1/ai-gateway/skill-bindings/:bindingID -
DELETE /api/v1/ai-gateway/skill-bindings/:bindingID
当前内置 Gateway 工具名称清单:
delivery.applications.listdelivery.applications.detaildelivery.applications.createdelivery.application_environments.listdelivery.application_services.listdelivery.build_sources.listdelivery.release_targets.listdelivery.actions.triggerdelivery.release_bundles.listdelivery.execution_tasks.listdelivery.execution_logs.listdelivery.workflow_templates.listdelivery.release_context.diffdelivery.rollback.contextk8s.pods.listk8s.pods.logsk8s.pods.describek8s.deployments.listk8s.deployments.rollout_statusk8s.deployments.eventsk8s.services.listk8s.services.backendsk8s.routes.contextk8s.storage.contextk8s.nodes.detailk8s.events.listdiagnosis.release_failure.analyze
Kubernetes 相关工具均为只读工具,统一通过平台资源应用服务路由执行;Gateway 在将日志返回给 MCP 或 CLI 调用方前会对常见敏感字段执行基础脱敏。
个人访问令牌(PAT)与服务账号令牌(SAT)在创建和轮换响应中仅一次性返回明文令牌值;数据库只持久化哈希值与显示前缀,调用方必须将返回的明文凭据妥善保存在本地 CLI 或 MCP 凭据存储中。
AI 客户端、工具授权、访问策略与技能绑定管理端点均要求 ai.gateway.manage 权限。工具授权、访问策略与技能绑定支持 user、service_account、role 与 ai_client 四类主体;运行时评估会合并主体、角色与客户端维度的规则:拒绝(Deny)策略与授权始终优先,允许(Allow)记录构成白名单,技能绑定仅用于收敛可见的技能与能力引用,不会额外放大已有权限。
每次工具调用都会同时写入平台标准审计表与 ai_gateway_audit_logs 专用审计表。AI Gateway 专用审计记录保存操作者、AI 客户端、技能、工具名称、风险等级、资源范围、请求/结果状态及关联单据 ID,不会落盘完整令牌、kubeconfig、原始容器日志或未裁剪的全量工具输入。
应用请求载荷示例
{
"id": "billing-api",
"name": "Billing API",
"key": "billing-api",
"group": "commerce",
"language": "Go",
"description": "Core billing service",
"ownerTeam": "platform",
"repositoryProvider": "gitlab",
"repositoryProjectId": "12345",
"repositoryPath": "platform/billing-api",
"defaultBranch": "main",
"defaultTag": "v1.0.0",
"buildImage": "registry.example.com/platform/billing-api",
"buildContextDir": ".",
"dockerfilePath": "Dockerfile",
"buildSources": [
{
"id": "default:billing-api",
"name": "Repository Dockerfile",
"type": "repo_dockerfile",
"enabled": true,
"isDefault": true,
"buildImage": "registry.example.com/platform/billing-api",
"defaultTag": "v1.0.0",
"config": {
"contextDir": ".",
"dockerfilePath": "Dockerfile",
"builderKind": "docker"
}
}
],
"enabled": true,
"metadata": {
"tier": "core"
}
}构建触发载荷示例
{
"applicationId": "billing-api",
"applicationEnvironmentId": "binding-prod",
"buildSourceId": "default:billing-api",
"refType": "branch",
"refName": "main",
"imageTag": "billing-api:manual-20260322",
"buildArgs": {
"profile": "default"
},
"variables": {
"GO_VERSION": "1.24"
}
}执行回调载荷示例
{
"callbackToken": "task-callback-token",
"status": "completed",
"payload": {
"logs": [
"checkout source",
"build image completed"
],
"image": "registry.example.com/platform/billing-api:20260505",
"imageDigest": "sha256:..."
}
}告警 Webhook 载荷示例
{
"source": "alertmanager",
"alerts": [
{
"fingerprint": "cpu-high-prod-1",
"title": "CPUHigh",
"summary": "CPU usage exceeded threshold",
"severity": "critical",
"status": "firing",
"clusterId": "local",
"namespace": "default",
"labels": {
"alertname": "CPUHigh",
"team": "platform"
},
"annotations": {
"runbook": "https://example.internal/runbooks/cpu-high"
},
"receiver": "platform-default",
"generatorUrl": "http://prometheus.local/graph"
}
]
}请求头:
X-Soha-Webhook-Token: <monitoring.webhook_token>或Authorization: Bearer <monitoring.webhook_token>
通知渠道载荷示例
{
"id": "platform-default-webhook",
"name": "Platform Default Webhook",
"channelType": "webhook",
"enabled": true,
"config": {
"url": "https://notify.example.internal/hooks/platform-alerts",
"method": "POST"
}
}集群注册载荷示例
直连 kubeconfig 模式
{
"id": "direct-prod-01",
"name": "Direct Production 01",
"region": "cn-shanghai",
"environment": "production",
"labels": {
"provider": "kubeconfig",
"owner": "platform"
},
"connectionMode": "direct_kubeconfig",
"kubeconfig": "apiVersion: v1\n..."
}Agent 连接模式
{
"id": "edge-prod-01",
"name": "Edge Production 01",
"region": "cn-shanghai",
"environment": "production",
"labels": {
"provider": "agent",
"owner": "platform"
},
"connectionMode": "agent",
"agentEndpoint": "https://agent.example.internal",
"agentToken": "optional-bearer-token"
}