生产环境故障排查

技能文档

---
name: blogic-cz-production-troubleshooting
title: 生产环境故障排查
description: "排查生产/测试环境事故，包括慢接口、高延迟、OOMKilled Pod 重启、Pod 崩溃/限流、慢查询、Sentry 报错与链路追踪。触发词：生产排查、故障诊断、Pod 崩溃、OOM、慢查询、Sentry、延迟排查、kubectl。"
category: 开发工具
---

# 生产环境故障排查

## 概述

使用 Sentry、kubectl 和 Helm 配置分析，通过系统化排查工作流诊断生产/测试环境中的性能问题与错误。

## 前置条件

排查前需确认 Sentry 和 Kubernetes 工具的访问权限。

- 优先使用终端工具执行环境感知命令。
- 若终端工具未安装或未配置，则回退到原生 `kubectl` 命令。
- 执行命令前确认命名空间和目标环境（`test` 或 `prod`）。

## 适用场景

以下情况请使用本技能：

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

## 技能工作流

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

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

根据报告的症状选择首条排查路径。

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

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

当事故与 Pod 相关时，在链路分析前先检查 Pod 健康状态。

**使用终端工具（优先）：**

```bash
终端工具 describe --resource pod --name <pod-name> --env <env>
终端工具 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 工具：**

- 搜索与报告问题相关的链路追踪
- 查找慢数据库查询（本项目中 >500ms 是有用的基线启发值，非通用阈值）
- 检查外部 API 调用延迟
- 识别错误模式和堆栈追踪

**重点关注：**

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

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

检查 kubectl 日志中的时序信息和错误模式。

**使用终端工具：**

```bash
终端工具 logs --pod <pod-name> --env <env> --tail 200
```

**关键日志模式：**

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

**常见问题：**

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

### 步骤4：检查 Pod 资源使用情况

验证 CPU 和内存使用率以检测限流。

**使用终端工具：**

```bash
终端工具 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` 了解详细的 Helm 配置结构。

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

编辑 Helm 值或代码前，确认修复方案与观察到的证据对应。

- 将每项变更关联到链路追踪、日志、Pod 事件或资源指标中的具体证据。
- 优先选择最小的可逆变更。
- 部署后重新检查链路追踪/日志以验证影响。

## 常见原因与解决方案

### CPU/内存限流

- **症状：** 持续高 CPU/内存使用率，伴随响应时间退化或重启
- **证据确认：** 将资源指标与限流信号、重启事件和延迟峰值关联
- **解决方案：** 确认后调整 Helm 值中的资源请求/限制

### 网络延迟

- **症状：** 外部 API 调用慢、DNS 解析延迟
- **证据确认：** 验证慢链路区间和定时日志条目中的网络绑定操作
- **解决方案：** 检查网络策略、验证 DNS 配置，适当调整重试行为

### 数据库连接池问题

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

### 串行 API 调用

- **症状：** 多个 API 调用累计耗时
- **证据确认：** 验证链路追踪中的串行区间排序或时间戳日志序列
- **解决方案：** 重构为使用 `Promise.all()` 并行执行

## 参考资料

### kubectl 命令

优先使用终端工具执行以下常用操作，或在回退时运行等效的原生 `kubectl` 命令：

- `终端工具 logs --pod <pod> --env <env> --tail 200` - 提取并过滤 Pod 日志
- `终端工具 top --env <env>` - 显示 Pod 的 CPU/内存使用率
- `终端工具 describe --resource pod --name <pod> --env <env>` - 检查资源限制和 Pod 配置
- `终端工具 kubectl --env <env> --cmd "get pods"` - 原生 kubectl 执行其他操作

### references/

- `helm-values-locations.md` - Helm 值文件结构和位置的详细指南
- `common-issues.md` - 常见生产问题及解决方案目录

使用说明

# 生产环境故障排查

系统化排查生产/测试环境中的性能问题与错误。

## 功能概述

本技能提供基于症状驱动的生产环境排查工作流，整合 Sentry 链路追踪、Kubernetes 命令行工具和 Helm 配置分析，帮助快速定位和解决以下问题：

- Pod 崩溃、重启循环与 OOMKilled
- 接口延迟升高与慢查询
- CPU/内存限流
- 数据库连接池问题
- 网络延迟与 DNS 问题

## 使用方法

1. 确认目标环境（test/prod）和命名空间
2. 根据症状选择排查路径（崩溃/重启 或 延迟/错误）
3. 按步骤收集证据（Pod 状态、日志、链路追踪、资源指标）
4. 确认证据后再进行配置变更

## 前置条件

- Kubernetes 集群访问权限
- Sentry 项目访问权限
- Helm 值文件仓库访问权限

## 参考资料

- `references/common-issues.md` - 常见生产问题目录
- `references/helm-values-locations.md` - Helm 值文件结构指南

如何安装此技能？

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