Checkout服務金絲雀發行

1）為什麼需要操作文檔

• 將口頭知識轉化為可重復的程序；
• 指定責任界限和升級點；
• 作為合規和安全證據的來源；
• 加快爬山速度，降低「狹窄頸部」的風險。

2）文件分類法（什麼）

政策（政策）：意圖和框架（「什麼以及為什麼」）。示例：事件管理政策。
標準（標準）：強制性最低要求（「多少」）。示例：TLS證書的更新時間。
SOP/Procedure（標準操作程序）：連續步驟（「as」）。示例：發行帶有金絲雀拆分的版本。

Runbook： 用於典型事件（Alert/Operation）的分步說明。示例：「5xx API成長為動作算法。」

劇本：一組具有變體和叉子的腳本解決方案。示例：「支付提供商的問題」。
KB（知識庫）：答案,常見問題,工具說明。
Checklist：操作前必備項目的簡要列表。
記錄/事件：執行步驟的日誌、截圖/記錄/簽名。

3）良好的文檔原則

單一真相來源（SSOT）。文件沒有重復；噴灑意味著過時。
Docs-as-Code.我們存儲在Git中，通過代碼評論，版本和誹謗-可見。
Actionable-first.一開始是一張簡短的卡片：何時運行，誰是所有者，該怎麼做，完成標準。
原子性和目標性。一個文檔是一個任務/過程。
可更新性。更新的明確所有者和SLA（例如季度）。
可觀察性。嵌入了對dashbords/alerta/度量的引用。
按設計安全。敏感性分類，掩蓋秘密，訪問控制。

4）文檔生命周期（政府）

1.啟動：申請/提要→文件類型→所有者。
2.草稿：模板、最少示例、標準參考和SLO。
3.評論：技術（SRE/平臺/安全），程序（流程經理）。
4.發布：在主分支中，標記版本/日期，狀態分配（active/experimental/deprecated）。
5.培訓/溝通：更改公告，短期培訓/演示。
6.回顧：根據事件/演習的結果進行編輯。
7.審核和歸檔：歸檔中舊版的不可變足跡（誰/何時更改）。

5） SOP/Runbook結構（最低限度）

1.卡：名稱,ID,版本/日期,所有者,負責角色,相關政策/標準。
2.何時應用：啟動條件（Alert/事件/工作窗口）。
3.準備：權利/工具/數據，風險評估，通信。
4.步驟：編號，帶有命令/屏幕截圖/預期結果。
5.成功/回滾標準：明確的SLI/SLO閾值。
6.升級：誰，何時以及如何（頻道，電話，提供商）。
7.安全/合規性：敏感數據，禁令，活動記錄。
8.後期行動：關閉滴答聲，更新狀態，收集證據。
9.更改歷史（changelog）。

6）設計風格和規則

清晰而簡短：1個步驟-1個動作-1個結果。
當務之急：「執行……」，「檢查……」，「滾動……」。
截圖/命令：靠近步驟；命令-可復制的塊；預期的輸出。

變異性： 「如果A →步驟X，如果B →步驟Y。」

隊列：在哪裏-指定區域/提供者/tenant。
本地化：關鍵文件-至少2種語言；指定翻譯狀態。
標簽和搜索：服務,組件,提供商,事件類型,SLO,版本。

7） Docs-as-Code和工具

存儲：git（主要/壯舉/bugfix），公關評論，要求檢查。
格式：Markdown/AsciiDoc；PlantUML/美人魚圖表；JSON/YAML方案。
發布：靜態站點（Docusaurus/MkDocs）+搜索。
驗證：CI-lint，參考測試，拼寫，代碼塊驗證器。
集成：ChatOps命令「/runbook open X」，在警報中顯示最新版本。
鏈接：CMDB/服務目錄 ↔文檔↔儀表板。

8）訪問控制和分類

Классы: Public / Internal / Confidential / Restricted.

分離：公共指令（共享狀態）vs私人（密鑰、命令、網絡圖表）。
秘密：禁止在文本中；使用秘密存儲和播放器。
審計：敏感SOP的閱讀/更改日誌。

9）與事件和發布的通信

在每個警報中，都引用了相關的運行手冊。
在每個事件中，都引用了使用的SOP和標記檢查。
RCA之後-將文檔更新為CAPA操作。
發行前-checklist：回滾準備、降級標誌、提供商聯系人。

10）最低強制性套裝（MVP基座套件）

事件管理和升級政策（SEV/P級別，時間）。
監控標準和警報策略（burn rate，法定人數）。
SOP：釋放/回滾（金絲雀/藍綠色），DB遷移（expand/contract）。
運行手冊：「高錯誤率」，「增長p99」，「支付成功率下降」，「TLS/DNS問題」。
外部提供商的劇本（付款/KYC/CDN）：聯系人，限制，後衛。
秘密和訪問管理策略。
RCA和Post-mortem模板。
服務所有者表（RACI）和行車記錄卡。

11）文檔質量指標（SLO文檔）

Coverage：使用SOP/Runbook的關鍵路徑的百分比。
Freshness：文檔比例為新鮮的N天（例如90）。
可用性：根據運行手冊關閉的事件百分比沒有升級。
Findability：搜索所需文檔的時間中位數（按調查/邏輯）。
Defect rate： 評論數/100份文件。
Adoption：正確引用運行簿的Alert分數。
合規性事件率：所附證據的任務百分比。

12）支票單

SOP創建支票清單

• 已確定所有者和目標受眾。
• 有發射條件和停止標準。
• 步驟可以復制,由其他工程師驗證。
• 嵌入了指向dashbords/alerta/工具的鏈接。
• 沒有秘密；有播放器並鏈接到vault。
• 描述了回滾和升級。
• 添加了「行動後」支票單。
• 版本、日期、changelog。

Review的支票清單

• 該文檔對應於分類法（不混合政策和步驟）。
• 語言簡單，強制性，沒有歧義。
• 在「幹運行「/stadge中測試團隊。
• 指明了風險和控制點。
• 可用性（內部/限制）是正確的。
• 在CI中通過了林特/驗證器。

13）本地化、版本和可用性

版本：'MAJOR。MINOR.PATCH',MAJOR打破了流程兼容性。
語言：標記「源」語言和翻譯狀態（up-to-date/needs review）。
外形規格：手機/夜間通話顯示、IC打印卡。

14） Doc自動化（來自實踐）

從CLI模板生成SOP框架（「doc new sop -service=payments」）。
按服務標簽自動插入指向最新行車記錄的鏈接。
過期文件提醒機器人（freshness SLA）。
在一段時間內導出Evidence軟件包（PDF/ZIP）進行審核。
將事件字幕與解決方案中使用的文檔版本關聯。

15）安全和合規性

強制性部分「風險」和「控制措施」。
將事件存儲在帶有簽名/哈希的不變檔案中。
綁定到法規遵從性（例如,通知/撤銷時間）、顯式合規性所有者。

16）反模式

「Vicky迷宮」沒有所有者和更新日期。
與團隊混合的政客-沒有人會發現要執行什麼。
沒有上下文的文檔（沒有SLO，dashbords，升級）。
帶有秘密的屏幕截圖或「單擊此處」指令，沒有CLI替代方案。
「一位大師知道如何」是部落知識，沒有固定。
存檔PDF作為唯一的版本-不編輯，不搜索。

17）模板（片段）

SOP帽子（示例）

SOP-ID: OPS-REL-001

18）嵌入日常工作

每周文件圈：審查1-2份文件、主流化、交流經驗。
遊戲日：模擬中的SOP/Runbook現實檢查。
Onbording：新手路線通過一組強制性文檔+短量表。
碼頭債務：優先級改進的逆向（impact × effort）。

19）結果

操作文檔不是存檔,而是工作工具。當它作為代碼進行維護時，擁有所有者，新鮮度度量標準並嵌入事件，發布和培訓中，組織變得可預測：錯誤更少，反應更快，可以理解的責任和審計準備。簡短地寫作，定期更新，自動化例程-文檔將開始節省時間和金錢。