返回列表

博客

在手机上调试生产环境问题

当生产环境在晚餐时间崩溃，你的手机就是你的调试界面。以下是如何在不用赶回电脑前的情况下诊断和修复问题。

发布于 标签: 上手教程 / debugging / production / incident-response
博客

继续查看该栏目下的产品与工程更新。

浏览此分类

周五晚上 7 点。你正和朋友吃晚饭，手机震动了——PagerDuty 告警：支付服务的错误率飙升到 15%。你的笔记本电脑在家里。队友们都不在线。这个事故由你来处理。

这正是 Tactic Remote 存在的意义。本教程将通过一个真实的生产环境调试工作流，演示如何仅使用 iPhone 来排查、诊断和修复生产环境问题。

场景设置

本教程将通过一个真实的场景进行演示：

  • 服务： Node.js 支付处理 API
  • 症状： /api/payments/process 端点返回 500 错误
  • 影响： 15% 的支付请求失败
  • 环境： 生产日志可通过 SSH 访问，代码库在你的 Mac 上

你的 Mac 在家里开着，运行着 Tactic Remote 伴侣应用。你从 iPhone 连接并开始排查。

第一阶段：分诊（5 分钟）

首要目标是了解问题的范围和紧急程度。启动一个指向项目目录的 Claude Code 会话：

We have a production incident. The /api/payments/process endpoint
is returning 500 errors for ~15% of requests. This started approximately
30 minutes ago.

Help me investigate:
1. Check the git log for any recent deployments (last 24 hours)
2. Look at the payment processing code in src/api/payments/
3. Check if there were any dependency updates recently

Claude Code 将检查代码和最近的变更。在它工作期间，用手机浏览器打开你的监控面板，检查：

  • 错误率是稳定的、在增长还是在下降？
  • 是所有实例都受到影响还是只有部分？
  • 失败的请求是否有规律？

Claude Code 可能的发现： 3 小时前的一次提交将 Stripe SDK 依赖从 v12.1.0 更新到了 v13.0.0，其中包含了破坏性的 API 变更。

第二阶段：诊断（10 分钟）

有了假设（Stripe SDK 更新），深入排查：

Compare the Stripe SDK v12 and v13 changelog.
Check our payment processing code for any API calls that changed
between versions. Focus on the payment intent creation and
confirmation flow in src/api/payments/processor.ts.

Claude Code 将分析代码并识别具体的不兼容之处。典型的发现如下：

Found the issue. In Stripe SDK v13, the `payment_intents.create()` method
changed its error handling behavior:

- v12: Returns { error: { type, message } } for card declines
- v13: Throws StripeCardError exception for card declines

Our code in processor.ts:45-52 checks for `result.error` but doesn't
catch the new exception type. When a card is declined, the uncaught
exception propagates as a 500 error.

This explains the 15% error rate — approximately 15% of payment
attempts involve card declines (expired cards, insufficient funds, etc.)
that now throw uncaught exceptions.

这个诊断是具体的、可验证的，并且解释了观察到的现象。在手机上，你可以在继续之前确认它是否合理。

第三阶段：修复（10 分钟）

现在实施修复。你有两个选择：

方案 A：快速回滚

如果情况紧急且之前的版本是稳定的：

Revert the Stripe SDK update. Change package.json to pin
stripe at v12.1.0. Create a commit with message:
"hotfix: revert Stripe SDK to v12 (fixes payment 500 errors)"

审批步骤： Claude Code 会请求批准修改 package.json 并运行 npm install。在审批卡片中检查变更内容并批准。

方案 B：向前修复

如果你想修复代码以适配 v13（避免回滚导致丢失其他改进）：

Fix the payment processing code to handle both the legacy error
response format and the new exception-based error handling in
Stripe SDK v13.

Specifically:
1. Wrap the payment_intents.create() call in a try/catch
2. Catch StripeCardError and convert it to our standard error format
3. Keep the existing result.error check as a fallback
4. Add a test case for the card decline scenario

Commit with: "hotfix: handle Stripe v13 exception-based card decline errors"

Claude Code 将进行修改并运行测试。在终端视图中观察测试结果。

审批流程： 你可能会看到多个审批请求：

  1. 修改 src/api/payments/processor.ts — 批准（这是修复代码）
  2. 修改 src/api/payments/__tests__/processor.test.ts — 批准（添加测试）
  3. 运行 npm test — 批准（验证修复）

第四阶段：部署（5 分钟）

修复已提交并测试通过后：

Push this commit to the main branch.
Then trigger the deployment pipeline by running our deploy script:
./scripts/deploy.sh production

关键审批： Claude Code 将请求批准部署命令。这是整个工作流中风险最高的操作。仔细审查：

  • 确认提交信息与你的修复一致
  • 确认部署目标正确（production）
  • 确保上一步的测试已通过

批准后，Claude Code 执行部署。在终端输出中监控部署进度。

第五阶段：验证（5 分钟）

部署完成后：

Check the deployment status. Then help me verify:
1. Run a test request against the production payment endpoint
2. Check if the error rate has started decreasing
3. Look for any new error patterns in the last 5 minutes

同时，在手机上查看你的监控面板。错误率应该在部署完成后几分钟内开始下降。

事后处理：编写报告

趁事故还新鲜（仍然在吃饭，两道菜之间）：

Write a post-incident report based on our investigation:

Include:
- Timeline of events
- Root cause (Stripe SDK v13 breaking change)
- Impact (15% payment failure rate for ~1 hour)
- Resolution (code fix to handle new exception type)
- Action items to prevent recurrence

Format as a markdown document in docs/incidents/

这样你的团队在周一早上就能看到一份完整的事故报告。你的饭友几乎没注意到你被打断了。

高效远程调试技巧

先广后窄。 不要立即跳到假设。让 Claude Code 先全面了解情况（最近的变更、错误模式、系统状态），然后再聚焦到具体原因。

利用审批关卡作为检查点。 每个审批请求都是一个自然的检查点，你可以在此审查 Claude Code 正在做什么。利用这些来确认排查方向是否正确。

将诊断和修复分开。 先获得清晰的诊断并确认其合理性，然后再实施任何更改。这可以防止在不理解根因的情况下"追着修"的情况。

调试时保持沟通。 如果你的团队有事故频道，从手机上发布进展：

  • "正在排查支付 500 错误。怀疑是 Stripe SDK 更新导致。"
  • "已确认：SDK v13 改变了卡片拒绝的错误处理方式。正在部署修复。"
  • "修复已部署。错误率正在恢复正常。"

这让利益相关者保持知情，防止重复排查。

知道自己的边界。 有些生产问题需要基础设施访问、数据库查询或系统级调试，这些无法通过 Claude Code 完成。如果你遇到瓶颈，及时升级处理——不要在手机上花一个小时去做在工作站上只需要 5 分钟的事情。

构建你的事故应急工具包

在事故发生之前做好准备：

  1. 预先配置一个生产调试会话，确保能够访问你的部署脚本和监控工具。
  2. 创建事故响应提示词，存放在你的提示词库中，供 Claude Code 遵循。
  3. 在非紧急情况下测试工作流，这样当压力真正来临时你已经熟悉了整个流程。
  4. 确保 Cloudflare Tunnel 访问可用，这样你可以从任何地方进行调试，而不仅仅是在家庭网络中。

生产事故不会等到方便的时间才发生。Tactic Remote 确保无论你身在何处，都有工具进行有效响应。

立即体验 Tactic Remote

用手机远程控制编程 Agent

连接 Mac、Windows 或 Linux 电脑上的 Claude Code、Codex 等 Agent，在 iPhone 或 iPad 上查看进展并发送下一条要求。

查看设置步骤查看所有下载