frpc-desktop 仓库开发指南：从工程布局、构建流程到 Electron 主进程架构约定

• 桌面应用
• 网络

导读

本文以开源仓库 luckjiawei/frpc-desktop 的官方开发指南（AGENTS.md）为主体，结合仓库内真实源码，系统梳理该跨平台 FRP 桌面客户端的工程布局、常用命令、主进程分层调用链（renderer → IPC route → controller → service/repository）、数据与安全约束以及文档维护规范。读完本文，你既能快速上手本地开发与构建，也能理解“新增一个 IPC 功能”时各参与方（路由、控制器、服务、渲染层）应该分别改哪里，以及仓库对代码风格、双语文案、数据库兼容与提交信息的具体要求。

1. 项目概览与技术栈

AGENTS.md开篇即给出定位：Frpc-Desktop 是一个跨平台的 Electron 桌面应用，核心职责是可视化配置 frp 并管理 frpc 进程，实现内网穿透。

• 渲染进程（Renderer）：Vue 3 + TypeScript + Vite + Pinia + Vue Router + Element Plus + vue-i18n，负责界面呈现与用户交互。
• 主进程（Main Process）：负责 frpc 进程管理、本地持久化（SQLite / NeDB）、frp 版本下载、系统集成（托盘、开机启动等）以及 IPC 通信。

这一点在 package.json 中得到印证：dependencies中既有vue、pinia、element-plus、vue-i18n等渲染层依赖，也有better-sqlite3（SQLite 持久化）、nedb（旧版数据兼容迁移）、electron-log（日志）、adm-zip/tar（frp 压缩包解压）、tree-kill（进程树终止）、smol-toml（frpc.toml 解析）等主进程依赖。

开发环境要求：Node.js 22.12 或更新版本，使用 npm 管理依赖。AGENTS.md 同时强调：保持改动聚焦，不要编辑生成产物或下载的依赖。

2. 仓库布局速览

AGENTS.md 对目录结构给出了明确的职责划分，与仓库实际文件一一对应：

从源码结构看，主进程内部还细分为database/（DatabaseManager.ts与migrations/）、utils/（PathUtils、ResponseUtils、SecureUtils等）、core/（BeanFactory、IpcRouter、Logger、BusinessError）等子模块，属于纯渲染层问题（样式、交互状态）与纯主进程问题（文件系统、进程、网络、数据库、OS 行为）被严格分开。

3. 常用命令与构建流程

AGENTS.md 给出的四条基础命令，对应 package.json 的scripts：

npm ci # 按 package-lock.json 精确安装依赖 npm run dev # 启动 Vite/Electron 开发应用 npm run lint # 对 src/ 与 electron/ 下的 .ts/.tsx/.vue 执行 ESLint npm run build # 先跑 vue-tsc --noEmit 类型检查，再执行 Vite 生产构建

关键细节：

• npm run dev启动开发应用：主进程读取VITE_DEV_SERVER_URL（见 package.json 中 debug 配置，默认http://127.0.0.1:3344/）加载 Vite 开发服务器，并自动打开 DevTools（见 electron/main/index.ts 中loadURL(url)分支）。
• npm run build在 Vite 构建之前先执行vue-tsc --noEmit，因此类型错误会直接中断生产构建。
• 打包命令按平台拆分：build:electron:mac、build:electron:win、build:electron:linux（以及build:electron:all），AGENTS.md 明确指出打包不是常规验证步骤，日常改动只需通过 lint 与 build。
• 仓库目前没有自动化测试脚本。AGENTS.md 要求：普通代码改动跑 lint 与 build；涉及 UI 或 Electron 行为的改动，还需在开发应用中手工演练受影响的工作流，并在提交时说明已验证了哪些内容。

4. 主进程架构与分层调用链约定

4.1 固定的调用链：renderer → IPC route → controller → service/repository

AGENTS.md 要求遵循固定的主进程调用流：

renderer → IPC route → controller → service/repository

• Controller 层负责把业务结果翻译成统一响应，失败时通过Logger记录。真实实现见 electron/utils/ResponseUtils.ts：成功返回{ bizCode, data, message }（bizCode取自ResponseCode.SUCCESS中;分隔的前半段），失败时把普通Error包装为BusinessError(ResponseCode.INTERNAL_ERROR)再输出{ bizCode, data: null, message }。
• 路由层的唯一权威定义在 electron/core/IpcRouter.ts。该文件导出一个ipcRouters对象，按业务域分组（SERVER、LOG、VERSION、LAUNCH、PROXY、SYSTEM），每个条目声明path（IPC 通道名）与controller（beanName.方法名字符串）。例如：

SERVER: { saveConfig: { path: "server/saveConfig", controller: "configController.saveConfig" }, ... }

• 装配逻辑在 electron/main/index.ts 的initializeRouters()：遍历ipcRouters，用ipcMain.on(router.path, ...)注册监听，收到请求后按controller字符串从BeanFactory取出对应 Bean 并调用方法，同时以Logger.debug记录每个请求的路由、通道与参数。这意味着新增 IPC 接口时，只需在 IpcRouter 声明路径与控制器映射，主进程即自动完成注册。
• 监听通道则由listeners导出：当前注册了frpcProcessService.watchFrpcProcess（通道frpcProcess:watchFrpcLog）与systemService.getSystemUsage（通道system:watchSystemUsage），由initializeListeners()统一初始化。

4.2 Bean 容器：BeanFactory 与手工装配

主进程的依赖管理采用轻量级的BeanFactory（见 electron/core/BeanFactory.ts），提供setBean/getBean/hasBean，Bean 名默认取类名首字母小写（getBeanName）。值得说明的是：

• 仓库electron/core/annotation/下的Component.ts与Resource.ts目前只是注释掉的占位实现，并未实际使用装饰器自动装配。
• 实际装配发生在 electron/main/index.ts 的initializeBeans()：按固定顺序注册 repository → service → controller（例如serverService依赖serverRepository与proxyRepository，proxyController依赖proxyService与proxyRepository）。从源码结构看，新增 service/repository/controller 时必须通过 BeanFactory 注册，且要遵守既有初始化顺序，否则依赖注入会失败。

4.3 启动时序与关键配置项

从 electron/main/index.ts 的initializeElectronApp()可以还原完整的启动时序：

1. 禁用 Windows 7（OS 版本6.1）的 GPU 加速，设置 Windows 通知 AppUserModelId；
2. requestSingleInstanceLock()保证单实例运行，二次启动触发second-instance事件并唤起主窗口；
3. app.whenReady()后：初始化DatabaseManager（SQLite）→ 创建各 Repository → 执行NedbMigrationService.migrate()迁移旧数据 →initializeBeans()→initializeRouters()→ 读取服务端配置并设置日志级别 → 创建窗口；
4. 窗口did-finish-load后启动后台任务：初始化监听器与托盘，随后依据配置决定startFrpcProcess()（autoConnectOnStartup）或restoreExistingProcess()。

其中两个配置项直接来自服务端配置：system.silentStartup（静默启动，不自动显示窗口）与system.autoConnectOnStartup（启动时自动连接 frpc）。窗口还有“最小化/关闭即隐藏到托盘”的行为（darwin平台同时隐藏 Dock 图标），退出时先stopFrpcProcess()再app.quit()。

5. 变更与提交约定

AGENTS.md 对代码变更提出了一系列强约束，是参与该仓库开发前必须了解的“契约”：

1. 关注点分离：渲染层只关心呈现与状态；文件系统、进程、网络、数据库、OS 行为一律放在electron/下。
2. 新增 IPC 行为必须联动全部参与方：路由（electron/core/IpcRouter.ts）、控制器注册/装配（electron/main/index.ts）、controller/service 实现、渲染层监听或发送；当组件作用域的订阅可被重建时，应移除旧监听。
3. Bean 注册：通过BeanFactory使用既有名称与初始化顺序注册新 service/repository/controller。
4. 类型集中：跨进程的公共接口放在types/（如types/core.d.ts、types/frp.d.ts），避免在 Vue 组件里重复定义载荷形状。
5. 双语必达：所有用户可见文案必须同时支持src/lang/en-US.ts与src/lang/zh-CN.ts，并保留 frp/frpc 既有术语。
6. 代码风格：保留现有格式——两个空格缩进、双引号、分号、Prettier 规则下的尾逗号，遵循 ESLint 与 Prettier 约束；渲染层导入用@/别名，Electron 代码一般用相对导入。
7. 避免无关改动：不做无关重构、大范围格式改动或依赖升级。

6. 数据与安全约束

AGENTS.md 用专门一节强调数据与安全，仓库实现也处处对应：

• 敏感数据处理：配置、token、代理定义、日志与本地路径均视为敏感信息。不得在日志中打印密钥，也不得在 fixtures、截图或示例中放置真实凭据。日志封装见 electron/core/Logger.ts：默认info级别，可通过服务端配置的log.level动态调整文件与控制台输出级别。
• 数据兼容性：必须保留对既有 NeDB 数据与 frpc 配置格式的兼容；任何 schema 或文件名变更都需要显式迁移或向后兼容的 fallback。仓库目前采用“双轨”方案：新版数据落在 SQLite（electron/database/DatabaseManager.ts 中frpc-desktop.sqlite3，启用 WAL、外键、integrity_check校验，并按migrations/目录下NNN_name.sql顺序执行迁移），旧 NeDB 数据则由 electron/database/NedbMigrationService.ts 迁移导入。
• IPC 入参校验：渲染层传入的 IPC 参数必须在主进程内先校验，再用于路径、shell 操作、下载或进程命令——这是防止路径穿越与命令注入的基本防线。

7. 文档规范与提交信息

AGENTS.md 最后强调文档与提交的纪律：

• UI 标准：规范性的前端 UI 开发标准文档是 docs/FRONTEND_UI_STANDARDS.md，创建或修改渲染层 UI、布局、样式、交互状态、图标或用户文案前必须先阅读并遵循。
• 数据库设计：规范性的数据库设计与迁移文档是 docs/DATABASES.md，修改持久化模型、SQLite schema 或迁移、repository、数据库路径或数据兼容行为前必须先阅读并遵循。仓库内已有 001_initial_schema.sql 与 002_tls2raw_plugin.sql 两份迁移脚本可供对照。
• README 同步：改变用户可见的安装/行为说明时，需同时更新 README.md 与 README.zh_CN.md。
• 提交信息：提交主题保持简短，尽可能遵循仓库既有 emoji 前缀历史习惯（例如🐛 Fix ...、✨ Add ...、🔧 Update ...）；不提交构建产物或本地应用数据。

8. 实战：新增一个 IPC 接口的完整清单

综合 AGENTS.md 的约定与源码装配逻辑，以“新增一个查询/操作接口”为例，开发者需要依次完成：

1. 服务层：在electron/service/下实现业务逻辑（如ProxyService的增删改查，参考 electron/service/ProxyService.ts）。
2. 控制器层：在electron/controller/下实现适配方法，成功用ResponseUtils.success返回，异常用ResponseUtils.fail包装并用Logger记录。
3. 路由声明：在 electron/core/IpcRouter.ts 的对应业务域分组中新增path与controller映射（initializeRouters()会自动注册ipcMain.on）。
4. Bean 注册：在 electron/main/index.ts 的initializeBeans()中按既有顺序注册新 Bean，并处理依赖。
5. 渲染层对接：通过src/utils/ipcUtils.ts发送/监听对应通道，组件销毁时清理监听。
6. 入参校验：主进程侧先校验渲染层参数，再触碰路径、进程或网络。
7. 文案与文档：涉及用户可见文案时同步更新 src/lang/en-US.ts 与 src/lang/zh-CN.ts；涉及持久化则先读 docs/DATABASES.md；最后跑npm run lint与npm run build验证。

按此清单操作，即可保证改动与该仓库既定的架构约束、安全底线与代码风格完全对齐。

结语

AGENTS.md篇幅不长，却浓缩了这个项目最重要的工程契约：目录边界、构建命令、IPC 分层调用链、Bean 装配方式、数据兼容与安全底线、文档与提交纪律。结合 electron/main/index.ts、electron/core/IpcRouter.ts 等源码对照阅读，即可将每一条约定落到具体文件与函数，快速具备在该仓库内安全、合规地开展开发与评审的能力。

• 桌面应用
• 网络