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