logan
2c0bfafd8d
- 补入库：server/internal/db/dump.go、redis 分页/扫描预算测试、opsxdb-mcp main_test、 packages/opsxdb-mcp package-lock、docs 审计与对比文档等 37 个新文件 - 含结构扁平化进行中的 80 处修改与 155 处旧结构删除（server/ src/ src-tauri/ 为当前有效源） - 构建产物（bin/target/dist）与签名私钥仍按规则排除
83 lines
4.7 KiB
Markdown
83 lines
4.7 KiB
Markdown
# OpsxDB JDBC Agent
|
||
|
||
纯 JDK + gson 的通用 JDBC 桥：Go 服务端通过 stdin/stdout 的 JSON Lines 协议驱动一个
|
||
本机 JVM 进程，由它加载**官方 JDBC 驱动**（用户自备 jar，许可合规）连接数据库。
|
||
设计对标 DBX 的 agent 模式；v1 先接达梦，新增驱动在
|
||
`server/internal/db/agent.go` 的 `agentDriverSpecs` 登记一行即可。
|
||
|
||
## 组成
|
||
|
||
```
|
||
agents/jdbc/OpsxJdbcAgent.java JDBC 通用桥（达梦等官方 JDBC 驱动）
|
||
agents/jdbc/OpsxZkAgent.java ZooKeeper 专属桥（官方客户端，NIO socket 免 netty 全家桶之外还需 6 个 netty jar 供 SSL 类初始化）
|
||
agents/jdbc/OpsxMongoAgent.java MongoDB 专属桥（官方 sync driver + 迷你 DSL）
|
||
server/internal/db/agent.go Go 侧：进程池 / 协议客户端 / 元数据与执行入口（注册表 agentDriverSpecs）
|
||
server/internal/db/es.go Elasticsearch 原生接入（HTTP + SQL API）
|
||
server/internal/db/influx.go InfluxDB 2.x 原生接入（HTTP + Flux）
|
||
```
|
||
|
||
> Elasticsearch 曾评估走 agent + x-pack-sql-jdbc，实测 basic 许可报
|
||
> "current license is non-compliant for [jdbc]"（JDBC/ODBC 是付费客户端），
|
||
> 故走原生 HTTP；SQL REST API 在 basic 许可可用。
|
||
|
||
## 协议（JSON Lines，一行一个对象）
|
||
|
||
请求 `{ "id": 1, "op": "open", "args": { ... } }`
|
||
响应 `{ "id": 1, "ok": true, "result": { ... } }` 或 `{ "id": 1, "ok": false, "error": "..." }`
|
||
|
||
进程启动后第一行主动推送 hello 公告（agent/version/protocol），供握手校验。
|
||
|
||
| op | args | result |
|
||
|---|---|---|
|
||
| `hello` | — | agent/version/protocol |
|
||
| `open` | url, user, password, readOnly, props{} | handle |
|
||
| `ping` | handle | —（SELECT 1，失败退 DUAL） |
|
||
| `query` | handle, sql, maxRows, timeoutSec | columns[], rows[], truncated |
|
||
| `exec` | handle, sql, timeoutSec | affectedRows（有结果集时返回行列） |
|
||
| `metaDatabases` | handle | names[]（无 catalog 退化为 schemas） |
|
||
| `metaTables` | handle, schema | names[]（TABLE+VIEW，走 DatabaseMetaData） |
|
||
| `metaColumns` | handle, schema, table | columns[]（name/type/nullable/key） |
|
||
| `close` | handle | — |
|
||
| `shutdown` | — | 进程退出 |
|
||
|
||
## 首次启用（达梦）
|
||
|
||
0. 安装 JDK 17+（或 `export OPSXDB_JAVA_BIN=/path/to/java`）
|
||
1. agent jar 与开源驱动 jar 在**首次连接时自动下载**（DMG 不打包 Java 产物，
|
||
落盘 `~/.opsxdb/agent/` 与 `~/.opsxdb/drivers/<id>/`，sha256 钉版本）；
|
||
开发期可用 `OPSXDB_AGENT_JAR` 指向本地构建的 jar
|
||
2. 离线/内网环境预放驱动（二选一）：
|
||
- 开源驱动（MongoDB/ZooKeeper 全套）：`git clone gitee.com:attacker/opsxdb-driver && ./opsxdb-driver/scripts/fetch.sh all`
|
||
（对标 dbeaver-driver-all 的一键离线包；Maven 自动下载 + sha256 校验）
|
||
- 商用驱动：把官方 `DmJdbcDriver-*.jar` 放到 `~/.opsxdb/drivers/dameng/`
|
||
（许可原因不代下；`OPSXDB_DAMENG_JARS` 可改目录）
|
||
- 离线/内网：opsxdb-driver 仓库 `pack.sh` 打的 zip 放 `~/.opsxdb/offline-driver-pack.zip`，
|
||
首次连接时自动导入（网络下载失败自动回退离线包）
|
||
4. gson 由 Go 侧首次使用时自动下载（Maven Central → 阿里云镜像，sha1 钉版本校验）
|
||
|
||
之后前端达梦连接即可测试/连接；未配置时错误信息会逐步提示缺什么。
|
||
|
||
## 安全约定（与主程序一致，防把业务库查崩）
|
||
|
||
- `query` 必带 `maxRows` → `Statement.setMaxRows` 硬截断（上限 20000，Go 侧深分页超限直接拒绝）
|
||
- 每条语句 `setQueryTimeout`（秒），Go 侧从请求 deadline 推算
|
||
- 危险语句拦截（`CheckDangerousSQL`）在 Go 侧入口统一执行，agent 之前
|
||
|
||
## ZooKeeper / MongoDB 的 SQL 框 DSL
|
||
|
||
**ZK**：`GET /路径`（读节点：path/data/version/ctime/mtime/ephemeral/children）、
|
||
`LS /路径`（列子节点带 stat）、`CREATE /路径 [数据]`、`SET /路径 数据`、`DELETE /路径`（须无子）。
|
||
|
||
**Mongo**：`db.<集合>.find([filter])`、`db.<集合>.count([filter])`、
|
||
`db.<集合>.insertOne({doc})`、`db.<集合>.updateOne({filter},{update})`、
|
||
`db.<集合>.deleteOne({filter})`、`db.<集合>.deleteMany({filter})`。
|
||
写动词在 Go 侧映射进危险词表（deleteMany→DELETE 等），未确认返回 NeedConfirm。
|
||
|
||
## 已知限制（v1）
|
||
|
||
- ctx 取消**不会**真正掐断 JDBC 执行（协议无中断 op），靠 timeoutSec 兜底
|
||
- SSH 隧道对 agent 无效（TCP 由 JVM 发起），入口明确拒绝而不是静默失败
|
||
- EXPLAIN 走通用 `EXPLAIN ` 前缀，未按方言定制计划格式
|
||
- 单元测试用 helper process 扮演 JVM（`go test ./internal/db -run Agent`），无需本机装 Java
|
||
- E2E（需真库，docker 见 tests/）：`OPSXDB_E2E_JDBC=1`（sqlite-jdbc 验桥）、`OPSXDB_E2E_ES/ZK/INFLUX/MONGO=1`
|