67 lines
3.8 KiB
Markdown
67 lines
3.8 KiB
Markdown
# 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)（文首已标明只读默认是历史规划）。
|