生产环境故障排查

技能文档

---
name: blogic-cz-production-troubleshooting
title: 生产环境故障排查
category: 开发工具
description: 按症状驱动的系统化流程排查生产/测试环境事故，覆盖慢接口、高延迟、OOMKilled Pod 重启、Pod 崩溃/限流、慢查询、Sentry 报错与链路追踪，并结合 kubectl 与 Helm 配置分析定位根因。当用户排查线上故障、生产事故、Pod 崩溃、接口变慢时触发。触发词：生产排查、故障诊断、Pod 崩溃、OOM、慢查询、Sentry、延迟排查、kubectl。
---

# 生产环境故障排查

## 概述

使用系统化的排查流程，结合 Sentry 链路追踪、kubectl 与 Helm 配置分析，诊断生产/测试环境中的性能问题与错误。

## 前置条件

排查前先确认 Sentry 与 Kubernetes 工具的可用性。

- 若当前环境提供 k8s-tool，优先使用它执行环境感知的命令。
- 若 k8s-tool 未安装或未配置，回退使用原生 `kubectl` 命令。
- 执行命令前先确认目标 namespace 与目标环境（`test` 或 `prod`）。

## 适用场景

在以下场景使用本技能：

- 排查测试/生产环境事故（而非本地环境）
- 排查慢接口、慢查询或延迟升高
- 调试 Pod 崩溃、重启循环、`OOMKilled` 或疑似限流
- 分析 Sentry 链路中的失败或性能退化事务
- 校验 Kubernetes 资源限额及相关 Helm 配置

## 技能工作流

按症状驱动的流程排查，任何变更前先确认证据。

### 步骤1：按主要症状分诊

根据反馈的症状选择第一条排查路径。

- Pod 崩溃/重启类症状（`CrashLoopBackOff`、`OOMKilled`、频繁重启）：优先检查 Pod 状态与日志。
- 延迟/慢接口类症状：优先查看链路追踪，再关联日志与 Pod 状态。

### 步骤2A：检查 Pod 状态与日志（崩溃/重启路径）

事故以 Pod 为中心时，先检查 Pod 健康状态，再做链路分析。

**使用 k8s-tool（优先）：**

```bash
k8s-tool describe --resource pod --name <pod-name> --env <env>
k8s-tool logs --pod <pod-name> --env <env> --tail 200
```

**回退使用 kubectl：**

```bash
kubectl describe pod <pod-name> -n <namespace>
kubectl logs <pod-name> -n <namespace> --tail 200
```

重点关注：重启原因、终止消息、探针失败、反复出现的启动错误。

### 步骤2B：检查 Sentry 链路（延迟/报错路径）

用 Sentry 定位慢数据库调用、外部延迟与事务级失败。

**使用 Sentry MCP：**

- 检索与反馈问题相关的链路
- 关注慢数据库查询（本项目以 >500ms 作为经验基线，非通用阈值）
- 检查外部 API 调用延迟
- 识别错误模式与堆栈信息

**重点关注：**

- 超出预期基线的数据库查询耗时（本项目常见基线约 500ms）
- 高延迟的外部 API 调用
- 反复出现的错误模式
- 性能退化趋势

### 步骤3：审查应用日志

通过 kubectl logs 查看耗时信息与错误模式。

**使用 k8s-tool：**

```bash
k8s-tool logs --pod <pod-name> --env <env> --tail 200
```

**重点检索的日志模式：**

- `[Server]` - 服务启动与初始化耗时
- `[SSR]` - 服务端渲染耗时
- `[tRPC]` - TRPC 查询执行耗时
- `[DB Pool]` - 数据库连接池状态
- `ERROR` 或 `WARN` - 应用错误与警告

**常见问题：**

- 串行 API 调用而非并行（Promise.all）
- 数据库连接获取耗时长
- SSR 渲染慢

### 步骤4：检查 Pod 资源用量

核实 CPU 与内存用量，识别限流风险。

**使用 k8s-tool：**

```bash
k8s-tool top --env <env>
```

**预警信号：**

- CPU 用量 >70% 可能存在限流风险
- 内存用量 >80% 可能存在较高 OOM 风险
- 持续高水位说明资源配置不足

### 步骤5：审查 Pod 配置

检查资源限额与 Helm 配置，定位错误配置。

**使用 kubectl：**

```bash
kubectl get pod <pod-name> -n <namespace> -o yaml
```

**重点检查项：**

- `resources.limits.cpu` 与 `resources.limits.memory`
- `resources.requests.cpu` 与 `resources.requests.memory`
- 环境变量配置
- 镜像版本与标签

**Helm 配置文件位置：**

- web-app：`/kubernetes/helm/web-app/values.{test,prod}.yaml`

详细结构参考 `references/helm-values-locations.md`。

### 步骤6：变更前确认证据

修改 Helm 配置或代码前，确认修复方案与观测证据相互对应。

- 每项变更都关联到链路、日志、Pod 事件或资源指标中的具体证据。
- 优先做最小的可回滚变更。
- 部署后复查链路/日志验证效果。

## 常见根因与解决方案

### CPU/内存限流

- **症状：** CPU/内存持续高水位，响应时间退化或重启
- **证据确认：** 将资源指标与限流信号、重启事件、延迟尖峰相互印证
- **解决方案：** 确认后才在 Helm 配置中调整资源 requests/limits

### 网络延迟

- **症状：** 外部 API 调用慢、DNS 解析延迟
- **证据确认：** 用慢 span 与计时日志验证网络型操作的耗时
- **解决方案：** 检查网络策略、核实 DNS 配置、必要时调整重试行为

### 数据库连接池问题

- **症状：** `[DB Pool]` 报错、连接获取慢
- **证据确认：** 将连接池告警与链路计时、连接等待模式相互印证
- **解决方案：** 审查 `idleTimeoutMillis` 与连接池大小配置

### 串行 API 调用

- **症状：** 多个 API 调用耗时累加
- **证据确认：** 在链路中验证串行 span 顺序，或检查带时间戳的日志序列
- **解决方案：** 重构为 `Promise.all()` 并行执行

## 参考资料

### kubectl 常用命令

有 k8s-tool 时优先使用，否则回退等效的 kubectl 命令：

- `k8s-tool logs --pod <pod> --env <env> --tail 200` - 提取并过滤 Pod 日志
- `k8s-tool top --env <env>` - 查看 Pod CPU/内存用量
- `k8s-tool describe --resource pod --name <pod> --env <env>` - 查看资源限额与 Pod 配置
- `k8s-tool kubectl --env <env> --cmd "get pods"` - 其余场景执行原生 kubectl

### references/

- `helm-values-locations.md` - Helm 配置文件结构与位置的详细说明
- `common-issues.md` - 常见生产问题目录与解决方案

使用说明

# 生产环境故障排查

按症状驱动的系统化流程，排查生产/测试环境事故：慢接口、高延迟、Pod 崩溃、OOMKilled、慢查询与 Sentry 报错。

## 使用

直接向 Agent 描述故障现象即可触发，例如：

```text
生产环境某个接口突然很慢，帮我排查一下
```

```text
Pod 一直 OOMKilled 重启，看看是什么原因
```

## 工作原理

技能按「症状分诊 → 检查 Pod 状态/日志或 Sentry 链路 → 审查应用日志 → 检查资源用量 → 审查 Pod/Helm 配置 → 变更前确认证据」的流程推进：

- Pod 崩溃/重启类症状优先查 Pod 状态与日志（k8s-tool 优先，回退 kubectl）
- 延迟/报错类症状优先查 Sentry 链路，再关联日志与 Pod 状态
- 每项修复都必须关联到链路、日志、事件或指标中的具体证据，优先做最小可回滚变更

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。