147 lines
10 KiB
Markdown
147 lines
10 KiB
Markdown
# IwoooS Docker / systemd / 主機服務變更證據驗收
|
||
|
||
| 項目 | 內容 |
|
||
|------|------|
|
||
| 日期 | 2026-06-15 |
|
||
| 狀態 | `change_evidence_acceptance_ready_no_runtime_action` |
|
||
| 工具 | `scripts/security/host-service-change-evidence-acceptance.py` |
|
||
| 輸入 | `docs/security/host-service-owner-response-acceptance.snapshot.json` |
|
||
| Snapshot | `docs/security/host-service-change-evidence-acceptance.snapshot.json` |
|
||
| runtime gate | `0` |
|
||
|
||
## 1. 目的
|
||
|
||
Docker / systemd / host service 事故不能只看「服務又起來了」。主機重啟、Docker daemon starting、compose stack 退出、systemd failed unit、repair-bot / runner 競爭、cold-start recovery 或 port binding 漂移，都可能讓公開 route 短暫恢復但根因仍未驗收。
|
||
|
||
本文件只定義變更 / 事故證據如何收件、補證、隔離、拒收與進 reviewer review。它不是 live host read、不是 SSH、不是 Docker / systemd 操作、不是 repair-bot、不是 Ansible、不是 route smoke，也不是 production write 或 runtime gate 授權。
|
||
|
||
## 2. 摘要
|
||
|
||
| 指標 | 值 | 說明 |
|
||
|------|----|------|
|
||
| change evidence candidate count | `9` | 對應 9 個 host service surface |
|
||
| write-capable candidate count | `3` | Ansible role、110 repair-bot、188 repair-bot |
|
||
| live evidence required candidate count | `8` | local dev compose 之外都需 owner-provided live metadata |
|
||
| change evidence field count | `45` | 每份 candidate 的 metadata-only 欄位 |
|
||
| required evidence field count | `25` | actor、before / after、daemon、compose、systemd、port、dependency、route、post-check 等 |
|
||
| reviewer check count | `26` | actor、service state、daemon、compose、systemd、dependency、route recovery、no-false-green 等 |
|
||
| outcome lane count | `10` | waiting、quarantine、reject、supplement、incident backfill、no-false-green supplement、review、maintenance、runtime gate |
|
||
| blocked action count | `39` | SSH、Docker、systemctl、repair-bot、Ansible、route smoke、raw log storage、runtime gate 等 |
|
||
| change evidence received / accepted | `0 / 0` | 尚未收到，尚未驗收 |
|
||
| runtime gate / action button | `0 / 0` | 未開啟 |
|
||
|
||
## 3. 驗收候選
|
||
|
||
| Candidate | Host scope | 類型 | 變更證據焦點 |
|
||
|-----------|------------|------|--------------|
|
||
| `host_service_change_evidence:local_dev_compose` | `local_dev_only` | Docker Compose | dev-only disposition、不得誤用 production、secret placeholder policy |
|
||
| `host_service_change_evidence:monitoring_110_compose` | `host_110` | Docker Compose | Docker daemon、compose stack、route recovery、Alertmanager / Prometheus 影響 |
|
||
| `host_service_change_evidence:monitoring_exporters_188_compose` | `host_188` | Docker Compose | exporter state、DB / Redis dependency、compose recovery 與 post-check |
|
||
| `host_service_change_evidence:sentry_110_reference_compose` | `host_110` | reference compose | source-of-truth、official revision、backup / rollback path |
|
||
| `host_service_change_evidence:langfuse_110_compose` | `host_110` | Docker Compose | compose state、secret placeholder disposition、route recovery |
|
||
| `host_service_change_evidence:ansible_docker_compose_service_role` | `multi_host` | Ansible executor role | check-mode、allowed service_dir、人工 gate、rollback owner |
|
||
| `host_service_change_evidence:repair_bot_110_whitelist` | `host_110` | repair whitelist | actor、disable switch、audit log ref、post-check、runner contention |
|
||
| `host_service_change_evidence:repair_bot_188_whitelist` | `host_188` | repair whitelist | systemd restart approval gate、sudoers boundary、route smoke plan |
|
||
| `host_service_change_evidence:config_backup_host_capture` | `host_cluster` | config backup capture | latest backup status、restore drill owner、secret handling proof |
|
||
|
||
> 上表使用 host alias，不把內網位址放進前台產品文案。Snapshot 內若保留既有 repo-only scope，仍不得把它當成可公開文案或 live host 授權。
|
||
|
||
## 4. 必填證據欄位
|
||
|
||
| 欄位 | 規則 |
|
||
|------|------|
|
||
| `change_or_incident_ref` | 可追溯 change / incident / ticket ref |
|
||
| `actor_role_or_team` | 只填角色或團隊，不填私人聯絡資料或 credential |
|
||
| `decision` / `decision_reason` | 說明 confirm、defer、reject 或 request_more_evidence 的理由 |
|
||
| `affected_scope` | 明確列出 host alias、service scope、route / agent / monitoring 影響 |
|
||
| `boot_or_restart_window_ref` | boot、restart、kill、cold-start 或 recovery 時間 ref |
|
||
| `before_service_state_ref` / `after_service_state_ref` | 變更前後服務狀態 ref，不能只寫「已恢復」 |
|
||
| `docker_daemon_state_ref` | Docker daemon active / starting / failed / socket / contention metadata ref |
|
||
| `compose_stack_state_ref` | compose stack / container state 摘要 ref，不保存 raw `docker ps` dump |
|
||
| `systemd_unit_state_ref` | systemd unit、failed unit 或 degraded state 摘要 ref |
|
||
| `failed_unit_review_ref` | failed unit 是否與事故或恢復相關的 review ref |
|
||
| `port_binding_state_ref` | host port、container port、proxy、gateway / firewall exposure 摘要 ref |
|
||
| `dependency_impact_ref` | 上游、下游、資料庫、queue、registry、AI provider 與 public route 依賴 ref |
|
||
| `cold_start_sequence_ref` | Docker daemon、compose stack、systemd unit、runner 與 post-check 順序 ref |
|
||
| `runner_or_repair_bot_contention_ref` | runner、repair-bot、backup job、iptables / xtables 或 compose action 競爭 ref |
|
||
| `public_route_recovery_refs` / `admin_route_recovery_refs` | route 恢復 ref；無影響需說明不適用 |
|
||
| `agent_provider_health_refs` | AI provider、agent、webhook 或 proxy 健康 ref |
|
||
| `monitoring_alert_refs` | alert / incident / monitoring ref，避免人工觀察 false green |
|
||
| `operator_notification_refs` / `cross_project_sync_ref` | 跨產品 / Session / owner 同步 ref |
|
||
| `restoration_time_ref` | 已恢復事故的恢復時間；未恢復則提供 still-degraded ref |
|
||
| `rollback_owner` / `rollback_plan_ref` | 回復責任與 plan |
|
||
| `postcheck_evidence_refs` | service、route、agent、queue、monitoring 與 rollback stop condition |
|
||
|
||
## 5. Reviewer checks
|
||
|
||
| Check | 說明 |
|
||
|-------|------|
|
||
| `change_ref_present` | 必須有可追溯 change / incident ref |
|
||
| `actor_role_traceable` | 不接受匿名 restart、kill、compose action 或 daemon 操作 |
|
||
| `decision_reason_present` | decision 與 reason 必須同時存在 |
|
||
| `affected_scope_matches_surface` | affected scope 必須能對回 host service surface |
|
||
| `boot_or_restart_window_present` | 重啟、cold-start 或恢復需有時間 ref |
|
||
| `before_after_service_state_present` | 需有 before / after service state ref |
|
||
| `docker_daemon_state_present` | Docker daemon state 必須有脫敏 metadata ref |
|
||
| `compose_stack_state_present` | compose / container state 不保存 raw dump |
|
||
| `systemd_unit_state_present` | systemd unit / failed unit / degraded state 必須可追溯 |
|
||
| `failed_unit_review_present` | failed unit 是否相關必須 review |
|
||
| `port_binding_state_present` | port / proxy / gateway / firewall exposure 必須一致性 review |
|
||
| `dependency_impact_present` | 必須列上游、下游、queue、registry、AI provider、public route 與 monitoring 影響 |
|
||
| `cold_start_sequence_present` | 必須提供 cold-start / recovery sequence ref |
|
||
| `runner_repair_bot_contention_present` | 必須確認 runner、repair-bot、backup job 或 xtables 競爭 |
|
||
| `route_recovery_evidence_present` | route 受影響時需有恢復 ref |
|
||
| `agent_provider_health_present` | AI provider、agent 或 webhook 受影響時需有健康 ref |
|
||
| `monitoring_alert_ref_present` | 需列 monitoring / alert / incident ref |
|
||
| `operator_notification_present` | 需提供已通知受影響 owner / Session 的脫敏 ref |
|
||
| `cross_project_sync_present` | 跨專案影響需有同步 ref |
|
||
| `restoration_time_present` | 已恢復事故需提供恢復時間或 still-degraded ref |
|
||
| `rollback_owner_present` | rollback owner 與 rollback plan 必須存在 |
|
||
| `postcheck_evidence_present` | post-check 必須覆蓋 service、route、agent、queue、monitoring 與 stop condition |
|
||
| `secret_or_raw_payload_absent` | 不得包含 secret、env dump、raw docker logs、raw journal、private key 或 cookie |
|
||
| `no_false_green_service_health` | 不得把 healthy、route 200、container up 或 dashboard up 當成驗收完成 |
|
||
| `no_runtime_authorization` | 證據驗收不授權 SSH、Docker、systemctl、repair-bot、Ansible 或 host write |
|
||
| `counts_transition_safe` | 只有 reviewer record 可更新 accepted count，且不得開 runtime gate |
|
||
|
||
## 6. 禁止事項
|
||
|
||
1. 不 SSH read / write。
|
||
2. 不讀 live host、live Docker、live systemd 或 live journal。
|
||
3. 不執行 `docker compose up/down/pull`、`docker restart`、`docker kill`。
|
||
4. 不執行 `systemctl restart/reload/kill`。
|
||
5. 不呼叫 repair-bot，不跑 Ansible apply。
|
||
6. 不做 sudo action、host file write、firewall / port change 或 route smoke。
|
||
7. 不保存 raw live config、raw docker log、raw journal、raw env dump、secret value 或 private key。
|
||
8. 不把服務 healthy、route `200`、container up 或 dashboard up 當成 recovery / config 已驗收。
|
||
9. 不跳過 source-of-truth、依賴圖、port binding、cold-start sequence 或 daemon / runner contention review。
|
||
10. 不開 runtime gate，不建立 action button。
|
||
|
||
## 7. 指令
|
||
|
||
產生 committed snapshot：
|
||
|
||
```bash
|
||
python3 scripts/security/host-service-change-evidence-acceptance.py \
|
||
--root . \
|
||
--owner-response-report docs/security/host-service-owner-response-acceptance.snapshot.json \
|
||
--output docs/security/host-service-change-evidence-acceptance.snapshot.json \
|
||
--generated-at 2026-06-15T18:50:00+08:00
|
||
```
|
||
|
||
驗證 guard：
|
||
|
||
```bash
|
||
python3 scripts/security/security-mirror-progress-guard.py --root .
|
||
```
|
||
|
||
## 8. 完成度
|
||
|
||
| 工作 | 完成度 | 說明 |
|
||
|------|--------|------|
|
||
| host service change evidence acceptance artifact | `100%` | 產生器、snapshot 與文件已固定 |
|
||
| Docker / systemd / host service 只讀治理成熟度 | `58% -> 62%` | 事故 / 變更證據、重啟 actor、before / after、daemon、compose、systemd、port、dependency、route recovery、operator notice 與 no-false-green 已納入 |
|
||
| change evidence received / accepted | `0%` | 尚未收到，尚未驗收 |
|
||
| live host read / SSH | `0%` | 尚未批准且未執行 |
|
||
| Docker / systemd / repair-bot / Ansible | `0%` | 尚未批准且未執行 |
|
||
| runtime gate / host write | `0%` | 未授權且未執行 |
|