KnoAI 技术站

主题

K8s 多集群管理平台 · 需求规格说明书 v2.1 ​

文档信息 ​

字段内容
文档版本v2.1
对应设计文档系统设计文档 v2.1
编写日期2026-07-31
状态待评审
变更摘要v2.0 → v2.1：新增性能优化需求（分页/缓存/字段裁剪/Watch增量/虚拟滚动）、应用负责人绑定与飞书告警通知需求

一、功能需求清单 ​

FR-01：集群管理 ​

ID需求描述优先级验收标准
FR-01-01支持注册新集群（录入名称、API 地址、kubeconfig）P0注册后自动校验连通性，成功/失败给出明确提示
FR-01-02支持查看集群列表和健康状态P0显示 apiserver / etcd / node Ready 状态，异常标红
FR-01-03支持同步集群节点信息到平台数据库P0节点信息包含：名称、IP、规格、Labels、Taints、Conditions、Allocatable
FR-01-04支持编辑 / 删除集群P1删除前校验无应用在使用该集群，有则拒绝并提示
FR-01-05集群连接信息 AES-256 加密存储P0数据库中的 kubeconfig / token 字段不可明文读取

FR-02：域（Zone）管理 ​

ID需求描述优先级验收标准
FR-02-01支持创建 / 编辑 / 删除域P0创建域时配置：名称、超卖比、HPA 默认值、ResourceQuota、污点策略
FR-02-02支持将节点分配到指定域（打 Label）P0节点打标后，已有 Pod 不受影响，新 Pod 按亲和性调度
FR-02-03支持查看域资源水位（Request / Limit / Actual）P0数据刷新间隔 ≤ 10s（WebSocket 增量），饱和度颜色正确
FR-02-04隐私域创建时自动配置 NetworkPolicy Deny AllP0新建隐私域 NS 时自动创建 Default Deny NetworkPolicy
FR-02-05异常观察域支持设置 TTL，到期后自动缩容P1TTL 到期前 3 天提醒，到期后 Pod 缩到 0，数据保留 7 天
FR-02-06域删除前校验无应用在使用P0有运行中的应用则拒绝删除并列出应用清单

FR-03：标签管理 ​

ID需求描述优先级验收标准
FR-03-01平台维护标签字典（枚举值），用户从字典中选择P0字典覆盖所有系统标签和业务标签，自由输入被拒绝
FR-03-02应用发布时未指定域标签，自动注入默认域P0注入同时记录审计日志，看板标注 "⚠️ 未指定域"
FR-03-03支持查看标签漂移（节点标签与实际调度不匹配）P1列出所有不一致的节点和应用，标注漂移方向
FR-03-04AI 标签命名建议：用户输入自由标签时推荐标准化名称P2推荐准确率 > 80%（人工抽检 100 条）
FR-03-05标签变更影响分析P2输入节点标签变更 → AI 给出受影响的应用列表

FR-04：应用管理 ​

ID需求描述优先级验收标准
FR-04-01支持从模板创建应用P0内置至少 3 种模板（微服务 / 批处理 / 前端静态）
FR-04-02支持从镜像创建应用P0填入镜像地址后自动解析端口和健康检查路径
FR-04-03支持查看应用列表（虚拟滚动 + 分页）P0万级数据首屏 < 1s，滚动 60fps 不卡顿
FR-04-04应用列表只返回摘要字段（fields=summary）P0默认响应体单条 < 2KB，不含 spec.template 完整定义
FR-04-05支持应用详情页按需加载各 Tab 数据P0首屏基本信息 < 500ms，其他 Tab 点击后 < 2s
FR-04-06支持应用发布（RollingUpdate）P0发布过程可视化，可暂停 / 继续 / 回滚
FR-04-07支持一键回滚到指定历史版本P0回滚后验证 Pod 状态，记录操作日志
FR-04-08支持手动扩缩容和 HPA 配置P0HPA 生效后看板显示当前副本数和目标
FR-04-09支持 ConfigMap / Secret 版本化管理P1修改 ConfigMap 后可触发滚动重启
FR-04-10支持查看 Pod 日志和 Web 终端P1日志支持关键字搜索和时间范围筛选
FR-04-11支持查看 K8s Events 时间线P1按时间倒序，支持按类型过滤
FR-04-12发布前 AI 风险评估P2对比新旧版本 diff，输出风险等级和高 / 中 / 低建议
FR-04-13发布后 AI 智能回滚判断P2发布后 5xx 飙升自动弹出回滚建议
FR-04-14应用负责人绑定P0创建 / 编辑应用时可搜索添加负责人（用户 / 团队），支持多负责人
FR-04-15负责人通知渠道配置P0每个负责人可独立配置飞书 / 邮件渠道和告警级别（全部 / 仅严重 / 不接收）
FR-04-16负责人降级策略P0无负责人时降级到域管理员 → 超级管理员

FR-05：智能看板 ​

ID需求描述优先级验收标准
FR-05-01全局总览：所有域卡片式排列，显示关键指标P0包含：节点数、Pod 数、Request%、Limit%、Actual%、饱和度
FR-05-02域详情：节点列表 + 应用 TopN + 时序图P0时序图支持 1h / 24h / 7d 切换
FR-05-03节点 / 应用详情：Pod 级明细P0显示每个 Pod 的 CPU / Mem Request / Limit / Actual
FR-05-04看板数据通过 WebSocket 增量推送P0事件到前端渲染延迟 < 500ms
FR-05-05看板数据三级缓存（L1 内存 5s / L2 Redis 30s / L3 K8s API）P0L1 命中率 > 50%，L2 命中率 > 80%
FR-05-06AI 异常标记：在看板上标注异常波动点P1点击异常点可查看 AI 分析的根因假设
FR-05-07自然语言查询："核心域过去 24h OOM 最多的 5 个应用"P2AI 生成 PromQL 并返回结果表格

FR-06：监控 & 告警 ​

ID需求描述优先级验收标准
FR-06-01每集群独立 Prometheus 采集，平台通过 VM 聚合查询P0看板数据来自 VM 统一查询接口
FR-06-02内置基础设施告警规则（节点 NotReady / etcd 切换等）P0告警触发后 5s 内出现在平台告警列表
FR-06-03支持用户自定义告警规则（PrometheusRule）P1提供表单和 YAML 两种编辑方式
FR-06-04告警通知：飞书 / 邮件 / WebhookP0按域路由到不同接收组，按负责人精准触达
FR-06-05飞书告警卡片消息P0卡片包含：应用名 / 集群 / 域 / 时间 / 指标值 / AI 分析 / 操作按钮
FR-06-06飞书卡片交互按钮（查看详情 / AI 诊断 / 一键回滚）P0点击按钮跳转平台对应页面（需登录鉴权）
FR-06-07告警风暴防护P0同应用 5min 内多条告警合并；单应用每分钟最多 3 条通知
FR-06-08AI 告警降噪：同域 5min 内多条告警聚合为一条P1聚合后显示根因假设 + 影响范围
FR-06-09AI 告警规则生成："P99>1s 告警" → 自动生成 PromQLP2生成结果可预览和微调

FR-07：RBAC & 审计 ​

ID需求描述优先级验收标准
FR-07-01三级角色：超级管理员 / 域管理员 / 只读用户P0域管理员只能看到自己管理的域
FR-07-02支持用户增删改查P0密码 bcrypt 加密存储
FR-07-03所有写操作记录审计日志（append-only）P0日志包含：用户、时间、操作、对象、变更前后；禁止 UPDATE / DELETE
FR-07-04审计日志支持按条件检索和导出P1支持按用户 / 时间 / 资源类型过滤，导出 CSV
FR-07-05AI 操作独立审计（ai_tool_audit 表）P1记录 AI 的每次 Tool 调用和结果
FR-07-06隐私域操作额外存证（不可篡改日志）P0使用独立日志通道，WORM 存储

FR-08：AI 智能体（Copilot） ​

ID需求描述优先级验收标准
FR-08-01Copilot 侧边栏：随时唤出对话界面P1不离开当前页面即可对话
FR-08-02对话支持流式输出（SSE）P1打字机效果，token 级流式
FR-08-03支持多轮对话和上下文记忆P1同一会话内可追问，跨会话不混淆
FR-08-04知识库管理：支持导入 K8s 文档和平台手册P2上传 PDF / Markdown 后自动向量化
FR-08-05AI 洞察中心：集中展示 AI 生成的建议P1每条洞察可确认 / 忽略 / 执行
FR-08-06安全护栏：危险操作二次确认P0DELETE / DRAIN 等操作必须用户点确认
FR-08-07安全护栏：AI 权限 ≤ 用户权限P0只读用户通过 AI 也不能执行写操作
FR-08-08安全护栏：隐私域数据只走本地模型P0隐私域查询时强制路由到本地 Ollama
FR-08-09安全护栏：AI 回答需附带数据来源P0数据类回答标注 PromQL / 日志来源

FR-09：AI 辅助排障 ​

ID需求描述优先级验收标准
FR-09-01应用详情页 "AI 诊断" 按钮，点击后执行诊断P130 秒内返回诊断结果
FR-09-02规则引擎覆盖 10 种常见故障P1每种故障命中时置信度 ≥ 75%
FR-09-03LLM 参与复杂日志分析和多信号关联P1输出结构化 JSON：根因 + 证据 + 建议
FR-09-04诊断结果展示：根因 + 证据链 + 修复建议 + 操作按钮P1低风险操作可一键执行，高风险需确认
FR-09-05告警触发时自动后台诊断，结果推送飞书P1推送包含根因 + 一键回滚按钮
FR-09-06诊断结果反馈收集（有帮助 / 无帮助）P2反馈数据存入数据库，用于模型迭代
FR-09-07排障知识沉淀：成功诊断自动生成知识库草稿P2草稿经人工审核后正式入库
FR-09-08知识库命中时直接给出方案（不调 LLM，秒级）P2命中后响应时间 < 1s

FR-10：🆕 性能优化 ​

ID需求描述优先级验收标准
FR-10-01应用列表使用游标分页（K8s Continue Token）P0万级数据翻页无性能衰减，无 offset
FR-10-02应用列表默认只返回摘要字段（fields=summary）P0默认 12 字段，单条 < 2KB；full 模式需显式指定
FR-10-03前端虚拟滚动渲染列表P0DOM 节点恒定 < 50 个，万级列表 60fps
FR-10-04三级缓存架构（L1 内存 5s / L2 Redis 30s / L3 K8s API）P0L1 命中率 > 50%，L2 命中率 > 80%
FR-10-05Write-Through 缓存失效（Watch 事件触发）P0数据变更后缓存 5s 内失效
FR-10-06WebSocket 增量推送（替代看板轮询）P0事件到渲染 < 500ms，HTTP 请求量减少 90%
FR-10-07应用详情页 Tab 懒加载P0首屏 < 500ms，非首屏 Tab 点击 < 2s
FR-10-08后端并行查询（goroutine pool，max 10）P0列表加载从 3s → 800ms
FR-10-09搜索防抖（300ms）P0输入停止 300ms 后才发送请求
FR-10-10告警风暴防护（合并 / 限速 / 静默）P0告警量下降 70%

FR-11：🆕 应用负责人 & 飞书通知 ​

ID需求描述优先级验收标准
FR-11-01应用创建 / 编辑时可绑定负责人（用户 / 团队）P0支持搜索用户、多选、设置主备
FR-11-02每个负责人独立配置通知渠道（飞书 / 邮件 / Webhook）P0渠道开关独立，可组合
FR-11-03每个负责人独立配置告警级别（全部 / 仅严重 / 不接收）P0级别过滤在路由层生效
FR-11-04飞书群机器人 Webhook 通知P0发送卡片消息，包含应用信息 + AI 分析 + 操作按钮
FR-11-05飞书卡片支持交互按钮（查看详情 / AI 诊断 / 一键回滚 / 认领 / 静默）P0按钮点击跳转平台对应页面
FR-11-06飞书个人消息通知（需用户绑定 open_id）P2通过 open_id 发送个人卡片消息
FR-11-07用户飞书绑定流程（OAuth2 授权）P2点击绑定 → 跳转飞书授权 → 回调获取 open_id
FR-11-08通知降级策略（负责人 → 域管理员 → 超级管理员）P0每级都有超时（5min），超时自动升级
FR-11-09通知日志记录（谁 / 什么告警 / 什么渠道 / 是否成功 / 是否点击）P0日志保留 90 天，支持查询统计
FR-11-10通知效果分析（告警响应时间 / 黑洞识别）P2统计面板，按负责人 / 应用 / 域维度

二、非功能需求 ​

ID需求描述量化指标验收方式
NFR-01平台 API 响应时间列表 < 1s（走缓存），详情 < 2s，P99 < 3s压测工具验证
NFR-02并发支持50 并发用户操作无报错压测：50 并发持续 10min
NFR-03数据安全kubeconfig AES-256 加密；HTTPS 全站；密码 bcrypt安全审计 + 渗透测试
NFR-04平台自身可用性99.9%（年度停机 < 8.76h）监控平台自身 uptime
NFR-05兼容性Kubernetes 1.24 ~ 1.30多版本测试矩阵
NFR-06浏览器兼容Chrome 100+, Firefox 100+, Edge 100+手动验证
NFR-07AI 响应时间规则命中 < 3s；LLM 诊断 < 30s；流式首字 < 2s计时验证
NFR-08列表性能万级应用列表首屏 < 1s，滚动 60fpsChrome DevTools 性能分析
NFR-09缓存命中率L1 > 50%，L2 > 80%Redis INFO + 应用 metrics
NFR-10WebSocket 可靠性断线重连成功率 100%，指数退避最大 30s网络模拟测试
NFR-11通知可达性飞书通知送达率 > 99%，P99 延迟 < 5s通知日志统计
NFR-12审计完整性审计日志零丢失，append-only 不可篡改定期校验 + WORM 测试

三、数据需求 ​

ID需求描述存储方式保留期限
DR-01平台业务数据（集群/域/应用/用户）PostgreSQL永久
DR-02指标数据（CPU/Mem/QPS 等）VictoriaMetrics90 天
DR-03日志数据（容器日志 / 平台日志）Loki / ES普通域 30 天，隐私域 90 天
DR-04AI 对话历史和知识库向量PostgreSQL（PGVector 扩展）对话 90 天，知识库永久
DR-05kubeconfig 等敏感字段AES-256 加密存储永久
DR-06审计日志append-only，禁止 UPDATE / DELETE永久
DR-07通知日志PostgreSQL90 天
DR-08告警事件PostgreSQL180 天

四、接口需求 ​

ID需求描述协议 / 格式
IR-01平台提供 RESTful APIJSON over HTTPS
IR-02API 认证使用 JWT Bearer TokenAuthorization: Bearer <token>
IR-03AI 对话接口使用 SSE（Server-Sent Events）流式返回text/event-stream
IR-04看板增量数据使用 WebSocket 推送WS / WSS
IR-05外部 CI 系统通过 API 触发发布Webhook（HMAC 签名验证）
IR-06告警通知通过 Webhook 推送到飞书飞书开放平台 API
IR-07飞书卡片按钮回调接收飞书事件订阅（加密验证）

五、约束与假设 ​

类型内容
约束目标用户为运维人员，界面可适当专业，不需过度简化
约束平台自身部署在虚拟机 / 物理机上，不依赖 K8s
约束隐私域必须使用独立集群
约束LLM 推理必须支持私有化部署
约束飞书通知 Phase 1 仅支持群机器人 Webhook，个人消息 Phase 2
假设每个业务团队拥有一个或多个 Namespace
假设每个集群至少有 2 个可用区（AZ）
假设公司已部署 Prometheus 和 VictoriaMetrics
假设公司已开通飞书开放平台，可创建企业自建应用

六、性能优化需求详述 ​

6.1 应用列表分页 ​

需求点说明
分页方式使用 K8s 原生 Continue Token（游标分页），不使用 offset
默认页大小20 条 / 页，最大 50 条 / 页
响应字段默认 fields=summary（12 字段），可选 basic（~30 字段）/ full（全部）
排序规则默认按异常程度降序（Error → Degraded → Healthy），其次按名称字母序
搜索前端 300ms 防抖后发送，支持应用名模糊匹配
筛选域筛选 / 状态筛选 / 团队筛选，组合条件 AND 逻辑

6.2 前端虚拟滚动 ​

需求点说明
组件vue-virtual-scroller 的 RecycleScroller
行高固定 56px
DOM 节点可视区域约 15-20 行，恒定 < 50 个 DOM 节点
触底加载滚动到距底部 200px 时触发 loadMore
筛选切换重置列表 + 从头加载（清空 next_token）
增量更新WebSocket 收到变更 → 更新对应行（不重新拉列表）

6.3 三级缓存 ​

层级存储TTL命中率目标失效策略
L1本地内存（sync.Map）5s> 50%Watch 事件触发立即失效
L2Redis30s> 80%（含 L1）Write-Through + TTL 兜底
L3K8s API-兜底List + Watch 增量

6.4 WebSocket 增量推送 ​

需求点说明
连接时机进入看板 / 应用列表页时建立
参数cluster_id（必选）+ zone（可选）
消息类型ADDED / MODIFIED / DELETED / ALERT_FIRING / ALERT_RESOLVED
重连策略指数退避：1s → 2s → 4s → ... → 最大 30s
心跳每 30s 发送 ping，60s 无 pong 则断开重连

6.5 详情页懒加载 ​

Tab加载时机数据量目标耗时
基本信息首屏立即加载~8KB< 500ms
Pod 列表点击 Tab 时加载~5KB< 1s
日志点击 Tab + 选择容器后加载按需< 2s
事件点击 Tab 时加载~3KB< 1s
监控点击 Tab 时加载时序数据< 2s
配置点击 Tab 时加载~2KB< 500ms
YAML点击 Tab 时加载（仅高级用户）~50KB< 2s

七、飞书通知需求详述 ​

7.1 飞书集成方案 ​

Phase能力说明
Phase 1群机器人 Webhook简单，无需用户授权，发到团队群
Phase 2个人消息（open_id）需用户 OAuth2 绑定，精准到个人

7.2 飞书卡片消息规格 ​

元素内容
Header严重等级图标 + 标题（应用名 + 告警摘要）
正文应用 / 集群 / 域 / 时间 / 指标值 / 影响范围
AI 分析区根因假设 + 置信度 + 证据摘要
操作按钮查看详情（primary）/ AI 诊断（default）/ 一键回滚（danger）/ 认领 / 静默
页脚平台链接 + 通知 ID（用于追踪）

7.3 通知降级流程 ​

Level 0: 应用负责人（飞书群 + 邮件）
    │ 5min 内未响应（无点击 / 无认领）
    ▼
Level 1: 域管理员（飞书群）
    │ 5min 内未响应
    ▼
Level 2: 超级管理员（飞书 + 邮件 + 电话）
    │ 仍无响应
    ▼
Level 3: 写入告警池（平台内可见）+ 日志记录

7.4 通知效果追踪 ​

指标计算方式用途
送达率成功发送数 / 总发送数监控飞书服务健康
响应时间首次点击时间 - 发送时间评估负责人响应速度
黑洞识别某负责人 7 天内告警响应率 < 20%提醒管理员调整负责人
告警收敛率合并后告警数 / 原始告警数评估降噪效果

八、待定事项（Open Issues） ​

#问题决策状态
OI-01告警自动诊断的范围仅手动触发，告警产生后不自动调用 AI 诊断，运维点击按钮后执行✅ 已确认
OI-02排障知识库是否对开发团队开放开放，新增 developer 角色，只读知识库 + 脱敏日志✅ 已确认
OI-03本地 LLM 的 GPU 资源配置需配置 GPU 节点，推荐 A100 80G×1 或 A6000 48G×2✅ 已确认
OI-04是否需要对接公司 LDAP/SSO对接 LDAP，Phase 1 即引入，LDAP group 映射平台角色✅ 已确认
OI-05飞书通知方式Phase 1 仅群机器人，Phase 2 加个人消息✅ 已确认
OI-06列表页默认排序规则按异常程度（Error 排最前）✅ 已确认

九、O-I 决策影响分析 ​

9.1 OI-01：仅手动触发 AI 诊断 ​

9.1.1 需求变更 ​

原需求变更后
FR-09-05：告警触发时自动后台诊断，结果推送飞书改为：告警产生后，在告警详情页和飞书卡片显示 [🤖 AI 诊断] 按钮，运维手动点击后触发诊断

9.1.2 新增需求 ​

ID需求描述优先级验收标准
FR-09-09告警详情页显示 [🤖 AI 诊断] 按钮P1按钮在所有非 resolved 状态的告警上可见
FR-09-10飞书告警卡片包含 [🤖 AI 诊断] 按钮P1点击跳转平台并自动执行诊断
FR-09-11AI 诊断历史与告警关联P1同一告警的多次诊断记录在告警详情页可查看

9.1.3 设计影响 ​

变更前：
  告警产生 → 自动后台诊断 → 结果推送飞书

变更后：
  告警产生 → 写入告警列表 → 展示 [AI 诊断] 按钮
                                      │
                              运维点击按钮
                                      ▼
                            执行 AI 诊断流程
                                      │
                              结果展示 + 推送飞书

好处：
├── 节省 LLM 算力（大量告警不需要诊断）
├── 避免误判干扰（AI 诊断不是 100% 准确）
├── 运维按需使用，体验更好
└── 不改变告警本身的通知链路（飞书通知照常发送）

9.1.4 算力节省估算 ​

假设：每天 500 条告警，其中 20% 需要诊断
变更前：500 × LLM 调用/天
变更后：100 × LLM 调用/天
节省：80% 算力

9.2 OI-02：排障知识库对开发开放 ​

9.2.1 新增角色：developer ​

属性说明
角色标识developer
认证方式LDAP（cn=developers group 自动映射）
权限范围只读：知识库 + 应用基本信息（脱敏）+ 应用日志（脱敏）
不可操作发布 / 回滚 / 扩缩 / 删除 / 配置修改

9.2.2 新增需求 ​

ID需求描述优先级验收标准
FR-12-01新增 developer 角色P1LDAP group=developers → 自动获得 developer 权限
FR-12-02developer 可搜索 / 浏览知识库P1仅显示 verified=true 的条目
FR-12-03developer 可查看应用基本信息（脱敏）P1不显示 Secret 值 / 镜像仓库凭证 / 内部 IP
FR-12-04developer 可查看应用日志（脱敏）P2自动遮蔽手机号 / 身份证 / token / 密码
FR-12-05developer 不可见：Secret 内容 / ConfigMap 敏感键P0前端校验 + 后端 API 拦截
FR-12-06developer 可评论 / 点赞知识条目P2评论内容人工审核后公开
FR-12-07developer 可见 "联系运维" 按钮P1点击后创建工单 / 发送飞书消息给负责人

9.2.3 权限矩阵 ​

资源super_adminzone_adminreadonlydeveloper
集群管理✅ RW❌❌❌
域管理✅ RW✅ RW（本域）❌❌
应用发布/回滚✅ RW✅ RW（本域）❌❌
应用基本信息✅ RW✅ RW✅ R✅ R（脱敏）
ConfigMap/Secret✅ RW✅ RW✅ R❌（仅元数据）
应用日志✅ RW✅ RW✅ R✅ R（脱敏）
Pod 终端✅ RW✅ RW❌❌
知识库（读写）✅ RW✅ RW✅ R✅ R（仅 verified）
知识库（评论）✅✅✅✅
AI 诊断✅ RW✅ RW✅ R❌
告警规则✅ RW✅ RW（本域）✅ R❌
审计日志✅ R✅ R（本域）✅ R❌

9.3 OI-03：本地 LLM 的 GPU 资源配置 ​

9.3.1 推荐配置方案 ​

方案GPU显存模型推理框架并发适用场景
A（推荐）A100 80G × 180GBQwen2.5-72B-Instruct (FP16)vLLM~20 req/s100+ 人团队
B（经济）A6000 48G × 2 (NVLink)96GBQwen2.5-32B-Instruct (FP16)vLLM~10 req/s50 人以下团队
C（起步）A100 80G × 180GBQwen2.5-14B-Instruct (FP16)Ollama~15 req/sMVP 阶段

9.3.2 部署需求 ​

ID需求描述优先级验收标准
FR-13-01GPU 节点独立部署（不在业务集群内）P0GPU 节点物理隔离，仅平台 API 可访问
FR-13-02推理服务通过内网 IP + 端口访问P0不暴露公网，防火墙仅放行平台 API IP
FR-13-03模型文件存储在本地 NVMe SSDP0可用空间 > 500GB，IOPS > 100K
FR-13-04平台通过 HTTP 调用推理服务（OpenAI 兼容接口）P0接口格式：/v1/chat/completions
FR-13-05定时健康检查（ping /v1/models）P0连续 3 次失败 → 告警 + 降级到备用模型
FR-13-06模型热加载 / 热切换能力P1不中断服务的前提下切换模型版本
FR-13-07推理服务资源限制（防 OOM 影响宿主）P0GPU 显存上限 + CPU/内存 cgroup 限制
FR-13-08推理请求超时控制P0默认 60s 超时，超时返回降级响应
FR-13-09Token 用量统计（按用户/团队/应用维度）P2月度报表，用于成本分摊

9.3.3 降级策略 ​

Primary: 本地 vLLM (Qwen2.5-72B)
    │ 健康检查连续 3 次失败 / 响应 > 60s
    ▼
Secondary: 本地 Ollama (Qwen2.5-14B)  ← 小模型兜底
    │ 同样不可用
    ▼
Tertiary: 规则引擎 only（不调 LLM）
    │
    └── 仅返回确定性规则匹配结果（如 OOM/ImagePull 等 100% 置信度规则）

9.4 OI-04：对接 LDAP ​

9.4.1 认证流程 ​

用户输入用户名/密码
       │
       ▼
平台将凭证转发至 LDAP 服务器验证
       │
  ┌────┴────┐
  │ 验证成功 │ → 查询 LDAP 获取用户属性
  └─────────┘   （displayName / email / groups）
       │
       ▼
  本地 users 表 upsert（同步 LDAP 属性）
       │
       ▼
  根据 LDAP group → 映射平台角色
  ┌─────────────────────────────────────────┐
  │ cn=ops-admin     → super_admin          │
  │ cn=ops-zone-core → zone_admin:core     │
  │ cn=developers     → developer          │
  │ cn=ops-readonly   → readonly           │
  └─────────────────────────────────────────┘
       │
       ▼
  签发 JWT Token → 正常登录

验证失败 → 返回 401 + 错误提示

9.4.2 新增需求 ​

ID需求描述优先级验收标准
FR-14-01平台支持 LDAP 认证（Phase 1 即引入）P0用户使用 LDAP 账号密码登录
FR-14-02LDAP group → 平台角色自动映射P0登录后角色正确，无需手动分配
FR-14-03LDAP 用户属性同步（displayName/email）P0首次登录自动创建本地用户记录
FR-14-04定时全量同步（默认 1h）P1LDAP 中禁用的账号 → 平台标记为 disabled
FR-14-05本地 admin 账号兜底P0LDAP 不可用时可用本地账号登录
FR-14-06LDAP 连接信息 AES-256 加密存储P0数据库中的 bind_password 不可明文读取
FR-14-07支持 LDAP over TLS（ldaps://）P0生产环境强制 TLS，否则拒绝连接
FR-14-08支持多 LDAP 服务器（主备）P2主服务器不可用时自动切换备服务器
FR-14-09登录审计（成功/失败/锁定）P1连续 5 次失败 → 锁定 30min

9.4.3 LDAP 配置项 ​

yaml
# config.yaml 中的 LDAP 配置段
ldap:
  enabled: true
  servers:
    - url: "ldaps://ldap-primary.company.com:636"
      priority: 1
    - url: "ldaps://ldap-standby.company.com:636"
      priority: 2
  base_dn: "dc=company,dc=com"
  bind_dn: "cn=platform-svc,ou=serviceaccounts,dc=company,dc=com"
  bind_password_enc: "AES-256 加密字符串"
  user_filter: "(uid={username})"
  user_attr_map:
    display_name: "displayName"
    email: "mail"
    phone: "mobile"
  group_filter: "(member={dn})"
  group_attr: "cn"
  group_mapping:
    "cn=ops-admin,dc=company,dc=com": "super_admin"
    "cn=ops-zone-core,dc=company,dc=com": "zone_admin:core"
    "cn=ops-zone-batch,dc=company,dc=com": "zone_admin:batch"
    "cn=developers,dc=company,dc=com": "developer"
    "cn=ops-readonly,dc=company,dc=com": "readonly"
  sync_interval: "1h"
  timeout: "10s"
  tls_verify: true
  tls_ca_cert: "/etc/platform/ldap-ca.pem"

9.4.4 认证方式优先级 ​

登录请求到达
  │
  ▼
┌─────────────────────────────────┐
│ 判断认证方式                     │
│                                 │
│ ldap.enabled == true？           │
│   ├── 是 → 尝试 LDAP 认证      │
│   │     ├── 成功 → 签发 JWT    │
│   │     └── 失败 → 尝试本地账号 │
│   │           ├── 成功 → 签发 JWT│
│   │           └── 失败 → 401    │
│   │                              │
│   └── 否 → 仅本地账号认证       │
└─────────────────────────────────┘

9.4.5 角色映射冲突处理 ​

场景处理方式
用户在多个 LDAP group 中取最高权限角色（super_admin > zone_admin > developer > readonly）
LDAP group 未配置映射默认赋 readonly 角色 + 记录告警日志
用户被从所有 LDAP group 移除保留本地账号但标记为 disabled
LDAP 中删除用户下次同步时标记为 disabled，不删除（保留审计记录）

十、需求追溯矩阵（更新版） ​

需求 ID需求简述设计文档章节优先级
FR-01 ~ FR-03集群/域/标签管理§3.1, §4 M1-M2P0/P1
FR-04应用管理（含负责人绑定）§3.2, §4 M3P0-P2
FR-05 ~ FR-06看板/监控告警§4 M4-M5P0-P2
FR-07RBAC & 审计§4 M6P0/P1
FR-08 ~ FR-09AI Copilot / 排障§4 M7-M8, §9P0-P2
FR-10性能优化§5, §10, 附录FP0
FR-11负责人 & 飞书通知§6, §10P0-P2
FR-12developer 角色 & 知识库开放§4 M6, §9.2P1/P2
FR-13GPU 资源配置 & 推理服务§9, §9.3P0/P1
FR-14LDAP 认证集成§4 M6, §9.4P0/P1

附录 ​

  • 附录 A：功能需求追溯矩阵（需求 ID ↔ 设计文档章节）
  • 附录 B：性能优化验收测试用例
  • 附录 C：飞书卡片消息 JSON Schema
  • 附录 D：API OpenAPI 3.0 规范（独立文件）
  • 附录 E：数据库 DDL（独立文件，见设计文档第七章）

附录 A：需求追溯矩阵 ​

需求 ID需求简述设计文档章节优先级
FR-01-01 ~ FR-01-05集群管理§3.1, §4 Module 1P0/P1
FR-02-01 ~ FR-02-06域管理§3.1, §4 Module 2P0/P1
FR-03-01 ~ FR-03-05标签管理§3.4, §4 Module 2P0/P1/P2
FR-04-01 ~ FR-04-16应用管理§3.2, §4 Module 3P0-P2
FR-05-01 ~ FR-05-07智能看板§4 Module 4P0-P2
FR-06-01 ~ FR-06-09监控告警§4 Module 5P0-P2
FR-07-01 ~ FR-07-06RBAC & 审计§4 Module 6P0/P1
FR-08-01 ~ FR-08-09AI Copilot§4 Module 7, §9P0-P2
FR-09-01 ~ FR-09-08AI 排障§4 Module 8, §9.4P1/P2
FR-10-01 ~ FR-10-10性能优化§5, §10, §附录FP0
FR-11-01 ~ FR-11-10负责人 & 飞书§6, §10P0-P2