一 · 数据源接入
把 API、数据库、CSV、爬虫切成可计价的工具，这一步最容易埋雷。
01采集器没关 gzip，对方一开压缩解析就炸
- 当时
- 采集对方接口时拿到的是 gzip 字节流，直接当文本解析，报一堆乱码错。
- 怎么解决
- 采集层固定发
Accept-Encoding: identity，不依赖对方默认行为；加超时与重试。
02从 0 扫链上日志，必失败
- 当时
- 链上数据从创世块开始扫，跑到超时也没结果。
- 怎么解决
- 从链头回退固定块数做增量扫描，游标落库，重跑可续。
03402 响应头发了，浏览器里读不到
- 当时
- 抓包能看到 payment 相关响应头，前端 JS 里却是 undefined。
- 怎么解决
- 自定义响应头必须显式加进
Access-Control-Expose-Headers，否则浏览器按安全策略屏蔽。
04金额单位写错，被 facilitator 直接拒
- 当时
- 0.01 USDC 写成 1e16，facilitator 只回「amount mismatch」，看不出是单位问题。
- 怎么解决
- USDC 是 6 位小数：0.01 = 10000。生成价格时统一走换算函数，不手写。
二 · 上线与路由
语法检查通过，不代表网站能打开——这一节的坑全在语法之外。
05nginx -t 全绿，站点因重定向死循环打不开
- 当时
- 精确 location 的 301 与 try_files 的内部重定向互相套娃，浏览器报「重定向次数过多」。
- 怎么解决
- 改动后必须真发请求看状态码和跳数，用
--max-redirs 限流验证，不只看语法。
06后台地址 301 → 带斜杠 → 403 白屏
- 当时
/admin 被 301 到 /admin/，那是真实目录且没有 index 文件，直接 403；只有 /admin.html 能进。- 怎么解决
- 内部 rewrite 直达文件：
rewrite ^/admin/?$ /admin.html last;，登录保护一层不变。
07location 里用 if 做正则判断，覆盖了捕获组
- 当时
- 干净 URL 规则里加 if 正则判断后，
$1 被重置，/pricing.html 被 301 到了首页。
- 怎么解决
- 把 if 判断移出该 location，或改用 map；location 内不要混用 if 与捕获组。
08MCP 端点反代被缓冲，SSE 卡死
- 当时
- streamable-http 走 SSE，nginx 默认缓冲把流卡住，客户端一直等不到响应。
- 怎么解决
proxy_buffering off; + proxy_cache off; + 拉长 proxy_read_timeout。
三 · 缓存与版本
最阴的一类：服务器一直正常，页面一直报错。
09改完 CSS / JS，线上「看起来没生效」（连踩三次）
- 当时
- nginx 给静态资源设了
expires 7d，页面引用又没有版本号。
- 怎么解决
- 设长缓存就必须配版本戳，改一次资源升一次版本号，写进发布清单。
10服务器日志全 200，页面却报「数据读不到」
- 当时
- 浏览器跑着被缓存七天的旧脚本，渲染新数据格式时崩溃，而 catch 统一报成「服务器读不到」。
- 怎么解决
- 后台脚本单独 no-cache；取数与渲染分成两个 try；彻底失败用 localStorage 兜底。
11有的页面新、有的页面旧
- 当时
- 同一个 CSS 被多个页面引用，只改了其中几个的版本号。
- 怎么解决
- 全站搜该资源名批量升版本，不要手工挑页面改。
12报错文案把你带偏方向
- 当时
- 渲染崩溃、网络失败、密钥失效、超时全被一个 catch 报成同一句，服务端查了两天。
- 怎么解决
- 四种失败报四种话；401/403 不重试直接提示重登；失败先显示缓存数据。
四 · 监控与运维
定时任务和探活脚本，写错了会安静地毁掉数据。
13手工改的 876 个页面被定时任务一次全覆盖
- 当时
- 静态生成站靠 cron 重生成，手改产物必然被冲掉。
- 怎么解决
- 只改生成器模板 → 重新生成 → 发布；加守护脚本盯产物 mtime。
14用 JSON 客户端探 MCP 端点，SSE 被判成「已死亡」
- 当时
- 探活脚本解析响应体，MCP 返回的是 SSE 流，解析失败就判死。
- 怎么解决
- 只按 HTTP 状态码判定，200 与 402 都算活，绝不解析响应体。
15探活字段名抄错，全部条目恒判「波动」
- 当时
- 写
p.ok 而实际字段是 p.lastOk，判定逻辑永远走异常分支。
- 怎么解决
- 字段名对着写库代码核，不要凭记忆；上线前用两条已知数据验证判定逻辑。
16按天汇总用增量累加，PV 一天翻一倍
- 当时
- 「昨天的值 + 今天的增量」，重跑一次就翻倍。
- 怎么解决
- 按天重算覆盖，保证幂等；时间字符串化必须放在所有聚合之后。
五 · GEO 与可引用
AI 看不到你，再好的数据也卖不出去。
17默认 robots.txt 把 AI 爬虫全 block，GEO 直接归零
- 当时
- 用了框架默认模板，主流 AI 爬虫被拦在门外。
- 怎么解决
- 逐条显式放行 40+ AI 爬虫，并单独 Disallow 后台等私有路径。
18llms.txt 写成营销文案，AI 一律不引用
- 当时
- 把介绍和形容词写进去，AI 无法核验，等于没写。
- 怎么解决
- 只写可核验事实：价格、网络、端点、绝对路径、明确的结算规则。
19外部 AI 提到了你，但把规则说错了
- 当时
- AI 把抽成说成 15%、结算说成 T+7，而「提及率」指标是绿的。
- 怎么解决
- 监测必须单列「口径正确率」——提到了但说错了，等于没提到。
六 · 定价与结算
钱的事，错一次就很难挽回信任。
20定价太低，一年都够不到起结门槛
- 当时
- 单次价定太低，月流水过不了 $50 起结线，钱一直挂在账上。
- 怎么解决
- 上架前先算：调用量 × 单价 × 分成，倒推最低可行定价，再看回本周期。
21运行时改数据文件，被内存里的旧值覆盖回去
- 当时
- 服务运行中直接改数据文件，重启前旧值又被写回。
- 怎么解决
- 改数据前先停服务；对账只认链上 Transfer 事件，容差 ±$0.02。
22免费额度按 IP 限流，对分布式 Agent 完全无效
- 当时
- Agent 每次来源 IP 都不同，按 IP 限等于不限。
- 怎么解决
- 额度绑 Agent / 密钥维度，加单日熔断；把免费额度当获客成本算 ROI。
这 22 条，我们做成了 20 个免费工具
每一条坑下面挂的工具都是免费的、不用登录、输入内容只在你的浏览器里计算。自己能跑通就用工具；跑不通的时候，我们代上架、代推广、代结算。