Frp Manager

August 22, 2026 · View on GitHub

多公司 frp-panel 隧道接入台 —— 把 frp-panel-client（frp-panel 托管客户端）包装成多档案可视化桌面工具。一台工作机同时接入多家公司的内网穿透通道，以"配线架"视角统一监控与调度。

基于 frp-panel-client v0.1.37（实测各行为）构建，Electron + React + TypeScript。

功能

模块	说明
多档案连接管理	每个公司一个档案（master API/RPC 地址、clientId/secret），独立进程、独立日志，并行运行
状态可视化（配线架）	每条连接 = 一个端口：乙烯基编号砖、状态 LED、光纤通道（在线=青色光芯流动、重连=琥珀呼吸、停止=暗槽断线）、活动行按状态染色描边光晕
一键解析指令	粘贴管理员下发的命令（`client -s … -i … --api-url … --rpc-url …`）自动填充表单；兼容废弃短参与 `KEY=VALUE` 环境变量形态，未知 token 不中断仅告警
日志	逐行捕获（ANSI 剥离 + 结构化解析 `{ts, level, src, msg}`），实时推送、级别过滤、跟随滚动；环形缓冲保留最近 1000 行
二进制托管	系统文件选择器选 `frp-panel-client` → `frp-panel version` 校验 → 复制到应用目录 `bin/`（自动执行权限、可覆盖换版）
拖拽排序	手柄按住即放大浮起（dnd-kit），列表实时交换，松手持久化；键盘也可操作（Tab 聚焦 + 空格拖动）
主题	暗色 / 亮色 / 跟随系统（实时响应操作系统切换），工具栏一键切换
跨平台	Windows / macOS / Linux（electron-builder：NSIS / DMG / AppImage）

快速开始

# 依赖（electron 二进制下载慢时可设镜像）
export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
npm install

# 开发模式（HMR）
npm run dev

# 类型检查 / 构建
npm run typecheck
npm run build

打包与分发：

npm run build:win   # NSIS 安装包
npm run build:mac   # DMG
npm run build:linux # AppImage

使用

配置二进制（首次必做）：设置（齿轮）→「选择二进制文件」→ 选中 frp-panel-client 平台对应二进制 → 校验失败会回显原因；版本显示 ✓ 即成功
创建档案：右上角「+」「新增连接」→ 两种方式：
- 贴链接：+ 新增连接 → 「一键解析」框内粘贴管理员下发的命令 → 解析填充 → 保存
- 手工：填写名称 / apiUrl / rpcUrl / clientId / clientSecret
启动：端口上点「启动」→ 观察 LED/光纤 → 「停止/重启」悬浮或运行态显现；错误行红字常驻
日志：点名称或「日志」图标打开抽屉，实时流 + 历史回看 + 级别过滤
排序：拖住行首六点手柄上下移动，目标行上缘出现青色插入线，松手即换位（重启保持）

架构速览

Electron Main（TS）：Profile 档案（electron-store + safeStorage 字段级加密）
                    ↓ spawn（flags 传参, cwd=档案目录, 进程组管理）
          每档案一个 frp-panel-client 子进程
                    ↓ stdout 捕获 → ANSI 剥离 → 结构化解析 → 环形缓冲/落盘
状态机：stopped → starting → running → online ⇄ reconnecting → error（指数退避重启）
renderer（React）：sandbox + contextBridge 严格 IPC，特权操作全部在主进程

存储：userData/profiles.json（敏感字段 safeStorage 加密）+ 每档案 workDir/.env 调试镜像（单向同步，仅为可复现）
约定：对外永远明文，仅落盘一瞬加密；跨层剥壳（decryptPeeled）自愈历史多层密文
说明：frp-panel-client 是"被管理端"，隧道代理配置由各公司 master 下发，本工具管理的是连接档案与进程，不越权修改 master 配置

目录结构

src/
├─ shared/        三端共享类型 + cliParse（一键解析纯函数）
├─ main/
│  ├─ index.ts    入口（单实例锁 / 退出收割 / 冒烟模式）
│  ├─ ipc.ts      IPC 注册与事件推送
│  ├─ store/      profiles/settings（electron-store）+ crypto（safeStorage）
│  ├─ client/     manager（生命周期）spawner（flags 传参）
│  │              binaryCore/binaryInstaller（二进制托管）logline（解析）
│  └─ mock.ts     FRP_MOCK 测试基础设施（截图回归 / UI e2e）
├─ preload/       contextBridge 类型安全桥（sandbox 零依赖）
└─ renderer/      React 界面（配线架端口 / 表单 / 日志抽屉 / 设置）
docs/             技术方案 + 开发问题实录（13 个坑的完整复盘）

开发与测试

npm run typecheck  # 三端类型检查
npm run lint
npm run format

# 无头环境视觉回归（配合 xvfb-run）
FRP_MOCK=1 FRP_THEME=dark FRP_SHOT=shot.png xvfb-run -a npm run dev
# UI e2e（真实指针拖拽排序 / 二进制区渲染 / 事件到达性）
FRP_MOCK=1 FRP_UI_TEST=reorder-real xvfb-run -a npm run dev

环境变量（仅开发）：FRP_MOCK（播种假档案）/ FRP_SHOT（截图路径）/ FRP_THEME（强制主题）/ FRP_UI_TEST（脚本化交互回归）/ FRP_SMOKE（主进程冒烟）。

已知限制

同一 clientID 同一时刻只允许一条活跃连接（frp-panel master 规则）：本机多进程/多机同时使用同一档案会被拒（日志表现为 invalid secret）——客户端请统一从本工具启停
FRP_LOGGER_LEVEL 环境变量在 v0.1.37 实测不生效（字段保留）
CLI 自带的 install/start/stop（systemd 服务）仅 Linux，本工具不用；进程生命周期由应用管理
打包后项目目录只读，二进制托管地址为系统 userData/bin/
logLevel/autoStart 字段已存储，autoStart 自动拉起逻辑待接通

致谢

VaalaCat/frp-panel —— 底层 frp-panel master/client 体系
dnd-kit —— 拖拽排序组件库
electron-vite —— 构建工具链