kubestellar/console
GitHub: kubestellar/console
KubeStellar Console 是一个 AI 驱动的多集群 Kubernetes 管理仪表板，提供 250+ 个 CNCF 项目的引导式安装任务和实时集群监控能力。
Stars: 108 | Forks: 109
# KubeStellar Console
[](https://console.kubestellar.io/acmm?repo=kubestellar%2Fconsole)
[](https://securityscorecards.dev/viewer/?uri=github.com/kubestellar/console)
[](https://www.bestpractices.dev/projects/12343)
[](https://github.com/kubestellar/console/issues)
AI 驱动的多集群 Kubernetes 仪表板，提供 250+ 个 CNCF 项目的引导式安装任务。
## 立即体验（无需安装）
评估控制台最快的方式是**托管版本**——无需 Kubernetes 集群、无需安装、无需配置。内置演示数据：
托管演示是一个独立的展示环境：它提供预设的演示数据，并且故意**不**与本地代理通信（Netlify 构建中禁用了 `LOCAL_AGENT_HTTP_URL`，因此浏览器无法访问你笔记本电脑上的 kc-agent）。使用它来探索 UI、浏览任务和测试卡片，而无需触碰你的机器。要连接**你自己的**集群或使用 AI 功能并配置你自己的密钥，你需要自行托管控制台——请参阅下一节。
## 我需要选择哪条路径？
| 我想要… | 做什么 | 需要集群吗？ | 需要安装任何东西吗？ |
|---|---|---|---|
| 探索 UI / 评估产品 | [console.kubestellar.io](https://console.kubestellar.io) | 否 | 否 |
| 将控制台连接到**我自己的**集群 | [**自行托管**](#local-install-self-host)控制台**并**在同一台机器上安装 [**kc-agent**](#kc-agent-bridge-self-hosted-console-to-your-clusters) | 是 | 是（curl + kc-agent） |
| 自行托管控制台（断网环境、自定义 OAuth 等） | [**本地安装**](#local-install-self-host) | 可选 | 是 |
| 在集群**内部**运行控制台 | [`deploy.sh`](deploy.sh) | 是 | Helm 风格脚本 |
## 本地安装（自行托管）
使用你自己的数据启动可用控制台的最快路径。`start.sh` 会下载预构建的控制台二进制文件和预构建的 `kc-agent`，启动两者，并打开 [http://localhost:8080](http://localhost:8080)：
```
curl -sSL https://raw.githubusercontent.com/kubestellar/console/main/start.sh | bash
```
使用 [`deploy.sh`](deploy.sh) 部署到集群中（`--openshift`、`--ingress `、`--github-oauth`、`--uninstall`）。对于需要与集群内 Kagenti 后端通信的 Helm chart 安装，请参阅 [连接 Kagenti](deploy/helm/kubestellar-console/README.md#connecting-kagenti)。
## kc-agent（桥接自行托管控制台到你的集群）
`kc-agent` 是一个小型本地 HTTP/WS 守护进程，**自行托管**的控制台与之通信（默认 `http://127.0.0.1:8585`）。它将来自浏览器的请求转发到你的 kubeconfig 上下文和 AI 提供方。[console.kubestellar.io](https://console.kubestellar.io) 上的托管演示无法访问它（#6195）——kc-agen 仅在自行托管时有用。
**如果你只想浏览 UI / 演示数据，则不需要 kc-agent**——直接使用托管演示即可。**`start.sh` 已经为你安装并启动了预构建的 kc-agent**，因此大多数用户无需手动安装。以下说明适用于开发构建或没有 Homebrew formula 的平台：
**kc-agent 的前置条件：**
- 一个指向一个或多个可访问集群的 kubeconfig（本地 `kubectl get nodes` 可用）
- macOS、Linux 或带有 WSL2 的 Windows（请参阅 [Windows 章节](#windows-wsl2)）
```
# macOS — Homebrew formula (pre-built)
brew tap kubestellar/tap && brew install kc-agent
# Linux / from source — requires Go 1.25+ (matches go.mod)
mkdir -p bin
go build -o bin/kc-agent ./cmd/kc-agent && ./bin/kc-agent
```
### kc-agent 认证（`KC_AGENT_TOKEN`）
`kc-agent` 通过 `KC_AGENT_TOKEN` 接受共享密钥。设置后，浏览器和代理的 WebSocket 请求必须提供 `Authorization: Bearer `（或真实 WebSocket 升级时使用 `?token=`）。当你希望增加额外保护层以防止其他本地进程访问 `127.0.0.1:8585` 时，推荐使用此方式。
- 如果你未设置，`start-dev.sh` 和 `startup-oauth.sh` 会为每次会话自动生成一个随机的 `KC_AGENT_TOKEN`。
- 如果你希望在重启之间使用稳定的密钥或手动启动 `kc-agent`，请自行设置 `KC_AGENT_TOKEN`。
- 使用 `openssl rand -hex 32` 生成一个。
```
export KC_AGENT_TOKEN="$(openssl rand -hex 32)"
./bin/kc-agent
```
当自行托管的控制台和 `kc-agent` 都在运行时，打开 [http://localhost:8080](http://localhost:8080)，你的本地集群会出现在集群选择器中。
## Windows（WSL2）
控制台安装脚本和 `kc-agent` 是 POSIX shell + Go，因此在 WSL2 中无需修改即可运行。不支持原生 Windows（PowerShell / CMD）——安装 [带 Ubuntu 的 WSL2](https://learn.microsoft.com/windows/wsl/install) 并从 WSL shell 运行所有内容：
```
# In PowerShell — one-time setup
wsl --install -d Ubuntu
```
然后从 Ubuntu/WSL shell 内部执行。**`start.sh` 只需要 `curl`**——它下载预构建的二进制文件，不需要 Go 工具链：
```
# Prerequisite: just curl
sudo apt-get update && sudo apt-get install -y curl
# Same install command as macOS / Linux
curl -sSL https://raw.githubusercontent.com/kubestellar/console/main/start.sh | bash
```
**从源码构建 `kc-agent` 是一条单独的路径**——仅当你想要代理的开发构建而不是 `start.sh` 已安装的预构建二进制文件时才需要。它需要 Go **1.25+**（`go.mod` 中固定的版本）和 `git`。Ubuntu 的 `golang-go` 包通常落后于当前版本；使用 [官方 Go 安装](https://go.dev/doc/install) 或 `longsleep/golang-backports` PPA 获取较新版本：
```
# add-apt-repository lives in software-properties-common — install it
# first on minimal Ubuntu/WSL images that don't ship with it.
sudo apt-get update && sudo apt-get install -y software-properties-common
sudo add-apt-repository -y ppa:longsleep/golang-backports
sudo apt-get update && sudo apt-get install -y golang-1.25 git
git clone https://github.com/kubestellar/console.git
cd console
mkdir -p bin
go build -o bin/kc-agent ./cmd/kc-agent && ./bin/kc-agent
```
在 **Windows** 浏览器中打开 http://localhost:8080——WSL2 会自动转发 `localhost`。由 [#6185](https://github.com/kubestellar/console/issues/6185) 跟踪。
## GitHub 认证
控制台使用 **两个** GitHub 凭据（#6190）。大多数用户**都不需要**——托管演示在没有任何 GitHub 认证的情况下也能正常工作。
| 凭据 | 作用 | 何时需要 |
|---|---|---|
| **GitHub OAuth App**（`GITHUB_CLIENT_ID` + `GITHUB_CLIENT_SECRET`） | 在 `localhost:8080** 对**自行托管**控制台进行登录 | 仅当你自行托管控制台**并且**需要用户登录时。对于托管演示可跳过。 |
| **整合的 GitHub PAT**（又名 `FeedbackGitHubToken`） | 同一个 PAT 驱动所有功能：夜间 E2E 状态、社区活动、排行榜小部件和打开 GitHub issue 的 `/issue` 页面 | 可选。没有它，`/issue` 返回 `503 Issue submission is not available`，GitHub 驱动的仪表板小部件将回退到演示数据。 |
**入门最低要求**：无需任何操作——访问 [console.kubestellar.io](https://console.kubestellar.io)。以上所有内容都是可选的。
### 设置整合的 PAT
有两种等效方式提供此 PAT——任选其一。两者都写入同一字段（`pkg/api/handlers/feedback.go` 和 `pkg/api/handlers/github_proxy.go` 中的 `FeedbackGitHubToken`），因此你不需要同时设置：
1. **仓库根目录的 `.env` 文件**——启动时设置，无需 UI 步骤：
FEEDBACK_GITHUB_TOKEN=ghp_…
2. **设置 UI**（仅限自行托管，**需要管理员角色**）——访问 Settings → GitHub Token → 粘贴。UI POST 到 `/api/github/token`，这受控制台 `admin` 角色限制，并由后端持久化到 `~/.kc/settings.json`。在全新的自行托管安装中，第一个认证用户会自动引导为管理员，因此本地实例不会被锁定在设置之外。
托管的 Netlify 演示无法持久化 PAT——它没有可写的本地后端——因此那里的设置 UI 保存不起作用。自行托管时使用环境变量路径。
### 设置 GitHub OAuth（仅限自行托管）
如果你自行托管控制台并需要登录：
1. **创建一个 [GitHub OAuth App](https://github.com/settings/developers)**
- 主页 URL：`http://localhost:8080`
- 回调 URL：`http://localhost:8080/auth/github/callback`
- **创建应用后**，记下你的 **Client ID**（立即可见）并生成一个 **Client Secret**（点击"Generate a new client secret"）
2. **克隆仓库**（如果尚未克隆）：
git clone https://github.com/kubestellar/console.git
cd console
3. **在仓库根目录创建 `.env` 文件**（`console/.env`）：
# 使用你的 GitHub OAuth App 凭据创建 .env 文件
cat > .env << 'EOF'
GITHUB_CLIENT_ID=your-client-id-here
GITHUB_CLIENT_SECRET=your-client-secret-here
EOF
**将 `your-client-id-here` 和 `your-client-secret-here`** 替换为你的 GitHub OAuth App 中的实际值（步骤 1）。
**⚠️ 常见错误：**
- **缺少 `.env` 文件**：控制台在仓库根目录（`console/.env`）查找 `.env`，而不是在你的主目录或其他位置。
- **凭据错误**：Client ID 和 Client Secret 必须与 GitHub OAuth App 设置中显示的内容**完全**匹配。复制粘贴以避免拼写错误。
- **密钥过期**：如果你在 GitHub 中重新生成了 Client Secret，必须用新值更新 `.env`。
**OAuth 错误排查：**
- `"invalid client credentials"` → 验证 `.env` 中的 `GITHUB_CLIENT_ID` 和 `GITHUB_CLIENT_SECRET` 是否与 https://github.com/settings/developers 中的 GitHub OAuth App 匹配
- `"redirect_uri_mismatch"` → GitHub OAuth App 中的回调 URL 必须完全是 `http://localhost:8080/auth/github/callback`
4. **启动控制台**：
./startup-oauth.sh
打开 http://localhost:8080 并使用 GitHub 登录。对于 Kubernetes 部署，请改为向 `deploy.sh` 传递 `--github-oauth`。
### 整合的 PAT 权限范围
无论你使用上述哪种路径（环境变量或设置 UI），[Personal Access Token](https://github.com/settings/tokens) 需要**以下之一**：
- 具有 `repo` 范围的 **classic** PAT，**或**
- 同时具有 **Issues: Read & Write** *和* **Contents: Read & Write** 的 **fine-grained** PAT（对照 `pkg/api/handlers/feedback.go:71` 验证——Contents 是必需的，不仅仅是 Issues）。
## AI 配置
控制台可以使用 AI 进行自适应卡片建议和任务帮助。AI 是**可选的**——UI、任务和仪表板在未配置任何 AI 密钥的情况下都能正常工作（#6191）。
**重要提示**：AI BYOK 仅在**自行托管**的控制台上有效。[console.kubestellar.io](https://console.kubestellar.io) 上的托管演示明确禁用了 `LOCAL_AGENT_HTTP_URL`（在 `web/src/lib/constants/network.ts` 中已验证），因此浏览器无法在那里访问本地代理。要使用你自己的 AI 密钥，请先自行托管控制台。
### 支持的 AI 提供方（基于 CLI 的和本地 LLM）
控制台使用**本地 CLI 提供方**和**自托管 LLM** 来保持对集群访问和工具功能的完全控制。不支持直接的 API 密钥提供方（如原始 `ANTHROPIC_API_KEY`、`OPENAI_API_KEY` 或 `GOOGLE_API_KEY`），因为它们绕过了执行集群命令所需的本地 CLI 工具模型（参见 `pkg/agent/registry.go:378` 和 [`docs/security/SECURITY-MODEL.md`](docs/security/SECURITY-MODEL.md#L175)）。
**推荐的设置路径：**
1. **基于 CLI 的代理**（具有完整工具执行能力）：
# 安装 Claude Desktop 或 claude CLI — https://claude.ai/download
# 安装 Gemini CLI — 按照官方 Google AI SDK 说明操作
# 安装 GitHub Copilot CLI — gh extension install github/gh-copilot
# 安装其他 CLI 代理：codex、antigravity、goose、bob
# kc-agent 将自动检测已安装的 CLI 代理 — 无需环境变量
./bin/kc-agent
2. **本地/自托管 LLM 服务器**（OpenAI 兼容端点）：
# Ollama（本地）
export OLLAMA_URL=http://127.0.0.1:11434
export OLLAMA_MODEL=llama3.2
# Open WebUI（自托管网关）
export OPEN_WEBUI_URL=https://your-openwebui.example.com
export OPEN_WEBUI_API_KEY=your-key
export OPEN_WEBUI_MODEL=gpt-4
# 其他支持的：llama.cpp、LocalAI、vLLM、LM Studio、Red Hat AI Inference Server
# 完整列表见 docs/security/SECURITY-MODEL.md
./bin/kc-agent
**如果未配置 AI 提供方**，AI 驱动的功能将回退到确定性/基于规则的行为。卡片建议、任务和仪表板仍然完全可用。
**安全模型、断网部署和本地/自托管 LLM** 在 [`docs/security/SECURITY-MODEL.md`](docs/security/SECURITY-MODEL.md) 中有详细说明。该文档解释了浏览器、Go 后端、kc-agent 和 AI 提供方之间的数据流；如何在没有外部 AI 访问的情况下运行控制台；以及目前使用 kc-agent 基于 CLI 的代理支持的自托管路径。
## 工作原理
1. **入门引导** — 使用 GitHub 登录，回答角色问题，获得个性化仪表板
2. **自适应 AI** — 跟踪卡片交互，当你的关注点转移时建议更换（Claude、OpenAI 或 Gemini）
3. **MCP Bridge** — 通过 `kubestellar-ops` 和 `kubestellar-deploy` 查询集群状态（pod、deployment、事件、漂移、安全）
4. **任务** — 分步引导式安装，包含预检、验证、故障排除和回滚
5. **实时** — 通过 WebSocket 从所有连接的集群进行实时事件流传输
## 架构
请参阅 KubeStellar 网站上的完整[架构文档](https://kubestellar.io/docs/console/overview/architecture)。
### 相关仓库
- **[console-kb](https://github.com/kubestellar/console-kb)** — 250+ 个 CNCF 项目和常见 Kubernetes 问题解决方案的知识库及引导式安装程序
- **[console-marketplace](https://github.com/kubestellar/console-marketplace)** — 每个 CNCF 项目的社区贡献监控卡片
- **[kc-agent](cmd/kc-agent/)** — 本地代理，桥接浏览器与 kubeconfig、编码代理（Codex、Copilot、Claude CLI）和 MCP 服务器（`kubestellar-ops`、`kubestellar-deploy`）
- **[claude-plugins](https://github.com/kubestellar/claude-plugins)** — 用于 Kubernetes 的 Claude Code 市场插件
- **[homebrew-tap](https://github.com/kubestellar/homebrew-tap)** — KubeStellar 工具的 Homebrew formula
- **[KubeStellar](https://kubestellar.io)** — 多集群配置管理
## 质量保证
控制台使用 AI 工具（GitHub Copilot、Claude Code）加速开发。质量通过**分层反馈循环**维护——无论作者如何，每个 PR 都会触发相同的自动化检查，持续监控捕获 PR 检查遗漏的问题。
- **提交前**：TypeScript 构建 + Go 构建 + 5 项构建后安全检查 + lint
- **合并前**：nil 安全、ts-null 安全、数组安全、API 契约、Playwright E2E、覆盖率门控、TTFI 性能、CodeQL、Copilot 代码审查、UI/UX 标准扫描器、视觉回归
- **视觉回归**：18 个 UI 组件记录为带有主题支持的 Storybook 故事。Playwright 在每次触及 UI 组件的 PR 上捕获截图并与基线进行差异对比。
- **合并后**：针对生产环境（`console.kubestellar.io`）运行目标 Playwright 测试；失败时重新打开原始 issue
- **持续**：每小时覆盖率（12 个分片）、每天 4 次 QA、夜间 E2E、夜间安全扫描、实时 GA4 错误跟踪、UI/UX 标准夜间扫描
当识别出回归类别时，维护者会在最早的可能循环中添加自动化检查。完整细分请参阅 [docs/AI-QUALITY-ASSURANCE.md](docs/AI-QUALITY-ASSURANCE.md)。
## 许可证
Apache License 2.0——参见 [LICENSE](LICENSE)。
标签：AIOps, AI辅助, AI风险缓解, API集成, CNCF, DNS解析, IT运维, MTTR, OpenSSF, Pandas, SaaS, Socks5代理, SRE, Web控制台, web渗透, 云原生计算基金会, 云安全态势管理, 云管理, 仪表盘, 任务引导, 偏差过滤, 全托管, 分布式系统, 前端应用, 可观测性, 响应大小分析, 基础设施管理, 多集群管理, 子域名突变, 安全合规, 安全评分, 安装向导, 容器编排, 平台工程, 开源项目, 提示注入, 故障响应, 日志审计, 智能运维, 最佳实践, 治理, 特权提升, 用户界面, 监控, 策略引擎, 网络代理, 网络安全挑战, 网络调试, 自动化, 自动化攻击, 自动化运维, 自动化部署, 自助服务, 自托管, 覆盖率, 请求拦截, 运维平台, 运维自动化, 部署, 集成平台, 集群管理, 集群编排