Kuboard 系统配置
本文面向管理员，梳理系统级配置：每个配置项在哪改、默认值是什么、改动后如何生效。
如何打开
入口：左侧菜单 → 设置 → 系统设置，页面以左侧 Tab 列出全部配置。保存界面上的修改需要管理员权限。
| 界面 Tab（设置 → 系统设置） | 负责的配置 | 说明 |
|---|---|---|
| 日志参数设置 | 日志级别 | 常规 / 最低 / 同步任务日志级别 |
| JWT Token | 登录令牌密钥 | 仅提供"重新生成"按钮 |
| 集群缓存设置 | 集群同步与资源缓存 | 同步线程池 + 各资源缓存方式 |
| 用户登录设置 | 登录、密码、MFA、OIDC | 最复杂，分多张卡片 |
| 审计策略设置 | 审计开关与规则 | Kuboard / 集群 / 命名空间 三类规则 |
| 界面设置 | 站点与终端主题 | 标题、图标、页脚、GA |
| 节点 Shell | 节点调试 Pod | 镜像、命名空间、会话时长 |
| 菜单项设置 | 可禁用资源与菜单 | 树形勾选，保存后刷新菜单 |
| MCP Server | MCP 服务与 Prometheus 工具 | 开关、限流、审批 |
配置总表
| 配置类别 | 默认值 | 保存后如何生效 |
|---|---|---|
| 登录会话 | 会话 30 分钟；多窗口登录 关；MFA 关；OIDC 关 | 即时（新会话生效） |
| 密码策略 | 6–24 位含大小写与数字；错误 5 次锁 60 分钟 | 即时 |
| JWT Token | 首次安装自动生成 | 重新生成后全员强制重登 |
| OIDC 加密密钥 | 首次启动自动生成（无界面） | 轮换后历史密文不可解密 |
| 审计 | 记录到数据库；文件日志关；保留 6 个月 | 即时 |
| 集群缓存同步 | 线程池 10/200；约 32 个资源 watch/轮询 | 即时 |
| 系统缓存 | 内部缓存，无界面 | — |
| 菜单与资源 | 默认禁用 21 个 K8s 资源 | 即时（刷新菜单后） |
| MCP Server | 总开关关；写操作审批开；Prometheus 工具开 | 即时；SSE 订阅上限需重启 |
| 站点界面 | 标题 Kuboard；GA 开 | 保存后刷新页面 |
| 日志级别 | 常规 INFO；最低 TRACE；同步任务 INFO | 即时 |
| 节点 Shell | 镜像 netshoot；命名空间 kube-system；TTL 3600 秒 | 新会话生效 |
生效方式的差异
界面保存后绝大多数配置即时生效（服务端会清除对应配置缓存）。仅以下例外：
- 界面设置：保存后需刷新浏览器页面才能看到新标题 / 图标 / 终端主题；
- JWT Token 重新生成：所有在线用户被强制退出，须重新登录；
- MCP 每用户 SSE 订阅上限：保存后需重启 Kuboard 服务；
- 日志级别：保存即生效，无需重启，但已打印的历史日志不会改变。
登录与认证
入口：设置 → 系统设置 → 用户登录设置，按"通用设置 / 密码策略 / MFA 设置 / OIDC SSO / 外部用户库"分卡片展示。
通用设置与会话
| 配置项 | 默认值 | 说明 |
|---|---|---|
| 会话超时（分钟） | 30 | 对之后建立的会话生效，超时后需重新登录 |
| 允许多窗口登录 | 关 | 关闭时同一账号后登录会踢掉前登录；开启后可多浏览器 / 多标签同时在线 |
密码策略
| 配置项 | 默认值 | 说明 |
|---|---|---|
| 密码长度 | 6–24 位 | 创建与修改密码时校验 |
| 字符组合 | 大写 / 小写 / 数字 开，特殊字符 关 | 组合要求 |
| 初始密码有效时长（天） | 3 | 创建用户或重置密码时把过期时间设为 N 天后 |
| 修改密码后有效时长（天） | 90 | 用户自行修改密码后的有效期 |
| 密码错误锁定 | 5 次锁 60 分钟 | 达到上限后锁定账号 |
| 不重复历史密码数 | 3 | 新密码不得与最近 N 次相同 |
MFA（多因素认证）
| 配置项 | 默认值 | 说明 |
|---|---|---|
| 启用 MFA | 关 | 开启后支持 TOTP 动态口令二次验证 |
| 强制绑定 | 关 | 开启后用户登录前必须先完成绑定 |
| 启用恢复码 | 开 | 允许生成恢复码，防止设备丢失后无法登录 |
OIDC SSO
"OIDC SSO" 卡片可维护多个 IdP（身份提供方），逐个添加、编辑、启用或停用：
- 基本设置：显示名称、是否启用、IdP 类型（Generic / Keycloak / Authing / 阿里云 IDaaS / 腾讯云 CIAM / Entra ID / Okta / Auth0 / GitLab / 企业微信 / 飞书）；
- Discovery 与客户端：后端 Issuer、浏览器 Issuer、Client ID、Client Secret（留空保持原值），提供连接测试；
- Claims 与高级：用户名 / 邮箱 / 姓名 claim 映射、邮箱信任、MFA 策略、组同步。
外部用户库（Webhook）
| 配置项 | 默认值 | 说明 |
|---|---|---|
| 启用外部用户 Webhook | 关 | 开启后用户名 / 密码交给外部 Webhook 服务校验 |
| 外部用户 Webhook URL | 空 | 启用时必填 |
JWT Token
入口：设置 → 系统设置 → JWT Token。这里只展示 JWT 公私钥（只读，私钥已脱敏），唯一操作是重新生成。重新生成后所有已登录用户都会被强制退出；多套实例共用同一个数据库时应保持密钥一致，一般无需定期更换。
审计
入口：设置 → 系统设置 → 审计策略设置。审计只记录经由 Kuboard 界面或 Kuboard API 执行的操作，对 kubectl 等外部 K8s 管理工具不生效。
日志落盘
| 配置项 | 默认值 | 说明 |
|---|---|---|
| 记录到数据库 | 开 | 按保留时长自动清理 |
| 记录到文件 | 关 | 写入容器内日志目录 |
| 保留时长（月） | 6 | 仅数据库日志；填 0 表示不自动删除 |
| 请求体最大长度 | 4096 | 仅文件日志，超过部分不记录 |
| 响应体最大长度 | 4096 | 仅文件日志 |
审计规则
审计规则按 Kuboard / 集群 / 命名空间 三个范围分别维护，一条规则包含：
| 维度 | 取值 | 说明 |
|---|---|---|
| 动作 | 记录 / 不记录 | 命中后执行的动作，忽略后续规则 |
| 资源 | 如 deployments、pods/exec；* 表示全部 | 资源名，可限定 API 组（如 apps） |
| 动词 | get / list / create / update / delete | 操作动词 |
| 范围 | 集群：clusters；命名空间：对应集群 + namespaces | 限定规则作用范围 |
匹配规则为自上而下逐条匹配，第一个命中的规则生效，未命中任何规则时默认记录。规则卡片支持拖拽排序，也支持导出 / 导入整套规则（JSON）。
首次安装的默认规则（可在界面中修改）：
- Kuboard 范围：只读操作不记录；登录刷新 Token 不记录；MCP 子系统读操作不记录、写操作记录；
- 集群范围：只读操作不记录；
- 命名空间范围：exec（进入容器）记录，其余只读操作不记录。
集群同步与资源缓存
入口：设置 → 系统设置 → 集群缓存设置。Kuboard 把集群常用资源同步到本地缓存，界面与 API 读取缓存以提升响应速度。
同步参数
| 配置项 | 默认值 | 说明 |
|---|---|---|
| 核心线程数 | 10 | 同步线程池常驻线程 |
| 最大线程数 | 200 | 峰值并发上限，不小于核心数 |
| 全量同步任务超时（分钟） | 5 | 长时间未完成则重启该任务 |
| 全量同步失败重试间隔（分钟） | 1 | 失败任务的最小延迟 |
| 失败重试有效期（分钟） | 30 | 超过不再重试 |
| 增量监听周期（秒） | 300 | watch 连接超时后重建 |
| 重置未完成增量任务（分钟） | 10 | 增量任务卡住超过则重启全量同步 |
缓存对象设置
| 维度 | 说明 |
|---|---|
| 资源标识 | 如 apps / deployments |
| 同步方式 | 实时监听（watch，推送）或 轮询（polling，按间隔拉取） |
| 轮询间隔（分钟） | 仅轮询方式需要 |
| 延迟删除（小时） | 仅 events 资源可用：K8s 侧删除后本地额外保留（默认 7 天） |
首次安装默认缓存约 32 个资源：Pod、Deployment、StatefulSet、DaemonSet 等实时监听；Service、配置字典、Secret、Ingress、RBAC 等每 5 分钟轮询；admission webhook 配置、FlowControl、RuntimeClass 等每 300 分钟轮询；DRA（动态资源分配）资源实时监听。
菜单与资源启停
入口：设置 → 系统设置 → 菜单项设置。页面以树形结构展示 Kuboard 菜单与全部 K8s 资源：勾选表示启用（界面上可见），取消勾选表示禁用（从菜单隐藏）。标注"核心"的资源不可禁用；保存后菜单缓存即被清除，刷新界面即可看到效果；搜索框可按标题 / 路径过滤。
首次安装默认禁用 21 个不常用的 K8s 资源，包括 RuntimeClass、VolumeSnapshot（快照）、CSI 相关、admission webhook 配置、FlowControl、Lease、PriorityClass、PodDisruptionBudget、EndpointSlice、DRA 相关资源等。
MCP Server
入口：设置 → 系统设置 → MCP Server。MCP Server 将 Kuboard 的能力（K8s 读写、Prometheus 查询、变更计划审批等）以 MCP（Model Context Protocol）工具形式暴露给 AI 客户端，端点为 <Kuboard 访问地址>/mcp。
| 配置项 | 默认值 | 说明 |
|---|---|---|
| 启用 MCP Server | 关 | 关闭时 /mcp 返回 404 |
| 强制审批 Agent 写操作 | 开 | 写操作先 dry-run 暂存为 plan，在界面人工审批后执行；关闭后立即执行，生产环境建议保持开启 |
| CORS 允许的 Origin | 空（拒绝所有跨域） | 浏览器端跨域白名单，按 Origin 精确匹配 |
| 单请求体最大字节数 | 10MB | 超过则拒绝请求 |
| 每用户限流 | 50 次 / 60 秒 | 滑动窗口，超限返回 HTTP 429 |
| 每用户最大 SSE 订阅数 | 100 | 保存后需重启服务生效 |
Prometheus 工具
| 配置项 | 默认值 | 说明 |
|---|---|---|
| 启用 Prometheus 工具 | 开 | 关闭后调用返回未发现服务 |
| 单次瞬时查询最大 series 数 | 10000 | 防止大查询拖垮 Prometheus |
| 单次范围查询最大 points 数 | 100000 | series × 时间点数 |
| 查询超时（秒） | 30 | Prometheus HTTP 查询超时 |
| 逐条 RBAC 鉴权 | 开 | 每个查询的资源逐条校验权限 |
| 聚合查询策略 | 允许并按维度鉴权 | 另有"拒绝聚合"与"仅允许 cluster scope" |
| 聚合查询限流倍率 | 5× | 按普通查询限额的倍数限流 |
| 聚合查询最大维度展开 | 100 | 单次聚合最多展开的命名空间 / 节点维度 |
| 按集群服务发现 | 空 | 按集群覆盖服务发现规则 |
站点界面
入口：设置 → 系统设置 → 界面设置。站点信息保存后需刷新浏览器页面才能看到新标题、图标与页尾。
| 配置项 | 默认值 | 说明 |
|---|---|---|
| 页面标题 / 产品名称 | Kuboard / Kubernetes 多集群管理 | 登录页与浏览器标签展示 |
| 页尾信息 | 默认显示官方站点域名 | 可按需改为自己的站点域名 |
| 系统图标 | 内置图标 | 上传 JPG/PNG（≤50KB） |
| Google Analytics | 启用 | 收集匿名使用数据，不涉及集群敏感数据 |
| 终端字体大小 / 行间距 | 14 / 1.2 | 终端显示 |
| 终端主题类型 / 名称 | dark / AtelierSulphurpool | 对后续打开的新终端会话生效 |
| 终端日志行数 | 500 | 终端回显的最大日志行数 |
日志级别
入口：设置 → 系统设置 → 日志参数设置。保存即即时生效，无需重启。
| 配置项 | 默认值 | 说明 |
|---|---|---|
| 常规日志级别 | INFO | 常规请求的日志级别 |
| 最低日志级别 | TRACE | 允许的最低级别，一般用于临时排查 |
| 同步任务日志级别 | INFO | 集群缓存同步任务；界面建议设为 ERROR，避免刷屏 |
| 错误堆栈输出到控制台 | 开 | 异常堆栈打印到 stdout |
| 错误堆栈输出到响应报文 | 关 | 返回给客户端，仅调试用 |
节点 Shell
入口：设置 → 系统设置 → 节点 Shell。节点 Shell 会在目标节点上创建一个特权级调试 Pod，通过容器终端访问节点的文件系统、进程与网络命名空间。以下参数全局生效：
| 配置项 | 默认值 | 说明 |
|---|---|---|
| 镜像 | nicolaka/netshoot | 创建调试 Pod 使用的镜像 |
| 启动命令 | sleep infinity | 保持容器存活以便进入 |
| 命名空间 | kube-system | 调试 Pod 创建的位置（须存在且有权限） |
| 会话时长（秒） | 3600 | 超时后会话过期，Pod 自动清理 |
| 资源限制 | 请求 100m CPU / 128Mi 内存；限制 500m CPU / 512Mi 内存 | 调试 Pod 的资源请求与上限 |
无界面配置
| 配置 | 说明 |
|---|---|
| 系统缓存 | 内部内存缓存（Caffeine），默认容量 50–500 项、过期 5–30 分钟，界面不可配置，一般保持默认 |
| OIDC 加密密钥 | 首次启动自动生成，用于加密 IdP 的 clientSecret 与 Token。启用 OIDC 前请先从数据库中备份；轮换会导致历史密文不可解密 |