docs: 补短架构与文档索引

2026-10-19 21:19:02 +08:00
1 parent 40b9bdcc8c
commit 9e7135782b
@@ -0,0 +1,66 @@
+# OpsxDB 架构（短）
+
+> 一页总览。专题不在这里展开：AI/MCP 见 [15-AI-MCP-Agent.md](./15-AI-MCP-Agent.md)，会话层见 [16-AI-Session-Harness.md](./16-AI-Session-Harness.md)。审计/对比文是参考，不是第二套总览。
+
+## 产品边界
+
+```text
+浏览器  →  只看官网 + 文档（Gin）
+操作    →  只走桌面 Tauri（./run.sh gui）
+```
+
+- **产品 UI 只认根级 `/src`**。验收、回归、交互口径都以 `/src` 为准。
+- `packages/` 里只有 MCP 的 npm 壳 `packages/opsxdb-mcp`，**没有** `packages/ui` 产品面，不进验收。
+- `src` 的 Vite（默认 `:5174`）只是桌面 `devUrl` / 打包源，**不是**浏览器工作台。
+- Gin（`server`）= 官网 / docs / health / 本机驱动与查询 API。不是远程多人协作后端。
+- `homepage/` 保持独立，不并进桌面 UI。
+
+## 模块
+
+| 路径 | 职责 |
+|------|------|
+| `/src` | React 桌面 UI：连接、对象树、SQL 工作台、结果、Redis 键面板、AI 侧栏 |
+| `src-tauri/` | Tauri 2 壳、本机 sidecar、能力配置 |
+| `server/` | Gin：官网/docs、`/health`、`/api/db/*`、AI/MCP 工具运行时 |
+| `connection-types/` | 引擎注册表（`ready` / `verified`）；未就绪的界面须灰态 |
+| `agents/` | JDBC / JVM agent 桥（达梦、Mongo、ZooKeeper 等） |
+| `packages/opsxdb-mcp` | 外部 Agent 用的 npm 启动壳，不是产品 UI |
+
+引擎分发在 `server/internal/db`（MySQL 族、Postgres、SQL Server、Oracle、SQLite、Redis、ES、Influx、agent）。注册表与代码现阶段手工对齐，以代码为准。
+
+## 端口
+
+| 服务 | 默认 | 环境变量 | 说明 |
+|------|------|----------|------|
+| Gin | **8788** | `OPSXDB_SERVER_PORT` | 官网、文档、本机 API。只绑本机 |
+| Vite | **5174** | `OPSXDB_WEB_PORT` | 仅 `./run.sh gui` / 打包。`strictPort`，代理 `/api`、`/health` → 8788 |
+
+## 关键数据流
+
+```text
+./run.sh gui
+  Tauri 壳 ──加载──▶ /src（开发态 Vite :5174，生产包内嵌）
+       │
+       ▼
+  本机 Gin :8788   /api/db/* 、AI
+       │
+       ├─ 原生驱动 / ES / Influx
+       └─ agents/ JDBC·JVM 桥
+```
+
+- 开发态 `/src` 经 Vite 把 `/api` 转到 `127.0.0.1:8788`；桌面包由 sidecar 注入 API 地址，否则回落 `http://127.0.0.1:8788`。
+- 连接保存在桌面本机，并双写 `~/.opsxdb/connections.json`，供 MCP 读。密码按现有混淆，不是钥匙串。
+- **Redis**：单机键浏览在 `/src` 的 `RedisKeyPane`，执行走 `server/internal/db/redis.go`。Sentinel/Cluster 表单与后端路径在，真拓扑以环境验收为准。危险命令（如 FLUSH*）未带确认则不执行。
+
+## MCP 与危险写
+
+工具层在 `server/internal/aitools`，桌面 Agent 与 `opsxdb-mcp`（stdio）共用。现状（以代码为准，不是早期「P0 纯只读」规划）：
+
+- 连接白名单 `~/.opsxdb/mcp.json` 的 `allowed_connection_ids` **为空 = 拒绝全部**。
+- **缺省无文件**时策略默认 `mode=read_write` 且 `allow_dangerous=true`；**已有文件**缺字段则按只读、且不允许危险 SQL。
+- 写路径：`mode=read_write` **并且**用户确认后才执行。`confirm_danger` / `ConfirmDanger` **不会**被模型自动带上（Agent 执行前会剥掉调用方的确认位）。未确认返回 `needConfirm`，不静默写。
+- 工作台 SQL 同样：`ExecSQL` 在 `ConfirmDanger` 未置位时，命中危险词表只回确认、不执行。
+- Redis：`FLUSH*` / `KEYS` / `CONFIG` 在工具层始终拒绝；其余写命令同样要 `read_write` + 确认。
+- 审计：`~/.opsxdb/logs/mcp-audit.jsonl`（不含密码）。
+
+会话状态机、incomplete、续跑见 [16-AI-Session-Harness.md](./16-AI-Session-Harness.md)。工具清单与历史阶段说明见 [15-AI-MCP-Agent.md](./15-AI-MCP-Agent.md)（文首已标明只读默认是历史规划）。