# dbtool

**Repository Path**: marvinma/dbtool

## Basic Information

- **Project Name**: dbtool
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-12
- **Last Updated**: 2025-08-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 数据库操作工具

这是一个轻量级的 Web 工具，用于安全地对 SQLite 和 DuckDB 数据库执行 SQL 查询。本工具内置了用户认证、表访问控制（针对 SQLite）和操作审计功能。

## 功能特性

-   **Web 界面**: 提供一个简单的 SQL 编辑器来执行查询。
-   **双数据库支持**:
    -   **SQLite**: 严格的权限控制。用户只能访问在配置文件中明确授权的表。权限的定义基于项目内置的 `scada.db` 数据库模板。
    -   **DuckDB**: 较为宽松的权限。用户可以访问所有表，但禁止执行任何 `DELETE`（删除数据）或 DDL（如 `CREATE`, `DROP`, `ALTER`）操作。
-   **用户认证**: 通过用户名和密码登录。
-   **操作审计**: 所有成功执行的 SQL 语句都会被记录到日志文件中，便于追踪。

## 技术栈

-   **后端**: Clojure, Ring, Reitit
-   **数据库连接**: next.jdbc
-   **SQL 安全**: JSqlParser
-   **前端**: Vue.js, Bulma CSS (TBD)

---

## 执行计划

本项目将根据以下计划进行重构：

1.  **更新文档**: 首先，将此执行计划更新到 `README.md` 文件中，确保目标明确。
2.  **分析与依赖管理**:
    -   检查 `project.clj` 文件。
    -   添加 `sqlite-jdbc`, `duckdb_jdbc`, `jsqlparser` 和 `buddy-hashers` 等核心依赖。
    -   移除项目模板中不再需要的依赖。
3.  **生成静态配置文件**:
    -   执行一个一次性任务：连接到项目中的 `scada.db` 文件以读取其所有表名。
    -   基于读取到的表名，创建一个新的 `resources/config.edn` 文件。
    -   此文件将包含：
        -   默认用户信息（`admin`/`ScadaDB@2025`，密码使用 BCrypt 加密）。
        -   审计日志的路径。
        -   一个 `:sqlite` 配置节，其中包含一个 `:allowed-tables` 键，其值为从 `scada.db` 读取到的表名列表。此列表将作为 SQLite 访问的唯一权限标准。
4.  **核心逻辑实现**:
    -   **数据库交互层**: 建立统一的函数来处理数据库连接和查询。
    -   **SQL 安全验证层**:
        -   **通用规则**: 使用 `jsqlparser` 禁止所有 DDL 语句 (`CREATE`, `DROP`, `ALTER` 等)。
        -   **DuckDB 特定规则**: 额外禁止 `DELETE` 语句。
        -   **SQLite 特定规则**: 解析 SQL，提取其操作的表，并验证这些表是否都存在于 `config.edn` 的 `:allowed-tables` 列表中。
5.  **API 端点与前端交互**:
    -   重构 `dbtool.routes.services` 以提供后端 API。
    -   `/api/login`: 用户认证。
    -   `/api/load-tables`:
        -   对于 DuckDB，返回所有表。
        -   对于 SQLite，连接用户指定的数据库，获取其表列表，然后仅返回那些与 `config.edn` 中 `:allowed-tables` 列表匹配的表。
    -   `/api/execute-sql`: 接收 SQL，执行安全验证，若通过则执行查询、记录审计日志，并返回结果。
6.  **清理与测试**:
    -   删除不再需要的旧文件和模板代码。
    -   执行 `lein run` 启动服务，确保应用能够无错误地编译和运行。

---

## 安装与运行

### 前提条件

-   Java Development Kit (JDK)
-   Leiningen (Clojure 项目管理工具)
-   SQLite 3 命令行工具 (用于初始配置生成)

### 运行方式

#### 方式一：开发环境运行

适用于开发和测试环境：

### 运行步骤

1.  **克隆仓库**:
    ```bash
    git clone <your-repo-url>
    cd dbtool
    ```

2.  **配置文件**:
    项目首次运行时，会自动（或通过脚本）生成 `resources/config.edn` 配置文件。
    -   **`users`**: 配置用户信息。密码为 BCrypt 哈希值。
    -   **`sqlite`**:
        -   `:allowed-tables`: 这是一个根据 `scada.db` 自动生成的列表，规定了所有 SQLite 数据库允许被访问的表。
    -   **`audit-log`**: 指定审计日志文件的路径。

3.  **启动服务**:
    ```bash
    lein run
    ```
    服务默认启动在 `http://localhost:3000`。

#### 方式二：桌面应用（推荐）

适用于生产环境和最终用户部署，提供类似原生应用的体验：

### 启动桌面应用

1.  **快速启动**:
    ```bash
    # 使用启动脚本（自动处理依赖和构建）
    ./start-desktop.sh
    ```

2.  **手动启动**:
    ```bash
    # 构建Java后端
    lein uberjar
    
    # 安装Electron依赖（首次运行）
    cd electron-app
    npm install
    
    # 启动桌面应用
    npm start
    ```

3.  **桌面应用特性**:
    - 🖥️ 无浏览器地址栏，类似原生应用体验
    - 🔒 隐藏localhost地址和端口信息
    - 🚀 自动启动Java后端服务
    - 🎯 Windows原生窗口管理
    - 📦 可打包为单一安装文件

### 可执行文件特性

- **自动启动**: 双击即可启动Web服务器
- **自动打开浏览器**: 启动后自动在默认浏览器中打开应用首页
- **无需命令行**: 用户无需了解命令行操作
- **便携性**: 独立安装包，包含所有依赖
- **自定义图标**: 支持自定义应用图标（参见 `icon-guide.md`）

### 相关文档

- `build-exe.md` - 详细的构建说明
- `deployment-guide.md` - 完整的部署指南
- `icon-guide.md` - 图标设置指南

---

## 使用方法

1.  **登录**: 打开浏览器并访问服务地址。使用 `config.edn` 中配置的凭据登录。
2.  **选择数据库**:
    -   在界面中，选择数据库类型（SQLite 或 DuckDB）。
    -   输入数据库文件的绝对路径。
    -   点击 “加载数据表” 按钮。
3.  **执行 SQL**:
    -   左侧会显示可用的数据表列表。
    -   在 SQL 编辑器中编写 SQL 语句。
    -   点击 “执行 SQL” 按钮。
4.  **查看结果**:
    -   查询结果或错误信息将显示在页面上。

## 安全模型

-   **SQL 注入**: 所有 SQL 都通过 JDBC 参数化查询执行，有效防止 SQL 注入。
-   **操作限制**:
    -   所有数据库都禁止 DDL 操作 (`CREATE`, `DROP`, `ALTER` 等)。
    -   对于 DuckDB，额外禁止 `DELETE` 操作。
-   **表访问控制 (SQLite)**: 用户只能查询 `config.edn` 中 `:sqlite` -> `:allowed-tables` 列表内定义的表。
-   **审计**: 所有通过验证并成功执行的 SQL 都会连同用户名和时间戳一起记录在 `:audit-log` -> `:path` 指定的文件中。

---

## 桌面应用构建指南

### 🎯 概述

本项目支持将应用打包为桌面应用，方便最终用户部署和使用。桌面应用具有以下特性：

- **一键启动**：双击启动应用
- **自动打开浏览器**：启动后自动在默认浏览器中打开应用首页
- **用户友好**：无需命令行操作

### 📋 前提条件

1. **Java环境**：JDK 8或更高版本
2. **Leiningen**：Clojure项目管理工具
3. **Node.js**：用于Electron桌面应用（可选）

### 🚀 构建步骤

#### 步骤1：构建Java后端

```bash
# 清理并构建JAR包
lein clean
lein uberjar
```

#### 步骤2：构建桌面应用（可选）

```bash
# 安装Electron依赖
cd electron-app
npm install

# 构建Windows安装包
npm run build-win
```

#### 步骤3：构建桌面应用

```bash
# 构建桌面应用
cd electron-app
npm run build-win
```

### 🧪 测试构建结果

#### 测试JAR包
```bash
# 测试应用启动
java -jar target/uberjar/dbtool.jar
```

#### 验证桌面应用
构建成功后，您将得到：
- Electron桌面应用安装包
- 启动后自动打开应用到 `http://localhost:3000`

### 📦 部署说明

#### 目标机器要求
- **操作系统**：Windows 7或更高版本
- **Java环境**：JRE 8或更高版本
- **内存**：建议至少512MB可用内存

#### 部署步骤
1. 安装Electron桌面应用
2. 确保目标机器已安装Java 8+
3. 启动桌面应用
4. 浏览器自动打开应用首页
5. 使用默认凭据登录（admin/ScadaDB@2025）

### 🔧 配置选项

#### 自定义端口
可以通过修改配置文件或环境变量指定端口

#### 自定义图标
1. 准备ICO格式图标文件（推荐32x32或48x48像素）
2. 将图标文件命名为 `icon.ico` 并放在项目根目录
3. 重新运行构建脚本

### 🛠️ 故障排除

#### 常见问题

**问题1**：Java后端无法启动
- **解决方案**：检查Java版本 `java -version`，确保为JDK 8+

**问题2**：Electron应用无法启动
- **解决方案**：检查Node.js版本 `node --version`，确保为14+

**问题3**：桌面应用窗口未显示
- **解决方案**：等待Java后端启动完成，检查3008端口是否被占用

**问题4**：打包失败
- **解决方案**：确认JAR文件存在于 `target/uberjar/dbtool.jar`

#### 获取详细日志
```bash
# 查看Electron应用日志
cd electron-app
npm start
```

### 📁 相关文件

构建过程中涉及的重要文件：
- `electron-app/main.js` - Electron主进程
- `electron-app/package.json` - Electron配置
- `start-desktop.sh` - 桌面应用启动脚本
- `src/clj/dbtool/core.clj` - 应用主入口
- `project.clj` - 项目配置（主类设置）

### 🔒 安全注意事项

1. **代码签名**：建议对生成的安装包进行代码签名以减少杀毒软件误报
2. **权限控制**：桌面应用继承了原应用的所有安全限制
3. **网络访问**：应用只监听本地端口，不接受外部连接
4. **开发者工具**：生产环境下自动禁用开发者工具

### 📈 性能优化

- **内存设置**：Java后端默认配置初始堆256MB，最大堆1024MB
- **启动优化**：Electron自动管理Java进程生命周期
- **文件大小**：可通过移除不必要的依赖来减小安装包大小
- **窗口管理**：隐藏菜单栏，提供原生窗口体验

### 🔄 更新和维护

#### 更新应用
1. 修改源代码
2. 重新构建JAR包：`lein uberjar`
3. 重新构建桌面应用：`cd electron-app && npm run build-win`
4. 重新部署安装包

#### 版本管理
- 在 `project.clj` 中更新版本号
- 在 `electron-app/package.json` 中同步更新版本信息

---

## 备注

### 项目文件结构
```
dbtool/
├── src/clj/dbtool/           # 源代码
├── resources/                # 资源文件
├── target/uberjar/          # 构建输出
├── electron-app/            # Electron桌面应用
│   ├── main.js             # 主进程
│   ├── preload.js          # 预加载脚本
│   ├── package.json        # 配置文件
│   └── dist/               # 打包输出
├── start-desktop.sh         # 桌面应用启动脚本
└── README.md               # 本文档
```

### 技术架构
- **后端**：Clojure + Ring + Reitit
- **数据库**：SQLite + DuckDB
- **安全**：JSqlParser + BCrypt
- **桌面应用**：Electron + Node.js
- **打包**：Electron Builder + Leiningen

### 开发团队
如需技术支持或报告问题，请联系开发团队或在项目仓库中提交Issue。