狀態頁搭建指南：給 AI 服務拆元件、定等級、寫事故更新
狀態頁搭建的難點不在選哪個工具，而在先想清楚四件事：頁面上列哪些元件，每個元件的狀態由誰判定，幾個等級各自代表什麼，出了事故每次更新寫什麼。對 AI API 服務來說，元件最好按“接入閘道器 + 各模型組 + 控制檯”來拆，狀態由自動探測和真實請求統計共同給出，人工只負責確認和寫說明。下面按這個順序講，文末附上線前檢查表。
文中拿 cdnping 自己的 API 狀態頁 和 AGI Plan 狀態頁 做參照。AGI Plan 是 cdnping 的商業合作方，這兩個頁面的做法和缺點我們都比較清楚。
狀態頁到底要回答使用者什麼問題？
使用者開啟狀態頁，通常只想知道三件事：
- 我現在遇到的問題，是不是你們那邊的？
- 如果是，影響哪部分，你們知道了沒有，大概什麼時候好？
- 過去一段時間你們穩不穩？
所以狀態頁不是監控大盤，不需要把 CPU、佇列長度這類內部指標搬上去，只需要給出使用者能對照自己情況的結論。使用者一般怎麼讀狀態頁，可以先看怎麼看 OpenAI 狀態頁和 Claude 狀態頁。
元件怎麼拆才對 AI 服務有用？
拆元件的原則是：使用者能分辨出的故障邊界，就是元件邊界。使用者分不出“鑑權服務”和“計費服務”的區別，但分得出“控制檯登不上”和“介面報 5xx”。
一個典型的 AI API 服務可以這樣拆：
| 元件 | 使用者看到的現象 | 主要資料來源 |
|---|---|---|
| API 接入閘道器 | 連不上、TLS 失敗、所有請求都報錯 | 外部探測 |
| 各模型組（例如推理組、通用組、輕量組） | 某一類模型報錯多、變慢，其他正常 | 真實請求成功率 |
| 控制檯與登入 | 網頁打不開、登不上、建不了金鑰 | 外部探測 + 人工 |
| 計費與額度 | 扣費異常、額度顯示不對 | 人工釋出 |
| 文件與官網 | 頁面打不開 | 外部探測 |
| 上游依賴（只展示，不計入自家可用率） | 上游廠商有事故 | 同步上游官方狀態頁 |
模型組為什麼要單獨拆，資料能說明。以 AGI Plan 為例，cdnping 在 2026 年 10 月 17 日的快照裡，從 Cloudflare 邊緣（丹佛節點）探測 agiplan.dev 入口，可用率欄位為 100%（採集當天才開始，實際只覆蓋約一個半小時）；同一份快照裡，AGI Plan 公開的按真實請求計算的可用率，最近 1 天“快速組”約為 77.3%，“均衡組”為 100%，“前沿模型組”約為 99.8%。入口能通，不代表每一組模型都能用。如果狀態頁只放一個“API”元件，這種情況下它會一直是綠色。
上游依賴建議單獨成區，標明“第三方”，不計入自己的可用率。
狀態資料從哪來：自動探測、真實請求還是人工釋出？
三種來源各有盲區，單用哪一種都不夠。
| 來源 | 能發現什麼 | 發現不了什麼 | 適合驅動 |
|---|---|---|---|
| 外部定時探測 | 入口不可達、DNS/TLS 問題、整體變慢 | 只有部分模型或部分請求失敗 | 閘道器、控制檯、文件 |
| 真實請求統計 | 按組的成功率、錯誤碼分佈 | 沒有流量的時段（夜裡請求很少，比例不可靠） | 各模型組 |
| 人工釋出 | 計費錯誤、資料問題、計劃維護 | 反應慢，依賴值班人員 | 事故說明、維護公告 |
探測和真實請求統計的區別，可以參考合成監控和真實使用者監控有什麼區別。
cdnping 的 /status 用的是前兩種加上游同步：從 Cloudflare 邊緣每 5 分鐘探測各家官方 API 入口，每 15 分鐘同步 OpenAI、Anthropic、Moonshot、Groq、Cloudflare、GitHub、Cursor 的官方狀態頁，保留 30 天曆史。具體口徑寫在資料方法裡。
探測資料會把真實情況放大或縮小，口徑要寫清楚。舉一個例子：cdnping 在 2026-10-17 北京時間 16:40 到 18:05 之間，從丹佛（DEN）節點共做了 242 次探測，這一視窗裡 Kimi 開放平臺的可用率欄位是 94.4%，p95 延遲 1125 ms，其餘入口都是 100%。視窗只有一個半小時、只有一個節點，這個數字說明“這段時間從這個位置探測到過失敗”，不能拿來評價長期穩定性。狀態頁上展示自己的數字時，同樣要標明視窗和探測位置。
真實請求統計要注意分母。AGI Plan 的公開口徑是“成功 /（成功 + 因平臺自身原因失敗）”，只有 5xx 算平臺失敗，使用者的 401、429 不算。這個口徑你可以不同意，但一定要寫出來。夜裡每小時只有幾個請求時，一次失敗就能讓比例掉一大截，可以設一個最低請求數，低於它就顯示“資料不足”而不是紅色。怎麼自己測、怎麼定口徑，可以看自己測 AI API 的可用率。
一個最小探測怎麼寫？
假設你的介面是 https://api.example.com，下面這條命令可以放進任意定時任務，每次輸出狀態碼、連線耗時和總耗時：
curl -s -o /dev/null --max-time 10 \
-w '%{http_code} %{time_connect} %{time_appconnect} %{time_total}\n' \
https://api.example.com/v1/models
判斷規則可以先這樣定：拿不到狀態碼（超時、DNS 失敗、TLS 失敗）記為失敗；5xx 記為失敗；不帶金鑰返回 401 說明閘道器在正常工作，記為成功。探測點至少放兩個不同地區，只有兩個點同時失敗才判定為“入口故障”，避免把單個探測點的網路問題算到自己頭上。更完整的探測和告警清單見AI 應用可用性監控怎麼做。
狀態等級怎麼定義？
等級越少越好用。建議四級加一個維護狀態，並且把閾值寫在頁面上：
| 等級 | 頁面文案 | 示例閾值（按 5 分鐘視窗，需按自己的情況調整） |
|---|---|---|
| 正常 | 執行正常 | 成功率 ≥ 99%，p95 延遲在基線 2 倍以內 |
| 效能下降 | 部分請求變慢 | 成功率 ≥ 99%，但 p95 延遲超過基線 2 倍 |
| 部分中斷 | 部分請求失敗 | 成功率在 90% 到 99% 之間，或某個模型組不可用 |
| 嚴重中斷 | 大部分請求失敗 | 成功率低於 90%，或入口不可達 |
| 維護中 | 計劃維護 | 提前公告的維護視窗 |
幾點經驗：
- 自動判定只負責調高等級；降回正常要人工確認或連續幾個視窗恢復，避免頁面黃綠來回跳。
- 各家給事故定的級別差異很大，不要拿別人的分佈當標準。cdnping 同步的官方狀態頁裡，2026-09-17 到 2026-10-17 這一個月，OpenAI 登記了 major 4 次、minor 19 次，Cloudflare 登記了 major 3 次、minor 19 次。大部分事故都標為 minor，標準由各家自己定。
- 可用率目標和等級閾值要對得上。目標和錯誤預算的演算法見SLI、SLO、SLA 到底差在哪。
事故更新每一段該寫什麼？
事故公告常見四個階段：調查中、已定位、觀察中、已恢復。每一段都要回答固定的問題：
| 階段 | 必須寫 | 不要寫 |
|---|---|---|
| 調查中 | 現象、受影響元件、開始時間、下次更新時間 | 未經確認的原因 |
| 已定位 | 原因的大類（上游、配置變更、容量）、正在做什麼 | 甩鍋給某個具體廠商的措辭 |
| 觀察中 | 已採取的措施、指標是否恢復、使用者需不需要操作 | “已完全修復”這類還沒驗證的結論 |
| 已恢復 | 影響時段（起止時間帶時區）、影響範圍、後續改進 | 空泛的致歉段落 |
標題寫“現象 + 範圍”。官方狀態頁裡的標題大多是這個結構，例如 cdnping 同步到的幾條：
- Increased HTTP 502 Errors（Cloudflare，minor，持續 591 分鐘）
- Network Performance Issues in London（Cloudflare，major，持續 13 分鐘）
- Elevated Errors in China Network Colos（Cloudflare，minor）
- Widespread feature degradation（OpenAI，major，持續 146 分鐘）
前三條一眼能看出影響和位置，最後一條範圍較寬，需要點進去看元件。中文模板如下：
【部分中斷】輕量模型組請求失敗率升高
開始時間：2026-10-16 14:05（北京時間）
影響：輕量模型組約一半請求返回 5xx，其他模型組和控制檯正常。
當前進展：已定位為上游供應商錯誤率升高，正在將流量切換到備用供應商。
使用者需要做什麼：無需修改配置；如有重試邏輯，建議使用指數退避。
下次更新：30 分鐘內。
模板裡的時間和比例是示例。AGI Plan 的公開資料裡確實能看到類似的小時：cdnping 映象的快照中，10 月 16 日北京時間 14 時起連續兩個小時桶，失敗請求分別是 722 和 877 次，多於同一小時的成功數（664 和 455）。像這樣的小時，狀態頁上應該有對應的事故記錄，否則使用者會覺得頁面沒有反映實際情況。
另外兩條規則：每次更新都寫“下次更新時間”，到點沒進展也要發一條“仍在處理”；已恢復的事故不要改寫前面的更新，保留原文，補充說明即可。
歷史保留多久？要不要提供 RSS 和 JSON？
歷史建議至少保留 30 天，足夠覆蓋“最近一個月穩不穩”這個最常見的問題；條件允許可以更長。cdnping 的 /status 目前保留 30 天，而且採集從 2026-10-17 才開始，歷史還很短，頁面上會如實標出。
機器可讀的出口建議都給：
- JSON：給使用者的監控系統和機器人用。cdnping 的開放資料介面
/api/status以 CC BY 4.0 釋出；AGI Plan 在https://agiplan.dev/api/status/requests?month=YYYY-MM提供逐小時、逐能力組的成功和失敗計數，不需要登入。 - RSS / Atom：給只想訂閱事故公告的人用，每次事故更新生成一條。
- Webhook 或郵件訂閱：使用者量大以後再加。
JSON 的欄位可以參考下面這個結構（示例，不是某個現有介面的定義）：
{
"updated": "2026-10-23T12:00:00Z",
"components": [
{"id": "gateway", "status": "operational", "uptime_30d": 0.999},
{"id": "group-fast", "status": "partial_outage", "uptime_30d": 0.98}
],
"incidents": [
{"id": "inc-001", "title": "輕量模型組請求失敗率升高",
"impact": "minor", "started": "2026-10-16T06:05:00Z", "resolved": null}
]
}
欄位一旦公開就儘量別改名，下游會有人寫死解析。
用什麼搭：需不需要伺服器？
開源和託管方案很多，這裡不排名，只按部署方式分三類，選哪類取決於你願意維護什麼：
| 型別 | 做法 | 適合 | 要注意 |
|---|---|---|---|
| 無伺服器 | 用 CI 定時任務或邊緣定時任務做探測，結果寫進倉庫或物件儲存，生成靜態頁 | 小團隊、元件少 | 探測頻率受定時任務限制，探測位置單一 |
| 自託管程式 | 常駐服務 + 資料庫，自帶後臺和事故編輯 | 需要人工釋出、訂閱通知 | 狀態頁要和主服務分開部署，否則主服務掛了它也一起掛 |
| 託管服務 | 第三方託管頁面和訂閱 | 不想維護 | 資料口徑受平臺限制，接入自家請求統計要自己推送 |
不管哪一類，有一條要堅持：狀態頁和被監控的服務不要共用同一套基礎設施，包括域名解析、CDN 和資料庫。如果你的主站在 Cloudflare 上，狀態頁可以放在另一家託管，反過來也一樣。2026 年 10 月中旬 Cloudflare 自己的狀態頁就登記過 Workers 定時觸發器（Cron Triggers）和 Durable Objects 的故障，探測程式如果跑在這些元件上，那幾天就可能缺資料。
上線前檢查表
- 元件按使用者能分辨的故障邊界拆分，模型組單獨列出
- 每個元件寫明資料來源：探測、請求統計還是人工
- 探測點至少兩個地區，單點失敗不直接判紅
- 請求統計設了最低請求數，樣本不足時顯示“資料不足”
- 等級閾值和可用率口徑寫在頁面或方法說明裡
- 事故模板包含現象、範圍、開始時間（帶時區）、使用者需要做什麼、下次更新時間
- 上游依賴單獨成區，不計入自家可用率
- 歷史至少 30 天，並標明採集起始日期
- 提供 JSON 和 RSS，欄位名寫進文件
- 狀態頁與主服務的 DNS、CDN、資料庫分開
- 演練一次：手動製造一個元件故障，看頁面多久變色、公告多久發出
最後一項最容易跳過，也最能暴露問題。上線後可以用 /down 這類綜合官方狀態、API 探測和使用者報告的頁面對照自己的狀態頁，看兩邊的判斷是否一致；想了解過去一段時間各家官方狀態頁實際登記了什麼，可以看 2026 年 9–10 月 AI 服務故障盤點。
