Files

OG T 6f7a4be2c7 docs: Sprint 5.1 資料安全護欄 — ADR-062/063 + 方案規範驗證

- ADR-062: Data Safety Guardrails (服務分級/Pre-flight/MultiSig)
- ADR-063: Service Registry IaC 設計規範
- Sprint 5.1 方案文件: 規範驗證通過，P1-P5 問題修正
  - P1: Playbook 存 Redis（非 SQL），M-001 改為 Pydantic model 修改
  - P2: velero_client.py 命名維持（與 signoz_client 慣例一致）
  - P3: docker-health-monitor 狀態釐清
  - P4/P5: DI setter + Deployment Verification 補充
- LOGBOOK: 當前焦點更新為 Sprint 5.1

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-04-08 16:07:12 +08:00

2.7 KiB

Raw Blame History

ADR-063 — Service Registry IaC 設計規範

狀態: 已批准 (首席架構師裁示 2026-04-08) 撰寫: Claude Sonnet 4.6 / 2026-04-08 Asia/Taipei 相關: ADR-062 (Data Safety Guardrails)

背景

ADR-062 決定使用靜態 YAML 儲存服務的 Stateful 分級（Q6 決策：IaC）。需要規範此 YAML 的設計原則、修改流程、以及與程式碼的整合方式。

設計原則

Infrastructure as Code：服務的 Stateful 屬性是架構本質，不允許在 Web UI 上隨意修改。所有變更必須透過 Git PR + 統帥審核。

檔案位置

ops/config/service-registry.yaml

此路徑在 service_registry.py 中以相對於 repo root 的方式計算：

Path(__file__).parents[5] / "ops" / "config" / "service-registry.yaml"

YAML 結構規範

services:
  - name: <service_name>           # 唯一識別，對應 container name / k8s service name
    display_name: <顯示名稱>
    host: <IP 或 "k3s">
    stateful_level: BLOCK | CRITICAL_HITL | STANDARD_HITL | AUTO
    reason: <說明為何此分級>        # 必填，記錄決策依據
    alert_only: true               # 僅 BLOCK 使用
    requires_pre_backup: false     # CRITICAL_HITL 使用
    restart_command: "docker start" # 特殊重啟命令（如 Prometheus/Grafana）
    containers: ["container-name"] # docker container 名稱（可多個）

backup_policies:
  velero_max_age_hours: 4
  emergency_backup_timeout: 600
  block_backup_on_high_io: true
  io_threshold_percent: 80

multisig:
  critical_required_votes: 2
  standard_required_votes: 1
  vote_expiry_minutes: 30

分級決策標準

分級	標準
`BLOCK`	有 PostgreSQL WAL / ClickHouse 列欄資料 / 重啟必然造成資料遺失或損壞
`CRITICAL_HITL`	有 Volume 掛載 / 重啟可能中斷活躍寫入 / AWOOOI 核心依賴
`STANDARD_HITL`	有 WAL 或狀態但可安全 `docker start`（非 restart）/ 監控基礎設施
`AUTO`	無狀態 / K3s Pod（有 PDB 保護）/ 重啟只影響短暫可用性

維護流程

新增服務 → PR to ops/config/service-registry.yaml
PR 描述必須說明：服務名稱、分級、理由
統帥審核後 merge
ServiceRegistryClient 下次載入時自動生效（singleton 有 lazy load）

失敗行為（Fail-Safe）

ServiceRegistryClient 讀取失敗時 fallback AUTO（不阻擋告警流程），並記錄 ERROR log。此設計確保 Service Registry 本身的故障不會導致整個告警鏈路中斷。

未來擴充

服務依賴關係（dependency edges）→ Sprint 5 拓撲圖使用
備份策略客製化（每個服務獨立設定）
動態覆寫（緊急情況時可 kubectl configmap 注入）

2.7 KiB Raw Blame History Unescape Escape