kubectl-qyai

kubectl-qyai

kubectl-qyai 是一个面向 Kubernetes 与 Linux 运维 的智能命令行助手：把自然语言需求转成可执行的命令（kubectl / bash），并在执行前做 风险分级 + 二次确认 + 审计/会话记录。

本项目基于开源项目 kubectl-ai 进行二次开发，重点增强：

• 运维安全：read/change/destructive 分层，可配置策略（提示/阻断）
• 多种运行方式：单次（预览/执行）、交互（terminal/tui）、Web UI、HTTP agent-serve、MCP tools server
• 默认中文提示，可切换英文
• 会话与审计：便于复盘与追责

目录

• 安装
• 三分钟上手
• 使用方式
  • 单次：预览 / 执行
  • 交互：terminal / tui（推荐）
  • Web UI（浏览器界面）
  • HTTP：agent-serve（远程触发本机 Agent）
  • MCP：tools server（给外部 Agent/平台用）
• 模型与提供方
• 配置与文件
  • config.yaml（模型与安全策略）
  • 凭据与 .env 加载顺序
  • 会话与审计
  • 日志
• 容器与开发

安装

方式 1：安装 Release（二进制，推荐）

curl -fsSL https://cnb.cool/qianyios/kubectl-qyai/-/git/raw/main/install.sh | bash

指定版本：

curl -fsSL https://cnb.cool/qianyios/kubectl-qyai/-/git/raw/main/install.sh | QYAI_VERSION=v1.1.2 bash

安装完成后的目录结构：

• /usr/local/kubectl-qyai/bin/：kubectl-qyai、kubeqy
• /usr/local/kubectl-qyai/conf/：config.yaml、config.example.yaml、.env、.env.example
• /usr/local/kubectl-qyai/scripts/：随包脚本（例如 start-agent-serve.sh）

install.sh 会把命令软链到 /usr/local/bin/，确保 PATH 可找到。

方式 2：从源码构建

go build -o ./bin/kubectl-qyai ./cmd/kubectl-qyai
ln -sf ./bin/kubectl-qyai ./bin/kubeqy

三分钟上手

1. 选择运行环境（影响工具执行方式与默认提示词）：

export KUBEQY_PATH=linux
# export KUBEQY_PATH=kubernetes

1. 准备配置文件（模型列表 + 默认模型 + 安全策略）：

• 复制 config.example.yaml 为 config.yaml 并修改，或直接放到默认路径：
  • /usr/local/kubectl-qyai/conf/config.yaml

1. 配置至少一个模型凭据（建议写到 .env）：

• 参考 .env.example（模板）
• 你至少需要设置一个 key（例如 DEEPSEEK_API_KEY / QWEN_API_KEY / OPENAI_API_KEY 等）

1. 开跑：

kubeqy

使用方式

单次：预览 / 执行

• 预览（默认）：

kubeqy -p "获取所有 Pod"

• 执行（会询问确认）：

kubeqy -p "获取所有 Pod" -e

交互：terminal / tui（推荐）

kubeqy
# 或
kubectl-qyai --ui-type=terminal
kubectl-qyai --ui-type=tui

交互模式要点：

• 默认对齐上游风格：terminal/tui + agent 多轮迭代 + 工具调用
• 常用内置命令：
  • help / ?
  • tools（可用工具）
  • models / model（模型列表 / 当前模型）
  • sessions / resume-session <id> / new-session
  • clear / reset
  • exit / quit
• Ctrl+C：两段式——先取消当前执行，再按一次退出

语言：默认中文，可切换英文。

• 切换为英文（环境变量方式）：

export KUBECTL_QYAI_LANG=en

交互模式里也可以用内置命令切换：输入 help 查看 lang 用法（通过序号选择）。

Web UI（浏览器界面）

kubectl-qyai ui --listen 127.0.0.1:18082

说明：Web UI 是本机 HTTP + SSE，用于浏览器里交互与会话管理。

HTTP：agent-serve（远程触发本机 Agent）

适用场景：A 机器有 kubeconfig/网络/权限，B 机器只想“远程发 prompt 拿结果”。

• 直接启动：

kubectl-qyai agent-serve --runtime linux --listen 127.0.0.1:18081

• 启用 token 鉴权（推荐用于局域网/跨机器调用）：

kubectl-qyai agent-serve --runtime linux --listen 0.0.0.0:18081 --token "your-strong-token"

• 使用随包脚本（自动识别本机 IP，并拼成 <ip>:<port>）：

scripts/start-agent-serve.sh

相关环境变量（优先级：系统环境变量 > .env）：

• KUBEQY_PATH：运行环境（linux / kubernetes）
• KUBECTL_QYAI_AGENT_SERVE_PORT：端口（默认 18081）
• KUBECTL_QYAI_AGENT_SERVE_TOKEN：可选鉴权 token（为空=不开启鉴权）

HTTP 接口：

• GET /healthz
• POST /agent/run（可选：Authorization: Bearer <token>）

远程调用示例（curl）：

• 健康检查：

curl -fsSL http://127.0.0.1:18081/healthz

• 触发一次 agent 运行（无 token）：

curl -sS http://127.0.0.1:18081/agent/run \
  -H "Content-Type: application/json" \
  -d '{"prompt":"列出所有 namespace","max_iterations":5}'

• 跨机器调用（有 token，B 机器请求 A 机器）：

curl -sS http://<A机器IP>:18081/agent/run \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"查看 kube-system 命名空间所有 Pod","model":"","max_iterations":10}'

说明：请求体支持字段：prompt（必填）、model（可选）、max_iterations（可选）。

MCP：tools server（给外部 Agent/平台用）

MCP server 只提供工具能力（kubectl/bash/...），不替调用方托管模型与密钥。

• stdio（本机/父进程拉起）：

kubectl-qyai mcp --mode stdio --runtime linux

• streamable-http（远端暴露，endpoint 默认 /mcp）：

kubectl-qyai mcp --mode streamable-http --http-port 8080 --runtime linux

模型与提供方

模型通过 config.yaml 的 models: 配置，按 priority 选择；默认使用 default_model。

支持的 type（总览，完整变量清单见 .env.example）：

内置适配器（面向国内常见厂商）

gollm Provider（通用，多 Provider 复用）

建议：当你同时配置了多个“兼容网关”的 key 时，在 config.yaml 里给对应模型显式设置 params.base_url，避免歧义。

配置与文件

config.yaml（模型与安全策略）

默认读取路径（可用 --config 或 KUBECTL_QYAI_CONFIG 覆盖）：

• /usr/local/kubectl-qyai/conf/config.yaml
• 若不存在：回退 /usr/local/kubectl-qyai/conf/config.example.yaml

核心字段：

• models[]：模型列表（name/type/priority/enabled/params）
• default_model：默认模型（对应 models[].name）
• safety：安全策略（read/change/destructive 分层，支持自定义规则）

示例与完整注释请直接看：config.example.yaml。

凭据与 .env 加载顺序

优先级：环境变量 > ~/.config/kubectl-qyai/credentials.yaml。

.env 仅用于“补齐未设置的环境变量”（不覆盖你已经 export 的变量），加载顺序：

1. KUBECTL_QYAI_DOTENV 指定路径
2. 当前目录向上查找 .env
3. ~/.config/kubectl-qyai/.env
4. /usr/local/kubectl-qyai/conf/.env

模板文件：/usr/local/kubectl-qyai/conf/.env.example（或仓库根 .env.example）。

会话与审计

• 会话（默认启用，可 --no-session 关闭）：~/.kubectl-qyai/sessions/<id>.jsonl
• 审计（默认启用，可 --no-audit 关闭）：~/.kubectl-qyai/audit/audit-YYYYMMDD.jsonl

日志

• 默认：优先写 /usr/local/kubectl-qyai/log/kubectl-qyai.log（目录存在时）
• 若无权限/目录不存在：回退写入系统临时目录

可选环境变量：

• KUBECTL_QYAI_LOG_DIR：自定义日志目录（会写入 kubectl-qyai.log）
• KUBECTL_QYAI_QUIET=1：关闭所有日志写入

容器与开发

• 容器运行与 kubeconfig 挂载方式见 CONTAINER.md
• 贡献指南见 contributing.md
• 测试：go test ./...