# 总部看不到的客户系统，出了 bug 怎么查

> 关键不在修好，而在做出同事能运行的复现，且客户数据一个字节都不带出现场。

原文: https://fdetimes.net/zh/guides/debug-without-production-access/

下午三点，客户反映他们的数据摄取管道从早上开始一直在悄无声息地丢记录。你人在客户现场，总部的工程团队却没有任何办法查看那套系统。他们知道的，只有你告诉他们的。

这种情形在一份职位描述里写得一字不差。Twenty 招聘 Senior/Staff Forward Deployed Software Engineer 的职位描述写道，在办公室的团队无法访问这个环境，因此前线部署工程师（FDE）是软件实际运行之处唯一在场的工程师。

所以修 bug 只是这项技能的一部分。你还得把 bug 以别人能运行、能读懂、能验证的形式带出客户环境，同时不带走客户的一个字节数据。

## 为什么不能依赖预发布环境和告警？

很多工程师第一反应是“我在 staging 上试试”。销售 bug 复现工具的公司 Speedscale 在一篇文章中指出，即使有预发布环境，它也很少与生产环境完全一致。配置、服务版本，尤其是真实数据的形态，往往差得足以让 bug 消失。

监控也救不了你。同一篇文章指出，监控能告诉你出了事，却给不出重建 bug 所需的完整请求和响应。告警只是起点。

从“知道有 bug”到“能复现 bug”之间的这段距离，正是 FDE 的工作所在。弥合它靠三样工具：日志指方向，数据样本帮你理解输入的形态，复现用来证明。

## 日志是用来排除的，不是用来从头读到尾的

Google 的《SRE》一书中“Effective Troubleshooting”一章把故障排查描述为一个循环：提出关于原因的假设，然后验证它。日志就是验证假设的地方，而不是一本要从第一行读起的小说。

同一章称分而治之是一种非常有用的通用解题技巧。在多阶段管道里，你要问：记录在哪个阶段还在，在哪个阶段消失了？每个答案都能把可疑范围砍掉一半。

在 Twenty 的客户现场，FDE 用 LGTM 技术栈（Grafana、Loki、Tempo 和 Mimir）监控平台健康状况和数据流。如果你的现场有类似工具，就用起来：用指标缩小时间窗口，用链路追踪跟踪一个请求跨服务的路径，用日志查看故障点的具体细节。

## 一个完整示例

回到那条丢记录的管道。以下是一个假设场景，用来演示方法。指标显示，进入 parse 阶段的记录数等于离开 ingest 阶段的记录数，但离开 parse 阶段的记录变少了。可疑范围缩小到了一个阶段。

第一个假设：parse 服务中途重启过。你按那个时间段过滤日志，没有发现重启。假设被否定，你把这一点记下来。SRE 一书强调，不应忽视或轻视否定结果，因为它们能告诉下一个人不必再走同一条路。

第二个假设：部分记录有空字段。你在现场查看了几条被丢弃的记录，不往外复制，发现它们有一个共同点：`quantity` 字段是空字符串，而不是数字。你只记录数据的形态，不记录真实值。

直到这时才开始写复现。scikit-learn 文档建议，最小复现应依赖代码在运行时生成的小数据集，而不是外部数据。文档还指出，大多数 bug 并不依赖真实数据的特定结构，因此合成数据通常就够了。

```python
import json
from ingest.parse import parse_event  # 团队代码仓库中的模块

# 合成数据：只保留形态，不含客户的任何真实值
rows = [
    {"id": "r1", "quantity": "3", "ts": "2026-01-01T00:00:00Z"},
    {"id": "r2", "quantity": "",  "ts": "2026-01-01T00:00:01Z"},
]

for r in rows:
    print(r["id"], parse_event(json.dumps(r)))
# 预期：两条都返回事件
# 实际（假设场景）：r2 返回 None，且没有记录任何错误
```

注意删掉了什么：没有队列连接，没有重试配置，没有读文件。按 scikit-learn 的说法，删除无关代码、去掉非默认选项，能帮你和他人缩小原因范围。删掉一行后 bug 依然存在，说明那一行不是元凶。

## 发送证据，而不是转发告警

向总部团队升级问题时，你要带去的是对发现的清晰描述，而不只是触发告警的那件事。因此，一份好的升级说明和一句“系统坏了，谁来看看”在结构上截然不同。

最关键的是复现文件。scikit-learn 指出，用文字描述的复现步骤往往含糊不清。一段接收方复制、粘贴就能立刻看到失败的代码，能省去许多来回沟通；SRE 一书同样指出，可靠的复现测试用例能让调试快得多。

**要点:** 目标不是把客户的数据带回来，而是把 bug 的形态带回来。

## 你自己的代码也必须能远程调试

问题也有反方向。你为客户现场写的代码，必须能让无法进入运行环境的工程师测试、调试和维护，Twenty 的职位描述把这一点列为要求。上面的例子里，bug 之所以难找，正是因为 `parse_event` 返回了 `None`，却连一行日志都没留下。

写代码时问问自己：如果这个函数失败，日志能否告诉远方的人它在哪条记录上失败、为什么失败？一行记录了记录 ID 和出问题字段名、不含任何敏感值的日志，就能省下一整个下午的排查。

## 常见错误

最常见的错误是相信预发布环境。bug 在 staging 上没出现，并不代表它不存在；很可能只是 staging 的数据缺少触发它的那种形态。

第二个错误是忘记已排除的假设。如果你没记下自己查过重启，总部的同事就会浪费时间再查一遍。

第三个错误是复现太大：把生产配置拖进来，读取别人没有的样本文件，更糟的是包含真实数据。如果接收方不能立刻在自己机器上运行这个文件，这份复现就没有完成任务。

## 求职时如何展示这项技能

如果你是想转做 FDE 的开发者，留意职位描述里的“on-site”“air-gapped”“cleared environment”等字眼，或对可观测性技术栈的要求。它们说明这个岗位需要的正是这项技能。

简历上不要只写“调试过生产问题”。描述一次你用日志或链路追踪缩小 bug 范围、用合成数据重建它、再交给另一个团队修复的经历。如果可以，附上你曾在 GitHub 开源项目 issue 中提交过的复现链接，让招聘经理亲眼看到。

好的 FDE 不是权限最大的人，而是走出客户机房时手里只有几行代码的人，而这几行代码足以让整个团队看到一个他们永远碰不到的 bug。

**本周动手试试:**

- 从项目里挑一个旧 bug，把它改写成不超过 20 行的复现文件：数据在代码中生成，不读取任何外部文件。
- 写一份示例升级说明，分三部分：你看到了什么、排除了哪些假设、运行复现的命令。请一位同事只凭这份说明复现 bug。
- 打开 Grafana 或你常用的日志工具，练习写查询：按单个请求 ID 过滤，以及按 bug 发生前后的狭窄时间窗口过滤。

## 信源

- [Senior/Staff Forward Deployed Software Engineer (Twenty)](https://jobs.generalcatalyst.com/companies/twenty-2-e7100602-0ba9-4628-a9c6-e2074bdb23ce/jobs/88352989-senior-staff-forward-deployed-software-engineer-ts-sci-cleared)

- [Debugging Without a Net: The Pain of Reproducing Production Issues](https://speedscale.com/blog/debugging-without-a-net-the-pain-of-reproducing-production-issues/)

- [Effective Troubleshooting (Google SRE Book, Chapter 12)](https://sre.google/sre-book/effective-troubleshooting/)

- [Crafting a Minimal Reproducer for scikit-learn](https://scikit-learn.org/1.2/_sources/developers/minimal_reproducer.rst.txt)
