网站部署成功、海外监控返回正常，并不能说明中国大陆用户始终能够连接。新域名启用后需要建立第一份检测记录；上线后的 DNS、HTTP 和 TLS 相关网络状态也可能发生变化。把 GFW 检测纳入发布流程和日常监控，目的不是得到一个永久有效的“未被墙”标签，而是及时发现变化，让负责人知道该检查哪个目标、哪个网络和哪个环节。
如果还没有用过 WeaveBit，先通过免费 DNS 污染检测检查一个域名，了解公开结果及其边界。批量、持续或程序化检测应使用 Console 或正式 API，不应自动化操作免费网页及其人机验证。本篇围绕自有运维系统的 API 集成展开；首次检测的步骤见GFW 检测入门指南。
网站上线后，哪些时刻值得自动检测？
建议区分两类触发。第一类是事件触发：新域名投入使用、一次网站发布完成，或运维人员希望复查已知问题。把检测记录与发布编号关联，可以回看某次变化前后的观测。第二类是定时触发：上线后按计划执行，帮助发现发布窗口之外出现的异常。
部署触发的一次检测不会自动变成全天候监控。定时任务需要由 Console 或你自己的调度程序安排；也不要因为部署脚本退出成功，就认为后续检测已经完成。若要把结果作为发布门禁，是否阻止上线、等待多久、何时转人工复核，都应是团队明确制定的策略，不能把“暂时无法判定”自动解释为通过。
使用 Console 报警，还是自行接入 API？
| 需求 | 适合的方式 | 由谁负责调度和通知 |
|---|---|---|
| 希望直接设置定时检测和联系人，不维护监控程序 | Console 监控任务 | 使用平台提供的任务与通知配置，按当前界面设置 |
| 希望关联发布编号、保存自有历史，接入已有值班系统 | API v2 检测批次 | 调用方负责触发、查询、保存、报警规则和通知投递 |
API 创建成功只表示批次已受理，不会自动创建 Console 定时任务，也不会自动发出 Console 报警。如果需要平台安排执行和通知，按照开始使用配置 Console；如果选择 API 路线，下面的调度和通知流程需要部署在自己的系统中。
先确定域名清单、检测方式和预算
按业务用途整理主站、登录、API 和关键资源域名，例如 www.example.com、login.example.com 和 api.example.com。这些是说明用域名，不是真实客户案例。仅检查主站，不能代表登录和接口依赖也正常；同样，不必为了“全面”把无关目标反复加入每轮任务。
如果只需要持续观察 DNS 污染，使用 dns_pollution_check，请求不传 nodes。需要同时观察 DNS 污染、HTTP Host 和 TLS SNI 三个维度时，使用 gfw_full_domain_check，并选择与实际用户地区、运营商相关的当前可用节点。“全量”不是全部七种检测，也不是完整浏览器加载。
执行频率、目标数量和节点范围共同影响成本与覆盖。可以按业务重要程度分组，但不应把某个示例频率当成所有网站的标准。通过 /task/get_nodes获取节点，再使用实际请求参数调用 /task/estimate审核费用；价格与可用余额以当次响应为准。比较连续结果时，应保持域名、方法、端口和节点组合一致，配置变化要单独记录。
把一次调用组织成可恢复的检测轮次
- 建立本轮记录。保存业务任务标识、触发原因和检测配置，为这次逻辑创建生成并持久化一个
Idempotency-Key。下一次计划检测是新轮次；本轮创建重试仍使用原标识和原请求体。 - 预估后创建。审核费用与余额，再调用
/task/create。创建可能产生费用。网络超时、无法确定是否受理时，不要换一个新标识盲目再创建。 - 保存批次再查询。取得
batch_id后先持久化，再调用/task/result。进程重启后应恢复查询原批次，而不是重新购买一轮检测。 - 有限等待并读完分页。对
pending或running使用有上限的查询与退避。一次脚本运行的等待预算耗尽，可以保留状态后稍后继续；不能无限循环，也不能通过重复创建催促结果。 - 保存结果，再交给报警流程。批次
completed只表示执行生命周期结束，其中仍可能存在无法判定项。先按目标和节点保存原始结果、判定与时间，再决定通知或复核动作。
查询接口本身不会创建新检测，轮询次数也不是异常次数。同一批次查询十次，仍是同一轮观测。若报警策略要求连续多轮异常，应按独立完成的轮次计数，并避免重复消费一个批次。
还要区分 execution_deadline_at 和 expires_at：前者是执行截止时间，后者是结果到期时间。按当前公开契约，批次最长执行六小时，目标与结果在创建后二十四小时到期清理，不是完成后再保留二十四小时。接入程序应在返回的到期时间之前保存需要的数据。参数和错误码详见API 文档，具体批量调用见批量检测教程。
让报警区分异常、证据不足和调用失败
DNS 污染检测读取公开的 result_code；GFW 全量检测读取各节点结果中的 overall_result，需要排障时再查看分项。不要把 HTTP 请求成功、API code=0、批次完成和检测正常混为一谈。
| 本轮情况 | 调用方可以采取的动作 | 不应采取的动作 |
|---|---|---|
明确异常，判定为 1 | 记录目标、节点和分项；按自定确认策略发出异常事件，必要时复查 | 仅凭一次结果宣称中国所有网络不可访问，或指定根因责任方 |
无法判定，值为 null，或缺少预期观测 | 保留证据不足状态，安排补查或人工复核 | 改成正常；将此前异常直接标记为恢复 |
| API 调用失败或执行程序出错 | 作为监控链路故障单独上报，检查认证、余额、限流或调度状态 | 把调用失败当成目标被墙，或长期静默忽略 |
| 原先异常，后续同配置得到可判读的正常结果 | 按自定恢复策略发出恢复事件，保留此前异常记录 | 仅凭没有收到新报警，就宣布恢复 |
异常确认次数、持续提醒间隔和恢复条件都是调用方的运维策略，不是本文替平台指定的默认值。按“目标、检测方式、节点或明确的覆盖集合”保存状态，避免拿一个地区的正常结果覆盖另一个地区的异常。若需要合并成域名级事件，应同时保留异常、正常、无法判定和未返回的观测数量。
通知投递也有自己的失败状态。生成了报警事件，不等于邮件或 Telegram 已经送达。接入自己的通知服务时，应保留待发送事件、确认投递结果并安排失败重试；持续提醒与恢复事件也需要按同一业务记录关联。更详细的判读边界见检测结果说明。
Python 示例：接通检测、记录与通知适配位置
下面的 Python 示例是教学参考，不是托管报警服务，也不是官方 SDK 的替代品。默认 dry-run 不访问网络、不执行真实检测；只有显式启用 --live 并配置自己的服务端密钥后，才会访问正式 API。真实创建可能计费。API Key 不应出现在网页、版本库、日志或通知正文中。
示例使用状态文件保留本轮请求与批次，避免重启后盲目创建；把需要交给通知系统的事件写为标准输出中的 JSON。输出 JSON 不代表已经发送邮件、Telegram 或其他消息。你需要连接自己的通知适配器；若希望直接使用平台通知，则应选择 Console 监控。不要把演示用本地状态文件原样当成多进程生产队列。
这份最小示例以整个配置中的目标清单为一个报警单元：任一明确异常会产生异常事件，恢复需要对应范围的观测全部正常。它保存原始目标与节点结果供进一步分析，不提供逐域名、逐节点的完整事件管理。若实际节点覆盖发生变化，程序保留原有异常并提示复核，不用新范围的正常结果清除旧异常。
下载 Python 教学示例与使用说明（ZIP）。配置文件用于描述目标和节点，--state 应使用网页不可访问的私有存储位置，--max-cost 用十进制金额设置本轮预算。预算参数是调用方保护措施，不是固定报价；运行前仍需检查实际预估。
下面是核心调用摘录，不能单独运行；所需函数、配置文件、离线测试和完整运行说明均在下载包中。金额仅为调用方预算示例，不代表检测价格。
# Workflow excerpt; download gfw_monitor.py for the complete runnable example.
# run() and the helpers below are defined in that file, not in the SDK.
body = validated_config(config)
with exclusive_state(state_directory):
event = run(body, state_directory, Api(server_side_key), Decimal("0.10"))
print(canonical(event))
# The caller's notification bridge must deliver and retry messages.
# An emitted JSON event is NOT a Telegram/email delivery receipt.
解压后，先在终端运行不联网的预览命令，检查生成的请求计划：
python3 gfw_monitor.py --config monitor-config.json --state ./private-monitor-state --max-cost 0.10默认配置演示 DNS 污染检测。需要 GFW 全量检测时，按包内说明修改检测方式和当前节点。确认目标、费用、状态目录和服务端密钥均已配置后，才添加 --live。发布流水线或调度器调用同一条命令即可触发或继续一轮检测；此处不会替你启用任何定时任务。
已完成轮次的事件会保存在本地结果文件中。标准输出或通知桥接失败时，可以按照包内说明用 --replay-events 离线重放；桥接程序应按稳定的 event_id 记录投递确认，并重试未确认事件，而不是重新创建检测。
运行前先阅读示例的参数和限制，在测试环境验证创建超时后的恢复、分页完整性、无法判定、异常转恢复以及通知失败。需要可复用客户端时，可参考官方轻量 SDK 与代码示例；示例策略和业务状态存储仍属于调用方。
生产运行前，逐项检查这些边界
- 费用：目标已去重，节点范围合理，创建前审核预估，并监控可用余额。不要把创建重试变成重复付费检测。
- 执行：调度器避免同一业务任务重叠；本轮查询尚未完成时，先恢复原批次。多进程环境使用可靠的锁、数据库和队列，而不是共享一个演示文件。
- 重试：设置连接与请求超时、总等待预算和有上限的退避；遇到限流遵守
Retry-After。结果已过期或幂等保留期已过时，先核对业务状态，不能自动当作安全重试。 - 报警：分别验证目标异常、无法判定、监控程序故障和通知失败的处理；确认负责人能收到消息，不只检查脚本退出码。
- 证据：保存时间、目标、节点、端口、分项与复查记录。收到异常后结合源站、CDN 和用户反馈排障；协议检测不能代替浏览器业务验证。
最稳妥的起点不是立刻建立复杂监控系统，而是先用免费 DNS 污染检测理解结果，再选择适合团队维护能力的路径：使用 Console 接收平台通知，或通过正式 API 把 GFW 检测纳入已有运维流程。