Go 语言构建运维 CLI 工具

为什么 Go 适合运维工具

运维 CLI 工具对部署便捷性和执行效率有极高要求，Go 语言在这方面具有天然优势：

优势	说明	对比 Python
单二进制	编译产出独立可执行文件，无运行时依赖	需 Python 环境 + 依赖
跨平台	`GOOS/GOARCH` 交叉编译，一次编写到处运行	需虚拟环境管理
启动速度	毫秒级冷启动	解释执行有开销
并发模型	goroutine 轻量并发	需 threading/asyncio
内存占用	静态二进制内存占用低	解释器开销
生态成熟	标准库覆盖网络/文件/加密	依赖第三方库

Kubernetes、Docker、Terraform、Prometheus 等云原生核心工具均使用 Go 编写，Go 已成为云原生运维工具的事实标准语言。

cobra 框架快速上手

cobra 是 Go 生态最流行的 CLI 框架，提供命令树、flag 解析、自动补全等能力。根据 cobra 官方文档，它的设计理念是组合优于继承。

安装与项目初始化

# 安装 cobra CLI 工具
go install github.com/spf13/cobra/cobra@latest

# 初始化项目
mkdir k8s-pod-cleaner && cd k8s-pod-cleaner
go mod init github.com/xubaojin/k8s-pod-cleaner

# 使用 cobra 生成项目骨架
cobra init --author "徐保金" --license mit --package cmd

# 添加子命令
cobra add list
cobra add clean
cobra add logs

命令树设计

一个优秀的 CLI 工具应该有清晰的命令层级：

k8s-pod-cleaner
├── list          # 列出异常 Pod
│   └── --status  # 按状态过滤
├── clean         # 批量清理
│   └── --force   # 强制删除
├── logs          # 日志导出
│   └── --tail    # 行数限制
└── version       # 版本信息

根命令与 Persistent Flag

// cmd/root.go
package cmd

import (
    "os"
    "github.com/spf13/cobra"
)

var kubeconfig string
var namespace string

var rootCmd = &cobra.Command{
    Use:   "k8s-pod-cleaner",
    Short: "K8s 异常 Pod 管理工具",
    Long: `k8s-pod-cleaner 是一个用于管理 Kubernetes 集群中异常 Pod 的 CLI 工具。

功能包括：
  - 列出异常状态的 Pod（CrashLoopBackOff、ImagePullBackOff 等）
  - 批量清理异常 Pod
  - 导出异常 Pod 日志`,
}

func Execute() {
    if err := rootCmd.Execute(); err != nil {
        os.Exit(1)
    }
}

func init() {
    // PersistentFlag 对所有子命令生效
    rootCmd.PersistentFlags().StringVarP(
        &kubeconfig, "kubeconfig", "k", "",
        "kubeconfig 文件路径 (默认使用 ~/.kube/config)",
    )
    rootCmd.PersistentFlags().StringVarP(
        &namespace, "namespace", "n", "",
        "Kubernetes 命名空间 (默认所有命名空间)",
    )
}

PersistentFlag vs Local Flag 的区别是 cobra 的核心概念：

PersistentFlags()：该 flag 对当前命令及所有子命令都可见
Flags()：该 flag 仅对当前命令可见

子命令与 Flag

// cmd/list.go
package cmd

import (
    "fmt"
    "github.com/spf13/cobra"
)

var statusFilter string

var listCmd = &cobra.Command{
    Use:   "list",
    Short: "列出异常状态的 Pod",
    Run: func(cmd *cobra.Command, args []string) {
        client, err := NewK8sClient(kubeconfig)
        if err != nil {
            fmt.Fprintf(cmd.ErrOrStderr(), "连接集群失败: %v\n", err)
            return
        }
        pods, err := client.ListAbnormalPods(namespace, statusFilter)
        if err != nil {
            fmt.Fprintf(cmd.ErrOrStderr(), "查询失败: %v\n", err)
            return
        }
        printPodTable(pods)
    },
}

func init() {
    listCmd.Flags().StringVarP(
        &statusFilter, "status", "s", "",
        "按状态过滤: CrashLoopBackOff, ImagePullBackOff, Pending, Failed",
    )
    rootCmd.AddCommand(listCmd)
}

实战：k8s-pod-cleaner CLI 工具

K8s 客户端封装

// pkg/k8s/client.go
package k8s

import (
    "context"
    "fmt"
    "path/filepath"

    corev1 "k8s.io/api/core/v1"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
    "k8s.io/client-go/kubernetes"
    "k8s.io/client-go/tools/clientcmd"
    "k8s.io/client-go/util/homedir"
)

type PodInfo struct {
    Namespace string
    Name      string
    Status    string
    Restarts  int32
    Age       string
    Node      string
    Reason    string
}

type Client struct {
    clientset *kubernetes.Clientset
}

func NewClient(kubeconfig string) (*Client, error) {
    if kubeconfig == "" {
        if home := homedir.HomeDir(); home != "" {
            kubeconfig = filepath.Join(home, ".kube", "config")
        }
    }

    config, err := clientcmd.BuildConfigFromFlags("", kubeconfig)
    if err != nil {
        return nil, fmt.Errorf("加载 kubeconfig 失败: %w", err)
    }

    clientset, err := kubernetes.NewForConfig(config)
    if err != nil {
        return nil, fmt.Errorf("创建 clientset 失败: %w", err)
    }

    return &Client{clientset: clientset}, nil
}

// ListAbnormalPods 列出异常状态的 Pod
func (c *Client) ListAbnormalPods(namespace, statusFilter string) ([]PodInfo, error) {
    ctx := context.Background()
    var pods []PodInfo

    nsList := []string{namespace}
    if namespace == "" {
        nsList = nil // nil 表示所有命名空间
    }

    if namespace != "" {
        podList, err := c.clientset.CoreV1().Pods(namespace).List(ctx, metav1.ListOptions{})
        if err != nil {
            return nil, err
        }
        for _, pod := range podList.Items {
            if info := c.checkAbnormal(pod, statusFilter); info != nil {
                pods = append(pods, *info)
            }
        }
    } else {
        // 列出所有命名空间
        podList, err := c.clientset.CoreV1().Pods("").List(ctx, metav1.ListOptions{})
        if err != nil {
            return nil, err
        }
        for _, pod := range podList.Items {
            if info := c.checkAbnormal(pod, statusFilter); info != nil {
                pods = append(pods, *info)
            }
        }
    }

    return pods, nil
}

func (c *Client) checkAbnormal(pod corev1.Pod, filter string) *PodInfo {
    status := string(pod.Status.Phase)
    reason := ""

    // 检查容器状态
    for _, cs := range pod.Status.ContainerStatuses {
        if cs.State.Waiting != nil {
            reason = cs.State.Waiting.Reason
            status = cs.State.Waiting.Reason // CrashLoopBackOff, ImagePullBackOff 等
        }
        if cs.State.Terminated != nil {
            reason = cs.State.Terminated.Reason
            status = "Terminated"
        }
    }

    // 异常状态判定
    abnormal := map[string]bool{
        "CrashLoopBackOff":  true,
        "ImagePullBackOff":  true,
        "ErrImagePull":      true,
        "Pending":           true,
        "Failed":            true,
        "Terminated":        true,
    }

    if !abnormal[status] {
        return nil
    }

    // 状态过滤
    if filter != "" && filter != status {
        return nil
    }

    var restarts int32
    if len(pod.Status.ContainerStatuses) > 0 {
        restarts = pod.Status.ContainerStatuses[0].RestartCount
    }

    return &PodInfo{
        Namespace: pod.Namespace,
        Name:      pod.Name,
        Status:    status,
        Restarts:  restarts,
        Node:      pod.Spec.NodeName,
        Reason:    reason,
    }
}

// DeletePod 删除指定 Pod
func (c *Client) DeletePod(namespace, name string, force bool) error {
    ctx := context.Background()
    deleteOpts := metav1.DeleteOptions{}
    if force {
        gracePeriod := int64(0)
        deleteOpts.GracePeriodSeconds = &gracePeriod
    }
    return c.clientset.CoreV1().Pods(namespace).Delete(ctx, name, deleteOpts)
}

// GetPodLogs 获取 Pod 日志
func (c *Client) GetPodLogs(namespace, name string, tailLines int64) (string, error) {
    ctx := context.Background()
    opts := &corev1.PodLogOptions{
        TailLines: &tailLines,
    }
    req := c.clientset.CoreV1().Pods(namespace).GetLogs(name, opts)
    logs, err := req.Stream(ctx)
    if err != nil {
        return "", err
    }
    defer logs.Close()

    buf := make([]byte, 0, 4096)
    tmp := make([]byte, 4096)
    for {
        n, err := logs.Read(tmp)
        if n > 0 {
            buf = append(buf, tmp[:n]...)
        }
        if err != nil {
            break
        }
    }
    return string(buf), nil
}

Clean 子命令

// cmd/clean.go
package cmd

import (
    "fmt"
    "strings"

    "github.com/spf13/cobra"
)

var forceDelete bool
var dryRun bool

var cleanCmd = &cobra.Command{
    Use:   "clean",
    Short: "批量清理异常 Pod",
    Run: func(cmd *cobra.Command, args []string) {
        client, err := NewK8sClient(kubeconfig)
        if err != nil {
            fmt.Fprintf(cmd.ErrOrStderr(), "连接集群失败: %v\n", err)
            return
        }

        pods, err := client.ListAbnormalPods(namespace, "")
        if err != nil {
            fmt.Fprintf(cmd.ErrOrStderr(), "查询失败: %v\n", err)
            return
        }

        if len(pods) == 0 {
            fmt.Println("没有异常 Pod 需要清理")
            return
        }

        fmt.Printf("发现 %d 个异常 Pod:\n", len(pods))
        for _, p := range pods {
            fmt.Printf("  %s/%s [%s] restarts=%d\n", p.Namespace, p.Name, p.Status, p.Restarts)
        }

        if dryRun {
            fmt.Println("\n--dry-run 模式，不执行实际删除")
            return
        }

        success := 0
        failed := 0
        for _, p := range pods {
            err := client.DeletePod(p.Namespace, p.Name, forceDelete)
            if err != nil {
                fmt.Printf("  ✗ %s/%s 删除失败: %v\n", p.Namespace, p.Name, err)
                failed++
            } else {
                fmt.Printf("  ✓ %s/%s 已删除\n", p.Namespace, p.Name)
                success++
            }
        }

        fmt.Printf("\n清理完成: 成功 %d, 失败 %d\n", success, failed)
    },
}

func init() {
    cleanCmd.Flags().BoolVarP(&forceDelete, "force", "f", false, "强制删除 (gracePeriod=0)")
    cleanCmd.Flags().BoolVar(&dryRun, "dry-run", false, "只显示将要删除的 Pod，不实际执行")
    rootCmd.AddCommand(cleanCmd)
}

Logs 子命令

// cmd/logs.go
package cmd

import (
    "fmt"
    "os"
    "path/filepath"

    "github.com/spf13/cobra"
)

var tailLines int64
var outputDir string

var logsCmd = &cobra.Command{
    Use:   "logs",
    Short: "导出异常 Pod 日志",
    Run: func(cmd *cobra.Command, args []string) {
        client, err := NewK8sClient(kubeconfig)
        if err != nil {
            fmt.Fprintf(cmd.ErrOrStderr(), "连接集群失败: %v\n", err)
            return
        }

        pods, err := client.ListAbnormalPods(namespace, "")
        if err != nil {
            fmt.Fprintf(cmd.ErrOrStderr(), "查询失败: %v\n", err)
            return
        }

        if outputDir == "" {
            outputDir = "./pod-logs"
        }
        if err := os.MkdirAll(outputDir, 0755); err != nil {
            fmt.Fprintf(cmd.ErrOrStderr(), "创建输出目录失败: %v\n", err)
            return
        }

        for _, p := range pods {
            logs, err := client.GetPodLogs(p.Namespace, p.Name, tailLines)
            if err != nil {
                fmt.Printf("  ✗ %s/%s 日志获取失败: %v\n", p.Namespace, p.Name, err)
                continue
            }
            filename := filepath.Join(outputDir, fmt.Sprintf("%s_%s.log", p.Namespace, p.Name))
            if err := os.WriteFile(filename, []byte(logs), 0644); err != nil {
                fmt.Printf("  ✗ %s 写入失败: %v\n", filename, err)
                continue
            }
            fmt.Printf("  ✓ %s/%s → %s\n", p.Namespace, p.Name, filename)
        }
    },
}

func init() {
    logsCmd.Flags().Int64VarP(&tailLines, "tail", "t", 100, "获取最后 N 行日志")
    logsCmd.Flags().StringVarP(&outputDir, "output", "o", "", "日志输出目录 (默认 ./pod-logs)")
    rootCmd.AddCommand(logsCmd)
}

输出格式化

// cmd/output.go
package cmd

import (
    "fmt"
    "os"
    "text/tabwriter"
)

func printPodTable(pods []PodInfo) {
    if len(pods) == 0 {
        fmt.Println("没有异常 Pod")
        return
    }

    w := tabwriter.NewWriter(os.Stdout, 0, 0, 2, ' ', 0)
    fmt.Fprintln(w, "NAMESPACE\tNAME\tSTATUS\tRESTARTS\tNODE\tREASON")

    for _, p := range pods {
        fmt.Fprintf(w, "%s\t%s\t%s\t%d\t%s\t%s\n",
            p.Namespace, p.Name, p.Status, p.Restarts, p.Node, p.Reason)
    }
    w.Flush()

    fmt.Printf("\n共 %d 个异常 Pod\n", len(pods))
}

使用示例

# 列出所有命名空间的异常 Pod
k8s-pod-cleaner list

# 只列出 CrashLoopBackOff 的 Pod
k8s-pod-cleaner list -s CrashLoopBackOff

# 指定命名空间
k8s-pod-cleaner list -n production

# 模拟清理（不实际删除）
k8s-pod-cleaner clean --dry-run

# 强制清理所有异常 Pod
k8s-pod-cleaner clean -f

# 导出异常 Pod 日志（最后 200 行）
k8s-pod-cleaner logs -t 200 -o ./incident-logs

跨平台编译与版本管理

交叉编译

# Linux amd64
GOOS=linux GOARCH=amd64 go build -o bin/k8s-pod-cleaner-linux-amd64

# macOS arm64 (Apple Silicon)
GOOS=darwin GOARCH=arm64 go build -o bin/k8s-pod-cleaner-darwin-arm64

# Windows amd64
GOOS=windows GOARCH=amd64 go build -o bin/k8s-pod-cleaner-windows-amd64.exe

版本信息注入

// cmd/version.go
package cmd

import (
    "fmt"
    "github.com/spf13/cobra"
)

var (
    Version   = "dev"
    Commit    = "none"
    BuildDate = "unknown"
)

var versionCmd = &cobra.Command{
    Use:   "version",
    Short: "显示版本信息",
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Printf("k8s-pod-cleaner %s\n", Version)
        fmt.Printf("  commit: %s\n", Commit)
        fmt.Printf("  build:  %s\n", BuildDate)
        fmt.Printf("  go:     %s\n", runtime.Version())
    },
}

func init() {
    rootCmd.AddCommand(versionCmd)
}

编译时注入版本信息：

go build -ldflags "\
  -X github.com/xubaojin/k8s-pod-cleaner/cmd.Version=v1.0.0 \
  -X github.com/xubaojin/k8s-pod-cleaner/cmd.Commit=$(git rev-parse --short HEAD) \
  -X github.com/xubaojin/k8s-pod-cleaner/cmd.BuildDate=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  -o bin/k8s-pod-cleaner

GoReleaser 自动化发布

GoReleaser 是 Go 项目的发布自动化工具，一步完成交叉编译、打包、changelog 和 GitHub Release：

# .goreleaser.yaml
version: 2

project_name: k8s-pod-cleaner

before:
  hooks:
    - go mod tidy

builds:
  - id: k8s-pod-cleaner
    main: ./main.go
    binary: k8s-pod-cleaner
    env:
      - CGO_ENABLED=0
    goos:
      - linux
      - darwin
      - windows
    goarch:
      - amd64
      - arm64
    ldflags:
      - -s -w
      - -X github.com/xubaojin/k8s-pod-cleaner/cmd.Version={{.Version}}
      - -X github.com/xubaojin/k8s-pod-cleaner/cmd.Commit={{.ShortCommit}}
      - -X github.com/xubaojin/k8s-pod-cleaner/cmd.BuildDate={{.Date}}

archives:
  - id: default
    formats: [tar.gz]
    format_overrides:
      - goos: windows
        formats: [zip]
    name_template: >-
      {{ .ProjectName }}_{{ .Version }}_
      {{- if eq .Os "darwin" }}macOS
      {{- else if eq .Os "linux" }}Linux
      {{- else if eq .Os "windows" }}Windows
      {{- end }}_{{ .Arch }}      

checksum:
  name_template: 'checksums.txt'

changelog:
  sort: asc
  filters:
    exclude:
      - '^docs:'
      - '^test:'
      - '^chore:'
  groups:
    - title: 'New Features'
      regexp: '^.*?feat(\([[:word:]]+\))??!?:.+$'
    - title: 'Bug Fixes'
      regexp: '^.*?fix(\([[:word:]]+\))??!?:.+$'
    - title: 'Other'
      default: true

release:
  github:
    owner: xubaojin
    name: k8s-pod-cleaner
  draft: false
  prerelease: auto

执行发布：

# 本地测试构建
goreleaser release --snapshot --clean

# 正式发布（需要 git tag）
git tag v1.0.0
git push origin v1.0.0
goreleaser release --clean

GoReleaser 会自动完成：

6 个平台的交叉编译（linux/darwin/windows × amd64/arm64）
生成 tar.gz/zip 压缩包
生成 SHA256 校验文件
自动生成 Changelog
创建 GitHub Release 并上传产物

总结

Go + cobra 是构建运维 CLI 工具的黄金组合。Go 的单二进制特性和跨平台能力解决了部署痛点，cobra 的命令树设计让复杂工具也能保持清晰的用户体验。

构建运维 CLI 的关键原则：命令层级简洁、flag 语义清晰、输出格式化可解析、提供 dry-run 模式。配合 GoReleaser 实现一键多平台发布，让工具的分发和维护变得轻而易举。

从 kubectl 到 helm 到 argocd，云原生生态中的优秀 CLI 工具几乎都遵循这一模式。掌握 Go + cobra，你就掌握了构建专业运维工具的核心能力。

参考资料与致谢

本文在撰写过程中参考了以下资料，感谢原作者的贡献：

cobra — Cobra，参考了相关技术内容
GoReleaser — Goreleaser，参考了GoReleaser相关内容

为什么 Go 适合运维工具#

cobra 框架快速上手#

安装与项目初始化#

命令树设计#

根命令与 Persistent Flag#

子命令与 Flag#

实战：k8s-pod-cleaner CLI 工具#

K8s 客户端封装#

Clean 子命令#

Logs 子命令#

输出格式化#

使用示例#

跨平台编译与版本管理#

交叉编译#

版本信息注入#

GoReleaser 自动化发布#

总结#

参考资料与致谢#