116 lines
4.3 KiB
Markdown
116 lines
4.3 KiB
Markdown
# 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：
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
只輸出目前清冊：
|
||
|
||
```bash
|
||
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%` | 未授權，未執行 |
|