# lingshu-dbtool

**Repository Path**: magic2060/lingshu-dbtool

## Basic Information

- **Project Name**: lingshu-dbtool
- **Description**: TRAE 宝复刻 nvaicat 工具。连接数据库
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-08
- **Last Updated**: 2026-11-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 灵枢 DBTool

类 Navicat 的跨库数据库管理工具：**Electron + Vue 3 界面 + 本地 Java 边车（JDBC）**，最终打包为 Windows 免安装 exe 与安装包。

> 当前版本 `0.1.0`。已完成：窗口、边车握手与健康检查、连接管理（新建/编辑/删除/测试/详情/备注）、密码加密落盘与受控查看、连接信息导出（JSON/CSV，明文或口令加密）、崩溃提示、生产模式与危险操作确认组件、SQL 编辑器（CodeMirror 6 高亮与补全、多标签草稿、分页结果、错误定位）、驱动管理（内置清单、外部 jar 添加/启停/删除、自定义 JDBC 连接）。**导出与备份（第三块）尚未开始**，当前进度与已知问题见 [docs/PROGRESS.md](docs/PROGRESS.md)。

## 功能进度

| 阶段 | 内容 | 状态 |
| --- | --- | --- |
| 第一期 骨架 | Electron 窗口、Java 边车握手与健康检查、连接管理页、MySQL 测试连接、加密存储、异常退出提示、一条命令开发启动 | 已完成 |
| 连接安全 | 显式确认后一次性解密查看密码（30 秒自动遮蔽）、连接信息导出（JSON/CSV，明文或口令加密）、复制后剪贴板自动清空 | 已完成（导入下一期） |
| 第二期 编辑 | CodeMirror 6 SQL 编辑器（高亮 + 表/字段/函数补全）、多标签草稿、执行当前/全部/停止、分页结果、错误定位；库表树与行内编辑未做 | 已完成（库表树除外） |
| 第三期 国产库 | openGauss、达梦（用户自备 jar）、类型映射、方言差异、驱动管理页 | 驱动管理已完成并实测；达梦/OpenGauss 仅做了自定义 JDBC 通路，未连真实实例 |
| 第四期 导出备份 | SQL / CSV / Excel / JSON 导出与导入、整库备份恢复、库到库复制、大表分批 | 未开始 |
| 安全能力 | 危险操作二次确认（名称输入校验）、生产模式（水印、红色横幅、默认只读、临时解锁） | 骨架已落地，SQL 执行已接入守卫 |

## 架构一览

```mermaid
flowchart LR
  subgraph Renderer["渲染进程（Vue 3 + Element Plus）"]
    V[页面 / 组件] --> A[api 模块 + axios 实例]
    A --> P[preload contextBridge]
  end
  P -->|IPC| M[Electron 主进程]
  M -->|spawn + 一次性 token| J[Java 边车 127.0.0.1:随机端口]
  M -->|连接配置加密落盘| F[(connections.json<br/>DPAPI 密文)]
  J -->|JDBC / HikariCP| DB[(MySQL …)]
  J -->|扫描 jar| D[(drivers/)]
```

- 渲染进程拿不到 Node、拿不到边车端口和令牌，所有请求经主进程转发。
- 边车只监听 `127.0.0.1`，端口由系统随机分配，每次启动生成一次性令牌，通过环境变量传递，不落盘、不出现在命令行。
- 边车启动后向 stdout 输出一行 `@@LINGSHU_READY@@ {port,pid,version}`，主进程解析后再回打健康检查，双确认后才算就绪。

更完整的时序见 [docs/03-communication.md](docs/03-communication.md)。

## 技术栈

| 层 | 选型 |
| --- | --- |
| 桌面壳 | Electron 33（contextIsolation + preload） |
| 界面 | Vue 3.5、Vite 6、Element Plus 2.9、Pinia、vue-router（hash 模式） |
| 主进程 | Node 20（Electron 内置），axios 自定义 adapter 走 IPC |
| 边车 | Java 17、Javalin 6.3、HikariCP 5.1、Jackson 2.17、mysql-connector-j 8.4 |
| 打包 | electron-builder（NSIS 安装包 + portable 免安装）+ jlink 裁剪 JRE |

为什么这么选，见 [docs/01-tech-selection.md](docs/01-tech-selection.md)。

## 目录结构

```text
lingshu-dbtool/
├─ electron/
│  ├─ main/
│  │  ├─ index.js            # 应用入口：单实例、窗口、生命周期
│  │  ├─ sidecar.js          # 边车进程管理：拉起、握手、健康监控、重启
│  │  ├─ ipc.js              # IPC 注册中心（对应若依 controller 的转发职责）
│  │  ├─ connection-store.js # 连接配置持久化（只存密文）
│  │  └─ secret-box.js       # safeStorage/DPAPI 加解密
│  └─ preload/index.js       # contextBridge 暴露 window.lingshu
├─ web/                      # Vite 根目录
│  ├─ index.html
│  └─ src/
│     ├─ api/                # 统一 axios 实例 + 按模块拆分的接口
│     ├─ views/              # 页面
│     ├─ components/         # 通用组件（侧边栏、连接弹窗、危险确认、水印、横幅）
│     ├─ store/              # Pinia
│     ├─ router/             # 路由
│     ├─ utils/              # 工具（危险操作分级、SQL 守卫）
│     └─ styles/             # 亮/暗主题变量与全局样式
├─ sidecar/                  # Java 边车（Maven 工程）
│  ├─ pom.xml
│  └─ src/main/java/com/lingshu/dbtool/
│     ├─ LingshuSidecarApplication.java
│     ├─ common/             # ApiResponse、ErrorCode、异常、工具
│     ├─ config/             # 环境变量、Javalin 装配、令牌校验
│     ├─ controller/         # 只做参数 → service → 返回
│     ├─ service/            # 接口 + impl
│     ├─ domain/             # 实体 / 请求响应对象 / 枚举
│     ├─ db/                 # 数据库适配器接口、注册表、impl
│     ├─ pool/               # Hikari 数据源工厂
│     └─ driver/             # 外部 jar 驱动加载
├─ scripts/                  # 环境检测、构建边车、构建 JRE、一条命令启动
├─ drivers/                  # 用户自备 JDBC jar（安装版在用户数据目录）
├─ docs/                     # 文档
├─ jre/                      # jlink 产物（生成物，不进 git）
├─ dist/                     # Vite 构建产物（不进 git）
├─ release/                  # electron-builder 产物（不进 git）
├─ maven-settings.xml        # 阿里云 Maven 镜像
├─ vite.config.mjs
└─ electron-builder.yml
```

## 环境要求

| 工具 | 要求 | 说明 |
| --- | --- | --- |
| Node.js | ≥ 18（实测 24.19） | npm 随 Node 安装 |
| JDK | **≥ 17** | 编译边车 + jlink 裁剪；JDK 8 不行 |
| Maven | ≥ 3.6（实测 3.6.3） | 构建边车 |
| 系统 | Windows 10/11 x64 | 目前只打包 Windows |

先自检：

```bash
npm run check:env
```

它会打印 Node / npm / JDK / Maven / git / 依赖与边车产物状态。JDK 解析顺序：

1. `scripts/local.env.json` 中的 `jdkHome`
2. 环境变量 `LINGSHU_JDK_HOME`
3. 环境变量 `JAVA_HOME`
4. 常见安装路径（如 `D:\magic\app\jdk\jdk17`）

机器上有多个 JDK 时，推荐新建 `scripts/local.env.json`（已在 `.gitignore`）：

```json
{
  "jdkHome": "D:\\path\\to\\jdk17",
  "mavenCmd": "mvn"
}
```

## 国内镜像（clone 后照抄）

```bash
# 1. npm 依赖
npm config set registry https://registry.npmmirror.com

# 2. Maven：仓库已带 maven-settings.xml（阿里云镜像），构建脚本会自动 -s 传入，
#    一般不需要额外配置。若要手工执行：
#    mvn -s maven-settings.xml clean package -DskipTests

# 3. Electron 二进制与打包工具（仅打包时需要，PowerShell 写法）
$env:ELECTRON_MIRROR = 'https://npmmirror.com/mirrors/electron/'
$env:ELECTRON_BUILDER_BINARIES_MIRROR = 'https://npmmirror.com/mirrors/electron-builder-binaries/'
```

## 开发启动

```bash
npm install          # 首次安装依赖
npm run dev          # 一条命令：必要时构建边车 → 启动 Vite → 拉起 Electron
```

`npm run dev` 做了这些事：

1. 比较 `sidecar/pom.xml`、`sidecar/src` 与 jar 的修改时间，需要时自动 `mvn package`；
2. 启动 Vite（默认 `127.0.0.1:5273`，可用 `LINGSHU_DEV_PORT` 覆盖）；
3. 等 Vite 就绪后以 `VITE_DEV_SERVER_URL` 拉起 Electron；
4. 退出时清理 Vite 与边车子进程。

> 5273 是本项目默认端口（5173 常被其他项目占用）。端口被占时设置 `LINGSHU_DEV_PORT` 即可。

## 常用命令

| 命令 | 作用 |
| --- | --- |
| `npm run check:env` | 打印环境自检结果 |
| `npm run dev` | 开发模式一条命令启动 |
| `npm run build:sidecar` | 只构建 Java 边车 fat jar |
| `npm run build:renderer` | 只构建前端 |
| `npm run build` | 边车 + 前端 |
| `npm run build:jre` | jdeps + jlink 裁剪 JRE 到 `jre/` |
| `npm run dist` | 完整打包：边车 + 前端 + JRE + 安装包/免安装 exe |
| `npm run dist:dir` | 只产出 `release/win-unpacked/`，便于快速验证 |

## 打包与产物

```bash
npm run dist
```

产物在 `release/`：

- `lingshu-dbtool-0.1.0-setup.exe`：NSIS 安装包（可选安装目录、桌面/开始菜单快捷方式）
- `lingshu-dbtool-0.1.0-portable.exe`：免安装版
- `win-unpacked/`：解包目录，便于排查

实测数据（本机）：

| 项目 | 体积 |
| --- | --- |
| jlink 裁剪后的 JRE | 40.5 MB |
| 边车 fat jar | 12.2 MB |
| `win-unpacked/` 解包总量 | 322.3 MB |
| 安装包 `-setup.exe` | 114.5 MB |
| 免安装 `-portable.exe` | 114.3 MB |

- 随包资源在 `resources/jre`、`resources/sidecar/lingshu-sidecar.jar`，主进程按文件存在性解析，不依赖 `app.isPackaged`。
- 没有代码签名证书，首次运行可能触发 SmartScreen 提示，属正常现象。
- 默认使用 Electron 图标，替换方法见 [docs/07-packaging-jre.md](docs/07-packaging-jre.md)。

## Gitee 发版步骤

```bash
# 1. 初始化并提交（仓库已 git init，可跳过第一行）
git init
git add .
git commit -m "feat: 第一期骨架"

# 2. 关联你自己的 Gitee 仓库（不要把凭据写进仓库）
git remote add origin https://gitee.com/<你的账号>/lingshu-dbtool.git
git push -u origin master

# 3. 打标签并推送
git tag v0.1.0
git push origin v0.1.0
```

然后在 Gitee 网页：**仓库 → 发行版 → 新建发行版**，选择标签 `v0.1.0`，上传 `release/` 下的两个 exe（不要提交整个 `release/` 目录），附上更新说明即可。

> 本项目约束：本地提交即可，不要 push、不要配置远端凭据；以上命令供你自行发版时使用。

## 数据与配置位置

| 内容 | 位置 |
| --- | --- |
| 连接配置 | `%APPDATA%\灵枢 DBTool\connections.json`（密码为 DPAPI 密文） |
| 开发模式驱动目录 | 仓库根目录 `drivers/` |
| 安装版驱动目录 | `%APPDATA%\灵枢 DBTool\drivers`（首次启动自动创建） |
| 随包 JRE | 安装目录 `resources/jre` |
| 边车 jar | 安装目录 `resources/sidecar/lingshu-sidecar.jar` |

密码落盘策略与取舍见 [docs/09-security.md](docs/09-security.md)。

## 安全设计（骨架已落地）

- **危险操作二次确认**：红色/黄色分级弹窗，库名/表名大字号加粗展示，必须手工输入完全一致的对象名称，按钮文案写明动作（如「永久删除 mydb 库」），默认焦点在「取消」。
- **生产模式**：连接级开关（默认关闭），列表中红色「生产」标识；进入后顶部红色条带 + 内容区对角水印；危险操作追加第三重确认；默认只允许 SELECT，写入需临时解锁。
- **查看密码**：编辑弹窗与连接详情的密码旁有「显示密码」，必须二次确认才通过一次性 IPC 解密；明文只留在组件内，30 秒自动遮蔽，可手动隐藏；不写日志、不落盘。
- **连接导出**：连接管理页支持导出全部或勾选的连接，JSON / CSV 两种格式；默认口令加密导出（PBKDF2-SHA256 210000 次 + AES-256-GCM，跨机器可用），明文导出需显式选择并显示红字警告；复制密码可选 30 秒后自动清空剪贴板。
- 组件位置：`web/src/components/DangerConfirmDialog.vue`、`ProductionBanner.vue`、`ProductionWatermark.vue`、`PasswordReveal.vue`、`ExportDialog.vue`、`ConnectionDetailDialog.vue`；分级与 SQL 守卫在 `web/src/utils/danger.js`。

详细设计见 [docs/09-security.md](docs/09-security.md)。

## 已知限制

- **数据库适配器**：MySQL、SQLite 为原生适配器；PostgreSQL、SQL Server、openGauss、达梦、Oracle、自定义 JDBC 走通用 JDBC 适配器（`GenericJdbcAdapter`），只保证连接与查询可用，方言差异（分页、系统表）未做专门适配。
- **MySQL 真实连接**：已在本机用真实 MySQL 验证连接与查询；达梦 / Oracle / openGauss 无实例，只验证了「加载驱动 + 建池」链路（用 H2 驱动模拟）。
- 只支持 Windows x64；未做 macOS/Linux 打包。
- 未做代码签名，安装包首次运行有 SmartScreen 提示。
- 外部驱动 jar 由 `URLClassLoader` 持有，删除前会先释放加载器；如果此时正好有连接池在用该驱动，需要先断开连接再删。
- WebSocket 中继通道（`ws:connect` 等）已实现但没有业务使用，留给导出进度使用。
- 连接测试失败时耗时可能接近 10 秒（驱动与 Hikari 的重试/超时叠加），后续会加可配置超时。
- 导出与备份（第四期）未开始，详见 [docs/PROGRESS.md](docs/PROGRESS.md)。

## 文档索引

| 文档 | 内容 |
| --- | --- |
| [docs/PROGRESS.md](docs/PROGRESS.md) | 当前进度、可用/未完成清单、已知问题、下次继续的第一步 |
| [docs/01-tech-selection.md](docs/01-tech-selection.md) | 技术选型全过程、候选方案对比、与 Navicat 的差异 |
| [docs/02-architecture.md](docs/02-architecture.md) | 整体架构、各层职责、与若依（RuoYi）的对应关系、新功能加在哪 |
| [docs/03-communication.md](docs/03-communication.md) | Electron 与 Java 边车的通信、握手时序、令牌与端口 |
| [docs/04-add-database-adapter.md](docs/04-add-database-adapter.md) | 如何新增一种数据库适配器（照抄即可） |
| [docs/05-driver-management.md](docs/05-driver-management.md) | 驱动目录、外部 jar 加载机制、授权注意事项 |
| [docs/06-troubleshooting.md](docs/06-troubleshooting.md) | 常见构建/启动失败排查 |
| [docs/07-packaging-jre.md](docs/07-packaging-jre.md) | 打包流程与 jlink 精简 JRE 详解 |
| [docs/08-type-mapping-charset.md](docs/08-type-mapping-charset.md) | JDBC 类型映射与中文乱码处理 |
| [docs/09-security.md](docs/09-security.md) | 密码存储、危险操作分级、生产模式与扩展方式 |
| [docs/10-sql-editor.md](docs/10-sql-editor.md) | SQL 编辑器：标签与草稿、补全来源、快捷键、结果分页、错误定位、实测记录 |

## License

MIT