# k8s_operation_1

**Repository Path**: huqi2020/k8s_operation_1

## Basic Information

- **Project Name**: k8s_operation_1
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 12
- **Created**: 2025-11-05
- **Last Updated**: 2025-11-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# k8soperation

## 🧩 项目简介

一个基于 **Go + Gin + Gorm + Zap** 的后端脚手架，专为中后台与微服务场景设计。
项目内置 **配置化（YAML/ENV）**、**JWT 鉴权（含刷新）**、**统一错误码**、**日志轮转**、**健康检查** 与 **优雅关闭** 等基础能力；并集成 **Swagger 文档系统** 与 **Makefile 工具链**，支持一键生成与预览 API 文档（`make swag` / `make swagger-standalone`），执行 `make run` 即可本地启动。

在此基础上，项目进一步整合了 **Kubernetes 后台运维管理能力**，提供对 **Pod / Deployment / StatefulSet / DaemonSet / Service / Ingress / Job / CronJob / Secret** 等资源的增删改查、扩缩容、滚动升级、版本回滚、事件与日志等接口，可作为企业级 K8s 管理平台的后端核心。

------

## ✨ 特性亮点

- ✅ **配置化管理**：集中式配置文件 `configs/config.yaml` + 全局加载 `global.AppSetting`，统一时区、JWT、日志等
- ✅ **鉴权体系**：`internal/pkg/jwt` 封装 Token 签发 / 刷新 / 验证，中间件一键集成
- ✅ **日志链路**：基于 Zap + 按日轮转，系统日志与业务日志分流
- ✅ **数据分层**：Gorm 初始化封装 + DAO / Service / Controller 清晰分层
- ✅ **健康与关闭**：内置健康探针与 `shutdown.Graceful` 优雅退出
- ✅ **Swagger 文档体系**：`/swagger` 与 `/swagger-standalone` 即点即测
- ✅ **Kubernetes 能力扩展**：已实现 **Pod / Deployment / StatefulSet / DaemonSet / Service / Ingress / Job / CronJob / Secret** 管理接口
- ✅ **DataSelect 引擎**：统一分页、模糊搜索、排序（所有列表接口风格一致）
- ✅ **事件聚合**：按资源聚合 K8s Event，快速排障

------

## 新增 Kubernetes 后台管理功能（v7.0+）

> 生产可用：接口均已在 Swagger 上验证通过。

### Deployment 管理

- 列表、详情、创建、更新、删除
- 扩缩容（Patch `spec.replicas`）
- 镜像更新（Strategic Merge Patch）
- 滚动重启（等价 `kubectl rollout restart`）
- 版本回滚（基于 ReplicaSet）
- 事件聚合（Deployment / RS / Pod）

### Pod 管理

- 列表、详情、优雅/强制删除
- 日志查看（一次性/流式、容器选择、尾行数）
- 容器镜像 Patch（SMP，mergeKey=name）
- 事件查看

### StatefulSet / DaemonSet 管理

- CRUD、详情、列表、扩缩容
- 历史版本与回滚（基于 ControllerRevision）
- 事件聚合

### Service 管理

- CRUD、详情、列表
- Patch：**StrategicMergePatch** / **JSON Merge Patch**
- 端口映射与选择器管理

### Ingress 管理

- CRUD、详情、列表
- Patch：**StrategicMergePatch**（适合加注解） / **JSON Merge Patch**（替换 `rules/tls`）
- TLS 证书绑定（通过 Secret）
- 事件查看

### Job / CronJob 管理

- Job：创建 / 删除 / 状态查询 / `TTLSecondsAfterFinished`
- CronJob：创建 / 删除 / 启停 / 历史 Job 列表（按标签选择器）

### Secret 管理

- 支持 `Opaque`、`kubernetes.io/tls`、`kubernetes.io/dockerconfigjson`
- 查看 / 创建 / 删除
- 自动 Base64 解码（仅管理员视图）
- 与 Ingress TLS 协同（`spec.tls[].secretName`）

------

## 认证

- **登录**：`POST /api/v1/auth/login`
- **退出**：`POST /api/v1/auth/logout`

**示例：**

```
# 登录获取 JWT
curl -s -X POST http://localhost:8080/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"123456"}'

# 携带 token 访问受保护接口
curl -H "Authorization: Bearer <JWT>" \
  "http://localhost:8080/api/v1/user/list?page=1&limit=10"
```

------

## K8s 集群管理

| 动作   | 方法 & 路径                                               | 说明                           |
| ------ | --------------------------------------------------------- | ------------------------------ |
| 创建   | `POST /api/v1/k8s/cluster/create`                         | 创建集群（保存 kubeconfig 等） |
| 初始化 | `POST /api/v1/k8s/cluster/init`                           | 连通性检测/预热                |
| 修改   | `POST /api/v1/k8s/cluster/update`                         | 更新集群信息                   |
| 删除   | `POST /api/v1/k8s/cluster/delete`                         | 软删除                         |
| 列表   | `GET /api/v1/k8s/cluster/list?cluster_name=&page=&limit=` | 支持分页与名称过滤             |

**示例：**

```
curl -H "Authorization: Bearer <JWT>" \
  "http://localhost:8080/api/v1/k8s/cluster/list?page=1&limit=10&cluster_name="
```

------

## Deployment 管理

| 动作         | 方法 & 路径                                    | 关键参数                                                     |
| ------------ | ---------------------------------------------- | ------------------------------------------------------------ |
| 创建         | `POST /api/v1/k8s/deployment/create`           | body: `KubeDeploymentCreateRequest`（可选创建 Service）      |
| 删除         | `DELETE /api/v1/k8s/deployment/delete`         | query: `namespace`,`name`                                    |
| 删除 Service | `DELETE /api/v1/k8s/deployment/delete_service` | query: `namespace`,`name`                                    |
| 详情         | `GET /api/v1/k8s/deployment/detail`            | query: `namespace`,`name`                                    |
| 列表         | `GET /api/v1/k8s/deployment/list`              | query: `namespace?`,`name?`,`page`,`limit`                   |
| 扩缩容       | `POST /api/v1/k8s/deployment/scale`            | body: `name`,`namespace`,`scale_num`                         |
| 更新镜像     | `POST /api/v1/k8s/deployment/update-image`     | body: `name`,`namespace`,`container`,`image`                 |
| 滚动重启     | `POST /api/v1/k8s/deployment/restart`          | body: `name`,`namespace`                                     |
| 回滚         | `POST /api/v1/k8s/deployment/rollback`         | body: `name`,`namespace`,`replica_set`                       |
| 关联 Pods    | `GET /api/v1/k8s/deployment/pods`              | query: `namespace`,`name`                                    |
| Patch        | `POST /api/v1/k8s/deployment/patch`            | body: `KubeDeploymentUpdateRequest`（JSONPatch / Strategic） |

**示例：扩缩容**

```
curl -X POST -H 'Content-Type: application/json' -H "Authorization: Bearer <JWT>" \
  http://localhost:8080/api/v1/k8s/deployment/scale \
  -d '{"namespace":"default","name":"demo","scale_num":5}'
```

------

## StatefulSet / DaemonSet 管理（节选）

| 资源        | 动作                               | 方法 & 路径                 | 备注                             |
| ----------- | ---------------------------------- | --------------------------- | -------------------------------- |
| StatefulSet | CRUD / 详情 / 列表 / 扩缩容 / 回滚 | `/api/v1/k8s/statefulset/*` | 回滚基于 **ControllerRevision**  |
| DaemonSet   | CRUD / 详情 / 列表 / 回滚          | `/api/v1/k8s/daemonset/*`   | 同样支持 ControllerRevision 历史 |

------

## Job / CronJob 管理（节选）

| 资源    | 动作                          | 方法 & 路径             | 备注                           |
| ------- | ----------------------------- | ----------------------- | ------------------------------ |
| Job     | 创建 / 删除 / 状态            | `/api/v1/k8s/job/*`     | 支持 `TTLSecondsAfterFinished` |
| CronJob | 创建 / 删除 / 启停 / 历史 Job | `/api/v1/k8s/cronjob/*` | 标签选择器查询对应 Jobs        |

------

## Service 管理（已实现）

| 动作                | 方法 & 路径                           | 说明                                     |
| ------------------- | ------------------------------------- | ---------------------------------------- |
| 创建                | `POST /api/v1/k8s/service/create`     | 创建 ClusterIP / NodePort / LoadBalancer |
| 删除                | `DELETE /api/v1/k8s/service/delete`   | 删除                                     |
| 详情                | `GET /api/v1/k8s/service/detail`      | 获取详情                                 |
| 列表                | `GET /api/v1/k8s/service/list`        | 名称模糊 + 分页                          |
| Patch（Strategic）  | `PATCH /api/v1/k8s/service/patch`     | 适合局部字段更新                         |
| Patch（JSON Merge） | `POST /api/v1/k8s/service/patch-json` | 覆盖式，适合端口数组整体替换             |

**示例（SMP 修改端口组）**

```
{
  "namespace": "default",
  "name": "demo-svc",
  "content": "{\"spec\":{\"ports\":[{\"name\":\"http\",\"port\":80,\"targetPort\":8080}]}}"
}
```

------

## Ingress 管理（已实现）

| 动作                | 方法 & 路径                           | 说明                        |
| ------------------- | ------------------------------------- | --------------------------- |
| 创建                | `POST /api/v1/k8s/ingress/create`     | 支持规则与 TLS              |
| 删除                | `DELETE /api/v1/k8s/ingress/delete`   | 前台级联，幂等              |
| 详情                | `GET /api/v1/k8s/ingress/detail`      | 获取详情                    |
| 列表                | `GET /api/v1/k8s/ingress/list`        | 名称模糊 + 分页             |
| Patch（Strategic）  | `PATCH /api/v1/k8s/ingress/patch`     | 适合加注解等局部修改        |
| Patch（JSON Merge） | `POST /api/v1/k8s/ingress/patch-json` | 覆盖式修改 `spec.rules/tls` |

**示例：为 Ingress 新增 `/repo` 路径（JSON Merge Patch）**

> 注意：接口约定 `content` 为**字符串**，内部 JSON 需转义。

```
{
  "namespace": "default",
  "name": "demo-nginx-ing",
  "content": "{\"spec\":{\"rules\":[{\"host\":\"demo.local\",\"http\":{\"paths\":[{\"path\":\"/\",\"pathType\":\"Prefix\",\"backend\":{\"service\":{\"name\":\"demo-nginx\",\"port\":{\"number\":80}}}},{\"path\":\"/repo\",\"pathType\":\"Prefix\",\"backend\":{\"service\":{\"name\":\"demo-nginx\",\"port\":{\"number\":80}}}}]}}]}}"
}
```

------

## Secret 管理（已实现）

- 类型：`Opaque` / `kubernetes.io/tls` / `kubernetes.io/dockerconfigjson`
- 能力：查看 / 创建 / 删除；自动 Base64 解码（仅管理员）
- 场景：镜像仓库拉取凭证（`imagePullSecrets`）、Ingress TLS 证书绑定

**TLS Secret 创建示例**

```
kubectl create secret tls my-tls \
  --cert=server.crt --key=server.key -n default
```

------

## 事件与 DataSelect

- **Event**：按资源聚合 Kubernetes 事件，定位如 `Backend service not found`、`ImagePullBackOff` 等问题
- **DataSelect**：统一的分页 + 排序 + 模糊查询（所有 List 接口参数：`page` 从 1 开始，`limit`）

------

## 返回与错误规范

- **成功**：HTTP `200`（或 2xx），业务数据在统一响应结构中返回
- **失败**：HTTP `4xx/5xx`，body 为 `errorcode.Error`
- **分页**：统一使用 `page`（从 1 开始）与 `limit`

------

## 📂 项目结构（节选）

```
k8soperation/
├── cmd/k8soperation/main.go
├── internal/
│   ├── bootstrap/            # 配置、日志、DB、K8s 初始化
│   ├── k8soperation/         # HTTP 服务器与优雅关闭
│   ├── app/
│   │   ├── controllers/      # Gin Handler
│   │   ├── services/         # 业务聚合
│   │   ├── dao/              # DB/K8s API
│   │   ├── models/
│   │   ├── requests/
│   │   └── routers/
│   ├── errorcode/
│   └── health/
├── initialize/               # setting/logger/db/session/k8s/engine
├── global/
├── pkg/                      # utils / middleware
├── configs/
└── docs/
```

🧩 调用流程（简图）

```
main.go
  └─ bootstrap.InitAll()
  └─ server.NewHTTPServer()
  └─ server.ListenAndServeAsync()
  └─ server.GracefulShutdown()
```

------

## ⚙️ 快速开始

```
git clone https://gitee.com/jay-kim/k8s_operation.git
cd k8s_operation
make build
./bin/k8soperation        # Windows: ./bin/k8soperation.exe
```

配置示例详见 `configs/config.yaml`。

------

## 🐳 使用 Docker / Containerd

- `build/docker/Dockerfile`（通用）
- `build/containerd/Dockerfile`（BuildKit/nerdctl 更快）

```
docker build -f build/docker/Dockerfile -t k8soperation:latest .
docker run -d --name k8soperation -p 8080:8080 \
  -v $(pwd)/configs:/app/configs:ro \
  -e APP_CONFIG=/app/configs/config.yaml \
  --restart=always k8soperation:latest
```

------

## 健康检查 (Kubernetes)

```
livenessProbe:
  httpGet:
    path: /healthz/live
    port: 8080
readinessProbe:
  httpGet:
    path: /healthz/ready
    port: 8080
```

**验证**

```
curl -i http://localhost:8080/healthz/live
curl -i http://localhost:8080/healthz/ready
```

------

## 🧪 常用命令

| 命令                                    | 说明                |
| --------------------------------------- | ------------------- |
| `make build`                            | 构建二进制到 `bin/` |
| `make run`                              | 编译并运行          |
| `make test`                             | 单元测试            |
| `make fmt` / `make lint`                | 格式化 / 静态检查   |
| `make clean`                            | 清理构建产物        |
| `make docker-build` / `make docker-run` | 构建/运行容器       |

------

## 📜 License

MIT License（如需商用授权请联系作者）。

------

## 🚀 项目进展与规划

**当前已完成**

- ✅ Pod / Deployment / StatefulSet / DaemonSet / Service / Ingress / Job / CronJob / Secret
- ✅ 滚动重启（注解触发）
- ✅ 回滚（Deployment 基于 ReplicaSet；StatefulSet/DaemonSet 基于 ControllerRevision）
- ✅ 事件聚合 + 统一 DataSelect 引擎

**规划中**

- 🧩 ConfigMap、PVC/PV 管理
- 🔍 更丰富的实时日志流
- 📊 资源监控（Metrics / Prometheus）
- 🚨 告警与外部通知
- 💻 Web 控制台（Arco Design）

项目将持续随 Kubernetes 版本演进而升级，目标是构建一个 **简洁实用的 K8s 运维管理平台**。 欢迎 **Star 🌟 / Fork 🍴 / Watch 👀**，一起推动项目成长！