name: runbooks-troubleshooting-guides user-invocable: false description: 用于创建操作性问题故障排除指南和诊断程序。覆盖问题诊断、根因分析和系统调试。 allowed-tools:

Read
Write
Edit
Bash
Grep
Glob

操作手册 - 故障排除指南

创建有效的故障排除指南，用于诊断和解决操作性问题。

故障排除框架

5步法

观察 - 收集症状和数据
假设 - 形成关于根因的理论
测试 - 通过实验验证假设
修复 - 应用解决方案
验证 - 确认解决

基本故障排除指南

# 故障排除: [问题陈述]

## 症状

用户/系统经历的情况:
- API返回503错误
- 响应时间 > 10秒
- 高CPU使用率警报

## 快速检查 (< 2分钟)

### 1. 服务是否在运行?
```bash
kubectl get pods -n production | grep api-server

预期: STATUS = Running

2. 最近部署是否导致问题?

kubectl rollout history deployment/api-server

检查: 我们在过去30分钟内是否部署过?

3. 这是否影响所有用户?

在Datadog中检查错误率:

如果 < 5%: 孤立问题, 可能特定于客户端
如果 > 50%: 广泛问题, 可能是基础设施问题

常见原因

症状	可能原因	快速修复
503错误	Pod崩溃循环	重启部署
响应慢	数据库连接池	增加池大小
高内存	内存泄漏	重启pods

详细诊断

假设 1: 数据库连接问题

测试:

# 检查数据库连接
kubectl exec -it api-server-abc -- psql -h $DB_HOST -c "SELECT count(*) FROM pg_stat_activity"

如果连接数 > 90: 池已饱和。 下一步: 增加池大小或调查慢查询。

假设 2: 高流量峰值

测试:

# 检查请求率
curl -H "Authorization: Bearer $DD_API_KEY" \
  "https://api.datadoghq.com/api/v1/query?query=sum:nginx.requests{*}"

如果请求是正常值的3倍: 流量峰值。 下一步: 扩展pods或启用速率限制。

假设 3: 外部服务降级

测试:

# 检查第三方API
curl -w "@curl-format.txt" https://api.stripe.com/v1/charges

如果响应时间 > 2秒: 外部服务慢。 下一步: 实施断路器或增加超时。

解决步骤

解决方案 A: 立即 (< 5分钟)

重启受影响pods:

kubectl rollout restart deployment/api-server -n production

何时使用: 调查根因时的快速缓解措施。

解决方案 B: 短期 (< 30分钟)

扩展资源:

kubectl scale deployment/api-server --replicas=10 -n production

何时使用: 流量峰值或资源耗尽。

解决方案 C: 长期 (< 2小时)

修复根因:

识别慢数据库查询
添加数据库索引
部署代码优化

何时使用: 立即压力缓解后。

验证

[ ] 错误率 < 1%
[ ] 响应时间 p95 < 200毫秒
[ ] CPU使用率 < 70%
[ ] 无活跃警报

预防

如何防止此问题再次发生:

添加连接池饱和监控警报
基于请求率实施自动扩展
设置负载测试以找到容量限制


## 决策树格式

```markdown
# 故障排除: 慢API响应

## 从这里开始

                检查响应时间
                       |
        ┌──────────────┴──────────────┐
        │                             │
    < 500毫秒                     > 500毫秒
        │                             │
   非本操作手册                   继续下文


## 步骤 1: 定位慢点

```bash
# 检查哪个服务慢
curl -w "@timing.txt" https://api.example.com/users

决策:

首字节时间 > 2秒 → 数据库慢 (转到步骤2)
首字节时间 < 100毫秒 → 网络慢 (转到步骤3)
超时 → 服务宕机 (转到步骤4)

步骤 2: 数据库诊断

# 检查活跃查询
psql -c "SELECT query, state, query_start FROM pg_stat_activity WHERE state != 'idle'"

决策:

查询运行 > 5秒 → 慢查询 (解决方案A)
许多事务空闲 → 连接泄漏 (解决方案B)
高连接数 → 池耗尽 (解决方案C)

解决方案 A: 优化慢查询

从上方识别慢查询
运行EXPLAIN ANALYZE
添加缺失索引或优化查询

解决方案 B: 修复连接泄漏

重启应用pods
审查未关闭连接的代码
添加连接超时

解决方案 C: 增加连接池

编辑数据库配置
增加max_connections
更新应用池大小

步骤 3: 网络诊断

… (继续网络故障排除)


## 分层故障排除

### 层 1: 应用

```markdown
## 应用层问题

### 检查应用健康

1. **健康端点:**
   ```bash
   curl https://api.example.com/health

应用日志:

kubectl logs deployment/api-server --tail=100 | grep ERROR

应用指标:
- 请求率
- 错误率
- 响应时间百分位数

常见应用问题

内存泄漏

症状: 内存使用随时间爬升
测试: 在Datadog中检查内存指标
修复: 重启pods, 用堆转储调查

线程饥饿

症状: 慢响应, 高CPU
测试: 线程转储分析
修复: 增加线程池大小

代码错误

症状: 特定端点失败
测试: 审查最近部署
修复: 回滚或热修复


### 层 2: 基础设施

```markdown
## 基础设施层问题

### 检查基础设施健康

1. **节点资源:**
   ```bash
   kubectl top nodes

Pod资源:
```
kubectl top pods -n production
```

网络连接性:

kubectl run -it --rm debug --image=nicolaka/netshoot --restart=Never -- ping database.internal

常见基础设施问题

节点压力

症状: Pods被驱逐, 调度慢
测试: kubectl describe node 查看压力条件
修复: 扩展节点池或添加节点

网络分区

症状: 间歇性超时
测试: Pods和目的地之间的MTR
修复: 检查安全组, 路由表

磁盘 I/O 饱和

症状: 慢数据库, 高延迟
测试: 在CloudWatch中检查IOPS指标
修复: 增加预配置IOPS


### 层 3: 外部依赖

```markdown
## 外部依赖问题

### 检查外部服务

1. **第三方API:**
   ```bash
   curl -w "@timing.txt" https://api.stripe.com/health

状态页:
- 检查status.stripe.com
- 检查status.aws.amazon.com

DNS解析:

nslookup api.stripe.com
dig api.stripe.com

常见外部问题

API速率限制

症状: 从外部服务返回429响应
测试: 检查速率限制头部
修复: 实施退避, 缓存响应

服务降级

症状: 慢外部API响应
测试: 检查其状态页
修复: 实施断路器, 使用备用方案

DNS失败

症状: 无法解析主机名
测试: DNS查询
修复: 检查DNS配置, 尝试替代解析器


## 系统调试

### 使用科学方法

```markdown
# 调试: 数据库连接失败

## 1. 观察

**我们知道:**
- 错误: 日志中的"connection refused"
- 开始: 2025-01-15 14:30 UTC
- 频率: 每个数据库查询失败
- 范围: 所有pods受影响

## 2. 假设

**可能原因:**
1. 数据库实例宕机
2. 安全组阻塞流量
3. 网络分区
4. 错误凭据

## 3. 测试每个假设

### 测试 1: 数据库实例状态

```bash
aws rds describe-db-instances --db-instance-identifier prod-db | jq '.DBInstances[0].DBInstanceStatus'

结果: “available” 结论: 数据库在运行 ✗ 假设1拒绝

测试 2: 安全组规则

aws ec2 describe-security-groups --group-ids sg-abc123 | jq '.SecurityGroups[0].IpPermissions'

结果: 端口5432只对10.0.0.0/16开放 Pod IP: 10.1.0.5 结论: Pod IP不在允许范围内 ✓ 找到根因

4. 修复

更新安全组:

aws ec2 authorize-security-group-ingress \
  --group-id sg-abc123 \
  --protocol tcp \
  --port 5432 \
  --cidr 10.1.0.0/16

5. 验证

从pod测试连接:

kubectl exec -it api-server-abc -- psql -h prod-db.rds.amazonaws.com -c "SELECT 1"

结果: 成功 ✓


## 时间限制调查

```markdown
# 故障排除: 生产中断

**时间限制:** 最多花15分钟调查, 然后升级。

## 前5分钟: 快速胜利

- [ ] 检查pod状态
- [ ] 检查最近部署
- [ ] 检查外部状态页
- [ ] 审查监控仪表板

**如果问题持续:** 进入下一阶段。

## 分钟5-10: 常见原因

- [ ] 重启pods (快速缓解)
- [ ] 检查数据库连接性
- [ ] 审查应用日志
- [ ] 检查资源限制

**如果问题持续:** 进入下一阶段。

## 分钟10-15: 深入调查

- [ ] 启用调试日志
- [ ] 捕获线程转储
- [ ] 检查内存泄漏
- [ ] 审查网络跟踪

**如果问题持续:** 升级到高级工程师。

## 升级

**升级到:** 平台团队负责人
**提供:**
- 问题时间线
- 已执行测试
- 当前错误率
- 缓解尝试

常见故障排除模式

二分搜索

## 查找哪个服务慢

使用二分搜索缩小问题范围:

1. **检查完整请求:** 5000毫秒总时间
2. **检查前半部分 (API → 数据库):** 4900毫秒
   → 问题是数据库查询
3. **检查数据库:** 查询耗时4800毫秒
4. **检查查询计划:** 在大表上顺序扫描
5. **根因:** 缺失索引

**修复:** 在频繁查询列上添加索引。

关联分析

## 查找相关事件

寻找模式和关联:

**时间线:**
- 14:25 - 部署完成
- 14:30 - 错误率飙升
- 14:35 - 数据库CPU达100%
- 14:40 - 请求超时

**关联:** 部署引入了N+1查询。

**证据:**
- 无配置更改
- 无基础设施更改
- 只有代码部署
- 错误与部署同时发生

**行动:** 回滚部署。

反模式

不要跳过明显检查

# 坏: 跳到复杂解决方案
## 数据库慢

一定是查询优化问题。让我们分析查询计划...

# 好: 先检查基础
## 数据库慢

1. 数据库是否在运行?
2. 我们能连接吗?
3. 有锁吗?
4. 慢查询日志显示什么?

不要随机猜测

# 坏: 随机更改
## API错误

让我们尝试:
- 重启数据库
- 扩展到100 pods
- 更改负载均衡器配置
- 更新内核

# 好: 系统方法
## API错误

1. 实际错误消息是什么?
2. 何时开始?
3. 开始前发生了什么变化?
4. 我们能复现吗?

不要跳过文档

# 坏: 无笔记
## 修复了

我重启了一些pods, 现在好了。

# 好: 记录发现
## 解决

**根因:** worker进程中的内存泄漏
**证据:** Pod内存在6小时内线性爬升
**临时修复:** 重启pods
**长期修复:** PR #1234修复内存泄漏
**预防:** 添加内存使用警报

操作手册故障排除技能Skill runbooks-troubleshooting-guides

操作手册 - 故障排除指南

故障排除框架

5步法

基本故障排除指南

2. 最近部署是否导致问题?

3. 这是否影响所有用户?

常见原因

详细诊断

假设 1: 数据库连接问题

假设 2: 高流量峰值

假设 3: 外部服务降级

解决步骤

解决方案 A: 立即 (< 5分钟)

解决方案 B: 短期 (< 30分钟)

解决方案 C: 长期 (< 2小时)

验证

预防

步骤 2: 数据库诊断

解决方案 A: 优化慢查询

解决方案 B: 修复连接泄漏

解决方案 C: 增加连接池

步骤 3: 网络诊断

常见应用问题

常见基础设施问题

常见外部问题

测试 2: 安全组规则

4. 修复

5. 验证

常见故障排除模式

二分搜索

关联分析

反模式

不要跳过明显检查

不要随机猜测

不要跳过文档

相关技能