# k8s_operation

**Repository Path**: ares-lyu/k8s_operation

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 11
- **Created**: 2025-10-27
- **Last Updated**: 2025-10-27

## 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 等核心资源的增删改查、扩缩容、滚动升级与回滚接口**，可作为企业级 K8s 管理平台的后端核心。

------

## ✨ 特性亮点

- ✅ **配置化管理**：集中式配置文件 `configs/config.yaml` + 全局加载 `global.AppSetting`，支持时区、JWT、日志等统一管理
- ✅ **鉴权体系**：`internal/pkg/jwt` 封装 Token 签发 / 刷新 / 验证，一键中间件集成
- ✅ **日志链路**：基于 Zap，按日轮转输出至 `storage/logs`，系统日志与业务日志分流
- ✅ **数据访问**：Gorm 初始化封装 + DAO / Service 分层抽象
- ✅ **健康与关闭**：内置健康探针与 `shutdown.Graceful` 优雅退出机制
- ✅ **Swagger 文档体系**：`swag` 自动生成 `/swagger/doc.json`，并附带独立交互式 UI（`/swagger-standalone`）
- ✅ **Kubernetes 能力扩展**：已完成 Pod 与 Deployment 资源管理接口开发（创建、删除、扩缩容、回滚、日志等），接口已全部验证通过

---

## 新增 Kubernetes 后台管理功能

> 自 v6.1 起，已稳定支持以下功能并经过验证：

### Deployment 管理

- 列表、详情、创建、更新、删除
- 扩缩容（Patch `spec.replicas`）
- 镜像更新（Strategic Merge Patch）
- 滚动重启
- 版本回滚（依赖 ReplicaSet 关联）
- 事件查看：聚合 Deployment / RS / Pod 的 Events

### Pod 管理

- 列表、详情、删除
- 日志查看（支持容器选择 & 指定行数）
- 重启（若通过控制器操作或删除重建）
- 事件查看

### 路由样例（部分）

------

## 认证

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

**示例：**

```bash
# 登录
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 / StrategicMergePatch） |

**常用示例：**

```bash
# 列表
curl -H "Authorization: Bearer <JWT>" \
  "http://localhost:8080/api/v1/k8s/deployment/list?namespace=default&page=1&limit=20"

# 扩缩容
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}'

# 更新镜像（触发滚动升级）
curl -X POST -H 'Content-Type: application/json' -H "Authorization: Bearer <JWT>" \
  http://localhost:8080/api/v1/k8s/deployment/update-image \
  -d '{"namespace":"default","name":"demo","container":"app","image":"nginx:1.27"}'

# 回滚到指定 ReplicaSet
curl -X POST -H 'Content-Type: application/json' -H "Authorization: Bearer <JWT>" \
  http://localhost:8080/api/v1/k8s/deployment/rollback \
  -d '{"namespace":"default","name":"demo","replica_set":"demo-7cdbd9d8ff"}'

# Patch（SMP 修改副本数）
curl -X POST -H 'Content-Type: application/json' -H "Authorization: Bearer <JWT>" \
  http://localhost:8080/api/v1/k8s/deployment/patch \
  -d '{"namespace":"default","name":"demo","content":{"spec":{"replicas":3}}}'
```

------

## Pod 管理

| 动作                  | 方法 & 路径                                | 关键参数                                            |
| --------------------- | ------------------------------------------ | --------------------------------------------------- |
| 列表                  | `GET /api/v1/k8s/pod/list`                 | query: `name?`,`namespace?`,`page`,`limit`          |
| 详情                  | `GET /api/v1/k8s/pod/detail`               | query: `namespace`,`name`                           |
| 删除（可优雅/强制）   | `DELETE /api/v1/k8s/pod/grace_delete_pod`  | query: `namespace`,`name`,`grace_seconds?`,`force?` |
| 容器名                | `GET /api/v1/k8s/pod/container_name`       | query: `namespace`,`name`                           |
| 容器镜像              | `GET /api/v1/k8s/pod/container_image`      | query: `namespace`,`name`                           |
| Init 容器名           | `GET /api/v1/k8s/pod/init_container_name`  | query: `namespace`,`name`                           |
| Init 容器镜像         | `GET /api/v1/k8s/pod/init_container_image` | query: `namespace`,`name`                           |
| 日志（一次性/流式）   | `GET /api/v1/k8s/pod/container_log`        | query: `namespace`,`name`,`container?`,`tail?`      |
| Patch Pod 镜像        | `PUT /api/v1/k8s/pod/patch_image`          | body: `name`,`namespace`,`container`,`new_image`    |
| 更新 Pod（原始 JSON） | `POST /api/v1/k8s/pod/update`              | body: `KubePodUpdateRequest`                        |

**常用示例：**

```bash
# 拉日志（一次性，最后 200 行）
curl -H "Authorization: Bearer <JWT>" \
  "http://localhost:8080/api/v1/k8s/pod/container_log?namespace=default&name=demo-abc&container=app&tail=200"

# 优雅删除 Pod（30s）
curl -X DELETE -H "Authorization: Bearer <JWT>" \
  "http://localhost:8080/api/v1/k8s/pod/grace_delete_pod?namespace=default&name=demo-abc&grace_seconds=30"

# 强制删除 Pod
curl -X DELETE -H "Authorization: Bearer <JWT>" \
  "http://localhost:8080/api/v1/k8s/pod/grace_delete_pod?namespace=default&name=demo-abc&force=true"

# Patch Pod 容器镜像（SMP，mergeKey=name）
curl -X PUT -H 'Content-Type: application/json' -H "Authorization: Bearer <JWT>" \
  http://localhost:8080/api/v1/k8s/pod/patch_image \
  -d '{"namespace":"default","name":"demo-abc","container":"app","new_image":"busybox:1.36"}'
```

------

## 用户管理

| 动作 | 方法 & 路径                                     |
| ---- | ----------------------------------------------- |
| 创建 | `POST /api/v1/user/create`                      |
| 删除 | `POST /api/v1/user/delete`                      |
| 更新 | `POST /api/v1/user/update`                      |
| 列表 | `GET /api/v1/user/list?page=&limit=&username?=` |

------

## 调试工具

| 路径                 | 说明                                                       |
| -------------------- | ---------------------------------------------------------- |
| `GET /debug/session` | 从请求 Cookie 的 SessionID 读取 Redis 中会话信息（仅调试） |

------

## 返回与错误规范

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

------




------

## 📦 功能特性

- **配置管理**：支持全局配置（Server/Database/Logger 等）。
- **日志系统**：使用 `zap`，结合 `lumberjack` 实现日志切割与持久化。
- **数据库支持**：封装了 `gorm`，可根据配置初始化数据库。
- **HTTP 服务**：基于 `Gin`，提供 RESTful API 路由管理。
- **优雅关闭**：捕获 `SIGINT` / `SIGTERM` 信号，支持请求完成后安全退出。
- **可观测性**：内置健康检查接口（`/healthz`），方便接入 K8s 探针。
- **跨平台构建**：支持 Windows / Linux / macOS，提供 `Makefile` 与 `Dockerfile`。

------

## 📂 项目结构

```bash
k8soperation/
├── cmd/                                     # ⛳ 程序入口（main 可执行文件）
│   └── k8soperation/
│       └── main.go                          # 应用启动入口，只负责调用 Run()
│
├── internal/                                # 内部逻辑（不会被外部包导入）
│   ├── bootstrap/                           # 🚀 系统初始化逻辑（配置、日志、DB、K8s）
│   │   └── bootstrap.go                     # 调用 initialize.SetupXXX() 初始化所有组件
│   │
│   ├── k8soperation/                              # 🌐 HTTP 服务器层
│   │   ├── http.go                          # 创建 http.Server 并加载 Gin Engine
│   │   └── shutdown.go                      # 优雅关停、信号监听(SIGINT/SIGTERM)
│   │
│   ├── app/                                 # 💼 业务层（MVC 模型）
│   │   ├── controllers/                     # 控制器层：Gin Handler（HTTP 请求入口）
│   │   ├── services/                        # 服务层：业务逻辑封装（聚合多个 DAO）
│   │   ├── dao/                             # 数据访问层：DB、K8s API、外部接口
│   │   ├── models/                          # 模型层：结构体定义、DB/K8s 对象映射
│   │   ├── requests/                        # 请求参数定义、校验规则绑定
│   │   └── routers/                         # 路由注册（挂载到 Gin Engine）
│   │
│   ├── errorcode/                           # ⚠️ 统一错误码定义、错误响应结构
│   └── health/                              # 🩺 健康检查与依赖检测模块（/healthz）
│
├── initialize/                              # ⚙️ 初始化模块
│   ├── setting.go                           # 加载配置文件（YAML/ENV）
│   ├── logger.go                            # 初始化 zap.Logger
│   ├── db.go                                # 初始化数据库连接
│   ├── session.go                           # 初始化 session store
│   ├── k8s.go                               # 初始化 K8s clientset
│   └── engine.go                            # 构建 Gin Engine（中间件/路由挂载）
│
├── global/                                  # 🌍 全局共享对象
│   ├── global.go                            # 全局变量声明(Logger、DB、Config)
│   └── setting.go                           # 全局配置结构体
│
├── pkg/                                     # 📦 通用工具包（内部库）
│   ├── utils/                               # 常用工具函数（字符串、文件、时间）
│   └── middleware/                          # Gin 中间件（日志、鉴权、CORS 等）
│
├── configs/                                 # 🧾 应用配置文件（.yaml/.json）
│   └── config.yaml
│
├── docs/                                    # 📚 文档目录（Swagger、README、API 文档）
│   └── swagger.yaml
│
└── go.mod                                   # Go 模块定义

```

🧩 调用流程（简图）

```
main.go
  └─ bootstrap.InitAll()          # 初始化配置、日志、DB、K8s 等
  └─ server.NewHTTPServer()       # 构建 HTTP Server (Gin Engine)
  └─ server.ListenAndServeAsync() # 异步启动 HTTP
  └─ server.GracefulShutdown()    # 监听信号，优雅关停
```

------

## ⚙️ 快速开始

### 1. 克隆项目

```bash
git clone https://github.com/yourname/k8soperation.git
cd k8soperation
```

### 2. 配置环境

在 `configs/config.yaml`（示例）中设置服务端口、数据库连接、日志路径等：

```yaml
Server:
  RunMode: debug
  Port: 8080
  ReadTimeout: 3600
  WriteTimeout: 3600
  IdleTimeout: 300
  ShutdownTimeout: 300

Database:
  DBType: mysql
  Username: root
  Password: 123456
  Host: localhost
  Port: 3306
  DBName: k8s_ci
  Charset: utf8
  ParseTime: True
  MaxIdleConns: 5
  MaxOpenConns: 30
  MaxLifeSeconds: 300

App:
  LogLevel: debug
  LogType: single
  LogFileName: storage/logs/app.log
  LogMaxSize: 1
  LogMaxBackup: 10
  LogMaxAge: 30
  LogCompress: true
```

### 3. 本地运行（Windows / Linux / Mac）

```bash
make build
./bin/k8soperation.exe   # Windows
./bin/k8soperation       # Linux / Mac
```

启动日志示例：

```bash
{"level":"info","time":"2025-08-21 16:46:14","caller":"server/main.go:67","msg":"http server starting","addr":":8080"}
```

### 4. 优雅关闭

运行时按 `Ctrl+C` 或发送 `kill` 信号，会触发优雅退出：

```bash
{"level":"info","time":"2025-08-21 16:46:23","caller":"server/main.go:78","msg":"server shutting down..."}
{"level":"info","time":"2025-08-21 16:46:23","caller":"server/main.go:88","msg":"server exited gracefully","timeout":5}
```

------



## 🐳 使用 Docker / Containerd

项目提供两份 Dockerfile（均需在**项目根目录**执行构建命令，`.` 作为构建上下文）：

- `build/docker/Dockerfile`：**通用版**，兼容所有 Docker 环境（不使用 BuildKit 缓存）。
- `build/containerd/Dockerfile`：**BuildKit 版**，适合 `nerdctl` / `containerd`，支持缓存依赖与构建，加快编译。

提示：不要在 Dockerfile 里写 `../../` 这类超出上下文的路径；用 `-f` 指定 Dockerfile，`.` 作为构建上下文即可。

启动容器：

```bash
make docker-run
# 等价于：
# 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
```

常用变体：

```bash
# 使用 nerdctl 构建（仍用通用版 Dockerfile）
DOCKER=nerdctl make docker-build

# 使用 BuildKit 版 Dockerfile（更快的依赖/构建缓存）
make bk-build                   # 默认 docker + BuildKit
DOCKER=nerdctl make bk-build    # nerdctl + BuildKit

# 查看日志 / 停止 / 删除容器
make docker-logs
make docker-stop
make docker-rm
```

> 若需多架构镜像（如 `linux/amd64,linux/arm64`）并推送镜像，可用：
>
> ```bash
> PLATFORMS=linux/amd64,linux/arm64 REGISTRY=registry.example.com/ns make docker-buildx
> ```

------

### 方法二：直接使用 Docker

构建镜像：

```bash
docker build -f build/docker/Dockerfile -t k8soperation:latest .
```

运行容器：

```bash
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
```

------

### 方法三：使用 nerdctl（containerd，默认启用 BuildKit）

构建镜像：

```bash
nerdctl build -f build/containerd/Dockerfile -t k8soperation:latest .
```

运行容器：

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

查看日志：

```bash
nerdctl logs -f k8soperation
```

------

### 方法四：使用 ctr（底层工具，不推荐新手）

> `ctr` 不支持 `-p` 端口映射，通常需要 `--net-host`。

```bash
ctr -n default run -d \
  --env APP_CONFIG=/app/configs/config.yaml \
  --mount type=bind,src=$(pwd)/configs,dst=/app/configs,options=rbind:ro \
  --net-host \
  k8soperation:latest k8soperation
```

访问服务：

```bash
curl http://127.0.0.1:8080/healthz/live
> 若你还没有 `Makefile`，用我之前给你的那份即可（含 `docker-build` / `bk-build` / `docker-run` 等目标）
```



------

### 健康检查示例 (Kubernetes)

```bash
livenessProbe:
  httpGet:
    path: /healthz/live
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 10
readinessProbe:
  httpGet:
    path: /healthz/ready
    port: 8080
  initialDelaySeconds: 2
  periodSeconds: 5
```

------



### 健康检查验证

服务启动后，可以手动验证健康检查接口：

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

- **/healthz/live**
  返回 `200 OK` 且 body 为 `ok` → 存活探测正常（进程活着）。
- **/healthz/ready**
  返回 `200 OK` 且 body 为 `ok` → 外部依赖（如数据库）已就绪。
  返回 `503 Service Unavailable` → 依赖未准备好，Pod 不会加入流量。

✅ 当 **live 和 ready 都返回 ok** 时，说明服务健康且探测通过。



## 🧪 常用命令

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

------

## 📜 License

MIT License. 请根据你的实际情况修改。

```bash
## 📜 License
本项目源码仅供学习与研究使用，禁止任何商业用途。  
如需商用，请联系作者获取授权。
```

------

> ## 🚀 项目进展与规划
>
> 本项目已正式进入 **Kubernetes 后台管理功能开发阶段**，目前已完成 **Pod 与 Deployment 核心资源管理接口**（创建、删除、扩缩容、滚动更新、回滚、日志查询等），并在持续完善中。
>
> 欢迎持续关注本项目的 Gitee 仓库：
>
> 🔗 https://gitee.com/jay-kim/k8s_operation
>
> 我们正在迭代开发以下功能模块：
>
> - ✅ Kubernetes **Pod / Deployment 管理接口（已完成并验证）**
> - 🧩 Kubernetes **Service 管理接口（开发中）**
> - 🔍 **实时日志查看与流式输出（支持配置开关）**
> - 📊 **容器资源监控与状态统计**
> - 🚨 **告警与健康检查集成（Prometheus / WeCom）**
> - 💻 **Web 控制面板（前端页面对接中）**
>
> > 本项目将持续随 Kubernetes 版本升级而演进，目标是构建一个 **简洁实用的 K8s 运维管理平台**。
> >  欢迎 Star 🌟、Fork 🍴 与 Watch 👀，一起推动项目成长！