简体中文 | English

花折 - KubeDoor

花开堪折直须折🌻莫待无花空折枝

AI 驱动的多 K8S 集群智能管控平台

官网 · 快速部署 · 文档 · 交流群

🏷目录

• 🌈概述
• 🎉2.x新特性
• 💠架构
• 💎功能

• 🚀快速部署
• ♻升级说明
• 📚文档
• 🔔交流群与赞赏
• 🙇贡献者
• 🥰鸣谢

🌈概述

🌼花折 - KubeDoor 是一个使用Python + Vue开发的AI驱动的多K8S集群智能管控平台：控制端装一套、每个业务集群装一个agent，就能在一个Web里完成多集群的监控、资源管理、告警与事件、高峰期资源治理、JVM管控和节点均衡；同时内置可审批、可审计的AI运维助手，并以标准MCP对外开放。

KubeDoor专注微服务每日高峰时段的资源视角：采集各微服务高峰期的真实资源用量，基于K8S准入控制让资源需求值与真实用量保持一致。2.x在此基础上把AI助手作为核心能力，并把数据库统一为PostgreSQL、把部署简化为一个脚本。

• 🤖AI运维助手：用自然语言排障、查询和变更；自动调用63个KubeDoor业务操作与K8S API、kubectl、istioctl等通用工具，查询自动执行，变更先展示参数与差异，人工批准后才执行。
• 🌐多集群统一纳管：agent主动外连控制端，业务集群无需开放入站端口；所有集群的资源、指标、事件和告警集中在一个平台。
• 🎯高峰期资源治理：按业务高峰时段采集资源数据，通过准入控制统一管控副本数、需求值、限制值和JVM启动参数。
• 🔔告警闭环：指标告警、K8S事件告警与告警屏蔽，通知推送到企业微信、钉钉、飞书、Slack。
• 🔐账号与权限：本地账号 + LDAP登录，按K8S集群授权「读写 / 只读 / 无」，登录、变更与越权操作全部留痕审计。
• 🚀部署简单：一个脚本 + 一份配置文件，PostgreSQL是唯一的数据库。

K8S资源总览：多集群资源、风险节点、今日异常告警与事件，一屏尽览

🎉2.x新特性

相对1.7，2.x是一次架构级升级：AI助手成为核心能力，PostgreSQL成为唯一数据库，部署改为一个脚本。 当前版本为2.2.0，下文【2.0】/【2.1】/【2.2】表示首次提供该能力的版本。

🤖AI

• 【2.1】内置AI助手（kubedoor-ai，随控制端必装）：使用自己的模型，选定集群后用自然语言排障和运维；变更经审批后执行，支持全局记忆与kubeconfig直连。
• 【2.1】新版MCP：并入kubedoor-ai，经Web入口提供/mcp（Streamable HTTP）与/sse，复用Web账号与读写权限，写操作需在Web中批准；兼容1.x的16个工具名。

• 【2.2】全新登录页：水墨月洞门背景 + 毛玻璃登录框，湖面水波、门环圆波、梅花飘落等动效；登录与会话改由master统一管理，支持「7天内免登录」，连续输错口令自动锁定。
• 【2.2】LDAP登录：在「系统管理 → LDAP 设置」配置并一键测试；登录时本地账号优先，本地没有再走LDAP，首次登录自动开通。
• 【2.2】K8S集群级权限：全局权限「管理员 / 读写 / 只读 / 无」+ 按用户×集群单独授权「读写 / 只读 / 无」，单独授权优先；「无」权限的集群在所有页面、告警和AI助手中都不可见，AI助手与MCP按所选集群判断能否执行和批准修改。
• 【2.2】操作审计：登录、账号与权限变更、所有写操作（含越权被拒）都可在「系统管理 → 操作审计」查询，默认保留180天。
• 【2.2】Agent账号认证：agent一律带内置Agent账号连接master，普通Web账号不能注册agent；Grafana改为auth proxy接入（KubeDoor管理员为Admin，其他人为Viewer）。

• 【2.0】PostgreSQL唯一数据库：移除ClickHouse与MySQL，master与kubedoor-ai启动时自动建表，无需任何扩展。
• 【2.0】脚本化部署：deploy/install.sh + kubedoor.conf取代Helm，支持渲染预览、组件按需开关、内网镜像仓库，并能自动发现集群里已有的kube-state-metrics。
• 【2.0】数据自动清理：K8S事件保留90天，告警记录与高峰快照保留365天，可调整。
• 【2.0】参数化数据接口：前端改用/api/db/*，不再直传SQL。

• 【2.0】告警屏蔽：Alertmanager风格的匹配条件、命中预览、到期自动失效；被屏蔽的告警照常入库，只拦截通知。

• 【2.1】Deployment实时状态：WebSocket实时推送就绪/期望副本、滚动更新状态和Pod明细。
• 【2.1】JVM启动参数管控：采集并管控Xms/Xmx/Xss/MaxMetaspaceSize，新增每日高峰P95堆内存与G1 Eden使用率。
• 【2.0】节点均衡：按节点CPU负载生成迁移计划，人工确认后分批隔离式迁移。
• 【2.0】CCI弹性扩容：华为云CCE临时扩容时，超出本地上限的Pod弹到CCI。
• 【2.0】日志增强：Deployment级聚合日志、容器切换、完整日志gzip下载；Pod页支持按节点筛选与命名空间多选。
• 【2.0】准入加速：准入查询改为单条SQL + 60秒缓存，修改开关、管控表后立即生效。

💠架构

控制端装一套，每个业务集群装一个agent；agent主动外连，数据统一存进PostgreSQL（指标在时序库）。

• 控制端（./install.sh master）：kubedoor-web（nginx统一入口 + Vue 3控制台）、kubedoor-master（API网关、agent连接中心）、kubedoor-ai（AI助手 + MCP Server）、kubedoor-alarm（告警屏蔽、入库与IM通知）、kubedoor-collect（每日高峰期采集CronJob），以及可选的VictoriaMetrics、vmalert、Alertmanager、Grafana。
• 集群端（./install.sh agent）：kubedoor-agent，以及可选的vmagent、kube-state-metrics、node-exporter。agent主动通过WebSocket连接控制端，业务集群无需开放入站端口；同集群直连master的Service，跨集群经Web入口，都使用内置Agent账号认证。
• PostgreSQL 18是唯一数据库：用docker compose独立部署在K8S外，也可用现成的PG（无需扩展），保存管控配置、高峰期资源、K8S事件、告警记录、屏蔽规则、Istio路由以及AI会话、审批与记忆。
• 监控栈可选：使用内置VictoriaMetrics单机版，或接入已有的Prometheus/VictoriaMetrics；各集群指标用标签=区分。
• 统一入口：Web、Grafana、AI助手和MCP共用kubedoor-web的一个NodePort；登录与权限由master统一管理（本地账号/LDAP，按K8S集群授权）。
• AI必装、MCP默认开放：kubedoor-ai随控制端安装；外部MCP入口（/mcp、/sse）可用ENABLE_MCP="false"关闭，不影响网页里的AI助手。

💎功能

覆盖K8S日常运维的完整链路；其中的查询与运维操作，大多也可以直接交给AI助手完成。

1. 🤖AI助手与MCP

点击顶栏正中的「AI 助手」，在「KubeDoor 助手」里选定集群，用一句话描述问题：查询自动执行，变更先审批再执行，全程可追溯。 同一套工具、权限与审批也以标准MCP开放给Cursor、Claude Code等外部客户端。

• 🧠自带模型：在「模型设置」填写Base URL、API Key和模型名（model ID），「测试连接」会实测工具调用能力；支持任意OpenAI兼容的Chat Completions接口（含无需鉴权的自建模型，模型需支持工具调用），并专门适配DeepSeek思考模式；模型配置只保存在本人浏览器。
• 🎯资源上下文：先选「K8S 集群」（每轮只操作选中的集群），可再细化到命名空间、Deployment、Pod；集群旁标注「Agent 在线」「已配置直连」「仅指标 / 历史」。
• 🧰统一受控工具：所有集群操作都经同一个工具kubedoor_tool，覆盖63个KubeDoor业务操作（37个只读、26个写入：日志、事件、资源与JVM、节点、扩缩容、重启、改镜像、定时/周期任务、节点均衡、管控配置等）和5类通用执行器（K8S API/CRD、kubectl、istioctl、诊断命令、Pod exec），已有接口优先。
• 🔌多种连接方式：KubeDoor已有接口、agent的集群内身份（免kubeconfig），或由管理员在「Agent管理」的「AI Kubeconfig」列上传kubeconfig直连（AES-256-GCM加密存储）；agent离线时仍可查询历史与监控数据。
• ⏰立即/定时/周期运维：Deployment重启与扩缩容支持立即执行、指定时间执行一次、按Cron周期执行。
• 📈自由指标查询：时序库为VictoriaMetrics时，AI可直接编写MetricsQL，服务端强制限定在当前集群，时间范围最长30天。
• 📝全局记忆：「总结为记忆」把会话提炼成可编辑草稿，全局读写账号「保存为全局记忆」后，所有登录用户都可查看和引用；提问时用「引入记忆（N）」按需带入，每轮最多10条。
• 🧩DeepAgents驱动：内置「KubeDoor K8S 运维」Skill，子Agent并行排查、上下文自动压缩、PostgreSQL持久化checkpoint；会话保存在服务端（仅本人可见），流式回复、断线续传，关闭对话框后任务继续执行。

🛡安全护栏

| 护栏 | 说明 | | --- | --- | | 审批 | 只读查询自动执行；变更、未知CLI命令、curl/openssl、Pod exec会先展示「准确参数」「执行命令」「变更预览」「配置差异」，点「批准这次操作」才执行，30分钟内有效。对所选集群有读写权限的账号可勾选「自动批准执行」（只对当前页面生效） | | 参数冻结 | 准备阶段把完整参数写入数据库，批准后按原样执行，模型无法替换；kubeconfig被替换后原批准失效 | | Dry-run | 通用K8S API写操作先以dryRun=All生成配置差异，并带resourceVersion/UID前置条件；kubectl apply先执行--dry-run=server；KubeDoor业务操作展示准确参数与变更预览 | | 不盲目重放 | 超时或断线的写操作标记为「执行结果不确定」，本轮不再继续写入；服务重启不会重发已派发的操作，待批准的操作可继续审批 | | 脱敏 | API Key只在单次运行的内存中使用，不写库、不写日志；流式输出、checkpoint、日志与记忆统一脱敏，Secret内容自动隐藏 | | 按集群授权 | 权限按会话所选集群计算：只读可以对话和查询，但不能批准变更、不能开启自动批准；「无」权限的集群在AI助手和MCP中都不可见；上传kubeconfig仅限管理员，维护全局记忆需要全局读写 | | 审计 | 会话、运行、每次工具调用（含完整参数、预览与结果）和事件写入PostgreSQL；外部MCP调用同样生成会话，可在Web中回看 |

提示：对集群只读的账号通过AI可执行的只读查询（如K8S API GET、查看日志与ConfigMap）比经典页面更宽，Secret脱敏为尽力而为，请按需分配账号；生产环境请在Web前加HTTPS。

🔗接入外部MCP客户端

• 地址：http(s):///mcp（Streamable HTTP，推荐）；只支持SSE的客户端用/sse。就是Web入口，如<节点IP>:。
• 鉴权：复用Web账号（本地或LDAP），请求头Authorization: Basic ；按该账号的集群权限执行，只读集群只能调用只读工具，「无」权限的集群不可见。
• 工具：保留1.x的16个工具名（如get_k8s_list、get_pods_logs、scale_deployment、get_pod_jvm_dump）+ 统一工具kubedoor_tool + Skill资源skills://kubedoor-k8s。
• 变更不会直接执行：写操作和需进入Pod执行的JVM诊断会返回pending和browserlink（相对路径），用同一账号登录Web打开即可审批；执行结果不会回推给MCP客户端，请再次查询核验。
• 关闭外部入口：kubedoor.conf中设置ENABLE_MCP="false"。

{
  "mcpServers": {
    "kubedoor": {
      "url": "http://<KubeDoor 地址>/mcp",
      "headers": {
        "Authorization": "Basic <base64(用户名:密码)>"
      }
    }
  }
}

可用printf '%s' '用户名:密码' | base64生成，建议为MCP单独建一个账号。

上下文：K8S 集群 prod-a · 命名空间 demo · Deployment deploy-demo-order
你：这个服务最近频繁重启，结合日志、事件和监控帮我找原因。
AI 助手：
  工具调用 5（只读查询，自动执行）
    ✓ pods                 Pod 列表与重启次数
    ✓ previous_logs        上次退出的容器日志
    ✓ events               相关 K8S 事件
    ✓ resource_inventory   管控表中的限制值与 JVM 参数
    ✓ metrics              近 6 小时内存曲线
  结论：容器内存持续贴近限制值，上次退出原因为 OOMKilled。
  建议：把内存限制调到 1024MB，并在低峰期滚动重启。需要我提交调整吗？
你：可以，内存限制调到 1024MB，今晚 23:30 重启一次。
AI 助手：
  1 项待批准  resource_config_update
    准确参数：limit_mem_mb=1024（其余字段保持当前值）   [拒绝] [批准这次操作]
  …… 批准后 ……
  1 项待批准  schedule_deployment_restart
    准确参数：run_at=<今天>T23:30                      [拒绝] [批准这次操作]
  …… 批准后 ……
  管控配置已保存（下次发布或重启时生效）；单次重启任务已注册，到点执行。

📖详见：AI助手使用说明

2. 📡多集群监控

各集群的vmagent把指标远程写入同一个时序库，靠一个标签区分集群——在一个Web里看全部集群。

• 🖥「K8S资源总览」大屏：可在「全部集群」与单集群之间切换，展示集群、节点、工作负载、容器组、持久卷数量，4类风险节点徽章和6项最高使用率/分配率，以及今日Top10异常Pod告警、Top10异常K8S事件与最近10日告警趋势，30秒自动刷新。
• 🌊统一时序库：每个集群的指标带=标签；可用内置VictoriaMetrics单机版，也可接入已有Prometheus/VictoriaMetrics（所有集群需汇总到同一个可查询的库）。
• 🔌已有监控自动适配：集群里已有kube-state-metrics、node-exporter时可关闭自带组件，vmagent会在全集群自动发现已有的kube-state-metrics。
• 📊Grafana看板：「K8S监控看板📊」「节点监控看板📊」「高峰资源看板📊」内嵌在Web中，随安装自动导入（Grafana为可选组件，高峰资源看板的数据来自PostgreSQL）。
• 📈Deployment资源指标：Deployment页按服务展示CPU、内存用量与需求值、限制值（来自时序库）。

3. 🎛K8S资源管理

在一个控制台里管理所有集群的Deployment、Pod、Service、Ingress、ConfigMap、StatefulSet、DaemonSet和节点，常用运维动作一键完成。

• 🗂统一资源页：各类资源的查看、Monaco编辑器编辑YAML（Create / Apply / Replace）与删除；所选集群和命名空间跨页面记忆。
• ⚡Deployment实时状态【2.1】：WebSocket推送Pod列的就绪/期望副本数与「更新中」「已暂停」「超时」状态，查询栏标注「实时」「连接中」「agent 离线」「实时不可用」，展开明细后Pod增删实时刷新。
• 📜日志查看器：实时跟随、关键字搜索/筛选/逐条定位、ERROR/WARN/INFO多色标记、保留ANSI颜色、「重启前日志」；【2.0】Deployment行的「日志」可聚合全部Pod（最多60个），支持切换容器；选中单个Pod时可「下载日志」（完整日志gzip）。
• 🔁扩缩容与重启：支持「立即执行」「定时执行」「周期执行」，可选「临时扩容」「调度到指定节点」；定时/周期任务由agent以CronJob形式创建在业务集群的kubedoor命名空间，Web上的时间按北京时间填写。
• 🧪Pod隔离：「隔离」把Pod的app标签改为<原值>-ALERT，使其脱离Service流量、保留现场排查，可同时「临时扩容1个Pod」；另支持删除与批量删除。
• 🏷镜像更新：「更新镜像」弹窗自动列出镜像仓库最近20个标签（阿里云ACR、华为云SWR、Harbor，需在REGISTRY_SECRET_JSON中配置仓库凭据），也可手动输入；只读账号可按集群、时间段、账号白名单授权，更新进度推送IM。
• 🔍Pod页：【2.0】按节点筛选、命名空间多选；一键跳转该Pod的「事件」「告警」。

📖详见：K8S微服务镜像更新配置说明

4. 🧬告警、事件与屏蔽

指标告警、K8S事件告警和运维操作通知统一推送到企业微信、钉钉、飞书、Slack；告警屏蔽只拦通知、不丢数据。

• 🚨指标告警：内置44条vmalert告警规则（Pod状态与资源、Deployment、节点、JVM等）和2条记录规则，经Alertmanager交给kubedoor-alarm推送IM（名称以K8S_Pod开头的Pod类告警同时入库PostgreSQL），故障/恢复通知标注持续时长。
• 📋告警分析：「告警面板」按告警名聚合并按日累计；「K8S告警详情」支持多条件筛选、处理标记与自动刷新，可直接对Pod执行隔离、删除、Dump、Jstack、JFR、JVM，或一键「屏蔽」。
• 🔕告警屏蔽【2.0】：Alertmanager风格条件（=、!=、=~、!~，正则需完全匹配），快捷时长与「命中预览」，状态分为生效中/待生效/已过期/已解除，支持解除、续期、重新启用、克隆；IM通知里的【屏蔽】链接可直达屏蔽页并预填条件（需配置KUBEDOOR_EXTURL）。被屏蔽的告警照常入库、只拦截通知，屏蔽不作用于K8S事件告警。
• 📺K8S事件中心：各集群agent采集全部K8S事件写入PostgreSQL（同一事件只保留一行），在「K8S事件详情」按集群、命名空间、Kind、名称、原因、消息、来源检索，命中规则的事件标为「已告警」。
• 🧾事件规则告警：用JSON配置忽略规则与告警规则（条件不区分大小写），内置关键事件、重启、健康检查失败、挂载失败、调度失败、资源压力、僵尸进程等规则；ALERT_DEDUP_WINDOW（默认300秒）内同一事件不重复通知。规则只来自ConfigMap kubedoor-master-file-cfg（源文件deploy/manifests/master/alert_rules.json），修改后需执行kubectl -n kubedoor rollout restart deploy/kubedoor-master。
• 📮运维通知：隔离、删除、JVM诊断、扩缩容、重启、改镜像进度、准入结果都由agent推送IM，可按集群配置不同的机器人；外部系统也可通过POST /api/custom_alert写入告警记录。

📖详见：告警屏蔽 · K8S事件告警规则配置说明

5. 🚧高峰期资源与准入管控

采集每个微服务每日业务高峰时段的真实资源用量，再通过K8S准入控制让需求值与高峰期真实用量保持一致——调度更准确，资源碎片更少。

• 📊高峰期采集：在「Agent管理」开启「自动采集」并设置「高峰时段」（默认10:00:00-11:30:00），每天北京时间01:00采集前一天的高峰数据；也可点「采集」补采历史数据（1~90天），重复采集不会重复写入。
• 📐采集口径：CPU、内存取高峰时段P80（列名「P80PodCPU%」「P80Pod内存%」），堆内存与G1 Eden使用率取P95；管控表采用最近10天里整个集群CPU总消耗最大的那一天的数据，CPU/内存用量作为需求值。
• 🗂「高峰资源管控」：集中查看当日Pod、指定Pod、使用率、需求值、限制值与JVM参数，支持批量扩缩容、批量重启、「配置」（保存并扩缩容 / 保存并重启 / 保存）和「新增资源」；「每日高峰资源」查看每天的原始采集数据，「高峰资源看板📊」看长期趋势与TOP10。
• 🚧准入控制：在「Agent管理」开启「准入控制」并选择管控命名空间后，agent自动创建MutatingWebhook。Deployment创建或发布时，副本数（优先「指定Pod」，未指定时取「当日Pod」）、第一个容器的requests/limits及JVM参数改写为管控值；通过scale扩缩容时只改写副本数。
• 🆕新服务管控：管控表中没有的服务，「新服务免确认」关闭时部署会被拒绝并通知，开启时直接放行、不做管控；每日采集也会把新出现的服务自动加入管控表并通知。
• ⏱临时扩容豁免：「临时扩容」后5分钟内，该Deployment的副本变更直接放行。
• ⚡准入加速【2.0】：master用单条SQL查询（5秒超时）并缓存60秒，修改开关、管控表或完成采集后立即生效。

⚠️ 准入控制默认关闭，开启后为fail-closed：agent或master不可用时，所有未打kubedoor-ignore标签的命名空间里的Deployment创建、发布和扩缩容都会被拒绝，应急可执行kubectl delete mutatingwebhookconfiguration kubedoor-admis-configuration。

> 💡 「新增资源」时「指定Pod」必须填写（0表示发布服务但暂不启动Pod，不能为-1）；-1（按「当日Pod」管控）只适用于已采集过高峰期数据的服务。

📖详见：K8S资源管控功能说明

6. ☕JVM管控与诊断

Java微服务的启动参数、高峰期堆内存使用率和一键诊断，都在KubeDoor里完成。

• 🩺一键诊断：在Deployment、Pod、K8S告警详情页对Pod执行「Dump」「Jstack」「JFR」「JVM」，结果弹窗展示并推送IM；Dump、Jstack、JFR的文件上传到OSS_URL指定的对象存储。
• 🧩JVM启动参数管控【2.1】：自动采集Deployment第一个容器args（args[0]为java）中的-Xms、-Xmx、-Xss、-XX:MaxMetaspaceSize，在「高峰资源管控」查看并在「配置」中修改（Xss单位k，其余m），下次发布或重启时由准入控制替换为管控值（需开启准入控制）。
• 📈堆内存与G1 Eden【2.1】：每日高峰时段的P95堆内存使用率「P95podHeap%」和G1 Eden使用率「P95podG1E%」，仅展示，辅助调整JVM参数。
• 🚨JVM告警：内置14条JVM告警规则（堆/非堆内存、GC、线程等），vmagent自动抓取带prometheus.io/jvm: "true"注解的Pod。

📖详见：JVM参数管控

7. ⚖节点均衡与弹性调度

按节点实时CPU负载生成迁移计划，人工确认后分批迁移；扩容时还能把Pod调度到指定节点或华为云CCI。

• ⚖「节点均衡」【2.0】：「分析负载」根据节点CPU使用率的极差与标准差迭代生成「迁移计划」，确认后「执行选中」或「执行全部」；采用隔离式迁移，分批执行，新Pod就绪后才进行下一批，旧Pod保留在「隔离Pod」中，确认无误后再清理。
• ⚙「负载均衡配置」：可调整不均衡阈值、均衡目标、最小副本数、黑名单、排除命名空间/节点、源/目标节点选择策略等。仅支持手动执行，依赖metrics-server；执行期间会临时禁止调度（cordon）其它节点，建议在低峰期操作。
• ☁CCI弹性扩容【2.0】：华为云CCE集群在「临时扩容」时勾选「CCI扩容」并设置「本地Pod数」，超出部分弹到CCI。
• 🎯调度到指定节点：扩缩容、重启、隔离时可按「当前CPU」「当前内存」「峰值CPU」「峰值内存」「Pod数」查看节点排行并挑选目标节点。
• 💻「节点管理」：查看节点CPU、内存、磁盘、Pod的用量与可分配量及节点状态，支持批量禁止/允许调度（用量数据依赖metrics-server）。

8. 🌐Istio路由管理（试用）

按「Istio组」统一维护一个项目的VirtualService：花折保存一份组标准（规则、默认路由、gateway全组共用），hosts和规则里的域名条件按集群各自维护，按需下发到组里的集群。

• 🗺「全局VS管理」：一个组 = 共用的测试集群 + 本项目的生产集群，一个集群可以加入多个组（多个项目共用的测试集群），每个VS自己选择部署到哪些集群；矩阵视图同时看到每个VS在各集群的hosts和状态（一致/待下发/不一致/集群中没有/缺少域名），hosts可单独修改、从其它集群复制。
• 🧩「组的VS范围」：同一个VS只能属于一个组，组用包含 / 忽略规则（通配符或正则）划分VS，单个VS也可以手动忽略、在「查看忽略」里取消；和共用集群的其他组冲突的VS整行标红，要先在其中一个组忽略才能纳管和下发。格子菜单可以直接删除集群里的VS（二次确认，删除前的内容记入审计）。
• 🏷「域名条件按集群」：规则里按域名区分的条件（authority、headers.host）和hosts一样各集群各存一份，下发时按该集群的域名展开；可按关键字一次在各集群里选域名，或从其它集群复制并替换机房标识（如penglai→kunlun）。
• 📥「刷新现状」：各集群各自采集VirtualService（只读快照，不影响别的集群）；对比各集群差异（规则按匹配条件对齐、YAML逐行对比），一致的一键纳管（只差hosts和域名的也算一致，域名取各集群自己的现状），不一致的选基准集群纳管后再下发拉齐。
• 🚀「下发」：先预览集群最新现状与将要下发内容的差异再执行；采集到的未建模字段（retries、corsPolicy等）原样保留，下发不丢配置。所有修改只允许管理员操作。
• 🚸「委托VS管理」页面仍在开发中；如需使用Istio路由管理，可联系作者。

9. 🔐平台与权限

一个入口、按集群授权：Web、Grafana、AI助手和MCP共用一个NodePort，登录与权限由KubeDoor自己管理。

• 🚪统一入口：kubedoor-web的nginx只做反向代理，登录、会话和权限校验都在master；AI助手、MCP、Grafana（/grafana/）通过nginx auth_request交给master判定。
• 👤账号【2.2】：本地账号 + LDAP（Web上配置并可一键测试，首次登录自动开通）；内置超级管理员kubedoor只能由自己改口令，不能被删除或改权限。
• 👥权限【2.2】：全局权限分「管理员 / 读写 / 只读（默认） / 无」，再按用户×K8S集群单独授权「读写 / 只读 / 无」，单独授权优先、全局权限兜底；「无」权限的集群在所有页面、告警和AI助手中都不可见。AI助手与MCP按目标集群判断能否执行和批准修改。镜像更新仍可通过UPDATE_IMAGE_JSON按集群、时间段、账号向只读账号开放。
• 🧾操作审计【2.2】：登录、账号与权限变更、所有写操作（含越权被拒）都可在「系统管理 → 操作审计」查询。
• 🛰多集群接入：agent首次连接自动登记；「Agent管理」查看在线状态、心跳和版本，「更新」可一键升级agent镜像，并集中配置采集、准入控制与「AI Kubeconfig」。
• 📝操作留痕：nginx以JSON格式记录访问日志（含登录用户与请求体）；master记录操作审计；运维操作由agent推送IM；AI的会话、审批与工具调用写入PostgreSQL。
• 🧹数据自动清理【2.0】：K8S事件保留90天，告警记录与高峰快照保留365天，master每天分批清理，可在kubedoor-config中调整（0表示不清理）。
• 🌗界面：【2.2】水墨月洞门登录页（毛玻璃登录框，湖面水波、门环圆波动效，系统开启「减少动态效果」时自动关闭）；简体中文/English（部分页面翻译）、浅色/深色/自动主题，适配移动端。

🚀快速部署

一份配置文件 + 一个bash脚本，三步完成：起PostgreSQL → 装控制端 → 每个集群装agent，不再需要Helm。 完整说明见部署指南。

前置条件

| 项目 | 要求 | | --- | --- | | 执行机器 | 能用kubectl连上目标集群，bash 4以上 | | Kubernetes | ≥ 1.21；每日采集与定时/周期任务按北京时间执行（timeZone: Asia/Shanghai），需要≥ 1.25，更老的集群按kube-controller-manager的时区执行 | | metrics-server | 需要：Pod/节点的CPU与内存用量、节点均衡都依赖它 | | 时序库 | 内置VictoriaMetrics（需要可用的StorageClass，默认100Gi PVC），或已有Prometheus/VictoriaMetrics。Deployment列表、K8S资源总览和高峰期采集都依赖时序库，没有监控数据时页面为空、也采集不到数据 | | 数据库 | 一台装有Docker Compose的机器运行PostgreSQL 18（K8S节点能访问它的5432端口），或现成的PostgreSQL（建议14+，无需扩展和超级用户） | | CPU架构 | 官方镜像仅提供amd64 | | 网络 | 跨集群时，agent要能访问控制端Web的NodePort（WebSocket），vmagent要能访问控制端时序库的NodePort（远程写） |

三步安装

git clone https://github.com/CassInfra/KubeDoor.git
cd KubeDoor

① 起数据库（在K8S节点能访问到的机器上，从仓库根目录开始）

cd deploy/postgres
cp .env.example .env
vi .env                 # 至少改掉 PG_PASSWORD
docker compose up -d
docker compose logs -f postgres    # 看到 database system is ready 就行

默认镜像只有amd64，海外或ARM机器可在.env里设置PG_IMAGE=postgres:18-alpine。不用手动建表，master与kubedoor-ai启动时会自动建好。

② 装控制端（在能用kubectl连上集群的机器上，从仓库根目录开始）

cd deploy
cp kubedoor.conf.example kubedoor.conf   # 从模板复制一份配置
vi kubedoor.conf        # 改 PG_HOST / PG_PASSWORD / MSG_TOKEN 等
./install.sh master

• PG_HOST填K8S里的Pod能访问到的地址（通常是数据库宿主机的内网IP），不能填127.0.0.1。
• 已有Prometheus/VictoriaMetrics时，设置ENABLE_VICTORIA_METRICS="false"并填写PROM_URL、PROM_TYPE。
• 想先检查生成的YAML：./install.sh render master -o /tmp/out。

vi kubedoor.conf        # 改 K8S_NAME 和 MASTER_WS（换机器执行时先 cp kubedoor.conf.example kubedoor.conf）
./install.sh agent

• K8S_NAME：集群的唯一标识，只能用字母、数字、-、_。
• MASTER_WS：必须带内置Agent账号口令，同集群填ws://Up4biLko1dNh:<口令>@kubedoor-master.kubedoor，跨集群填ws://Up4biLko1dNh:<口令>@<控制端节点IP>:（装控制端时脚本会把两种写法打印出来）；跨集群还要把REMOTE_WRITE_URL改成控制端时序库的外部写入地址（同样会打印）。
• 多个集群建议各用一份配置：./install.sh agent -c ./cluster-a.conf。
• 几十秒后即可在「Agent管理」看到该集群「在线」。

访问Web

• 浏览器打开安装脚本打印的http://<节点IP>:，内置管理员账号kubedoor / kubedoor，首次登录会强制修改口令。
• 在「系统管理 → 用户与权限」添加账号、按集群授权，在「LDAP 设置」接入LDAP。
• ⚠️ 内置Agent账号Up4biLko1dNh（出厂口令qCa22jDkfc9y）供agent连接master，请在「用户与权限」里重置口令，并同步修改各集群agent的MASTER_WS（同集群、跨集群都要带账号口令），重新执行./install.sh agent后执行kubectl -n kubedoor rollout restart deploy/kubedoor-agent。

首次使用

1. 打开「Agent管理」，确认集群状态为「在线」。
2. 打开「自动采集」，在弹窗中设置「高峰时段」（默认10:00:00-11:30:00）。
3. 点「采集历史数据」列的「采集」，选择「采集天数」（默认10天，可选1~90），把历史高峰数据写入管控表；之后每天北京时间01:00自动采集。新装的监控要经历一个完整的高峰时段后才有数据可采，之后也可执行kubectl -n kubedoor create job --from=cronjob/kubedoor-collect collect-now立即采集一次。
4. 在「高峰资源管控」确认数据无误后，再按需开启「准入控制」（默认关闭）。
5. 点顶栏「AI 助手」→「模型设置」，填写Base URL、API Key、模型名并「测试连接」，即可开始对话。

生产环境提示

• 🔒Web与MCP默认是HTTP，生产环境建议在Web前加HTTPS（Ingress/LB需支持WebSocket）；TLS在nginx前面终结时把kubedoor-config的AUTH_COOKIE_SECURE设为"true"。
• 🚧准入控制为fail-closed，agent或master不可用时Deployment变更会被拒绝；应急执行kubectl delete mutatingwebhookconfiguration kubedoor-admis-configuration。卸载或重装agent前，先在「Agent管理」关闭「准入控制」。
• 💾请把PostgreSQL数据、kubedoor.conf和kubedoor.conf.ai-secrets（与Secret kubedoor-ai-security一致）一起备份；更换AI加密密钥会使已保存的kubeconfig无法解密。
• 📌NAMESPACE请保持默认的kubedoor，准入控制、定时任务等功能依赖这个命名空间。

♻升级说明

2.x改用PostgreSQL和脚本化部署，从1.x升级需要全新安装；2.x版本之间修改TAG_*后重新执行安装脚本即可（升级到2.2还要迁移账号，见下文）。

从1.x（Helm）升级

• 1.x的ClickHouse/MySQL数据不会迁移，2.x按全新安装设计；旧Helm chart注入的是CK_*变量，不要与新清单混用。
• 建议顺序：

• 1.x的MCP地址（独立kubedoor-mcp的NodePort /sse）已废弃，改用Web入口的/mcp。

从2.0.x升级到2.1

1. 更新到最新仓库代码；在kubedoor.conf中把TAG_MASTER、TAG_AGENT、TAG_WEB改为2.1.0，并新增TAG_AI="2.1.0"（不写会回退到latest）；旧的TAG_MCP不再使用，可以删除。
2. ENABLE_MCP的含义变了：现在只控制Web是否开放kubedoor-ai的/mcp、/sse、/messages，默认true。
3. 执行./install.sh master，再到各集群执行./install.sh agent（新版agent才支持AI的通用工具）。
4. 安装脚本只做apply，不会删除2.0.x遗留的独立MCP服务，请手动删除：

kubectl -n kubedoor delete deploy/kubedoor-mcp svc/kubedoor-mcp

1. 外部MCP客户端改用/mcp（/sse仍然兼容）；2.1起外部MCP的写操作需在Web中批准后才执行。
2. 首次安装2.1时脚本会生成kubedoor.conf.ai-secrets，请与PostgreSQL数据一起备份。

从2.1.x升级到2.2

2.2把登录与权限从nginx basic auth改为由master统一管理（本地账号 + LDAP，按K8S集群授权）。

1. 更新到最新仓库代码，在kubedoor.conf中把TAG_MASTER、TAG_AGENT、TAG_WEB、TAG_AI改为2.2.0（告警服务本版没有变化，TAG_ALARM保持2.1.0）。
2. 原WEB_AUTH_USERS/WEB_RW_USERS不再生效（安装时会提示）。执行./install.sh master后用内置管理员kubedoor登录，在「系统管理 → 用户与权限」重新建账号，或在「LDAP 设置」接入LDAP后按集群授权。
3. agent一律要带内置Agent账号Up4biLko1dNh：同集群agent的MASTER_WS改成ws://Up4biLko1dNh:<口令>@kubedoor-master.kubedoor，再到各集群执行./install.sh agent。跨集群agent如果沿用出厂口令，MASTER_WS不用改；以前改过这个账号口令的，升级前在kubedoor.conf里把KUBEDOOR_INIT_AGENT_PASSWORD设为原口令（只在首次创建账号时生效）。来不及一起改时，可先设AGENT_AUTH_REQUIRED="false"过渡，改完再改回true并重跑./install.sh master。
4. Grafana改为auth proxy接入：KubeDoor管理员是Admin、其他人是Viewer，并且只对能看到全部集群的账号开放。

2.x内部升级：master与kubedoor-ai采用Recreate策略，升级期间AI/MCP短暂不可用，开启了准入控制的集群在master重启期间Deployment变更会被拒绝，建议低峰期操作。nginx配置以subPath挂载，若Web镜像标签未变，需执行kubectl -n kubedoor rollout restart deploy/kubedoor-web让新配置生效。

📚文档

先看部署指南，再按需查阅各功能说明。

| 文档 | 内容 | | --- | --- | | 部署指南 | 一个脚本 + 一份配置安装控制端与各集群agent，PostgreSQL独立部署，含常见场景、改配置与排查 | | 账号与权限 | 本地账号与LDAP、全局权限与集群授权、内置账号、操作审计与忘记口令 | | AI助手 | 模型配置、资源范围、多轮对话、变更审批、全局记忆、kubeconfig直连与外部MCP | | 告警屏蔽 | 屏蔽规则语法、状态、命中预览与IM【屏蔽】链接 | | JVM参数管控 | Xms/Xmx/Xss/MaxMetaspaceSize的采集与管控，高峰期堆内存与G1 Eden使用率 | | K8S资源管控功能说明 | 基于准入控制管控副本数、需求值与限制值 | | K8S事件告警规则配置说明 | 事件告警规则文件的语法、默认规则与生效方式 | | K8S微服务镜像更新配置说明 | 按集群、时间段、账号授权镜像更新，以及镜像仓库凭据配置 | | 常见问题 | 常见问题与排查 |

开发者参考

• src/kubedoor-master/auth/README.md：认证、授权与审计的实现（权限模型、接口权限登记表、nginx auth_request）
• src/kubedoor-ai/README.md：AI服务的接口、环境变量、构建与测试
• src/kubedoor-tools/README.md：AI与agent共用的K8S执行库及安全边界
• src/kubedoor-web/README.md：前端开发与构建、登录页与系统管理页面
• src/kubedoor-agent/load_balance/README.md：节点均衡算法与参数

🔔KubeDoor交流群与🧧赞赏

如果觉得项目不错，麻烦动动小手点个⭐️Star⭐️ 如果你还有其他想法或者需求，欢迎在 issue 中交流

加作者微信或关注公众号加入交流群

🙇贡献者

StarsL.cn

xiaofennie

shidousanxia

comqx

seaworld008

🥰鸣谢

感谢如下优秀的项目，没有这些项目，不可能会有KubeDoor：

• Python AIOHTTP FastAPI Flask VUE Pure Admin Element Plus ECharts Monaco Editor Kubernetes VictoriaMetrics Prometheus PostgreSQL Grafana Nginx LangChain LangGraph DeepAgents FastMCP ...

• CassTime：KubeDoor的诞生离不开🦄开思的支持。