# KubeNest

**Repository Path**: yunwe/kube-nest

## Basic Information

- **Project Name**: KubeNest
- **Description**: 面向 Kubernetes 与 Docker 的轻量级 Web 管理平台，提供集群资源可视化、工作负载管理、便捷排障、监控告警、应用插件一键部署能力。
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-01
- **Last Updated**: 2026-10-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Docker, Kubernetes, prometheus

## README

# KubeNest · 容器云管理平台

> 面向 Kubernetes 与 Docker 的轻量级 Web 管理平台，提供集群资源可视化、工作负载管理、便捷排障、监控告警、应用插件一键部署能力。

![Version](https://img.shields.io/badge/version-1.53.3-blue) ![License](https://img.shields.io/badge/license-MIT-green)

---

## 📋 版本说明

完整的版本变更记录请查阅 [VERSION.md](./docs/VERSION.md)。

## 📸 界面预览

### 仪表盘

![仪表盘](./docs/img/仪表盘.png)

### 角色配置

![插件管理](./docs/img/角色配置.png)

### 插件管理

![插件管理](./docs/img/插件管理.png)

### 集群权限配置

![](./docs/img/RBAC.png)

---

## ✨ 功能概览

KubeNest 按功能划分为四大模块组，覆盖容器云管理的完整链路。

### 概览

#### 仪表盘

进入平台后的首页，提供全局视角的资源总览：

- **平台统计卡片**：展示已纳管的 K8s 集群数、Docker 环境数、用户数、已安装插件数
- **集群资源统计**：当前选中集群的 14 类资源计数（Deployment / Service / ConfigMap / PVC 等），跟随顶栏命名空间过滤实时联动，支持展开/折叠
- **集群信息**：API Server 地址、K8s 版本、集群状态、节点数量
- **节点列表**：展示 CPU / 内存 / 磁盘使用率（需接入 Prometheus），支持编辑节点标签/污点、驱逐 Pod
- **最近事件**：集群级 Warning 事件流，快速定位异常
- **资源使用率趋势**：CPU / 内存 / 磁盘 / 网络 IO 趋势图（需接入 Prometheus）

#### 集群与环境

统一管理所有 K8s 集群与 Docker 环境的入口：

- **K8s 标签页**：添加/编辑/删除集群，支持 kubeconfig 文件上传或 API Token + Server 地址两种接入方式
- **Docker 标签页**：管理 Docker Standalone / Swarm 环境，支持 `direct`（Docker Socket）、`push`（Agent 主动上报）、`pull`（平台拉取 Agent）三种连接模式
- 所有凭据（Token、kubeconfig、TLS 证书）均使用 AES-256 加密存储

---

### 资源

#### 工作负载

支持 6 类 K8s 工作负载的完整生命周期管理：

| 资源类型 | 支持操作 |
|----------|----------|
| Deployment | 创建/编辑/删除/扩缩容/重启/回滚/暂停恢复/YAML 编辑 |
| StatefulSet | 创建/编辑/删除/扩缩容/重启/回滚/暂停恢复/YAML 编辑 |
| DaemonSet | 创建/编辑/删除/重启/回滚/暂停恢复/YAML 编辑 |
| Job | 创建/编辑/删除/YAML 编辑 |
| CronJob | 创建/编辑/删除/暂停恢复/YAML 编辑 |
| Pod | 查看详情/删除/日志查看/Web Terminal |

**使用方式**：

1. 左侧菜单选择具体工作负载类型，进入列表页
2. 列表按命名空间分组，支持多命名空间筛选、关键词搜索、排序
3. 点击「创建」进入可视化表单页面，填写基础信息、容器配置、资源与调度策略后提交
4. 点击行内「编辑」修改已有工作负载，提交前可预览 YAML
5. 操作列提供重启、扩缩容、回滚、YAML 编辑、删除等操作
6. 勾选多行可批量删除或下载 YAML
7. 点击名称进入详情页，查看 Pod 列表、关联 Service/Ingress、事件、调度与安全配置

**工作负载详情页**包含 7 个 Tab：

- **概览**：基本信息、选择器、数据卷、注解、环境变量、容忍、所有者引用
- **调度与安全**：Pod 安全上下文、容器安全上下文、镜像拉取策略、亲和性规则、拓扑分布约束、DNS 策略
- **网络**：关联 Service（含 ClusterIP/端口/Selector）与 Ingress（含规则/路径/TLS）
- **Pods**：Pod 列表（含 Pod IP / QoS / 容器资源配额），支持展开查看容器状态、查看日志、进入终端
- **状态与事件**：Conditions 状态、关联 Pod/ReplicaSet 事件
- **YAML**：实时 YAML 查看

#### 服务发现

管理集群内的 Service 与 Ingress 资源：

- **Service**：创建/编辑/删除，支持可视化表单，自动展示关联的 Pod 端点
- **Ingress**：创建/编辑/删除，支持域名冲突检测，展开行显示路径规则与 TLS 配置
- 列表按命名空间分组，支持排序、多选批量删除/下载 YAML

#### 权限控制（RBAC）

管理 K8s 原生 RBAC 资源，分为 4 个子菜单：

- **角色 Role**：命名空间级角色，支持可视化编辑规则
- **角色绑定 RoleBinding**：将角色绑定到用户/组/ServiceAccount
- **集群角色 ClusterRole**：集群级角色
- **集群角色绑定 ClusterRoleBinding**：集群级角色绑定

每个子页面均支持创建、编辑、删除操作，创建时可使用可视化表单而非直接写 YAML。

#### 配置存储

管理集群内的配置与存储资源：

- **ConfigMap**：创建/编辑/删除/克隆，支持可视化键值编辑与 YAML 详情
- **Secret**：创建/编辑/删除，数据自动脱敏显示（`***`），支持可视化键值编辑
- **PVC 存储卷**：创建/编辑/删除，展示绑定状态与关联 PV
- **StorageClass**：创建/编辑/删除，支持可视化表单
- **PV**：创建/编辑/删除，集群级资源

#### Docker 容器管理

仅在选中 Docker 环境时显示，提供容器与应用的编排能力：

- **容器**：查看容器列表（名称/镜像/状态/端口），支持启动/停止/重启/删除，查看日志，进入 Web Terminal
- **应用栈**：通过 Docker Compose 文件部署多容器应用栈，支持查看/删除已部署的 Stack
- **环境管理**（管理员）：添加/编辑/删除 Docker 环境，配置 Agent 连接模式

---

### 平台

#### 插件管理

内置插件市场，支持一键部署常用中间件到目标集群：

- **模板语法**：Helm 风格 `{{ .Values.变量名 }}` 占位符，后端自动转换为 Jinja2 渲染
- **参数表单**：前端根据 Schema 动态渲染表单（string/number/boolean/select）
- **一键部署**：选择目标集群 → 填写参数 → 确认 YAML 预览 → 部署
- **部署历史**：记录每次部署的完整 YAML，支持一键卸载（反向删除已部署资源）
- **内置模板**：Prometheus Server 一键部署（ConfigMap + Deployment + Service），部署后自动回填 Prometheus 地址

#### 可观测性

- **事件**：按命名空间筛选集群 Warning/ Normal 事件，支持关键词搜索与时间排序
- **Prometheus 集成**：仪表盘趋势图与节点使用率依赖 Prometheus，未接入时显示占位提示，不影响其他功能

---

### 系统

#### 用户中心（管理员）

- 创建/编辑/删除用户，分配角色（admin/viewer 或自定义角色）
- 启用/禁用用户账号
- 支持关键词搜索与分页

#### 角色配置（管理员）

- 内置 admin（全部权限）与 viewer（只读）角色
- 支持自定义角色，按 26 项权限细粒度分配
- 角色启用/禁用，最后管理员保护（防止删光管理员）

#### 审计日志

- 所有写操作（创建/编辑/删除/启停）自动记录
- 记录内容：操作人、操作类型、目标资源、时间、IP
- 默认保留 90 天，每周日 03:00 自动清理过期日志

#### 个人信息

- 任何登录用户可查看自己的账号信息（用户名/邮箱/角色/最近登录时间）
- 修改密码（需验证旧密码）

---

### 其他特性

- **顶栏命名空间多选**：横向单行排列，超过 3 个显示省略号，hover 可查看完整列表
- **导入 YAML**：支持粘贴文本或上传文件，多文档 apply 部署到当前集群
- **Web Terminal**：浏览器直接进入 Pod 终端（基于 xterm.js + WebSocket），支持多窗口
- **全局搜索**：顶栏搜索框可快速检索集群资源
- **双 Token 认证**：Access Token (2h, LocalStorage) + Refresh Token (7d, HttpOnly Cookie)，自动刷新
- **国际化**：中英文双语切换，所有界面文本通过 `vue-i18n` 管理
- **暗色主题**：亮色 / 暗色 / 跟随系统三种模式平滑切换
- **响应式布局**：适配 4K / 2K / 笔记本 / 平板 / 手机屏幕

---

## 🛠️ 技术栈

| 层级 | 技术 | 说明 |
| --- | --- | --- |
| 前端 | Vue 3 + Vite + Element Plus | Composition API + Pinia + Vue Router |
| 国际化 | vue-i18n | 中英文双语，按需切换 |
| 图表 | ECharts | Dashboard 趋势图 |
| 编辑器 | Monaco Editor | YAML / JSON 编辑，Worker 按需加载 |
| 终端 | xterm.js | WebSocket 实时双向通信 |
| 后端 | FastAPI (Python 3.10+) | 异步框架 + Pydantic v2 |
| 数据库 | PostgreSQL 14+ | SQLAlchemy 异步 ORM + 启动时自动执行 migrations SQL（MIGRATION_ENABLED=true 启用） |
| K8s SDK | kubernetes | kubeconfig / Token 双模式接入 |
| Docker SDK | docker-py | 含 TLS 证书认证 |
| 加密 | AES-256 (Fernet) | 所有 `_encrypted` 字段加密存储 |

---

## 📁 项目结构

```
kubenest/
├── backend/                # FastAPI 后端（含全局配置 config.yaml）
│   ├── app/
│   │   ├── api/            # API 路由（按模块划分）
│   │   ├── core/           # 配置/数据库/响应/安全/migration_runner
│   │   ├── models/         # SQLAlchemy ORM 模型
│   │   ├── schemas/        # Pydantic 请求/响应模型
│   │   ├── services/       # 业务逻辑（K8s/Docker/插件/审计）
│   │   ├── utils/          # JWT/AES/YAML 工具
│   │   └── main.py         # FastAPI 入口
│   ├── requirements.txt
│   ├── Dockerfile          # 含 ARM 变体 Dockerfile.arm
│   └── version.yaml        # 平台版本号
├── frontend/               # Vue 3 前端
│   ├── src/
│   │   ├── api/            # API 调用封装
│   │   ├── components/     # YamlEditor / DeployDialog / ...
│   │   ├── layouts/        # 主布局
│   │   ├── views/          # 页面视图
│   │   ├── router/         # 路由 + 权限守卫
│   │   ├── store/          # Pinia 状态
│   │   ├── styles/         # 主题变量 + 暗色模式
│   │   └── locales/        # zh-CN.json / en.json
│   ├── vite.config.js      # Monaco Worker + manualChunks 优化
│   ├── Dockerfile
│   └── nginx.conf          # 含 WebSocket 转发
├── docs/                    # 文档 + 配置（redis.conf）+ k8s 部署清单 + 界面截图
├── init-scripts/           # init-db.sql 建表 + Demo 数据
├── docker-compose.yml      # 一键启动所有服务
└── README.md
```

---

## 🚀 快速启动

### 方式一：Docker Compose 一键启动（推荐）

```bash
# 1. 克隆项目
git clone https://gitee.com/yunwe/kube-nest.git kubenest && cd kubenest

# 2. 生成密钥并配置环境变量（.env 已被 gitignore，凭据仅存本地，不会提交）
cp .env.example .env
#    编辑 .env，填入 SECRET_KEY / ENCRYPTION_KEY / POSTGRES_PASSWORD / REDIS_PASSWORD
#    两个密钥的生成命令见下方「🔐 密钥管理」

# 3. 一键启动（首次会自动构建镜像）
docker compose up -d

# 4. 查看启动状态
docker compose ps

# 5. 访问应用
#    前端：http://localhost:8002
#    后端 API 文档：http://localhost:8001/docs
```

### 方式二：本地开发模式

#### 后端

```bash
cd backend

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 配置环境变量（项目根目录，.env 已被 gitignore）
cp .env.example .env
# 编辑 .env，填入 SECRET_KEY / ENCRYPTION_KEY / POSTGRES_PASSWORD / REDIS_PASSWORD
# 数据库与 Redis 连接串在 backend/config.yaml 中配置（占位符，真实密码经环境变量注入）

# 初始化数据库（PostgreSQL 已启动）
psql -h localhost -U kubenest -d kubenest -f ../init-db.sql

# 启动开发服务器
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

#### 前端

```bash
cd frontend

# 安装依赖
npm install

# 启动开发服务器（自动代理 /api 到 localhost:8000）
npm run dev

# 访问 http://localhost:5173
```

### 方式三：Kubernetes 部署

将 KubeNest 部署到已有的 Kubernetes 集群中，所有部署 YAML 位于 `docs/k8s/` 目录下。

#### 前置条件

- 一个可用的 Kubernetes 集群（v1.20+）
- 已安装 `kubectl` 并配置好 kubeconfig
- 工作节点需有可写目录 `/mnt/kube-nest/postgres`（PostgreSQL 数据以 hostPath 方式保存，注意 Pod 迁移到其他节点时数据不会自动跟随）
- （可选）已安装 Ingress Controller

#### 部署步骤

**1. 构建并推送镜像**

```bash
# 后端镜像
docker build -t <your-registry>/kubenest-backend:latest ./backend
docker push <your-registry>/kubenest-backend:latest

# 前端镜像
docker build -t <your-registry>/kubenest-frontend:latest ./frontend
docker push <your-registry>/kubenest-frontend:latest
```

**2. 修改配置**

```bash
# 编辑 docs/k8s/secret.yaml，替换所有密码和密钥（SECRET_KEY / ENCRYPTION_KEY / DATABASE_URL 等）
# 编辑 docs/k8s/kubenest.yaml，将 image 地址替换为你的镜像仓库地址
# docs/k8s/configmap.yaml 已包含 kube-nest-config（挂载 config.yaml）与 kube-nest-init-sql（数据库初始化 SQL）
```

**3. 部署到集群**

```bash
# 一键部署所有资源
kubectl apply -f docs/k8s/

# 或按顺序部署
kubectl apply -f docs/k8s/namespace.yaml
kubectl apply -f docs/k8s/secret.yaml
kubectl apply -f docs/k8s/configmap.yaml
kubectl apply -f docs/k8s/kubenest.yaml
kubectl apply -f docs/k8s/svc.yaml
kubectl apply -f docs/k8s/ingress.yaml
```

**4. 验证部署**

```bash
# 查看 Pod 状态
kubectl -n kubenest get pods

# 查看 Service
kubectl -n kubenest get svc

# 查看 Ingress（如果启用）
kubectl -n kubenest get ingress
```

**5. 访问应用**

- 如果启用了 Ingress：通过配置的域名访问
- 如果使用 NodePort：`http://<node-ip>:<frontend-nodeport>`
- 临时测试：`kubectl -n kubenest port-forward svc/kubenest-frontend 8080:80`

#### K8s 资源清单说明

| 文件 | 资源类型 | 说明 |
|------|----------|------|
| `docs/k8s/namespace.yaml` | Namespace | 创建 `kubenest` 命名空间 |
| `docs/k8s/secret.yaml` | Secret | 密码与密钥（SECRET_KEY / ENCRYPTION_KEY / DATABASE_URL / POSTGRES_PASSWORD 等） |
| `docs/k8s/configmap.yaml` | ConfigMap | `kube-nest-config`（挂载 config.yaml）+ `kube-nest-init-sql`（数据库初始化 SQL） |
| `docs/k8s/kubenest.yaml` | Service + StatefulSet + Deployment | PostgreSQL（hostPath 持久化）+ 后端 + 前端合并部署清单 |
| `docs/k8s/svc.yaml` | Service | 前后端 ClusterIP 服务 |
| `docs/k8s/ingress.yaml` | Ingress | 可选，对外暴露前端服务 |

---

## 🔑 默认账号

| 用户名 | 密码 | 角色 | 说明 |
| --- | --- | --- | --- |
| `admin` | `admin123` | admin | 全部权限（仅限 Demo，生产部署后请立即修改） |
| `viewer` | `viewer123` | viewer | 只读权限 |

> ⚠️ **安全提示**：默认账号仅供开发与演示。生产环境部署后请立即登录 admin 修改密码或创建新的管理员账户后禁用默认账户。

---

## 📚 API 文档

后端启动后自动生成 OpenAPI 文档：

- **Swagger UI**：http://localhost:8000/docs
- **ReDoc**：http://localhost:8000/redoc
- **OpenAPI JSON**：http://localhost:8000/openapi.json

所有 API 遵循统一响应格式：

```json
{
  "code": 0,
  "message": "success",
  "data": { ... }
}
```

错误时 `code` 非 0，并携带友好错误信息。

---

## 🔐 密钥管理

后端依赖**两把独立密钥**，均通过项目根目录 `.env`（已被 gitignore，禁止提交）或环境变量注入。生产环境（`APP_ENV=production`）下任一密钥缺失或为占位符，启动即失败（错误信息会给出生成命令）。

### 1. SECRET_KEY — JWT 签名密钥（认证）

用于签发/校验登录 Token（HMAC-SHA256）。**泄露**：可伪造任意用户登录态；**变更**：所有已登录用户 Token 失效，需重新登录（可接受）。

**生成**（64 位十六进制）：

```bash
openssl rand -hex 32
# 或：python -c "import secrets; print(secrets.token_hex(32))"
```

### 2. ENCRYPTION_KEY — AES-256 数据加密密钥（存储）

用于加密数据库中敏感字段（集群 Token / kubeconfig、Docker 环境 TLS 证书、Agent API Key 等 `*_encrypted` 字段）。**泄露**：可解密全部凭据；**变更**：⚠️ 历史密文永久无法解密（不可逆），请务必做好备份。

**生成**（32 字节 Base64）：

```bash
python -c "import os,base64;print(base64.b64encode(os.urandom(32)).decode())"
```

### 配置方式

```bash
# 项目根目录
cp .env.example .env
# 编辑 .env：将上方两条命令的输出分别填入 SECRET_KEY 与 ENCRYPTION_KEY
# docker-compose 通过 ${SECRET_KEY} / ${ENCRYPTION_KEY} 注入后端容器
```

> ⚠️ **密钥丢失将导致已有敏感数据无法解密**（ENCRYPTION_KEY）或全部用户掉线（SECRET_KEY），请务必备份并存放在安全位置。

---

## 🎨 主题与语言

- 顶栏右侧提供 **主题切换**（亮色 / 暗色 / 跟随系统）和 **语言切换**（中文 / English）
- 偏好保存在浏览器 LocalStorage，刷新后自动恢复
- 登录页同样支持独立的主题与语言切换，与主应用共享偏好

---

## 📝 审计日志保留策略

- 默认 **永久保存**
- 管理员可在「审计日志」页面配置保留天数（0 = 永久保存）
- 后台任务在 **每周日 03:00 UTC** 按平台设置自动清理过期日志
- GET 类只读请求不记录审计日志

---

## 🐛 常见问题

**Q：启动后无法登录，提示数据库连接失败？**

A：检查 `docker compose ps` 中 `db` 容器是否健康，并确认项目根目录 `.env` 中的 `POSTGRES_PASSWORD` 与 `backend/config.yaml` 中数据库连接配置一致。

**Q：监控图表显示"监控数据暂不可用"？**

A：未配置 Prometheus 时接口返回 `null` + `prometheus_unavailable: true`，前端展示占位提示。配置 `PROMETHEUS_URL` 环境变量即可启用。

**Q：插件部署失败提示"资源已存在"？**

A：部署冲突检测发现目标 Namespace / Stack 中已存在同名资源。请修改名称或先删除现有资源后重试。

**Q：WebSocket 终端连接不上？**

A：检查浏览器是否通过 https 访问（wss 需 https），以及 Nginx 是否正确转发 WebSocket 升级请求（参考 `frontend/nginx.conf`）。

**Q：Pod 无法使用终端，报错 "[WebSocket error]"？**

A：通常是浏览器与后端之间存在代理（Nginx / 网关 / 负载均衡等）未配置 WebSocket 转发。需要在上游代理中开启 `Connection: Upgrade` 与 `Upgrade: websocket` 请求头透传（Editor 升级相关），并确认 nginx.conf 已将 `/api/v1/.../exec` 等终端接口纳入 WebSocket 代理规则。可参考 `frontend/nginx.conf`。

---

## 🧩 Git 钩子与提交规范

本项目已提供 Git 钩子，用于：

- 验证提交信息是否符合 Conventional Commits 规范

首次使用或重新克隆仓库后，请运行：

```bash
./scripts/install-git-hooks.sh
```

提交信息格式示例：

```text
feat(cluster): add cluster switch feature

支持在主页快速切换 Kubernetes/Docker 环境。
```

如果 commit message 不符合规范，提交会被阻止。

---

## 📄 License

MIT © 2026 KubeNest