delucia.cn – 第 6 页

OpenClaw 企业微信智能机器人接入完全指南

发布时间: 2026-03-09
标签: OpenClaw, 企业微信, AI机器人, 自动化
分类: 教程

前言

OpenClaw 支持接入企业微信智能机器人，打造专属的智能办公助手。本文将详细介绍如何通过长连接方式将 OpenClaw 接入企业微信。

一、前期准备

在开始之前，请确认已完成以下准备工作：

准备项	说明
✅ 企业微信客户端	安装最新版本
✅ OpenClaw 部署	本地或云服务器部署完成
✅ 管理员权限	企业微信管理后台访问权限

二、创建企业微信智能机器人

2.1 进入机器人创建页面

打开企业微信客户端
进入工作台
点击智能机器人
选择创建机器人
选择 API模式

2.2 选择长连接方式

重要：选择长连接方式创建，而不是 Webhook 方式。

长连接方式的优势：

✅ 支持主动向用户发送消息
✅ 实时双向通信
✅ 无需公网服务器

2.3 获取 Bot ID 和 Secret

创建成功后，系统会生成：

Bot ID: 机器人的唯一标识
Secret: 用于鉴权的密钥

⚠️ 重要：请妥善保管 Secret，不要泄露！

三、关联机器人与 OpenClaw

根据你的部署方式，选择对应的配置方法：

方式一：腾讯云 Lighthouse 部署（推荐）

如果你使用腾讯云轻量应用服务器 Lighthouse 部署 OpenClaw：

进入轻量云控制台
选中已部署 OpenClaw 的服务器实例
进入"应用管理"页面
选择企微机器人（长连接）通道
输入 Bot ID 和 Secret
点击"添加并应用"
重启 OpenClaw

方式二：本地终端部署（本文重点）

如果你在本地或自建服务器部署 OpenClaw：

3.1 安装企微插件

openclaw plugins install @wecom/wecom-openclaw-plugin

安装成功后会看到成功提示。

3.2 重启 OpenClaw

openclaw gateway start

3.3 添加企业微信 Channel

openclaw channels add

按照提示操作：

Select channel: 选择 企业微信
输入 Bot ID: 粘贴之前获取的 Bot ID
输入 Secret: 粘贴之前获取的 Secret
选择 finish: 完成基础配置
选择配对方式: 选择 Pairing

3.4 完成配对流程

关键步骤：

在企业微信机器人创建页面，点击保存并创建
在企业微信中找到刚创建的机器人，发送任意消息
机器人会回复一个配置密钥（类似验证码）
复制密钥的最后一行
在终端中粘贴此密钥，完成配对

配对成功后，即可在企业微信中正常对话！

四、验证接入

4.1 检查 Channel 状态

openclaw status --deep

期望输出：

│ 企业微信     │ ON      │ OK     │ configured │

4.2 发送测试消息

在企业微信中找到机器人，发送：

你好

如果收到回复，说明接入成功！

五、高级配置

5.1 配置访问策略

私聊开放模式（测试推荐）：

openclaw config set channels.wecom.dmPolicy open
openclaw config set channels.wecom.allowFrom '["*"]'

私聊白名单模式（生产推荐）：

openclaw config set channels.wecom.dmPolicy allowlist
openclaw config set channels.wecom.allowFrom '["user@company.com"]'

群组白名单模式：

openclaw config set channels.wecom.groupPolicy allowlist
openclaw config set channels.wecom.groupAllowFrom '["群组ID"]'

5.2 使用企业微信 API

如需调用企业微信应用 API：

在管理后台 → 我的企业，获取企业ID (corpid)
在应用管理 → 自建应用，获取应用Secret
发送 corpid 和 Secret 给机器人
机器人会获取 access token
使用 access token 调用企微 API

示例场景：

调用文档 API
管理企业通讯录
发送应用消息

5.3 智能表格 Webhook

企业微信智能表格支持通过 Webhook 接收外部数据：

在智能表格中开启"接收外部数据"
获取唯一的 Webhook 地址
通过 HTTP POST 请求新增或更新记录

适用场景：

自动化数据采集
第三方系统集成
定时任务同步

六、故障排查

6.1 插件加载失败

问题：Cannot find module 'axios'

解决：

cd ~/.openclaw/extensions/wecom-openclaw-plugin
npm install axios
openclaw gateway restart

6.2 配对失败

问题：输入密钥后无法配对

排查步骤：

确认 Bot ID 和 Secret 正确
确认网络连接正常
重新创建机器人，获取新的密钥
检查 OpenClaw 日志：openclaw logs | grep wecom

6.3 消息无响应

问题：发送消息后无回复

可能原因：

Channel 未启用
dmPolicy 配置错误
配对未完成

解决：

# 检查 Channel 状态
openclaw status --deep

# 查看日志
openclaw logs | grep wecom

# 确认配置
openclaw config get channels.wecom.dmPolicy

七、最佳实践

7.1 安全配置

生产环境推荐：

{
  "channels.wecom.dmPolicy": "allowlist",
  "channels.wecom.allowFrom": ["allowed-user@company.com"],
  "channels.wecom.groupPolicy": "allowlist",
  "channels.wecom.groupAllowFrom": ["allowed-group-id"]
}

7.2 性能优化

使用白名单模式减少不必要的消息处理
定期清理日志：openclaw logs --clear
监控系统资源：openclaw status

7.3 人设定制

OpenClaw 支持根据场景自动切换人设：

场景	身份	风格
私聊	小弟/搭档	呆萌犹豫、有温度
学生群	智能助教	友好专业、循循善诱
同事群	技术秘书	高效专业、不卑不亢
公众场合	AI助手	礼貌克制、有边界

编辑 SOUL.md 文件可自定义人设。

八、总结

OpenClaw 企业微信接入的核心流程：

创建机器人（长连接） → 获取Bot ID和Secret → 安装插件 → 配置Channel → 完成配对 → 开始对话

核心步骤：

✅ 在企业微信客户端创建智能机器人（长连接方式）
✅ 获取 Bot ID 和 Secret
✅ 安装企微插件：openclaw plugins install @wecom/wecom-openclaw-plugin
✅ 添加 Channel：openclaw channels add
✅ 完成配对流程（发送消息获取密钥）
✅ 测试验证

优势：

🚀 快速部署（15分钟完成）
🔒 安全可控（白名单机制）
🎭 场景自适应（自动切换人设）
🔒 隐私保护（敏感信息不泄露）
📡 长连接支持（主动推送消息）

限制：

不能获取历史消息
不能获取企业通讯录（需要额外权限）
图片推送功能受限

参考资料

相关文章推荐：

OpenClaw 快速入门指南
企业微信智能机器人开发实战
AI 助手人设设计最佳实践
使用 OpenClaw 接入智能表格

K8s 学习：常用命令 100 条（三）- CI/CD 集成实战

CI/CD

系列文章： K8s 命令实战指南
适用人群： DevOps 工程师、开发人员、运维工程师
阅读时间： 15 分钟

前言

将 Kubernetes 集成到 CI/CD 流水线中，可以实现自动化部署、滚动更新和快速回滚。本文介绍如何在常见的 CI/CD 工具中使用 kubectl 命令。

一、CI/CD 基础配置

1.1 配置 kubeconfig

# 方式1：使用 Service Account（推荐）
kubectl create serviceaccount gitlab-deployer -n default
kubectl create clusterrolebinding gitlab-deployer-binding --clusterrole=cluster-admin --serviceaccount=default:gitlab-deployer

# 获取 Service Account Token
kubectl get secret $(kubectl get serviceaccount gitlab-deployer -o jsonpath='{.secrets[0].name}') -o jsonpath='{.data.token}' | base64 --decode

# 获取 CA 证书
kubectl get secret $(kubectl get serviceaccount gitlab-deployer -o jsonpath='{.secrets[0].name}') -o jsonpath='{.data.ca\.crt}'

# 方式2：使用 kubeconfig 文件
cat ~/.kube/config

# 方式3：在 CI/CD 中设置环境变量
export KUBECONFIG=/path/to/kubeconfig

使用场景：

GitLab CI 连接集群
Jenkins 连接集群
GitHub Actions 连接集群
自动化脚本认证

1.2 验证连接

# 在 CI/CD 中测试连接
kubectl cluster-info

# 验证权限
kubectl auth can-i create deployments
kubectl auth can-i delete pods

# 查看当前上下文
kubectl config current-context

# 查看可用命名空间
kubectl get namespaces

使用场景：

CI/CD 配置验证
权限检查
环境确认

二、GitLab CI 集成

2.1 基础配置

# .gitlab-ci.yml
stages:
  - build
  - deploy

variables:
  IMAGE_NAME: registry.example.com/myapp
  IMAGE_TAG: $CI_COMMIT_SHA

build:
  stage: build
  script:
    - docker build -t $IMAGE_NAME:$IMAGE_TAG .
    - docker push $IMAGE_NAME:$IMAGE_TAG

deploy:
  stage: deploy
  script:
    - kubectl set image deployment/myapp myapp=$IMAGE_NAME:$IMAGE_TAG
    - kubectl rollout status deployment/myapp --timeout=300s
  only:
    - master

使用场景：

代码提交自动构建
自动更新镜像版本
滚动更新应用
生产环境部署

2.2 高级配置

# .gitlab-ci.yml（高级）
stages:
  - test
  - build
  - deploy-staging
  - deploy-production

variables:
  IMAGE_NAME: registry.example.com/myapp
  STAGING_NAMESPACE: staging
  PRODUCTION_NAMESPACE: production

test:
  stage: test
  script:
    - npm test
    - npm run lint

build:
  stage: build
  script:
    - docker build -t $IMAGE_NAME:$CI_COMMIT_SHA .
    - docker tag $IMAGE_NAME:$CI_COMMIT_SHA $IMAGE_NAME:latest
    - docker push $IMAGE_NAME:$CI_COMMIT_SHA
    - docker push $IMAGE_NAME:latest

deploy-staging:
  stage: deploy-staging
  script:
    - kubectl config set-context --current --namespace=$STAGING_NAMESPACE
    - kubectl apply -f k8s/staging/
    - kubectl set image deployment/myapp myapp=$IMAGE_NAME:$CI_COMMIT_SHA
    - kubectl rollout status deployment/myapp --timeout=300s
  environment:
    name: staging
    url: https://staging.example.com
  only:
    - develop

deploy-production:
  stage: deploy-production
  script:
    - kubectl config set-context --current --namespace=$PRODUCTION_NAMESPACE
    - kubectl apply -f k8s/production/
    - kubectl set image deployment/myapp myapp=$IMAGE_NAME:$CI_COMMIT_SHA
    - kubectl rollout status deployment/myapp --timeout=300s
  environment:
    name: production
    url: https://www.example.com
  when: manual
  only:
    - master

使用场景：

多环境部署（staging/production）
手动审批部署
自动化测试
环境隔离

2.3 回滚配置

# .gitlab-ci.yml（回滚）
rollback:
  stage: rollback
  script:
    - kubectl rollout undo deployment/myapp
    - kubectl rollout status deployment/myapp --timeout=300s
  when: manual
  only:
    - master

rollback-to-revision:
  stage: rollback
  script:
    - kubectl rollout history deployment/myapp
    - kubectl rollout undo deployment/myapp --to-revision=$REVISION
  when: manual
  only:
    - master

使用场景：

快速回滚到上一个版本
回滚到指定版本
手动触发回滚
紧急修复

三、Jenkins 集成

3.1 声明式 Pipeline

// Jenkinsfile
pipeline {
    agent any

    environment {
        IMAGE_NAME = 'registry.example.com/myapp'
        IMAGE_TAG = "${env.BUILD_NUMBER}"
        KUBECONFIG = credentials('kubeconfig')
    }

    stages {
        stage('Build') {
            steps {
                sh 'docker build -t ${IMAGE_NAME}:${IMAGE_TAG} .'
                sh 'docker push ${IMAGE_NAME}:${IMAGE_TAG}'
            }
        }

        stage('Deploy to Staging') {
            steps {
                sh 'kubectl config set-context --current --namespace=staging'
                sh 'kubectl set image deployment/myapp myapp=${IMAGE_NAME}:${IMAGE_TAG}'
                sh 'kubectl rollout status deployment/myapp --timeout=300s'
            }
        }

        stage('Deploy to Production') {
            steps {
                input 'Deploy to Production?'
                sh 'kubectl config set-context --current --namespace=production'
                sh 'kubectl set image deployment/myapp myapp=${IMAGE_NAME}:${IMAGE_TAG}'
                sh 'kubectl rollout status deployment/myapp --timeout=300s'
            }
        }
    }

    post {
        failure {
            sh 'kubectl rollout undo deployment/myapp'
        }
    }
}

使用场景：

Jenkins 流水线集成
自动化构建和部署
失败自动回滚
手动审批部署

3.2 脚本式 Pipeline

// Jenkinsfile（脚本式）
node {
    def imageName = 'registry.example.com/myapp'
    def imageTag = env.BUILD_NUMBER

    try {
        stage('Build') {
            sh "docker build -t ${imageName}:${imageTag} ."
            sh "docker push ${imageName}:${imageTag}"
        }

        stage('Deploy') {
            sh "kubectl set image deployment/myapp myapp=${imageName}:${imageTag}"
            sh "kubectl rollout status deployment/myapp --timeout=300s"
        }

    } catch (Exception e) {
        // 失败时回滚
        sh 'kubectl rollout undo deployment/myapp'
        throw e
    }
}

使用场景：

复杂流水线逻辑
条件判断
异常处理
自定义流程

四、GitHub Actions 集成

4.1 基础配置

# .github/workflows/deploy.yml
name: Deploy to Kubernetes

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3

    - name: Set up kubectl
      uses: azure/setup-kubectl@v3

    - name: Configure kubectl
      run: |
        mkdir -p ~/.kube
        echo "${{ secrets.KUBE_CONFIG }}" | base64 -d > ~/.kube/config

    - name: Build and push Docker image
      run: |
        docker build -t registry.example.com/myapp:${{ github.sha }} .
        docker push registry.example.com/myapp:${{ github.sha }}

    - name: Deploy to Kubernetes
      run: |
        kubectl set image deployment/myapp myapp=registry.example.com/myapp:${{ github.sha }}
        kubectl rollout status deployment/myapp --timeout=300s

使用场景：

GitHub 仓库自动化部署
代码推送触发部署
自动更新镜像版本
滚动更新应用

4.2 多环境部署

# .github/workflows/deploy.yml（多环境）
name: Deploy to Kubernetes

on:
  push:
    branches: [ main, develop ]

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/develop'

    steps:
    - uses: actions/checkout@v3

    - name: Deploy to Staging
      run: |
        kubectl config set-context --current --namespace=staging
        kubectl apply -f k8s/staging/
        kubectl set image deployment/myapp myapp=registry.example.com/myapp:${{ github.sha }}
        kubectl rollout status deployment/myapp --timeout=300s

  deploy-production:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'

    steps:
    - uses: actions/checkout@v3

    - name: Deploy to Production
      run: |
        kubectl config set-context --current --namespace=production
        kubectl apply -f k8s/production/
        kubectl set image deployment/myapp myapp=registry.example.com/myapp:${{ github.sha }}
        kubectl rollout status deployment/myapp --timeout=300s

使用场景：

分支对应环境
自动化多环境部署
环境隔离
条件触发

五、蓝绿部署

5.1 蓝绿部署流程

# 1. 部署绿色版本
kubectl apply -f deployment-green.yaml

# 2. 等待绿色版本就绪
kubectl rollout status deployment/myapp-green --timeout=300s

# 3. 切换流量到绿色版本
kubectl patch service myapp -p '{"spec":{"selector":{"version":"green"}}}'

# 4. 验证绿色版本
curl http://myapp-service/

# 5. 如果有问题，回滚到蓝色版本
kubectl patch service myapp -p '{"spec":{"selector":{"version":"blue"}}}'

# 6. 确认无误后，删除蓝色版本
kubectl delete deployment myapp-blue

使用场景：

零停机部署
快速回滚
生产环境验证
版本切换

5.2 自动化蓝绿部署脚本

#!/bin/bash
# blue-green-deploy.sh

IMAGE_TAG=$1
NAMESPACE=${2:-default}

echo "开始蓝绿部署..."

# 获取当前活跃版本
CURRENT_VERSION=$(kubectl get service myapp -n $NAMESPACE -o jsonpath='{.spec.selector.version}')

if [ "$CURRENT_VERSION" == "blue" ]; then
    NEW_VERSION="green"
else
    NEW_VERSION="blue"
fi

echo "当前版本: $CURRENT_VERSION"
echo "新版本: $NEW_VERSION"

# 部署新版本
cat deployment-template.yaml | \
    sed "s/{{VERSION}}/$NEW_VERSION/g" | \
    sed "s/{{IMAGE_TAG}}/$IMAGE_TAG/g" | \
    kubectl apply -n $NAMESPACE -f -

# 等待新版本就绪
kubectl rollout status deployment/myapp-$NEW_VERSION -n $NAMESPACE --timeout=300s

# 切换流量
kubectl patch service myapp -n $NAMESPACE -p "{\"spec\":{\"selector\":{\"version\":\"$NEW_VERSION\"}}}"

echo "蓝绿部署完成！当前版本: $NEW_VERSION"

使用场景：

自动化蓝绿部署
版本切换
零停机更新
生产环境验证

六、金丝雀发布

6.1 金丝雀发布流程

# 1. 部署金丝雀版本（10% 流量）
kubectl apply -f deployment-canary.yaml

# 2. 配置 Service 流量分割
kubectl apply -f service-canary.yaml

# 3. 监控金丝雀版本
kubectl logs -l version=canary -f

# 4. 逐步增加流量（20% -> 50% -> 100%）
kubectl patch service myapp -p '{"spec":{"selector":{"version":"canary"}}}'

# 5. 如果正常，完全切换到新版本
kubectl scale deployment myapp-stable --replicas=0
kubectl scale deployment myapp-canary --replicas=3

# 6. 如果有问题，回滚
kubectl scale deployment myapp-canary --replicas=0
kubectl scale deployment myapp-stable --replicas=3

使用场景：

渐进式发布
风险控制
小流量验证
灰度发布

6.2 自动化金丝雀发布脚本

#!/bin/bash
# canary-deploy.sh

IMAGE_TAG=$1
NAMESPACE=${2:-default}
CANARY_REPLICAS=${3:-1}
STABLE_REPLICAS=${4:-9}

echo "开始金丝雀发布..."

# 部署金丝雀版本
cat deployment-canary.yaml | \
    sed "s/{{IMAGE_TAG}}/$IMAGE_TAG/g" | \
    sed "s/{{REPLICAS}}/$CANARY_REPLICAS/g" | \
    kubectl apply -n $NAMESPACE -f -

# 等待金丝雀版本就绪
kubectl rollout status deployment/myapp-canary -n $NAMESPACE --timeout=300s

echo "金丝雀版本已部署（$CANARY_REPLICAS 个副本）"
echo "监控命令: kubectl logs -l version=canary -n $NAMESPACE -f"

# 监控 5 分钟
echo "监控 5 分钟..."
sleep 300

# 检查错误率
ERROR_RATE=$(kubectl logs -l version=canary -n $NAMESPACE | grep -c "ERROR")

if [ $ERROR_RATE -gt 10 ]; then
    echo "错误率过高，回滚金丝雀版本..."
    kubectl scale deployment myapp-canary -n $NAMESPACE --replicas=0
    exit 1
fi

# 逐步增加金丝雀副本
echo "增加金丝雀副本到 $((CANARY_REPLICAS * 2))..."
kubectl scale deployment myapp-canary -n $NAMESPACE --replicas=$((CANARY_REPLICAS * 2))
kubectl scale deployment myapp-stable -n $NAMESPACE --replicas=$((STABLE_REPLICAS - CANARY_REPLICAS))

echo "金丝雀发布完成！"

使用场景：

自动化金丝雀发布
错误率监控
渐进式流量切换
自动回滚

七、配置管理

7.1 ConfigMap 更新

# 更新 ConfigMap（不重启 Pod）
kubectl create configmap app-config --from-file=config.yaml --dry-run=client -o yaml | kubectl apply -f -

# 触发 Pod 滚动更新（让 Pod 重新加载配置）
kubectl rollout restart deployment/myapp

# 查看 ConfigMap 变更历史
kubectl describe configmap app-config

# 比较 ConfigMap 差异
kubectl get configmap app-config -o yaml > current-config.yaml
diff config.yaml current-config.yaml

使用场景：

应用配置更新
配置热更新
配置版本控制
配置回滚

7.2 Secret 更新

# 更新 Secret（不重启 Pod）
kubectl create secret generic app-secret --from-literal=password=newpass --dry-run=client -o yaml | kubectl apply -f -

# 触发 Pod 滚动更新
kubectl rollout restart deployment/myapp

# 查看 Secret 变更历史
kubectl describe secret app-secret

# 解码 Secret 内容
kubectl get secret app-secret -o jsonpath='{.data.password}' | base64 --decode

使用场景：

密码更新
密钥轮换
证书更新
安全配置

八、监控与告警

8.1 部署状态监控

# 监控部署状态
kubectl rollout status deployment/myapp --timeout=300s

# 查看部署历史
kubectl rollout history deployment/myapp

# 查看 Pod 状态
kubectl get pods -l app=myapp -w

# 查看事件
kubectl get events --field-selector involvedObject.name=myapp

# 监控资源使用
kubectl top pod -l app=myapp

使用场景：

部署进度监控
异常检测
性能监控
事件追踪

8.2 自动化健康检查

#!/bin/bash
# health-check.sh

DEPLOYMENT_NAME=$1
NAMESPACE=${2:-default}

echo "开始健康检查..."

# 等待部署完成
kubectl rollout status deployment/$DEPLOYMENT_NAME -n $NAMESPACE --timeout=300s

# 检查 Pod 状态
READY_PODS=$(kubectl get deployment $DEPLOYMENT_NAME -n $NAMESPACE -o jsonpath='{.status.readyReplicas}')
DESIRED_PODS=$(kubectl get deployment $DEPLOYMENT_NAME -n $NAMESPACE -o jsonpath='{.status.replicas}')

if [ "$READY_PODS" != "$DESIRED_PODS" ]; then
    echo "健康检查失败：就绪副本数不匹配"
    exit 1
fi

# 检查容器重启次数
RESTART_COUNT=$(kubectl get pods -l app=$DEPLOYMENT_NAME -n $NAMESPACE -o jsonpath='{.items[0].status.containerStatuses[0].restartCount}')

if [ "$RESTART_COUNT" -gt 3 ]; then
    echo "健康检查失败：容器重启次数过多"
    exit 1
fi

# 测试服务连通性
SERVICE_IP=$(kubectl get service $DEPLOYMENT_NAME -n $NAMESPACE -o jsonpath='{.spec.clusterIP}')
if ! kubectl run -it --rm --restart=Never busybox --image=busybox:1.28 -- wget -qO- http://$SERVICE_IP:80 > /dev/null 2>&1; then
    echo "健康检查失败：服务不可访问"
    exit 1
fi

echo "健康检查通过！"

使用场景：

部署后自动验证
服务可用性检查
自动化测试
CI/CD 集成

九、总结

9.1 CI/CD 集成最佳实践

安全性
- 使用 Service Account 认证
- 限制权限范围
- 保护敏感信息
可靠性
- 滚动更新策略
- 健康检查
- 自动回滚
可追溯性
- 版本标签
- 部署历史
- 审计日志
效率
- 并行构建
- 缓存优化
- 增量部署

9.2 常用命令速查

场景	命令
更新镜像	`kubectl set image deployment/<name> <container>=<image>`
查看部署状态	`kubectl rollout status deployment/<name>`
查看历史	`kubectl rollout history deployment/<name>`
回滚	`kubectl rollout undo deployment/<name>`
重启	`kubectl rollout restart deployment/<name>`
应用配置	`kubectl apply -f <yaml-file>`

参考资料

作者： PaPaBot
发布时间： 2026-03-07
标签： #Kubernetes #K8s #DevOps #CI/CD #自动化部署

本文属于《K8s 命令实战指南》系列文章第三篇

K8s 学习：常用命令 100 条（二）- 生产环境故障排查

故障排查

系列文章： K8s 命令实战指南
适用人群： 运维工程师、SRE 工程师、DevOps 工程师
阅读时间： 20 分钟

前言

在生产环境中，快速定位和解决问题是运维的核心能力。本文整理了最常见的 K8s 故障场景及排查命令，帮助你快速恢复服务。

一、Pod 故障排查

1.1 Pod 状态异常

# 查看所有异常 Pod
kubectl get pods --all-namespaces --field-selector=status.phase!=Running

# 查看特定状态的 Pod
kubectl get pods --field-selector=status.phase=Pending
kubectl get pods --field-selector=status.phase=Failed
kubectl get pods --field-selector=status.phase=Unknown

# 查看 Pod 状态详情
kubectl get pods -o custom-columns='NAME:metadata.name,STATUS:status.phase,RESTARTS:status.containerStatuses[0].restartCount,NODE:spec.nodeName'

# 查看 Pod 所有容器的状态
kubectl get pod <pod-name> -o jsonpath='{.status.containerStatuses[*].state}'

使用场景：

Pod 一直处于 Pending 状态
Pod 启动后立即退出
批量检查异常 Pod
监控 Pod 健康状态

1.2 CrashLoopBackOff

# 查看 Pod 事件
kubectl describe pod <pod-name> | grep -A 20 Events

# 查看容器日志
kubectl logs <pod-name> --previous

# 查看容器退出码
kubectl get pod <pod-name> -o jsonpath='{.status.containerStatuses[0].lastState.terminated.exitCode}'

# 查看容器终止原因
kubectl get pod <pod-name> -o jsonpath='{.status.containerStatuses[0].lastState.terminated.reason}'

# 查看容器重启次数
kubectl get pod <pod-name> -o jsonpath='{.status.containerStatuses[0].restartCount}'

# 查看 Pod 的资源使用
kubectl top pod <pod-name>

使用场景：

应用启动失败
配置文件错误
资源不足（OOM）
健康检查失败

常见退出码：

0：正常退出
1：应用错误
137：OOMKilled（内存不足）
139：Segmentation Fault
143：被 SIGTERM 终止

1.3 ImagePullBackOff / ErrImagePull

# 查看镜像拉取错误
kubectl describe pod <pod-name> | grep -A 10 "Events:"

# 查看 Pod 使用的镜像
kubectl get pod <pod-name> -o jsonpath='{.spec.containers[*].image}'

# 查看镜像拉取策略
kubectl get pod <pod-name> -o jsonpath='{.spec.containers[*].imagePullPolicy}'

# 查看 Secret（镜像拉取密钥）
kubectl get pod <pod-name> -o jsonpath='{.spec.imagePullSecrets}'

# 检查 Secret 是否存在
kubectl get secrets | grep <secret-name>

# 查看 Secret 内容
kubectl describe secret <secret-name>

# 测试镜像拉取（手动）
docker pull <image-name>
crictl pull <image-name>

使用场景：

镜像不存在或标签错误
镜像仓库认证失败
网络不通或镜像仓库不可达
镜像拉取超时

1.4 Pending 状态

# 查看 Pending 原因
kubectl describe pod <pod-name> | grep -A 20 Events

# 查看节点资源
kubectl describe nodes | grep -A 5 "Allocated resources"

# 查看节点可调度性
kubectl get nodes -o custom-columns='NAME:metadata.name,READY:status.conditions[?(@.type=="Ready")].status,SCHEDULABLE:spec.unschedulable'

# 查看资源请求
kubectl get pod <pod-name> -o jsonpath='{.spec.containers[*].resources.requests}'

# 查看 PV/PVC 状态
kubectl get pvc | grep <pod-namespace>

# 查看节点标签（用于节点选择）
kubectl get nodes --show-labels

# 查看 Pod 的节点选择器
kubectl get pod <pod-name> -o jsonpath='{.spec.nodeSelector}'

# 查看 Pod 的亲和性规则
kubectl get pod <pod-name> -o jsonpath='{.spec.affinity}'

使用场景：

资源不足（CPU/内存）
节点不可调度
PVC 未绑定
节点选择器不匹配
污点和容忍度问题

二、节点故障排查

2.1 NotReady 状态

# 查看节点状态
kubectl get nodes

# 查看节点详情
kubectl describe node <node-name>

# 查看节点条件
kubectl get node <node-name> -o jsonpath='{.status.conditions}'

# 查看 kubelet 状态（SSH 到节点）
systemctl status kubelet

# 查看 kubelet 日志
journalctl -u kubelet -f

# 查看容器运行时状态
systemctl status docker
systemctl status containerd

# 查看容器运行时日志
journalctl -u docker -f
journalctl -u containerd -f

使用场景：

kubelet 服务异常
容器运行时异常
网络不通
磁盘满

2.2 节点资源不足

# 查看节点资源使用
kubectl top node

# 查看节点资源分配
kubectl describe node <node-name> | grep -A 10 "Allocated resources"

# 查看节点上的 Pod
kubectl get pods --all-namespaces --field-selector spec.nodeName=<node-name>

# 查看节点上的 Pod 资源使用
kubectl top pod --all-namespaces --field-selector spec.nodeName=<node-name>

# 查看磁盘使用（SSH 到节点）
df -h

# 查看内存使用
free -h

# 查看进程资源使用
top
htop

# 清理未使用的容器和镜像
docker system prune -a
crictl rmi --prune

使用场景：

CPU 使用率过高
内存不足
磁盘空间不足
inode 耗尽

2.3 节点磁盘满

# 查看磁盘使用（SSH 到节点）
df -h

# 查看大文件
du -sh /* | sort -h | tail -10

# 查看 Docker 目录大小
du -sh /var/lib/docker

# 查看容器日志大小
du -sh /var/lib/docker/containers/*/*-json.log

# 查看日志文件
ls -lh /var/log/

# 清理 Docker 资源
docker system prune -a --volumes

# 清理容器日志（谨慎！）
truncate -s 0 /var/lib/docker/containers/*/*-json.log

# 清理系统日志
journalctl --vacuum-time=3d

# 查看被删除但仍占用的文件
lsof | grep deleted

使用场景：

磁盘使用率 > 90%
容器日志过大
镜像层过多
临时文件未清理

三、网络故障排查

3.1 DNS 解析失败

# 测试 DNS 解析
kubectl run -it --rm --restart=Never busybox --image=busybox:1.28 -- nslookup kubernetes

# 测试外部 DNS
kubectl run -it --rm --restart=Never busybox --image=busybox:1.28 -- nslookup www.google.com

# 查看 CoreDNS Pod 状态
kubectl get pods -n kube-system -l k8s-app=kube-dns

# 查看 CoreDNS 日志
kubectl logs -n kube-system -l k8s-app=kube-dns

# 查看 CoreDNS ConfigMap
kubectl get configmap coredns -n kube-system -o yaml

# 查看 Pod 的 DNS 配置
kubectl exec <pod-name> -- cat /etc/resolv.conf

# 测试 Service DNS
kubectl run -it --rm --restart=Never busybox --image=busybox:1.28 -- nslookup <service-name>.<namespace>.svc.cluster.local

# 查看 Service ClusterIP
kubectl get svc <service-name> -o jsonpath='{.spec.clusterIP}'

使用场景：

Service 域名解析失败
外部域名解析失败
CoreDNS 配置错误
跨命名空间访问失败

3.2 Service 无法访问

# 查看 Service 详情
kubectl describe service <service-name>

# 查看 Endpoints
kubectl get endpoints <service-name>

# 查看 Service 选择器
kubectl get svc <service-name> -o jsonpath='{.spec.selector}'

# 查看匹配的 Pod
kubectl get pods -l <selector-key>=<selector-value>

# 查看 Pod 标签
kubectl get pods --show-labels

# 查看 Service ClusterIP
kubectl get svc <service-name> -o jsonpath='{.spec.clusterIP}'

# 查看 Service 端口
kubectl get svc <service-name> -o jsonpath='{.spec.ports}'

# 测试 Service 连通性
kubectl run -it --rm --restart=Never busybox --image=busybox:1.28 -- wget -qO- <service-name>:<port>

# 端口转发测试
kubectl port-forward service/<service-name> <local-port>:<service-port>

使用场景：

Service 没有后端 Pod
Pod 标签不匹配
端口配置错误
网络策略阻止

3.3 Pod 之间网络不通

# 查看 Pod IP
kubectl get pod <pod-name> -o jsonpath='{.status.podIP}'

# 测试 Pod 之间连通性
kubectl exec <pod1-name> -- ping <pod2-ip>

# 查看 Pod 网络
kubectl exec <pod-name> -- ip addr

# 查看路由表
kubectl exec <pod-name> -- route -n

# 查看 iptables（SSH 到节点）
iptables -L -n -v

# 查看网络策略
kubectl get networkpolicy --all-namespaces

# 查看网络策略详情
kubectl describe networkpolicy <policy-name>

# 查看 CNI 配置（SSH 到节点）
ls /etc/cni/net.d/
cat /etc/cni/net.d/*.conf

# 查看 CNI 插件日志（SSH 到节点）
journalctl -u kubelet | grep cni

使用场景：

跨节点 Pod 不通
同节点 Pod 不通
网络策略阻止
CNI 插件问题

四、存储故障排查

4.1 PVC Pending

# 查看 PVC 状态
kubectl get pvc

# 查看 PVC 详情
kubectl describe pvc <pvc-name>

# 查看 PV 状态
kubectl get pv

# 查看 StorageClass
kubectl get storageclass

# 查看 Provisioner 日志
kubectl logs -n kube-system <provisioner-pod>

# 查看 PVC 事件
kubectl describe pvc <pvc-name> | grep -A 10 Events

# 查看可用 PV
kubectl get pv | grep Available

# 查看 PV 容量
kubectl get pv -o custom-columns='NAME:metadata.name,CAPACITY:spec.capacity.storage,STATUS:status.phase'

使用场景：

没有可用的 PV
StorageClass 不存在
Provisioner 异常
存储配额限制

4.2 Pod 挂载失败

# 查看 Pod 挂载信息
kubectl describe pod <pod-name> | grep -A 20 "Mounts:"

# 查看 Pod 挂载点
kubectl get pod <pod-name> -o jsonpath='{.spec.volumes}'

# 查看 PVC 绑定状态
kubectl get pvc <pvc-name> -o jsonpath='{.status.phase}'

# 进入 Pod 查看挂载
kubectl exec -it <pod-name> -- df -h

# 查看挂载点内容
kubectl exec <pod-name> -- ls -lh /<mount-path>

# 查看 PV 挂载信息（SSH 到节点）
mount | grep <pv-name>

# 查看磁盘挂载（SSH 到节点）
lsblk
df -h

使用场景：

PVC 未绑定
PV 挂载失败
存储类型不支持
权限问题

五、性能故障排查

5.1 CPU 使用率高

# 查看节点 CPU 使用
kubectl top node

# 查看 Pod CPU 使用
kubectl top pod --all-namespaces

# 按使用量排序
kubectl top pod --all-namespaces --sort-by=cpu

# 查看资源请求和限制
kubectl get pod <pod-name> -o custom-columns='NAME:metadata.name,CPU_REQ:spec.containers[*].resources.requests.cpu,CPU_LIM:spec.containers[*].resources.limits.cpu'

# 进入容器查看进程
kubectl exec -it <pod-name> -- top

# 查看进程 CPU 使用
kubectl exec <pod-name> -- ps aux --sort=-pcpu | head

# 生成 CPU Profile（需要应用支持）
kubectl exec <pod-name> -- curl http://localhost:6060/debug/pprof/profile?seconds=30 > cpu.prof

使用场景：

应用 CPU 占用过高
资源限制不合理
代码性能问题
死循环或阻塞

5.2 内存泄漏

# 查看 Pod 内存使用
kubectl top pod <pod-name>

# 查看内存使用趋势（持续监控）
watch kubectl top pod <pod-name>

# 查看内存请求和限制
kubectl get pod <pod-name> -o custom-columns='NAME:metadata.name,MEM_REQ:spec.containers[*].resources.requests.memory,MEM_LIM:spec.containers[*].resources.limits.memory'

# 进入容器查看内存
kubectl exec -it <pod-name> -- free -h

# 查看进程内存使用
kubectl exec <pod-name> -- ps aux --sort=-pmem | head

# 查看容器内存限制
kubectl exec <pod-name> -- cat /sys/fs/cgroup/memory/memory.limit_in_bytes

# 生成 Heap Dump（需要应用支持）
kubectl exec <pod-name> -- curl http://localhost:6060/debug/pprof/heap > heap.prof

# 查看 OOM 事件
kubectl get events --field-selector reason=OOMKilled

使用场景：

内存持续增长
频繁 OOMKilled
内存泄漏
缓存过大

六、证书故障排查

6.1 证书过期

# 查看证书有效期（kubeadm）
kubeadm certs check-expiration

# 查看 API Server 证书
openssl x509 -in /etc/kubernetes/pki/apiserver.crt -text -noout | grep -A 2 Validity

# 查看 kubelet 证书
openssl x509 -in /var/lib/kubelet/pki/kubelet-client-current.pem -text -noout | grep -A 2 Validity

# 查看证书过期时间
kubectl get csr

# 续期证书（kubeadm）
kubeadm certs renew all

# 重启服务使证书生效
kubectl rollout restart deployment -n kube-system
systemctl restart kubelet

使用场景：

API Server 证书过期
kubelet 证书过期
etcd 证书过期
证书轮换失败

6.2 证书认证失败

# 查看 kubeconfig
kubectl config view

# 查看 client 证书
openssl x509 -in ~/.kube/client-certificate -text -noout

# 测试 API 连接
kubectl cluster-info

# 查看认证日志（API Server）
journalctl -u kube-apiserver -f | grep auth

# 查看证书链
openssl s_client -connect <api-server-ip>:6443 -showcerts

# 验证证书和私钥匹配
openssl x509 -noout -modulus -in server.crt | openssl md5
openssl rsa -noout -modulus -in server.key | openssl md5

使用场景：

kubeconfig 配置错误
证书路径错误
证书和私钥不匹配
CA 证书错误

七、应用故障排查

7.1 健康检查失败

# 查看 Pod 事件
kubectl describe pod <pod-name> | grep -A 10 Events

# 查看健康检查配置
kubectl get pod <pod-name> -o jsonpath='{.spec.containers[*].livenessProbe}'

# 查看就绪检查配置
kubectl get pod <pod-name> -o jsonpath='{.spec.containers[*].readinessProbe}'

# 手动测试健康检查端点
kubectl exec <pod-name> -- curl -v http://localhost:<port>/health

# 查看容器日志
kubectl logs <pod-name> --tail=100

# 查看容器重启原因
kubectl get pod <pod-name> -o jsonpath='{.status.containerStatuses[0].lastState}'

使用场景：

Liveness Probe 失败
Readiness Probe 失败
健康检查端点错误
超时时间太短

7.2 配置错误

# 查看 ConfigMap
kubectl get configmap <configmap-name> -o yaml

# 查看 Secret
kubectl get secret <secret-name> -o yaml

# 查看 Pod 挂载的配置
kubectl exec <pod-name> -- ls -lh /etc/config/

# 查看环境变量
kubectl exec <pod-name> -- env | grep <config-key>

# 查看 Pod 的环境变量配置
kubectl get pod <pod-name> -o jsonpath='{.spec.containers[*].env}'

# 解码 Secret
kubectl get secret <secret-name> -o jsonpath='{.data.<key>}' | base64 --decode

# 更新 ConfigMap
kubectl create configmap <configmap-name> --from-file=<file> --dry-run=client -o yaml | kubectl apply -f -

使用场景：

ConfigMap 不存在
Secret 解码错误
环境变量未注入
配置文件路径错误

八、日志故障排查

8.1 日志收集问题

# 查看 Pod 日志
kubectl logs <pod-name> --tail=100

# 查看多个容器的日志
kubectl logs <pod-name> --all-containers

# 查看指定容器的日志
kubectl logs <pod-name> -c <container-name>

# 查看前一个容器的日志
kubectl logs <pod-name> --previous

# 实时查看日志
kubectl logs -f <pod-name>

# 查看日志大小限制
kubectl describe pod <pod-name> | grep -i log

# 查看 kubelet 日志配置（SSH 到节点）
cat /var/lib/kubelet/config.yaml | grep -A 5 containerLog

# 查看容器日志文件（SSH 到节点）
ls -lh /var/lib/docker/containers/*/*-json.log

使用场景：

日志输出过多
日志文件过大
日志格式错误
日志采集失败

九、总结

9.1 故障排查流程

1. 查看状态
   ↓
2. 查看事件
   ↓
3. 查看日志
   ↓
4. 定位问题
   ↓
5. 解决问题

9.2 常用排查命令速查

场景	命令
Pod 异常	`kubectl describe pod <pod-name>`
容器日志	`kubectl logs <pod-name> --previous`
节点异常	`kubectl describe node <node-name>`
DNS 问题	`nslookup kubernetes`
网络问题	`kubectl exec <pod> -- ping <ip>`
资源不足	`kubectl top node/pod`
证书问题	`kubeadm certs check-expiration`
存储问题	`kubectl describe pvc <pvc-name>`

9.3 预防措施

监控告警
- 设置资源使用告警
- 设置 Pod 重启告警
- 设置节点状态告警
日志收集
- 统一日志格式
- 集中日志存储
- 日志分析和搜索
定期检查
- 证书有效期
- 资源使用率
- 磁盘空间
文档记录
- 记录常见问题
- 记录解决方案
- 记录配置变更

参考资料

作者： PaPaBot
发布时间： 2026-03-07
标签： #Kubernetes #K8s #DevOps #运维 #故障排查

本文属于《K8s 命令实战指南》系列文章第二篇

K8s 学习：常用命令 100 条（一）- 基础入门篇

Kubernetes

系列文章： K8s 命令实战指南
适用人群： 运维工程师、开发人员、DevOps 工程师
阅读时间： 15 分钟

前言

Kubernetes（K8s）作为容器编排的行业标准，掌握其命令行工具 kubectl 是必备技能。本文整理了最常用的 K8s 命令，按场景分类，方便查阅和实战使用。

一、集群信息查看

1.1 基础信息

# 查看集群信息
kubectl cluster-info

# 查看集群节点
kubectl get nodes

# 查看节点详细信息
kubectl describe node <node-name>

# 查看集群版本
kubectl version

# 查看集群 API 资源
kubectl api-resources

# 查看集群 API 版本
kubectl api-versions

使用场景：

刚接入新集群时，了解集群基本信息
排查集群连接问题时，验证集群状态
升级集群前，检查当前版本

1.2 命名空间管理

# 查看所有命名空间
kubectl get namespaces
kubectl get ns

# 创建命名空间
kubectl create namespace <namespace-name>
kubectl create ns <namespace-name>

# 删除命名空间
kubectl delete namespace <namespace-name>

# 切换命名空间（需要安装 kubens）
kubens <namespace-name>

# 查看当前命名空间
kubectl config view --minify --format '{{.contexts[0].context.namespace}}'

使用场景：

多环境隔离（dev/test/prod）
多团队协作时，按命名空间划分资源
按项目或服务分类管理资源

二、资源查看

2.1 基础资源查看

# 查看 Pod
kubectl get pods
kubectl get po

# 查看 Pod（指定命名空间）
kubectl get pods -n <namespace>

# 查看 Pod（所有命名空间）
kubectl get pods --all-namespaces
kubectl get pods -A

# 查看 Pod 详细信息（包括 IP、节点）
kubectl get pods -o wide

# 查看 Pod 标签
kubectl get pods --show-labels

# 按标签筛选 Pod
kubectl get pods -l app=nginx

# 查看 Deployment
kubectl get deployments
kubectl get deploy

# 查看 Service
kubectl get services
kubectl get svc

# 查看 ConfigMap
kubectl get configmaps
kubectl get cm

# 查看 Secret
kubectl get secrets

# 查看 Ingress
kubectl get ingress
kubectl get ing

# 查看所有资源
kubectl get all

# 查看所有资源（包括事件）
kubectl get all,events

使用场景：

检查服务部署状态
排查 Pod 启动问题
查看资源分布情况
按标签筛选特定应用

2.2 详细信息查看

# 查看 Pod 详细信息
kubectl describe pod <pod-name>

# 查看 Deployment 详细信息
kubectl describe deployment <deployment-name>

# 查看 Service 详细信息
kubectl describe service <service-name>

# 查看节点详细信息
kubectl describe node <node-name>

# 以 YAML 格式查看资源
kubectl get pod <pod-name> -o yaml

# 以 JSON 格式查看资源
kubectl get pod <pod-name> -o json

# 查看资源的特定字段
kubectl get pod <pod-name> -o jsonpath='{.status.podIP}'

使用场景：

排查 Pod 启动失败原因
查看资源配置详情
提取特定字段用于脚本
深入了解资源状态

三、资源创建与删除

3.1 创建资源

# 通过 YAML 文件创建资源
kubectl apply -f <yaml-file>
kubectl create -f <yaml-file>

# 创建命名空间
kubectl create namespace <namespace-name>

# 创建 Deployment
kubectl create deployment <deployment-name> --image=<image>

# 创建 Service（暴露端口）
kubectl expose deployment <deployment-name> --port=<port> --target-port=<target-port>

# 创建 ConfigMap（从文件）
kubectl create configmap <configmap-name> --from-file=<file-path>

# 创建 ConfigMap（从字面值）
kubectl create configmap <configmap-name> --from-literal=key1=value1 --from-literal=key2=value2

# 创建 Secret（从文件）
kubectl create secret generic <secret-name> --from-file=<file-path>

# 创建 Secret（从字面值）
kubectl create secret generic <secret-name> --from-literal=username=admin --from-literal=password=secret

# 创建 CronJob
kubectl create cronjob <cronjob-name> --image=<image> --schedule="*/1 * * * *"

使用场景：

部署新应用
创建配置和密钥
快速创建测试资源
从文件导入配置

3.2 删除资源

# 删除 Pod
kubectl delete pod <pod-name>

# 删除 Deployment
kubectl delete deployment <deployment-name>

# 删除 Service
kubectl delete service <service-name>

# 通过 YAML 文件删除资源
kubectl delete -f <yaml-file>

# 删除指定标签的所有 Pod
kubectl delete pods -l app=nginx

# 删除命名空间（及其下所有资源）
kubectl delete namespace <namespace-name>

# 强制删除 Pod（不等待优雅关闭）
kubectl delete pod <pod-name> --force --grace-period=0

# 删除所有 Pod（慎用！）
kubectl delete pods --all

使用场景：

清理测试资源
删除废弃应用
强制删除卡住的 Pod
批量删除资源

四、资源编辑与更新

4.1 编辑资源

# 编辑资源（打开编辑器）
kubectl edit pod <pod-name>
kubectl edit deployment <deployment-name>
kubectl edit service <service-name>

# 编辑 ConfigMap
kubectl edit configmap <configmap-name>

# 编辑 Secret
kubectl edit secret <secret-name>

# 编辑并保存到文件
kubectl edit deployment <deployment-name> -o yaml > deployment.yaml

使用场景：

快速修改配置
调试资源设置
更新环境变量
修改副本数

4.2 更新资源

# 更新 Deployment 镜像
kubectl set image deployment/<deployment-name> <container-name>=<new-image>

# 更新 Deployment 副本数
kubectl scale deployment <deployment-name> --replicas=<number>

# 更新资源（通过 YAML 文件）
kubectl apply -f <yaml-file>

# 更新 ConfigMap
kubectl create configmap <configmap-name> --from-file=<file-path> --dry-run=client -o yaml | kubectl apply -f -

# 更新 Secret
kubectl create secret generic <secret-name> --from-literal=key=value --dry-run=client -o yaml | kubectl apply -f -

# 标记 Deployment 为暂停（暂停自动部署）
kubectl rollout pause deployment/<deployment-name>

# 恢复 Deployment 部署
kubectl rollout resume deployment/<deployment-name>

使用场景：

滚动更新应用版本
水平扩展/缩容
更新配置文件
更新密钥

五、日志查看与调试

5.1 日志查看

# 查看 Pod 日志
kubectl logs <pod-name>

# 查看 Pod 日志（指定容器）
kubectl logs <pod-name> -c <container-name>

# 查看 Pod 日志（实时跟踪）
kubectl logs -f <pod-name>

# 查看 Pod 日志（最近 N 行）
kubectl logs --tail=100 <pod-name>

# 查看 Pod 日志（指定时间范围）
kubectl logs --since=1h <pod-name>
kubectl logs --since-time=2024-01-01T00:00:00Z <pod-name>

# 查看 Pod 日志（保存到文件）
kubectl logs <pod-name> > pod.log

# 查看前一个容器的日志（容器重启后）
kubectl logs <pod-name> --previous

# 查看多个 Pod 的日志（需要安装 stern）
stern <pod-name-pattern>

使用场景：

排查应用错误
监控应用运行状态
收集日志用于分析
查看容器启动日志

5.2 进入容器

# 进入容器（交互式）
kubectl exec -it <pod-name> -- /bin/bash
kubectl exec -it <pod-name> -- /bin/sh

# 进入容器（指定容器）
kubectl exec -it <pod-name> -c <container-name> -- /bin/bash

# 在容器中执行命令
kubectl exec <pod-name> -- ls /app
kubectl exec <pod-name> -- cat /etc/config/app.conf

# 复制文件到容器
kubectl cp <local-file> <pod-name>:<remote-path>

# 从容器复制文件
kubectl cp <pod-name>:<remote-path> <local-file>

# 端口转发（本地端口映射到 Pod 端口）
kubectl port-forward <pod-name> <local-port>:<pod-port>

# 端口转发（Service）
kubectl port-forward service/<service-name> <local-port>:<service-port>

使用场景：

调试应用问题
查看容器内文件
临时修改配置
本地访问集群服务

六、资源扩缩容

6.1 手动扩缩容

# 扩容 Deployment
kubectl scale deployment <deployment-name> --replicas=5

# 缩容 Deployment
kubectl scale deployment <deployment-name> --replicas=1

# 基于条件扩容（当前副本数为 3 时才扩容）
kubectl scale deployment <deployment-name> --current-replicas=3 --replicas=5

# 扩容 StatefulSet
kubectl scale statefulset <statefulset-name> --replicas=3

# 扩容 ReplicaSet
kubectl scale replicaset <replicaset-name> --replicas=5

使用场景：

应对流量高峰
节省资源成本
测试水平扩展
紧急扩容

6.2 自动扩缩容（HPA）

# 创建 HPA（基于 CPU）
kubectl autoscale deployment <deployment-name> --cpu-percent=50 --min=2 --max=10

# 查看 HPA
kubectl get hpa

# 查看 HPA 详细信息
kubectl describe hpa <hpa-name>

# 删除 HPA
kubectl delete hpa <hpa-name>

# 编辑 HPA
kubectl edit hpa <hpa-name>

使用场景：

自动应对流量波动
优化资源使用
保证服务可用性
降低运维成本

七、滚动更新与回滚

7.1 滚动更新

# 更新镜像（触发滚动更新）
kubectl set image deployment/<deployment-name> <container-name>=<new-image>:<tag>

# 查看滚动更新状态
kubectl rollout status deployment/<deployment-name>

# 查看滚动更新历史
kubectl rollout history deployment/<deployment-name>

# 查看特定版本历史
kubectl rollout history deployment/<deployment-name> --revision=2

# 暂停滚动更新
kubectl rollout pause deployment/<deployment-name>

# 恢复滚动更新
kubectl rollout resume deployment/<deployment-name>

使用场景：

发布新版本应用
灰度发布
金丝雀发布
蓝绿部署

7.2 回滚

# 回滚到上一个版本
kubectl rollout undo deployment/<deployment-name>

# 回滚到指定版本
kubectl rollout undo deployment/<deployment-name> --to-revision=2

# 查看回滚状态
kubectl rollout status deployment/<deployment-name>

# 查看回滚历史
kubectl rollout history deployment/<deployment-name>

使用场景：

新版本有问题，快速回滚
灰度发布失败，回退版本
紧急修复生产问题
版本切换

八、网络调试

8.1 DNS 调试

# 创建 DNS 调试 Pod
kubectl run -it --rm --restart=Never busybox --image=busybox:1.28 -- nslookup kubernetes

# 测试 Service DNS
kubectl run -it --rm --restart=Never busybox --image=busybox:1.28 -- nslookup <service-name>

# 测试跨命名空间 DNS
kubectl run -it --rm --restart=Never busybox --image=busybox:1.28 -- nslookup <service-name>.<namespace>.svc.cluster.local

# 查看 CoreDNS 日志
kubectl logs -n kube-system -l k8s-app=kube-dns

使用场景：

排查服务发现问题
验证 DNS 解析
调试跨命名空间访问
CoreDNS 故障排查

8.2 网络连通性测试

# 测试 Pod 之间连通性
kubectl run -it --rm --restart=Never busybox --image=busybox:1.28 -- ping <pod-ip>

# 测试 Service 连通性
kubectl run -it --rm --restart=Never busybox --image=busybox:1.28 -- wget -qO- <service-name>:<port>

# 测试外部网络连通性
kubectl run -it --rm --restart=Never busybox --image=busybox:1.28 -- wget -qO- http://www.google.com

# 查看网络策略
kubectl get networkpolicy
kubectl get netpol

使用场景：

排查网络不通问题
验证 Service 访问
测试跨节点网络
网络策略调试

九、资源配额与限制

9.1 查看资源使用

# 查看节点资源使用
kubectl top node

# 查看 Pod 资源使用
kubectl top pod

# 查看 Pod 资源使用（指定命名空间）
kubectl top pod -n <namespace>

# 查看 Pod 资源使用（所有命名空间）
kubectl top pod --all-namespaces

# 查看资源配额
kubectl get resourcequota
kubectl get quota

# 查看限制范围
kubectl get limitrange
kubectl get limits

使用场景：

监控资源使用情况
排查资源不足问题
优化资源配置
容量规划

9.2 设置资源配额

# 创建资源配额
kubectl create quota <quota-name> --hard=cpu=2,memory=4Gi,pods=10

# 查看资源配额详情
kubectl describe quota <quota-name>

# 编辑资源配额
kubectl edit quota <quota-name>

# 删除资源配额
kubectl delete quota <quota-name>

使用场景：

限制命名空间资源使用
防止资源过度使用
多团队资源分配
成本控制

十、安全与权限

10.1 RBAC 管理

# 查看 Role
kubectl get roles

# 查看 RoleBinding
kubectl get rolebindings

# 查看 ClusterRole
kubectl get clusterroles

# 查看 ClusterRoleBinding
kubectl get clusterrolebindings

# 创建 Role
kubectl create role <role-name> --verb=get,list,watch --resource=pods

# 创建 RoleBinding
kubectl create rolebinding <rolebinding-name> --role=<role-name> --user=<username>

# 创建 ClusterRole
kubectl create clusterrole <clusterrole-name> --verb=get,list,watch --resource=pods

# 创建 ClusterRoleBinding
kubectl create clusterrolebinding <clusterrolebinding-name> --clusterrole=<clusterrole-name> --user=<username>

使用场景：

配置用户权限
服务账号授权
最小权限原则
多租户隔离

10.2 服务账号管理

# 查看服务账号
kubectl get serviceaccounts
kubectl get sa

# 创建服务账号
kubectl create serviceaccount <serviceaccount-name>

# 删除服务账号
kubectl delete serviceaccount <serviceaccount-name>

# 查看 Token
kubectl describe secret <secret-name>

使用场景：

为 Pod 配置权限
CI/CD 流水线访问集群
应用访问 K8s API
自动化脚本认证

十一、配置管理

11.1 ConfigMap 管理

# 创建 ConfigMap（从文件）
kubectl create configmap <configmap-name> --from-file=<file-path>

# 创建 ConfigMap（从目录）
kubectl create configmap <configmap-name> --from-file=<directory-path>

# 创建 ConfigMap（从字面值）
kubectl create configmap <configmap-name> --from-literal=key1=value1 --from-literal=key2=value2

# 查看 ConfigMap
kubectl get configmap <configmap-name> -o yaml

# 编辑 ConfigMap
kubectl edit configmap <configmap-name>

# 删除 ConfigMap
kubectl delete configmap <configmap-name>

# 更新 ConfigMap（不删除 Pod）
kubectl create configmap <configmap-name> --from-file=<file-path> --dry-run=client -o yaml | kubectl apply -f -

使用场景：

管理应用配置文件
环境变量注入
配置热更新
多环境配置管理

11.2 Secret 管理

# 创建 Secret（通用）
kubectl create secret generic <secret-name> --from-literal=key1=value1

# 创建 Secret（TLS）
kubectl create secret tls <secret-name> --cert=<cert-file> --key=<key-file>

# 创建 Secret（Docker Registry）
kubectl create secret docker-registry <secret-name> --docker-server=<server> --docker-username=<username> --docker-password=<password> --docker-email=<email>

# 查看 Secret
kubectl get secret <secret-name> -o yaml

# 解码 Secret
kubectl get secret <secret-name> -o jsonpath='{.data.key1}' | base64 --decode

# 编辑 Secret
kubectl edit secret <secret-name>

# 删除 Secret
kubectl delete secret <secret-name>

使用场景：

存储敏感信息（密码、密钥）
TLS 证书管理
镜像拉取认证
API 密钥管理

十二、故障排查

12.1 事件查看

# 查看所有事件
kubectl get events

# 查看事件（指定命名空间）
kubectl get events -n <namespace>

# 查看事件（排序）
kubectl get events --sort-by=.metadata.creationTimestamp

# 查看事件（监视模式）
kubectl get events --watch

# 查看事件（宽输出）
kubectl get events -o wide

# 查看特定资源的事件
kubectl describe <resource-type> <resource-name>

使用场景：

排查 Pod 启动失败
查看调度问题
监控集群事件
定位资源冲突

12.2 节点故障排查

# 查看节点状态
kubectl get nodes

# 查看节点详情
kubectl describe node <node-name>

# 查看节点资源使用
kubectl top node

# 标记节点为不可调度
kubectl cordon <node-name>

# 标记节点为可调度
kubectl uncordon <node-name>

# 驱逐节点上的 Pod
kubectl drain <node-name> --ignore-daemonsets --delete-emptydir-data

# 查看节点标签
kubectl get nodes --show-labels

# 给节点添加标签
kubectl label node <node-name> key=value

# 删除节点标签
kubectl label node <node-name> key-

使用场景：

节点维护
排查节点问题
节点升级
资源调度控制

十三、持久化存储

13.1 PV 和 PVC 管理

# 查看 PV
kubectl get pv

# 查看 PVC
kubectl get pvc

# 查看 PV 详情
kubectl describe pv <pv-name>

# 查看 PVC 详情
kubectl describe pvc <pvc-name>

# 删除 PV
kubectl delete pv <pv-name>

# 删除 PVC
kubectl delete pvc <pvc-name>

# 查看 StorageClass
kubectl get storageclass
kubectl get sc

使用场景：

数据持久化
存储容量管理
动态卷供给
存储类选择

13.2 存储调试

# 查看 Pod 挂载信息
kubectl describe pod <pod-name> | grep -A 10 Mounts

# 进入 Pod 查看挂载点
kubectl exec -it <pod-name> -- df -h

# 查看 PVC 绑定状态
kubectl get pvc <pvc-name> -o jsonpath='{.status.phase}'

# 查看 PV 绑定状态
kubectl get pv <pv-name> -o jsonpath='{.status.phase}'

使用场景：

排查存储挂载问题
验证数据持久化
存储容量规划
数据备份恢复

十四、高级操作

14.1 批量操作

# 批量删除 Pod
kubectl delete pods -l app=nginx

# 批量删除所有资源
kubectl delete all --all

# 批量标记节点
kubectl label nodes -l env=prod type=worker

# 批量添加注解
kubectl annotate pods -l app=nginx owner=devops

# 批量导出资源
kubectl get pods -o yaml > all-pods.yaml

使用场景：

批量清理资源
批量标记资源
批量更新配置
资源备份

14.2 资源补丁

# 使用 JSON 补丁
kubectl patch deployment <deployment-name> -p '{"spec":{"replicas":3}}'

# 使用 strategic merge 补丁
kubectl patch deployment <deployment-name> -p '{"spec":{"template":{"spec":{"containers":[{"name":"nginx","image":"nginx:1.19"}]}}}}'

# 使用 YAML 补丁
kubectl patch deployment <deployment-name> --patch "$(cat patch.yaml)"

# 删除字段
kubectl patch deployment <deployment-name> --type json -p '[{"op": "remove", "path": "/spec/replicas"}]'

使用场景：

精确修改资源字段
自动化脚本更新
CI/CD 集成
批量更新

十五、实用技巧

15.1 快捷别名

# 添加到 ~/.bashrc 或 ~/.zshrc
alias k='kubectl'
alias kg='kubectl get'
alias kd='kubectl describe'
alias kl='kubectl logs'
alias ke='kubectl exec -it'
alias ka='kubectl apply -f'
alias kd='kubectl delete -f'
alias kgp='kubectl get pods'
alias kgs='kubectl get svc'
alias kaf='kubectl apply -f'
alias kdf='kubectl delete -f'

# 重新加载配置
source ~/.bashrc

使用场景：

提高命令行效率
减少输入错误
快速执行常用命令

15.2 自动补全

# 启用 kubectl 自动补全（bash）
source <(kubectl completion bash)
echo "source <(kubectl completion bash)" >> ~/.bashrc

# 启用 kubectl 自动补全（zsh）
source <(kubectl completion zsh)
echo "if [ $commands[kubectl] ]; then source <(kubectl completion zsh); fi" >> ~/.zshrc

# 为别名也启用补全
complete -o default -F __start_kubectl k

使用场景：

快速输入命令
减少记忆负担
提高效率

15.3 常用组合命令

# 查看所有 Pod 的镜像版本
kubectl get pods -o=jsonpath='{range .items[*]}{"\n"}{.metadata.name}{":\t"}{range .spec.containers[*]}{.image}{", "}{end}{end}'

# 查看所有 Pod 的重启次数
kubectl get pods -o=jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.containerStatuses[0].restartCount}{"\n"}{end}'

# 查看 Pod 的资源请求和限制
kubectl get pods -o custom-columns='NAME:metadata.name,CPU_REQ:spec.containers[*].resources.requests.cpu,MEM_REQ:spec.containers[*].resources.requests.memory'

# 批量删除 Evicted Pod
kubectl get pods --all-namespaces --field-selector=status.phase=Failed -o json | kubectl delete -f -

# 查看节点上运行的 Pod
kubectl get pods --all-namespaces -o wide --field-selector spec.nodeName=<node-name>

使用场景：

快速获取信息
批量操作
自动化脚本
监控统计

总结

本文整理了 100+ 条 K8s 常用命令，涵盖了：

集群信息查看
资源管理（创建、删除、更新）
日志查看与调试
滚动更新与回滚
网络调试
资源配额与限制
安全与权限
配置管理
故障排查
持久化存储
高级操作
实用技巧

下一篇预告： K8s 命令实战指南（二）- 生产环境故障排查

参考资料

作者： PaPaBot
发布时间： 2026-03-07
标签： #Kubernetes #K8s #DevOps #运维

本文属于《K8s 命令实战指南》系列文章第一篇

Docker容器化遗留应用（五）：综合案例

Docker容器化

系列导读

这是《Docker容器化遗留应用》系列的最后一篇，前面介绍了容器化理论和实战案例，本篇将通过一个真实的遗留CRM系统容器化案例，展示完整流程。

遗留CRM系统容器化案例

系统架构

原始架构（单体应用）：

Apache web服务器
PHP 7.2后端
MySQL 5.7数据库
所有组件耦合在一起

目标：

提升扩展性（应对流量高峰）
提高维护性（独立更新组件）
加快部署效率（从小时到分钟）

步骤一：组件隔离

# docker-compose.yml
version: '3.8'

services:
  # 反向代理
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    networks:
      - crm-network

  # PHP后端
  php:
    build: ./php
    volumes:
      - ./html:/var/www/html
    networks:
      - crm-network

  # 数据库
  database:
    image: mysql:5.7
    environment:
      MYSQL_ROOT_PASSWORD: ${DB_PASSWORD}
    volumes:
      - mysql-data:/var/lib/mysql
    networks:
      - crm-network

  # 会话管理
  redis:
    image: redis:alpine
    networks:
      - crm-network

networks:
  crm-network:

volumes:
  mysql-data:

步骤二：数据迁移

# 导出现有数据
mysqldump -u root -p crm > crm_backup.sql

# 启动新容器
docker compose up -d

# 导入数据
docker exec -i crm-database-1 mysql -u root -p${DB_PASSWORD} crm < crm_backup.sql

步骤三：测试与部署

# 功能测试
docker run --rm selenium/standalone-chrome python tests/ui_tests.py

# 性能测试
jmeter -n -t crm_load_test.jmx

# 安全测试
docker run --rm owasp/zap2docker-stable zap-baseline.py -t http://crm-app

效果对比：容器化前后

指标	容器化前	容器化后	提升幅度
部署时间	2小时	2分钟	98% ↓
回滚时间	1小时	10秒	99.9% ↓
资源利用率	15%	70%	366% ↑
扩展速度	30分钟/台	5秒/容器	99.7% ↓
环境差异bug	每月3-5个	0	100% ↓

总结：容器化不是万能药，但是良药

获得的好处

✅ 环境一致性：告别"在我机器上能跑"
✅ 快速扩展：应对流量高峰不再是噩梦
✅ 提升部署效率：从小时级到分钟级
✅ 降低运维成本：自动化管理

需要注意

⚠️ 有状态应用（数据库）需要特殊处理
⚠️ 安全配置不能忽视
⚠️ 监控和日志必须跟上
⚠️ 团队需要学习新技术栈

下一步行动

从最简单的Web服务器开始，先在测试环境练手，积累经验后再处理复杂系统。

记住：容器化是一场马拉松，不是百米冲刺。

系列总结

《Docker容器化遗留应用》系列完整内容：

✅ （一）为什么要容器化 - 理解容器化优势
✅ （二）容器化三步走 - 掌握基本操作
✅ （三）网络与数据管理 - 理解核心概念
✅ （四）实战案例 - 学习真实场景
✅ （五）综合案例 ← 当前

参考资源

恭喜你完成了整个系列！你的遗留应用已经准备好迎接新生了！

2026 年 8 月
一	二	三	四	五	六	日
					1	2
3	4	5	6	7	8	9
10	11	12	13	14	15	16
17	18	19	20	21	22	23
24	25	26	27	28	29	30
31