awoooi/docs/security/PUBLIC-GATEWAY-PREFLIGHT-INVENTORY.md

IwoooS Public Gateway 變更前置 Gate 只讀清冊

項目	內容
日期	2026-06-12
狀態	repo_only_preflight_contract_ready
工具	scripts/security/public-gateway-preflight-inventory.py
Snapshot	docs/security/public-gateway-preflight-inventory.snapshot.json
Schema	docs/schemas/public_gateway_preflight_inventory_v1.schema.json
runtime gate	0

1. 目的

Public gateway 是所有產品、後台、API、callback、Webhook、ACME 與 WebSocket 的入口。Nginx 或 reverse proxy 若被手動修改，可能造成公開路由錯轉、管理後台暴露、憑證路徑錯置、ACME renew 失敗、WebSocket 中斷或 AI provider proxy 失效。

本清冊把 Nginx reload / public route change 前必備證據固定成只讀 Gate：誰負責、影響哪些 route、是否有 live conf evidence、是否有 rendered diff、是否有 nginx -t、是否有 route smoke、是否有 rollback owner。它不做任何 live 操作。

2. repo-only 摘要

指標	值
Nginx source config	3
C0 source config	2
route impact	14
unique upstream	14
TLS certificate path	10
certificate owner 確認缺口	4
ACME challenge domain	7
admin route domain	1
WebSocket route domain	6
preflight gate	12
repo-only ready gate	2
owner acceptance required gate	10
owner response / accepted	0 / 0
live conf / rendered diff / nginx -t / route smoke	0 / 0 / 0 / 0
maintenance window / rollback owner	0 / 0
runtime gate / action button	0 / 0

3. 已納入的 public gateway source

config id	主機	角色	等級	source
host188_all_sites	192.168.0.188	public gateway all sites	C0	infra/ansible/roles/nginx/templates/188-all-sites.conf.j2
host188_internal_tools_https	192.168.0.188	internal tools HTTPS	C0	infra/ansible/roles/nginx/templates/188-internal-tools-https.conf.j2
host110_ollama_proxy	192.168.0.110	Ollama proxy gateway	C1	infra/ansible/roles/nginx/templates/110-ollama-proxy.conf.j2

4. Reload / route change 前置 Gate

Gate	內容	目前狀態
PG1	source-of-truth hash	repo-only ready
PG2	affected route list	repo-only ready
PG3	owner response	0
PG4	owner-provided live config	0
PG5	rendered diff	0
PG6	nginx -t evidence	0
PG7	public route smoke	0
PG8	admin route smoke	0
PG9	WebSocket / API smoke	0
PG10	ACME / TLS owner check	0
PG11	maintenance window	0
PG12	rollback owner and ref	0

5. owner response 欄位

任何 public gateway 變更、live drift 判讀或 reload 候選，都至少要具備：

1. owner_role_or_team
2. decision
3. decision_reason
4. affected_scope
5. redacted_evidence_refs
6. followup_owner
7. rollback_owner
8. maintenance_window
9. validation_plan
10. nginx_test_evidence_ref
11. route_smoke_evidence_ref

6. 指令

更新 snapshot：

python3 scripts/security/public-gateway-preflight-inventory.py \
  --root . \
  --generated-at 2026-06-12T10:30:00+08:00 \
  --output docs/security/public-gateway-preflight-inventory.snapshot.json

只輸出目前清冊：

python3 scripts/security/public-gateway-preflight-inventory.py --root .

7. 邊界

1. 本清冊不執行 SSH。
2. 本清冊不讀 live Nginx conf。
3. 本清冊不執行 nginx -t。
4. 本清冊不 reload / restart Nginx。
5. 本清冊不做 DNS query、TLS probe 或 certbot renew。
6. 本清冊不修改主機、不改 DNS、不改憑證、不讀 private key。
7. IwoooS UI 可顯示 preflight Gate，但不得把卡片可見視為 owner 已確認或 runtime 已授權。

8. 完成度

工作	完成度	說明
public gateway preflight 契約	100%	已固定 12 個 reload / route change 前置 Gate
source-of-truth hash / affected route list	100%	由既有 Nginx / DNS-TLS snapshot 推導
owner response / live conf / rendered diff	0%	尚未收到，不能宣稱 live 無漂移
nginx -t / route smoke / rollback owner	0%	尚未批准且未執行
runtime reload / host write	0%	未授權，未執行