Electron 安全边界与本地文件保护.md 27 KB

Electron 安全边界与本地文件保护

**本文引用的文件 **

  • main.ts
  • windowCtl.ts
  • smartWindow.ts
  • windowOptions.ts
  • config.default.ts
  • preload/index.ts
  • preload/bridge.ts
  • lifecycle.ts
  • osCtl.js
  • localSettings.js
  • downloadService.js
  • os.js
  • HtmlBlock.vue
  • offlineMap.ts
  • package.json

目录

  1. 引言
  2. 项目结构
  3. 核心安全模型
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 本地敏感数据与文件保护
  8. 安全风险与防护建议
  9. 故障排查
  10. 结论

引言

本文面向清鉴 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

图示来源

  • package.json:1-20
  • main.ts:1-19
  • config.default.ts:1-50
  • windowOptions.ts:1-41
  • smartWindow.ts:1-60
  • windowCtl.ts:1-30
  • osCtl.js:1-30
  • localSettings.js:1-25
  • downloadService.js:1-30

章节来源

  • package.json:1-20
  • main.ts:1-19

核心安全模型

当前 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 代码,不应直接信任其输入

为什么不应直接暴露 Node/Electron API

  1. 渲染进程可能被恶意内容利用:如果 HTML 视图、模板、第三方页面进入渲染进程,它们就可能获得文件系统、网络、外壳打开、窗口控制等能力。
  2. IPC 是更好的审计面:把文件读取、目录选择、外部链接打开、下载、窗口管理集中在主进程 controller 中,便于校验参数、记录日志、拒绝非法请求。
  3. Context isolation + context bridge 才是标准模式:只暴露明确的方法名和数据类型,避免把整个 ipcRenderer 或 process 对象传给渲染进程。
  4. 当前实现存在矛盾:预加载桥注释说明“启用上下文隔离后通过 contextBridge 导出 API”,但窗口配置又显式关闭了上下文隔离并开启 Node 集成,因此当前真正限制渲染进程能力的并不是这个桥。

章节来源

  • windowOptions.ts:5-14
  • config.default.ts:10-26
  • preload/bridge.ts:1-10
  • preload/index.ts:1-16

架构总览

下图展示当前应用中主进程、预加载、渲染进程、控制器和服务之间的关系,以及两个窗口:主窗口和智能工作台窗口。

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}"

图示来源

  • windowCtl.ts:20-48
  • smartWindow.ts:40-110
  • smartWindow.ts:110-170
  • osCtl.js:80-140

章节来源

  • windowCtl.ts:1-123
  • smartWindow.ts:1-232
  • osCtl.js:1-169

详细组件分析

主进程与生命周期

主进程使用 ElectronEgg 框架注册 ready、electron-app-ready、window-ready、before-close 生命周期,并注册 preload。生命周期负责:

  • 处理双击图标时聚焦已有窗口;
  • 优先拉回智能工作台窗口;
  • 设置主窗口居中、按比例缩放;
  • 根据配置决定是否延迟显示窗口。

这些逻辑本身不直接暴露危险能力,但它是所有窗口和资源加载的起点。

章节来源

  • main.ts:1-19
  • lifecycle.ts:1-73

窗口控制器 windowCtl

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 : "委托窗口行为"
    

图示来源

  • windowCtl.ts:20-110
  • smartWindow.ts:40-90

章节来源

  • windowCtl.ts:1-123

智能工作台窗口 smartWindow

智能工作台是一个单例窗口,职责包括:

  • 保证最多只有一个工作台窗口;
  • 已存在时只做恢复、聚焦、选择性重载或导航;
  • 渲染进程崩溃后销毁空壳窗口;
  • 保存和恢复窗口 bounds;
  • 严格限制 fullPath 必须以 /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"]
    

图示来源

  • smartWindow.ts:110-170

章节来源

  • smartWindow.ts:1-232

预加载桥接与上下文隔离现状

当前预加载入口创建托盘和安全服务,并尝试向全局暴露 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
    

图示来源

  • preload/bridge.ts:1-10
  • windowOptions.ts:5-14

章节来源

  • preload/index.ts:1-16
  • preload/bridge.ts:1-10
  • windowOptions.ts:5-14

系统能力与本地文件读取

osCtl.js 暴露窗口控制、目录选择、本机文件读取、离线地图路径、外部链接打开、数据源上传等方法。其中与本地文件相关的关键能力包括:

  • readBinaryFileRange:分块读取二进制文件,主要用于离线地图瓦片;
  • readTextFile:读取文本文件,例如离线地图样式;
  • getMapLocalPath / setMapLocalPath:读取和保存本机离线地图目录;
  • openUserDataFolder / openInstallFolder:打开用户数据目录和安装目录;
  • selectDirectory:让用户选择目录。

底层 os.js 提供 userData 路径、PMTiles 字节范围读取、工作区扫描等实现。

章节来源

  • osCtl.js:1-169
  • os.js:30-70
  • os.js:130-180

依赖关系分析

当前 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"]
    

图示来源

  • package.json:1-42

章节来源

  • package.json:1-42

本地敏感数据与文件保护

数据存储位置总览

数据类型 存储位置 控制方式 安全风险
客户端偏好设置 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 一般不敏感,但可被替换攻击

章节来源

  • localSettings.js:1-53
  • downloadService.js:1-120
  • os.js:30-45
  • os.js:130-180
  • offlineMap.ts:1-40

敏感配置与访问控制

当前对敏感数据的保护主要体现为:

  1. 下载目录校验:只接受绝对路径,必须存在且必须是目录;
  2. 离线地图目录校验:同样要求绝对路径、存在、是目录;
  3. 文件名清理:下载文件名去掉路径分隔符和非法字符,防止路径穿越;
  4. PMTiles 范围读取:底层强调只支持 getBytes(offset, length),并做绝对路径和真实文件检查;
  5. 清单分离:下载清单放在数据目录,不与用户下载目录混在一起;
  6. 最大条目限制:下载清单最多保留 300 条。

但这些保护主要覆盖“写入下载目录”和“离线地图目录选择”,并不等于对所有本地文件读写的全面白名单。

章节来源

  • downloadService.js:60-120
  • osCtl.js:100-150
  • os.js:60-70

PMTiles 与离线地图的安全路径

前端通过 offlineMap.ts 构造 pmtiles:// 协议地址,并由主进程通过 IPC 分块读取文件。这种方式避免了把整个 PMTiles 文件一次性加载到浏览器内存,但仍需注意:

  • PMTiles 文件通常很大,可能包含敏感地理数据;
  • 如果离线地图目录被设置为工作区或其他敏感目录,PMTiles 访问路径就等价于“部分文件读取通道”;
  • 应确保离线地图目录不能由不可信 HTML 视图动态设定,而只能由可信界面经用户确认后写入 local-settings.json。

章节来源

  • offlineMap.ts:1-40
  • offlineMap.ts:35-73

安全风险与防护建议

风险一:渲染进程具备 Node 能力

现状:contextIsolation: false、nodeIntegration: true,意味着渲染进程中的业务代码可以执行任意 Node 命令、读写本地文件、访问网络、打开外部程序。

风险

  • 恶意 HTML 视图、模板、第三方页面可窃取本地文件;
  • 恶意内容可读取 local-settings.json,发现离线地图目录、下载目录、用户数据目录;
  • 恶意内容可通过 shell.openPath 或系统命令造成系统级影响。

建议

  1. 将 contextIsolation 设为 true,nodeIntegration 设为 false;
  2. 将 webSecurity 保持为默认开启状态;
  3. 仅通过 contextBridge 暴露具体方法,如 openWorkbench、readBinaryFileRange、openExternal;
  4. 对每个 IPC 方法做参数白名单校验;
  5. 禁止渲染进程直接 require('electron') 或访问 process。

章节来源

  • windowOptions.ts:5-14
  • config.default.ts:10-26
  • preload/bridge.ts:1-10

风险二:预加载桥未形成有效边界

现状:预加载桥当前向全局暴露 electron.ipcRenderer,但主窗口并未启用上下文隔离,所以该暴露不是真正的最小权限边界。

风险

  • 如果未来开启上下文隔离,却仍暴露 ipcRenderer,则等同于重新打开 IPC 直通;
  • 即使当前 Node 集成可用,也应尽早收敛到“只暴露必要方法”。

建议

  • 移除 exposeInMainWorld('electron', { ipcRenderer });
  • 新增明确方法,例如:
    • openWorkbench(path);
    • readBinaryFileRange({ filePath, offset, length });
    • readTextFile({ filePath, encoding });
    • openExternal(url);
    • selectDirectory();
    • showUserDataFolder();
    • saveDownload(file);
  • 所有方法在主进程 controller 中校验路径、大小、MIME、来源。

章节来源

  • preload/bridge.ts:1-10
  • windowCtl.ts:20-48
  • osCtl.js:80-169

风险三:智能工作台 URL 白名单不够严格

现状:smartWindow.ts 对 fullPath 做了正则校验,只允许 /workbench 开头的路径;但该校验发生在智能工作台内部,且开发环境会从 cmd/bin.js 读取前端地址。

风险

  • 如果未来新增其他窗口或视图入口,可能绕过 /workbench 限制;
  • 开发环境 URL 解析容错较强,若 bin.js 配置被篡改,可能加载非预期主机;
  • 没有全局的 allowlist 机制阻止任意远程 URL 加载。

建议

  1. 维护全局允许的窗口 URL 白名单,包括:
    • 本地 file:// 的 index.html;
    • 开发服务器固定 host/port;
    • 必要时允许的后端 API 域名;
  2. 对智能工作台以外的窗口也实施相同白名单;
  3. 禁止从业务数据、用户输入、URL query、模板中拼接最终 loadURL;
  4. 对 cmd/bin.js 的配置增加版本签名或完整性校验。

章节来源

  • smartWindow.ts:110-170

风险四:恶意 HTML 视图加载

现状:前端存在 HtmlBlock.vue,使用 iframe 并以 sandbox="allow-scripts" 渲染 HTML 内容,但没有 allow-same-origin。这是相对安全的做法,因为 sandbox 切断了同源能力。

风险

  • 如果未来误加 allow-same-origin、allow-forms、allow-popups 等,sandbox 防护会被削弱;
  • 如果 HTML 来自用户上传或后端生成,仍可能触发 XSS 或脚本执行;
  • sandbox 不等于零风险,应避免让不受信任内容访问 Electron 能力。

建议

  1. 保持 sandbox 最小权限,不添加 allow-same-origin;
  2. 不对用户提供的 HTML 注入 Electron API;
  3. 如需与主进程通信,只能通过主进程 IPC,而不能直接访问 Node;
  4. 对 HTML 内容进行 DOM 清洗和长度限制;
  5. 在部署产物中对静态 HTML 进行完整性校验。

章节来源

  • HtmlBlock.vue:20-40

风险五:本地文件泄露与跨域读取

现状:

  • 主进程提供 readBinaryFileRange 和 readTextFile;
  • 离线地图目录由用户选择并保存在本地设置;
  • PMTiles 通过 pmtiles:// 协议驱动范围读取;
  • 下载清单记录本地文件路径。

风险

  • 如果渲染进程可直接调用 Node,则无需经过 IPC;
  • 如果 IPC 参数未充分校验,可能读取任意本地文件;
  • 离线地图目录如果被设置为工作区,PMTiles 访问可能成为敏感数据通道;
  • 下载清单可能泄露用户下载的文件名、路径和时间。

建议

  1. 所有文件读取必须走主进程 controller;
  2. 对 filePath 做绝对路径校验、路径规范化、根目录白名单;
  3. 对 readBinaryFileRange 增加文件大小上限、偏移和长度上限;
  4. 对 PMTiles 文件类型做后缀白名单;
  5. 对下载清单中的敏感路径脱敏后再传给前端;
  6. 不在日志中打印 token、密钥、完整工作区路径。

章节来源

  • osCtl.js:80-150
  • downloadService.js:60-120
  • localSettings.js:1-53
  • offlineMap.ts:35-73

风险六:弹窗与外部链接

现状:

  • windowCtl.ts 提供跨窗口状态同步;
  • osCtl.js 提供 openExternal;
  • smartWindow.ts 负责智能工作台窗口创建和生命周期。

风险

  • 外部链接可由业务页面发起,若 URL 来源不可信,可能钓鱼或跳转到恶意站点;
  • 跨窗口同步事件可能被渲染进程伪造;
  • 多窗口环境下,弹窗和子窗口可能绕过主窗口的安全策略。

建议

  1. openExternal 只允许 HTTPS 或已知协议白名单;
  2. 对用户输入的链接先解析再校验 scheme、host、port;
  3. 对 syncState 事件增加来源校验和动作白名单;
  4. 对所有新窗口统一套用最小权限 windowOptions;
  5. 禁用不必要的 nodeIntegration、webview、devTools(生产环境)。

章节来源

  • windowCtl.ts:70-110
  • osCtl.js:150-169
  • smartWindow.ts:1-40

故障排查

智能工作台无法打开或停留在旧页面

  • 检查 fullPath 是否符合 /workbench 前缀规则;
  • 检查开发环境前端端口是否与 cmd/bin.js 一致;
  • 查看智能窗口是否因渲染进程崩溃被销毁,需要重新打开;
  • 确认 smartWindowBounds 是否越界导致恢复失败。

章节来源

  • smartWindow.ts:40-110
  • smartWindow.ts:170-232

离线地图无法加载 PMTiles

  • 检查 local-settings.json 中离线地图目录是否为绝对路径;
  • 检查目录下是否存在 china.pmtiles;
  • 检查前端 offlineMap.ts 构造的 pmtiles:// 地址是否正确;
  • 检查主进程 readBinaryFileRange 是否返回成功;
  • 确认离线地图目录未被误设为不可读路径。

章节来源

  • offlineMap.ts:1-40
  • osCtl.js:100-140
  • localSettings.js:1-53

下载清单与实际文件不一致

  • 检查应用重启后是否把“下载中”记录标记为失败;
  • 检查 downloads.json 是否在数据目录而非下载目录;
  • 检查文件名是否被清理导致与原始名称不同;
  • 检查目标目录权限是否允许写入。

章节来源

  • downloadService.js:1-120

结论

当前 Electron 客户端在窗口控制和文件访问方面已经实现了部分主进程封装,包括智能工作台 URL 前缀校验、下载目录校验、文件名清理、PMTiles 范围读取、下载清单分离等。但整体安全模型仍存在明显隐患:渲染进程启用了 Node 集成且未启用上下文隔离,预加载桥也未形成最小权限边界。

短期建议:

  • 停止信任渲染进程输入;
  • 将所有文件读取、目录操作、外部链接打开、窗口创建收敛到主进程 controller;
  • 对 IPC 参数做路径、大小、类型、来源校验;
  • 对智能工作台和其他窗口建立全局 URL 白名单。

长期建议:

  • 启用 contextIsolation: true 和 nodeIntegration: false;
  • 用 contextBridge 暴露精确方法;
  • 对敏感配置文件和日志进行加密或脱敏;
  • 对工作区、离线地图目录、PMTiles 文件实施更严格的访问白名单;
  • 对打包产物和静态资源进行完整性校验。