production-troubleshooting

生产环境故障排查

概述

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

前提条件

开始故障排查前，请确认可以访问 Sentry 和 Kubernetes 工具。

• 如果有 k8s-tool，优先使用它来运行适配环境的命令。
• 如果未安装 k8s-tool，或它未在当前环境中配置，请改用原始 kubectl 命令。
• 运行命令前，确认命名空间和目标环境（test 或 prod）。

何时使用此技能

在以下情况下使用此技能：

• 调查测试/生产环境（非 localhost）中的故障
• 排查端点响应缓慢、查询缓慢或延迟升高的问题
• 调试 Pod 崩溃、重启循环、OOMKilled 或潜在的限流问题
• 分析 Sentry 跟踪中的故障或性能下降的事务
• 验证 Kubernetes 资源限制和相关 Helm 值

调查工作流

按照此症状驱动的工作流进行调查，并在做出更改前确认相关证据。

步骤 1：根据主要症状进行初步判断

根据报告的症状选择首要调查路径。

• 对于 Pod 崩溃/重启症状（CrashLoopBackOff、OOMKilled、频繁重启）：先检查 Pod 状态和日志。
• 对于延迟/端点响应缓慢的症状：先检查跟踪，再结合日志和 Pod 状态进行分析。

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

如果故障以 Pod 为中心，在分析跟踪之前先检查 Pod 的健康状态。

使用 k8s-tool（首选）：

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

使用 kubectl 作为备选：

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 日志中的耗时信息和错误模式。

使用 k8s-tool：

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

需要搜索的关键日志模式：

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

常见问题：

• API 调用按顺序执行，而非并行执行（Promise.all）
• DB 连接获取耗时过长
• SSR 渲染缓慢

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

检查 CPU 和内存使用情况，以检测是否存在限流。

使用 k8s-tool：

k8s-tool top --env <env>

警示信号：

• CPU 使用率 >70% 可能表示存在限流
• 内存使用率 >80% 可能表示 OOM 风险较高
• 持续高利用率表明资源配置不足

步骤 5：查看 Pod 配置

检查资源限制和 Helm 值，以发现配置错误。

使用 kubectl：

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

详细的 Helm 配置结构请参阅 references/helm-values-locations.md。

步骤 6：在更改配置前确认证据

在编辑 Helm values 或代码前，确认拟议的修复与观察到的证据相符。

• 将每项更改与追踪记录、日志、Pod 事件或资源指标中的具体证据关联起来。
• 优先尝试影响最小且可逆的更改。
• 部署后重新检查追踪记录和日志，以验证影响。

常见原因与解决方案

CPU/内存节流

• 症状： CPU/内存持续高占用，并伴有响应时间变长或重启
• 通过证据确认： 将资源指标与节流信号、重启事件和延迟峰值进行关联
• 解决方案： 确认问题后，再调整 Helm values 中的资源请求和限制

网络延迟

• 症状： 外部 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 values 文件结构和位置的详细指南
• common-issues.md - 常见生产问题及解决方案汇总