# deepshell-plugin

**Repository Path**: decentant/deepshell-plugin

## Basic Information

- **Project Name**: deepshell-plugin
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-30
- **Last Updated**: 2026-10-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DeepShell Plugin

DeepShell 官方桌面插件的独立仓库。所有插件共用这一个 Gitee 项目，主程序不再内置插件 ZIP，安装包体积因此显著减小。

- 主程序：<https://gitee.com/decentant/deepshell>
- 插件目录（主程序默认读取）：<https://gitee.com/decentant/deepshell-plugin/raw/master/catalog.json>

## 插件列表

| 插件 | ID | 版本 | 后端依赖 |
| --- | --- | --- | --- |
| Redis 管理器 | `com.itdct.deepshell.plugin.redis` | 2.1.0 | 纯 JDK（RESP2） |
| Elasticsearch 管理器 | `com.itdct.deepshell.plugin.elasticsearch` | 1.0.0 | 纯 JDK（HTTP REST） |
| Kafka 管理器 | `com.itdct.deepshell.plugin.kafka` | 1.0.0 | kafka-clients 3.7.1 / lz4 / snappy / zstd |
| MongoDB 管理器 | `com.itdct.deepshell.plugin.mongodb` | 1.0.0 | MongoDB Java Driver 5.2.1 / BSON |
| 数据库管理器 | `com.itdct.deepshell.plugin.database` | 1.0.0 | 纯 JDK（自行导入 JDBC 驱动） |
| 容器与集群管理器 | `com.itdct.deepshell.plugin.containers` | 1.0.0 | 宿主 JSch + 本机 docker / kubectl |

插件前端运行在 DeepShell 桌面窗口的沙箱 iframe 中；带后端的插件由主程序以独立 `URLClassLoader` 加载，不依赖主程序的 Maven 依赖。

数据库管理器不内置任何数据库驱动：用户在插件内导入 JDBC 驱动 JAR（及其依赖 JAR），驱动与连接配置保存在插件数据目录，不进入签名包。支持 MySQL / MariaDB、PostgreSQL、SQL Server、Oracle、ClickHouse、SQLite、H2、达梦、人大金仓、OceanBase、DB2、Hive、Trino 等；有主键的表可在数据页直接新增、编辑、删除行，写操作使用参数化 SQL 并校验单行影响。

## 目录结构

```text
.
├─ plugins/                 插件源码（前端 + backend/src）
│  └─ <name>/
│     ├─ plugin.json
│     ├─ index.html / app.js / style.css / icon.svg
│     └─ backend/
│        ├─ src/            后端 Java 源码
│        ├─ lib/            插件自带的第三方 JAR（提交到仓库）
│        └─ <name>-backend.jar   构建产物（不提交）
├─ catalog.json             主程序读取的官方插件目录
├─ catalog/
│  └─ icons/                目录图标源文件（catalog 内嵌为 data URI）
├─ dist/                    已签名的插件 ZIP（提交到仓库，供主程序下载）
├─ sdk/                     插件 API（DesktopPluginModule / PluginContext）
├─ vendor/                  编译期依赖（Jackson、JSch）
├─ keys/                    官方签名公钥
└─ tools/                   构建、签名、目录生成与发布脚本
```

`dist/*.zip` 是唯一分发给主程序的产物；`catalog.json` 中的 `file` 与 `sha256` 必须与之一致。

## 构建

要求：JDK 17+（`javac` / `jar` / `java`），Windows PowerShell 5.1+。

```powershell
# 构建全部插件并刷新 catalog
powershell -ExecutionPolicy Bypass -File tools/build-all.ps1

# 只构建某个插件
powershell -ExecutionPolicy Bypass -File tools/build-plugin.ps1 -Name redis

# 双击 tools/build-all.cmd 也可以
```

构建流程：

1. 用 `javac --release 8` 编译 `plugins/<name>/backend/src`；
2. 打包为 `plugins/<name>/backend/<name>-backend.jar`；
3. 组装前端、后端 JAR 与 `backend/lib` 第三方依赖；
4. 生成 `dist/<name>-<version>.zip`；
5. 使用官方 RSA 私钥签名并立即验签；
6. 重新生成 `catalog.json`（包含版本、SHA-256、大小与图标）。

### 签名私钥

私钥只保存在维护者本机，**不进入仓库、不进入分发包**：

```text
%USERPROFILE%\.deepshell\signing\deepshell-plugin-private.pem
```

也可以通过 `-PrivateKey` 或环境变量 `DEEPSHELL_PLUGIN_KEY` 指定。公钥在 `keys/deepshell-plugin-public.pem`，与主程序内置公钥一致。丢失私钥后只能轮换 keyId 与公钥并重新发布全部插件。

## 发布

首次发布前需要在 Gitee 创建空仓库 `decentant/deepshell-plugin`（不要勾选初始化 README），本仓库已配置：

```text
origin  https://gitee.com/decentant/deepshell-plugin.git
```

创建后执行一次：

```bash
git push -u origin master
```

之后的日常发布：

```powershell
# 构建 + 更新 catalog + 本地提交
powershell -ExecutionPolicy Bypass -File tools/publish.ps1

# 构建 + 提交 + 推送 Gitee
powershell -ExecutionPolicy Bypass -File tools/publish.ps1 -Push
```

发布后，主程序下一次打开「安装 / 管理」即可看到新版本；无需重新发布主程序安装包。

## 主程序如何安装

主程序默认读取：

```text
https://gitee.com/decentant/deepshell-plugin/raw/master/catalog.json
```

可在主程序 `application.yml` 中覆盖，或留空关闭在线目录（仍支持手动导入 ZIP）：

```yaml
deepshell:
  plugins:
    catalog-url: https://gitee.com/decentant/deepshell-plugin/raw/master/catalog.json
```

安装时主程序会：

1. 读取并缓存 catalog；
2. 按 `file` 下载 ZIP，校验 `sha256` 与大小；
3. 校验插件 RSA 签名，官方插件 ID 必须带有效签名；
4. 解压到数据目录 `plugins/<id>/`，后端插件重启后加载。

## 新增插件

1. 在 `plugins/` 下新建目录，加入 `plugin.json`、前端文件与图标；
2. 后端入口实现 `com.itdct.deepshell.plugin.DesktopPluginModule`，源码放在 `backend/src`；
3. `plugin.json` 的 `backend.jars` 列出后端 JAR（含 `backend/lib` 依赖）；
4. 需要第三方库时把 JAR 放入 `backend/lib`，并在构建脚本中确认 classpath；
5. 运行 `tools/build-all.ps1`，把 `dist/<name>-<version>.zip` 与 `catalog.json` 一起提交。

## 插件 API

```java
public interface DesktopPluginModule {
    String id();
    default void initialize(PluginContext context) throws Exception {}
    Object invoke(String action, Map<String, Object> payload) throws Exception;
    default void close() {}
}
```

`PluginContext` 提供插件独立数据目录与本机密钥加解密；插件不依赖 Spring，也拿不到宿主服务。API 变更时，从主程序重新导出 `sdk/deepshell-plugin-api.jar` 中的 `DesktopPluginModule` 与 `PluginContext` 两个类即可。

## 许可证

插件与主程序一致，采用 AGPL-3.0（详见 `LICENSE`）。