**本文引用的文件 **
本文面向清鉴 AI 客户端的 Electron 桌面端,说明主进程、预加载模块和渲染进程之间的权限隔离现状、当前能力边界,以及本地文件、工作区、地图资源、PMTiles、下载清单等数据的存储位置与访问控制。文档同时基于现有代码指出尚未达到生产级安全基线的风险点,并给出渐进式加固建议。
Electron 入口由应用包主字段指向打包后的 public/electron/main.js,而 TypeScript 源码位于 ai-electron/electron 下:主进程启动生命周期、窗口控制器、预加载桥接和本地服务都集中在这里;前端资源位于 ai-electron/frontend,通过配置以本地 file:// 或开发服务器 URL 加载。
graph TB
A["package.json<br/>main: public/electron/main.js"] --> B["electron/main.ts<br/>注册生命周期与 preload"]
B --> C["electron/preload/index.ts<br/>创建托盘与安全服务"]
B --> D["electron/preload/lifecycle.ts<br/>应用与窗口生命周期"]
B --> E["electron/config/config.default.ts<br/>主窗口 webPreferences"]
B --> F["electron/config/windowOptions.ts<br/>共享 WebPreferences"]
B --> G["electron/service/window/smartWindow.ts<br/>智能工作台单例窗口"]
H["electron/controller/windowCtl.ts<br/>跨窗口 IPC 控制器"] --> G
I["electron/controller/osCtl.js<br/>系统能力与文件读取 IPC"] --> J["electron/service/os/os.js<br/>底层文件操作"]
K["electron/service/setting/localSettings.js<br/>local-settings.json"] --> I
L["electron/service/download/downloadService.js<br/>downloads.json + 下载目录"] --> I
图示来源
章节来源
当前 Electron 安全模型可以概括为:主进程拥有 Node/Electron API,预加载模块可选暴露有限能力,但渲染进程默认仍启用 Node 集成。这意味着渲染进程中的业务代码在理论上可以直接使用 require('electron') 调用主进程能力,而不是必须经过一个最小化的上下文桥接层。
| 层次 | 当前能力 | 主要文件 | 安全含义 |
|---|---|---|---|
| 主进程 | 完整 Node、Electron、文件系统、网络、窗口控制 | main.ts、windowCtl.ts、smartWindow.ts | 应作为唯一可信边界,封装所有危险操作 |
| 预加载模块 | 当前主要创建托盘和安全服务,并尝试向全局暴露 electron.ipcRenderer |
preload/index.ts、preload/bridge.ts | 如果渲染进程已启用 nodeIntegration,则该桥接不是实际限制 |
| 渲染进程 | 目前 contextIsolation: false 且 nodeIntegration: true |
windowOptions.ts、config.default.ts | 渲染进程可执行任意 Node 代码,不应直接信任其输入 |
ipcRenderer 或 process 对象传给渲染进程。章节来源
下图展示当前应用中主进程、预加载、渲染进程、控制器和服务之间的关系,以及两个窗口:主窗口和智能工作台窗口。
sequenceDiagram
participant FE as "渲染进程"
participant PL as "预加载模块"
participant MP as "主进程"
participant WC as "WindowCtl"
participant SW as "smartWindow"
participant OS as "OsCtl / os.js"
participant FS as "本地文件系统"
FE->>MP: "IPC 调用 openSmartWindow()"
MP->>WC: "路由到 windowCtl.openSmartWindow"
WC->>SW: "openSmartWindow(fullPath)"
SW->>SW: "normalizeFullPath(fullPath)"
alt 开发环境
SW->>FE: "loadURL(开发服务器地址)"
else 生产环境
SW->>FE: "loadFile(index.html, hash)"
end
FE->>OS: "readBinaryFileRange / readTextFile / getMapLocalPath"
OS->>FS: "按绝对路径读取文件"
FS-->>OS: "返回数据或错误"
OS-->>FE: "{success, data|message}"
图示来源
章节来源
主进程使用 ElectronEgg 框架注册 ready、electron-app-ready、window-ready、before-close 生命周期,并注册 preload。生命周期负责:
这些逻辑本身不直接暴露危险能力,但它是所有窗口和资源加载的起点。
章节来源
windowCtl.ts 暴露一组统一的 IPC 方法,用于打开、关闭、判断智能工作台窗口,以及将主窗口拉到前台。它采用“统一返回 { success, data|message }”的模式,失败不会直接把 Electron 异常抛给渲染进程。
关键安全点:
openSmartWindow 接收 fullPath,但最终交给 smartWindow 做归一化;syncState 会向除发送者外的所有窗口广播事件,需确保事件 payload 不被渲染进程伪造成破坏性指令;getWindowRole 通过 event.sender 判断窗口角色,属于跨窗口身份识别的重要逻辑。
classDiagram
class WindowCtl {
+openSmartWindow(params)
+closeSmartWindow()
+isSmartWindowOpen()
+focusMainWindow()
+getWindowRole(params, event)
+syncState(params, event)
}
class SmartWindow {
+openSmartWindow(options)
+closeSmartWindow()
+focusSmartWindow()
+focusMainWindow()
}
WindowCtl --> SmartWindow : "委托窗口行为"
图示来源
章节来源
智能工作台是一个单例窗口,职责包括:
/workbench 开头;开发环境从 cmd/bin.js 读取前端开发服务器地址,生产环境走 file:// 本地 index.html。
flowchart TD
Start["传入 fullPath"] --> Trim["去除空白"]
Trim --> Empty{"是否为空?"}
Empty -->|是| Default["使用 /workbench"]
Empty -->|否| Check["匹配 /^\\/workbench(\\/|\\?|$)/"]
Check -->|是| UseRaw["保留原始 fullPath"]
Check -->|否| Default
Default --> LoadDev{"是否开发环境?"}
UseRaw --> LoadDev
LoadDev -->|是| DevUrl["加载 devServerUrl + fullPath"]
LoadDev -->|否| FileUrl["加载 file:// 本地 index.html + hash"]
图示来源
章节来源
当前预加载入口创建托盘和安全服务,并尝试向全局暴露 electron.ipcRenderer。但窗口配置显式关闭 contextIsolation 并开启 nodeIntegration,因此:
require('electron');contextBridge.exposeInMainWorld 在当前模式下不是强制约束;若未来开启 contextIsolation,则需要把所有需要暴露的能力逐一改为受控方法,而不是直接透传 ipcRenderer。
graph LR
RP["渲染进程"] -->|当前可直接 require| NP["Node/Electron API"]
RP -->|可选| CB["contextBridge"]
CB -->|当前未强制| PM["主进程 IPC"]
NP -.-> PM
图示来源
章节来源
osCtl.js 暴露窗口控制、目录选择、本机文件读取、离线地图路径、外部链接打开、数据源上传等方法。其中与本地文件相关的关键能力包括:
readBinaryFileRange:分块读取二进制文件,主要用于离线地图瓦片;readTextFile:读取文本文件,例如离线地图样式;getMapLocalPath / setMapLocalPath:读取和保存本机离线地图目录;openUserDataFolder / openInstallFolder:打开用户数据目录和安装目录;selectDirectory:让用户选择目录。底层 os.js 提供 userData 路径、PMTiles 字节范围读取、工作区扫描等实现。
章节来源
当前 Electron 侧的主要依赖如下:
ee-core:提供应用框架、生命周期、配置、日志、路径、主窗口获取等能力;electron:提供 BrowserWindow、shell、app、screen 等桌面能力;electron-updater:更新能力;前端工程通过 Vite 构建,开发时由 cmd/bin.js 提供前端开发服务器配置。
graph TB
P["qingjian-ai-client<br/>package.json"] --> EE["ee-core"]
P --> EL["electron"]
P --> EU["electron-updater"]
EE --> EP["ee-bin"]
EP --> BIN["cmd/bin.js"]
图示来源
章节来源
| 数据类型 | 存储位置 | 控制方式 | 安全风险 |
|---|---|---|---|
| 客户端偏好设置 | getDataDir()/local-settings.json |
localSettingsService |
包含离线地图目录等路径,可能间接泄露工作区位置 |
| 下载清单 | getDataDir()/downloads.json |
DownloadService |
记录已下载文件路径、大小、时间、来源 |
| 下载文件 | 用户配置的下载目录,或系统下载目录 | DownloadService.getDownloadDir() |
大文件和敏感数据落盘 |
| 用户数据目录 | app.getPath('userData') |
os.js |
应用缓存、会话、SQLite 数据库等 |
| 离线地图目录 | 用户选择的绝对目录,保存在 local-settings.json |
osCtl.getMapLocalPath/setMapLocalPath |
可能指向工作区或含敏感数据的目录 |
| PMTiles 文件 | 离线地图目录下的 .pmtiles 文件 |
前端通过 pmtiles:// 协议 + 主进程范围读取 |
大型地理数据文件,可能包含敏感空间信息 |
| 工作区目录 | 后端按 <user.dir>/QingJian/workspace/<案件ID> 推导 |
前端通过接口获取 workspacePath |
案件数据、附件、日志等 |
| 安装包与公共资源 | getBaseDir() 对应安装目录 |
静态资源、图标、HTML | 一般不敏感,但可被替换攻击 |
章节来源
当前对敏感数据的保护主要体现为:
getBytes(offset, length),并做绝对路径和真实文件检查;但这些保护主要覆盖“写入下载目录”和“离线地图目录选择”,并不等于对所有本地文件读写的全面白名单。
章节来源
前端通过 offlineMap.ts 构造 pmtiles:// 协议地址,并由主进程通过 IPC 分块读取文件。这种方式避免了把整个 PMTiles 文件一次性加载到浏览器内存,但仍需注意:
local-settings.json。章节来源
现状:contextIsolation: false、nodeIntegration: true,意味着渲染进程中的业务代码可以执行任意 Node 命令、读写本地文件、访问网络、打开外部程序。
风险
local-settings.json,发现离线地图目录、下载目录、用户数据目录;shell.openPath 或系统命令造成系统级影响。建议
contextIsolation 设为 true,nodeIntegration 设为 false;webSecurity 保持为默认开启状态;contextBridge 暴露具体方法,如 openWorkbench、readBinaryFileRange、openExternal;require('electron') 或访问 process。章节来源
现状:预加载桥当前向全局暴露 electron.ipcRenderer,但主窗口并未启用上下文隔离,所以该暴露不是真正的最小权限边界。
风险
ipcRenderer,则等同于重新打开 IPC 直通;建议
exposeInMainWorld('electron', { ipcRenderer });openWorkbench(path);readBinaryFileRange({ filePath, offset, length });readTextFile({ filePath, encoding });openExternal(url);selectDirectory();showUserDataFolder();saveDownload(file);章节来源
现状:smartWindow.ts 对 fullPath 做了正则校验,只允许 /workbench 开头的路径;但该校验发生在智能工作台内部,且开发环境会从 cmd/bin.js 读取前端地址。
风险
/workbench 限制;bin.js 配置被篡改,可能加载非预期主机;allowlist 机制阻止任意远程 URL 加载。建议
file:// 的 index.html;cmd/bin.js 的配置增加版本签名或完整性校验。章节来源
现状:前端存在 HtmlBlock.vue,使用 iframe 并以 sandbox="allow-scripts" 渲染 HTML 内容,但没有 allow-same-origin。这是相对安全的做法,因为 sandbox 切断了同源能力。
风险
allow-same-origin、allow-forms、allow-popups 等,sandbox 防护会被削弱;建议
allow-same-origin;章节来源
现状:
readBinaryFileRange 和 readTextFile;pmtiles:// 协议驱动范围读取;风险
建议
readBinaryFileRange 增加文件大小上限、偏移和长度上限;章节来源
现状:
windowCtl.ts 提供跨窗口状态同步;osCtl.js 提供 openExternal;smartWindow.ts 负责智能工作台窗口创建和生命周期。风险
建议
openExternal 只允许 HTTPS 或已知协议白名单;syncState 事件增加来源校验和动作白名单;nodeIntegration、webview、devTools(生产环境)。章节来源
fullPath 是否符合 /workbench 前缀规则;cmd/bin.js 一致;smartWindowBounds 是否越界导致恢复失败。章节来源
local-settings.json 中离线地图目录是否为绝对路径;china.pmtiles;offlineMap.ts 构造的 pmtiles:// 地址是否正确;readBinaryFileRange 是否返回成功;章节来源
downloads.json 是否在数据目录而非下载目录;章节来源
当前 Electron 客户端在窗口控制和文件访问方面已经实现了部分主进程封装,包括智能工作台 URL 前缀校验、下载目录校验、文件名清理、PMTiles 范围读取、下载清单分离等。但整体安全模型仍存在明显隐患:渲染进程启用了 Node 集成且未启用上下文隔离,预加载桥也未形成最小权限边界。
短期建议:
长期建议:
contextIsolation: true 和 nodeIntegration: false;contextBridge 暴露精确方法;