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