chore: track version files, docs, web app split, scripts (missed commits from March work)

2026-09-13 08:41:35 +08:00
parent 84c709bbcc
commit edf76db56b
33 changed files with 3082 additions and 504 deletions
@@ -0,0 +1,144 @@
+# Advanced Override 开关说明（INP2P）
+
+> 目标：在不破坏默认最小权限模型的前提下，提供**临时、可审计、可回滚**的越权能力。
+
+## 1. 开关清单
+
+## 总开关（必须先开）
+
+- `advanced_override_enabled`
+  - `0`：关闭（默认）
+  - `1`：开启
+
+> 总开关关闭时，所有越权子开关均不生效。
+
+## 越权子开关
+
+- `allow_apikey_mutate_sdwan`
+  - 允许 `apikey` 执行 `mutate_sdwan`（如 `POST /api/v1/sdwan/edit`）
+  - 默认 `0`
+
+- `allow_operator_kick_cross_node`
+  - 预留：允许 operator 执行更高风险节点控制（当前主要用于后续扩展）
+  - 默认 `0`
+
+- `allow_connect_cross_tenant`
+  - 允许 operator 在 connect 目标检查中放宽跨租户限制
+  - 默认 `0`
+
+## 兼容旧开关（保留）
+
+- `advanced_impersonate`
+- `advanced_force_network`
+- `advanced_cross_tenant`
+
+---
+
+## 2. 默认安全策略
+
+- 所有高级开关默认 `0`（关闭）
+- 仅系统管理员（`tenant_id=1` 且 `role=admin`）可在 `/api/v1/admin/settings` 修改
+- `master token` 仍禁止访问 tenant API
+- 默认禁止跨租户写操作
+
+---
+
+## 3. RBAC 行为
+
+系统先走基线权限 `TenantCan`，若基线拒绝，再尝试 `TenantCanWithOverride`：
+
+1. 若 `advanced_override_enabled != 1` → 拒绝
+2. 若命中对应子开关 → 放行（并记录 override 审计）
+3. 否则拒绝
+
+当前已接入接口：
+
+- `POST /api/v1/sdwan/edit`
+- `POST /api/v1/nodes/apps`
+- `POST /api/v1/nodes/kick`
+- `POST /api/v1/connect`
+
+---
+
+## 4. 审计事件
+
+## 开关配置审计
+
+- `setting_change`
+  - `target_type=setting`
+  - `target_id=<key>`
+  - `detail=<value>`
+
+## 越权使用审计
+
+- `rbac_override_used`
+  - 示例 detail：
+    - `action=mutate_sdwan tenant=4`
+    - `action=mutate_connect tenant=3`
+    - `action=connect_cross_tenant tenant=3 from=a to=b`
+
+## connect 失败审计
+
+- `connect_request_denied`
+  - 典型 reason：
+    - `source_offline`
+    - `tenant_mismatch_source`
+    - `target_offline`
+    - `tenant_mismatch_target`
+
+---
+
+## 5. 启用与回滚（操作手册）
+
+## 启用（示例）
+
+```bash
+BASE=http://127.0.0.1:27183
+ADMIN_TOKEN=<system-admin-session-token>
+
+curl -s -X POST "$BASE/api/v1/admin/settings" \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"key":"advanced_override_enabled","value":"1"}'
+
+curl -s -X POST "$BASE/api/v1/admin/settings" \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"key":"allow_apikey_mutate_sdwan","value":"1"}'
+```
+
+## 回滚（推荐顺序）
+
+```bash
+# 先关子开关
+curl -s -X POST "$BASE/api/v1/admin/settings" \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"key":"allow_apikey_mutate_sdwan","value":"0"}'
+
+curl -s -X POST "$BASE/api/v1/admin/settings" \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"key":"allow_connect_cross_tenant","value":"0"}'
+
+curl -s -X POST "$BASE/api/v1/admin/settings" \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"key":"allow_operator_kick_cross_node","value":"0"}'
+
+# 最后关总开关
+curl -s -X POST "$BASE/api/v1/admin/settings" \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"key":"advanced_override_enabled","value":"0"}'
+```
+
+---
+
+## 6. 风险与建议
+
+- 建议仅在临时排障窗口启用，完成后立即回滚。
+- 启用前后均应检查审计日志，确认“谁在何时以何种方式使用了越权能力”。
+- 生产环境优先保持：
+  - `advanced_override_enabled=0`
+  - `allow_* = 0`