491 lines
22 KiB
Markdown
491 lines
22 KiB
Markdown
---
|
||
AIGC:
|
||
ContentProducer: '001191110102MAD55U9H0F10002'
|
||
ContentPropagator: '001191110102MAD55U9H0F10002'
|
||
Label: '1'
|
||
ProduceID: '1148f2f2-715c-4f80-80d7-010cab5af4b0'
|
||
PropagateID: '1148f2f2-715c-4f80-80d7-010cab5af4b0'
|
||
ReservedCode1: '57f1878c-c8f1-41ec-9020-31dae82dcead'
|
||
ReservedCode2: '57f1878c-c8f1-41ec-9020-31dae82dcead'
|
||
---
|
||
|
||
# WFJ Panel 项目说明文档
|
||
|
||
## 一、项目概述
|
||
|
||
WFJ Panel 是一款基于 Electron + React + ssh2 构建的**远程服务器管理面板**桌面应用，通过 SSH 协议远程连接 Linux 服务器，提供服务器概览监控、文件管理、交互式终端、Docker 容器管理、应用商店一键部署、防火墙管理等功能。
|
||
|
||
- **产品名称**：WFJ Panel
|
||
- **版本**：v0.0.1
|
||
- **许可**：MIT
|
||
- **构建产物**：NSIS 安装程序（Windows x64，约 107MB）
|
||
|
||
---
|
||
|
||
## 二、技术栈
|
||
|
||
| 层级 | 技术 | 说明 |
|
||
|------|------|------|
|
||
| 桌面框架 | Electron 44 + electron-vite 5 | 跨平台桌面应用，Vite 驱动构建 |
|
||
| 前端框架 | React 19 | 函数组件 + Hooks |
|
||
| 终端模拟 | @xterm/xterm 5 + @xterm/addon-fit | 交互式终端渲染 |
|
||
| SSH 通信 | ssh2 1.17 | 纯 JS 实现的 SSH2 客户端 |
|
||
| 打包工具 | electron-builder 26 | NSIS 安装包 |
|
||
| 后端服务 | Flask 3 + mysql-connector-python | 应用商店 API 服务 |
|
||
| 数据库 | MySQL 8 | 应用商店模板与版本数据 |
|
||
|
||
---
|
||
|
||
## 三、项目结构
|
||
|
||
```
|
||
ssh_panel/
|
||
├── package.json # 项目元数据、依赖、构建配置
|
||
├── electron.vite.config.mjs # electron-vite 配置（main/preload/renderer 三入口）
|
||
├── .npmrc # Electron 国内镜像配置
|
||
├── .gitignore
|
||
├── build/
|
||
│ └── icon.png # 应用图标 (256x256)
|
||
├── src/
|
||
│ ├── main/
|
||
│ │ └── index.js # ★ 主进程（1377行）—— SSH 连接、IPC、Docker、部署、SFTP、终端
|
||
│ ├── preload/
|
||
│ │ └── index.js # ★ Preload 桥接层 —— 暴露 window.panel API（90行）
|
||
│ └── renderer/
|
||
│ ├── index.html # HTML 入口
|
||
│ └── src/
|
||
│ ├── main.jsx # React 挂载入口
|
||
│ ├── App.jsx # ★ 根组件 —— 登录/面板切换、连接状态管理
|
||
│ ├── theme.css # 设计令牌（色彩/间距/阴影/按钮体系）
|
||
│ ├── main.css # 全局样式
|
||
│ └── pages/
|
||
│ ├── Login.jsx # SSH 登录页（凭据保存/自动填充）
|
||
│ ├── Panel.jsx # ★ 主面板（导航栏 + 功能模块切换 + 版本更新）
|
||
│ ├── overview/ # 服务器概览监控
|
||
│ │ ├── Overview.jsx
|
||
│ │ ├── useMetric.js # 通用指标采集 Hook
|
||
│ │ └── cards/ # CPU/内存/硬盘/网络/进程 五张卡片
|
||
│ ├── files/ # SFTP 远程文件管理
|
||
│ │ └── FileManager.jsx
|
||
│ ├── terminal/ # 交互式终端
|
||
│ │ └── TerminalPanel.jsx
|
||
│ ├── container/ # Docker 容器管理
|
||
│ │ ├── ContainerPanel.jsx # 容器面板入口（状态检测+子菜单）
|
||
│ │ ├── ContainerList.jsx # 容器列表（启动/停止/删除/日志）
|
||
│ │ ├── ImageList.jsx # 镜像列表
|
||
│ │ ├── AppStore.jsx # ★ 应用商店（在线模板+一键部署）
|
||
│ │ ├── TaskCenter.jsx # 后台部署任务中心
|
||
│ │ ├── DockerConfig.jsx # Docker 配置文件查看/编辑
|
||
│ │ ├── NetworkPanel.jsx # Docker 网络管理
|
||
│ │ ├── VolumePanel.jsx # Docker 卷管理
|
||
│ │ ├── ContainerCreate.jsx # 手动创建容器
|
||
│ │ ├── DockerLog.jsx # 容器日志查看
|
||
│ │ ├── cmdParser.js # docker run 命令解析
|
||
│ │ └── appTemplates.js # 内置应用模板（离线备用）
|
||
│ └── firewall/ # 系统防火墙管理
|
||
│ └── Firewall.jsx
|
||
├── appstore-server/ # 应用商店后端服务
|
||
│ ├── app.py # Flask API（/api/apps、/api/version、/api/health）
|
||
│ ├── init.sql # 数据库建表 + 初始数据（Redis/MySQL/Halo 模板）
|
||
│ ├── requirements.txt # Python 依赖
|
||
│ ├── Dockerfile # API 服务容器化
|
||
│ └── deploy.sh # 一键部署脚本
|
||
└── release/ # 打包产物输出目录（.gitignore）
|
||
```
|
||
|
||
---
|
||
|
||
## 四、架构设计
|
||
|
||
### 4.1 Electron 三层架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 渲染进程 (Renderer) │
|
||
│ React 19 + xterm.js + CSS │
|
||
│ ┌──────────┬──────────┬──────────┬────────┬──────────┐ │
|
||
│ │ 概览监控 │ 文件管理 │ 交互终端 │ Docker │ 防火墙 │ │
|
||
│ └─────┬────┴─────┬────┴─────┬────┴───┬────┴─────┬────┘ │
|
||
│ │ │ │ │ │ │
|
||
│ └──────────┴──────────┴────────┴──────────┘ │
|
||
│ window.panel.* │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ Preload (桥接层) │
|
||
│ contextBridge.exposeInMainWorld │
|
||
│ ipcRenderer.invoke / on │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ 主进程 (Main) │
|
||
│ ┌─────────────────────────────────────────────────┐ │
|
||
│ │ SSH 连接管理 (ssh2 Client) │ │
|
||
│ │ ┌──────────┬──────────┬───────────┐ │ │
|
||
│ │ │ 主连接 │ Docker │ 部署连接 │ │ │
|
||
│ │ │ (exec + │ 专用连接 │ 专用连接 │ │ │
|
||
│ │ │ sftp + │ (独立队列)│ (后台任务) │ │ │
|
||
│ │ │ shell) │ │ │ │ │
|
||
│ │ └──────────┴──────────┴───────────┘ │ │
|
||
│ │ 串行队列 (execQueue) │ │
|
||
│ └─────────────────────────────────────────────────┘ │
|
||
│ IPC Handlers │
|
||
│ ssh / cred / sftp / shell / │
|
||
│ docker / appstore / app │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ 应用商店后端 (appstore-server) │
|
||
│ Flask API ←→ MySQL 8 │
|
||
│ /api/apps · /api/version · /api/health │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 4.2 三条 SSH 连接设计
|
||
|
||
这是本项目的核心架构决策，通过连接隔离避免不同模块互相阻塞：
|
||
|
||
| 连接 | 变量名 | 用途 | 特点 |
|
||
|------|--------|------|------|
|
||
| **主连接** | `activeConnection` | 概览监控、SFTP 文件管理、交互式终端 | 登录时建立；exec + sftp 共用串行队列 |
|
||
| **Docker 连接** | `dockerConnection` | Docker 容器/镜像/网络/卷管理 | 登录时自动建立；独立串行队列 |
|
||
| **部署连接** | `deployConnection` | 应用商店后台部署任务 | 懒创建（首次部署时建立）；直接并发 exec |
|
||
|
||
**串行队列机制**：
|
||
- 主连接和 Docker 连接各有独立的串行队列（`execQueue` / `dockerQueue`）
|
||
- 同一连接同一时刻只执行一个 channel，避免并发打开过多 channel 导致 `Channel open failure: open failed` 错误
|
||
- 命令轻量（如 `free -m`），串行执行几乎无感知延迟
|
||
- 部署连接不串行（部署任务内部已 `await` 顺序执行，任务间可并行）
|
||
|
||
### 4.3 安全设计
|
||
|
||
- **contextIsolation: true**：渲染进程与 Node.js 隔离，无法直接 `require`
|
||
- **nodeIntegration: false**：渲染进程无 Node.js 权限
|
||
- **sandbox: false**：preload 可用 Node.js（暴露受控 API）
|
||
- **密码加密存储**：使用 Electron `safeStorage` API（Windows 上为 DPAPI 加密），不可用时降级 base64
|
||
- **API 鉴权**：应用商店 API 通过 `Authorization: Bearer <token>` 校验
|
||
|
||
---
|
||
|
||
## 五、功能模块详解
|
||
|
||
### 5.1 登录与凭据管理
|
||
|
||
- SSH 连接表单（host / port / username / password）
|
||
- 「记住密码」：连接成功后加密保存到本机 `userData/credentials.json`
|
||
- 已保存服务器列表：点击快速填充、删除
|
||
- 打开时自动预填最近一次保存的凭据
|
||
|
||
### 5.2 服务器概览监控
|
||
|
||
五张实时卡片，每张卡片独立轮询：
|
||
|
||
| 卡片 | 数据源命令 | 刷新间隔 |
|
||
|------|-----------|----------|
|
||
| CPU | `top -bn1` / `mpstat` / `vmstat` | 2s |
|
||
| 内存 | `free -m` | 3s |
|
||
| 硬盘 | `df -h` | 15s |
|
||
| 网络 | `/proc/net/dev` 两次采样计算速率 | 2s |
|
||
| 进程 | `ps aux` + `ss -tlnp`/`netstat -tlnp`（监听端口） | 5s |
|
||
|
||
- **依赖检测**：`useMetric` Hook 检测命令是否存在（如 `sysstat` 未安装时卡片置灰，提供一键安装按钮）
|
||
- **CPU% / 内存% 点击排序**（降序，表头高亮箭头）
|
||
- 进程卡片显示监听端口（蓝色徽章）
|
||
|
||
### 5.3 SFTP 文件管理
|
||
|
||
- 远程目录浏览（目录优先排序）
|
||
- 文件上传（支持多选，实时进度推送 `sftp:progress`）
|
||
- 文件下载（单文件保存对话框，批量下载到指定目录）
|
||
- 新建远程目录
|
||
- 删除（统一用 `rm -rf`，路径用单引号包裹防止注入）
|
||
- SFTP 会话缓存复用（同一个 channel）
|
||
|
||
### 5.4 交互式终端
|
||
|
||
- 基于 xterm.js + ssh2 PTY 实现
|
||
- 深色主题（`#1a1d29` 背景，靛蓝光标）
|
||
- 支持窗口大小自适应（FitAddon）
|
||
- 切换导航/断开连接/切换服务器/关窗时自动清理 Shell
|
||
- React StrictMode 双挂载防护（`setTimeout(0)` + `disposed` 标记）
|
||
|
||
### 5.5 Docker 容器管理
|
||
|
||
子菜单包含 8 个功能页：
|
||
|
||
| 子菜单 | 功能 |
|
||
|--------|------|
|
||
| 概览 | 容器数/镜像数/CPU/内存/缓存/存储路径/配置文件 |
|
||
| 容器列表 | 启动/停止/删除/查看日志/进入终端 |
|
||
| 镜像 | 镜像列表/删除/清理 |
|
||
| 应用商店 | ★ 在线模板同步 + 一键部署 |
|
||
| 任务中心 | 后台部署任务进度（步骤+日志） |
|
||
| 配置 | Docker `daemon.json` 查看/编辑 |
|
||
| 网络 | Docker 网络列表/创建/删除 |
|
||
| 卷 | Docker 数据卷列表/删除 |
|
||
|
||
**Docker 状态管理**：
|
||
- 自动检测：`command -v docker` → `docker info`
|
||
- 状态机：checking → running / stopped / notInstalled / error
|
||
- 启动/停止按钮（停止时先杀容器再 kill dockerd，防止卡死）
|
||
|
||
### 5.6 应用商店一键部署
|
||
|
||
这是项目的核心特色功能：
|
||
|
||
**数据流**：
|
||
```
|
||
MySQL (app_templates + 子表) → Flask API → Electron 主进程 (HTTP GET)
|
||
→ 本地缓存 (appstore-cache.json) → 前端渲染应用卡片
|
||
→ 用户填写参数 → 提交部署 → 后台任务执行 → 实时进度推送
|
||
```
|
||
|
||
**部署步骤**（4 步）：
|
||
1. **拉取镜像** `docker pull <image>`（超时 5 分钟）
|
||
2. **创建目录** `mkdir -p` 宿主机挂载目录
|
||
3. **写入配置** `cat > file << 'EOF'` heredoc 方式写入配置文件
|
||
4. **创建容器** 动态构建 `docker run` 命令并执行
|
||
|
||
**模板参数系统**：
|
||
- `{{}}` 占位符替换（如 `{{REDIS_PASSWORD}}`、`{{PORT}}`）
|
||
- 特殊占位符 `{{REDIS_PASSWORD_LINE}}`：根据密码是否存在动态生成配置行
|
||
- 条件渲染 `show_when`：如 Halo 选择 MySQL 数据库时才显示 MySQL 配置字段
|
||
- 下拉选项 `options`（JSON 数组）：如 Halo 数据库类型选择 H2/MySQL
|
||
- 环境变量值含空格时自动加单引号包裹（修复 `-Xmx256m -Xms256m` 的问题）
|
||
- `extra_args` 额外参数在镜像名前插入（如 Halo 数据库连接参数）
|
||
|
||
**内置模板**：
|
||
| 应用 | 镜像 | 说明 |
|
||
|------|------|------|
|
||
| Redis | `redis:8.10.0` | 密码可选，自定义配置文件 |
|
||
| MySQL | `mysql:8.4.11` | root 密码必填，自定义 my.cnf |
|
||
| Halo | `registry.fit2cloud.com/halo/halo:2.26` | 支持 H2/MySQL 双模式，JVM 参数可调 |
|
||
|
||
### 5.7 防火墙管理
|
||
|
||
- 自动检测防火墙类型：`firewalld` / `ufw` / `iptables`
|
||
- firewalld：状态开关、服务/端口管理（添加端口弹窗）
|
||
- ufw / iptables：仅展示规则列表
|
||
- 全程复用 `window.panel.exec`，零新增 IPC
|
||
|
||
### 5.8 客户端版本管理
|
||
|
||
- 主进程内置 `CLIENT_VERSION` 常量
|
||
- 「更新」按钮触发 `/api/version` 接口检查
|
||
- 弹窗显示三种状态：有新版本（显示更新说明+前往下载）、已是最新、检查失败
|
||
- 下载链接通过 `shell.openExternal` 在系统浏览器打开
|
||
|
||
---
|
||
|
||
## 六、IPC API 参考
|
||
|
||
### 6.1 SSH 连接
|
||
|
||
| IPC 通道 | Preload API | 说明 |
|
||
|----------|-------------|------|
|
||
| `ssh:connect` | `panel.connect(config)` | 建立 SSH 连接，自动建立 Docker/部署连接 |
|
||
| `ssh:disconnect` | `panel.disconnect()` | 断开所有连接 |
|
||
| `ssh:session` | `panel.getSession()` | 获取当前会话信息 |
|
||
| `ssh:exec` | `panel.exec(cmd, timeout)` | 在主连接上执行命令（串行队列） |
|
||
| `ssh:disconnected` | `panel.onDisconnected(cb)` | 监听连接断开事件 |
|
||
|
||
### 6.2 凭据管理
|
||
|
||
| IPC 通道 | Preload API | 说明 |
|
||
|----------|-------------|------|
|
||
| `cred:save` | `panel.saveCredential(cred)` | 保存凭据（密码加密） |
|
||
| `cred:list` | `panel.listCredentials()` | 列出已保存凭据 |
|
||
| `cred:delete` | `panel.deleteCredential(key)` | 删除凭据 |
|
||
|
||
### 6.3 SFTP 文件管理
|
||
|
||
| IPC 通道 | Preload API | 说明 |
|
||
|----------|-------------|------|
|
||
| `sftp:list` | `panel.sftpList(path)` | 列目录 |
|
||
| `sftp:upload` | `panel.sftpUpload(local, remote)` | 上传文件 |
|
||
| `sftp:download` | `panel.sftpDownload(remote, local)` | 下载文件 |
|
||
| `sftp:mkdir` | `panel.sftpMkdir(path)` | 创建目录 |
|
||
| `sftp:delete` | `panel.sftpDelete(path, isDir, recursive)` | 删除文件/目录 |
|
||
| `sftp:selectLocalFile` | `panel.sftpSelectLocalFile()` | 选择本地文件（多选） |
|
||
| `sftp:selectSavePath` | `panel.sftpSelectSavePath(name)` | 选择保存路径 |
|
||
| `sftp:selectDownloadDir` | `panel.sftpSelectDownloadDir()` | 选择下载目录 |
|
||
| `sftp:progress` | `panel.onSftpProgress(cb)` | 上传/下载进度事件 |
|
||
|
||
### 6.4 交互式终端
|
||
|
||
| IPC 通道 | Preload API | 说明 |
|
||
|----------|-------------|------|
|
||
| `shell:start` | `panel.shellStart(cols, rows)` | 启动 PTY Shell |
|
||
| `shell:write` | `panel.shellWrite(data)` | 向 Shell 写入数据 |
|
||
| `shell:resize` | `panel.shellResize(cols, rows)` | 调整终端窗口大小 |
|
||
| `shell:close` | `panel.shellClose()` | 关闭 Shell |
|
||
| `shell:data` | `panel.onShellData(cb)` | 监听 Shell 输出 |
|
||
| `shell:close` | `panel.onShellClose(cb)` | 监听 Shell 关闭 |
|
||
|
||
### 6.5 Docker 管理
|
||
|
||
| IPC 通道 | Preload API | 说明 |
|
||
|----------|-------------|------|
|
||
| `docker:exec` | `panel.dockerExec(cmd, timeout)` | 在 Docker 连接上执行命令 |
|
||
| `docker:disconnect` | `panel.dockerDisconnect()` | 断开 Docker 连接 |
|
||
| `docker:deployApp` | `panel.dockerDeployApp(deploy, params)` | 提交部署任务 |
|
||
| `docker:checkConnections` | `panel.dockerCheckConnections()` | 检查 SSH 连接数 |
|
||
| `docker:listTasks` | `panel.dockerListTasks()` | 列出所有部署任务 |
|
||
| `deploy:taskUpdate` | `panel.onDeployTaskUpdate(cb)` | 监听部署进度更新 |
|
||
| `docker:ready` | `panel.onDockerReady(cb)` | Docker 连接就绪事件 |
|
||
| `docker:disconnected` | `panel.onDockerDisconnected(cb)` | Docker 连接断开事件 |
|
||
|
||
### 6.6 应用商店与版本管理
|
||
|
||
| IPC 通道 | Preload API | 说明 |
|
||
|----------|-------------|------|
|
||
| `appstore:sync` | `panel.appstoreSync()` | 从远程 API 同步模板到本地 |
|
||
| `appstore:getLocal` | `panel.appstoreGetLocal()` | 获取本地缓存模板 |
|
||
| `appstore:getApiUrl` | `panel.appstoreGetApiUrl()` | 获取 API 地址 |
|
||
| `appstore:setApiUrl` | `panel.appstoreSetApiUrl(url)` | 设置 API 地址 |
|
||
| `appstore:checkInstalled` | `panel.appstoreCheckInstalled()` | 检查已安装应用 |
|
||
| `app:checkUpdate` | `panel.appCheckUpdate()` | 检查客户端版本更新 |
|
||
| `app:getVersion` | `panel.appGetVersion()` | 获取当前版本号 |
|
||
| `app:openUrl` | `panel.appOpenUrl(url)` | 用系统浏览器打开 URL |
|
||
|
||
---
|
||
|
||
## 七、应用商店后端服务
|
||
|
||
### 7.1 API 端点
|
||
|
||
| 路由 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/api/apps` | GET | 获取所有应用模板（含完整详情和子表） |
|
||
| `/api/apps/<app_key>` | GET | 获取单个应用模板详情 |
|
||
| `/api/version` | GET | 获取客户端最新版本信息 |
|
||
| `/api/health` | GET | 健康检查 |
|
||
|
||
### 7.2 数据库表结构
|
||
|
||
```
|
||
app_templates (主表)
|
||
├── app_ports (端口映射子表)
|
||
├── app_volumes (挂载卷子表)
|
||
├── app_envs (环境变量子表)
|
||
├── app_mkdirs (自动创建目录子表)
|
||
├── app_write_files (配置文件子表)
|
||
└── app_params (用户参数子表，含下拉选项和条件显示)
|
||
|
||
app_version (客户端版本管理表)
|
||
```
|
||
|
||
### 7.3 部署方式
|
||
|
||
```bash
|
||
# 在服务器上执行
|
||
cd appstore-server
|
||
bash deploy.sh
|
||
# 流程：建表 → 构建镜像 → 启动容器（3001 端口）
|
||
```
|
||
|
||
环境变量配置：
|
||
- `DB_HOST` / `DB_PORT` / `DB_USER` / `DB_PASSWORD` / `DB_NAME`：数据库连接
|
||
- `API_PORT`：API 监听端口（默认 3001）
|
||
- `API_TOKEN`：鉴权 token（可选）
|
||
|
||
---
|
||
|
||
## 八、开发与构建
|
||
|
||
### 8.1 环境要求
|
||
|
||
- Node.js 18+
|
||
- npm（国内网络建议配置 `.npmrc` 中的 Electron 镜像）
|
||
- Python 3.12+（应用商店后端）
|
||
- MySQL 8（应用商店数据库）
|
||
|
||
### 8.2 开发
|
||
|
||
```bash
|
||
npm install # 安装依赖（Electron 自动走国内镜像）
|
||
npm run dev # 启动开发服务器（Vite HMR 热更新）
|
||
```
|
||
|
||
开发模式下按 `F12` 打开开发者工具。
|
||
|
||
### 8.3 构建
|
||
|
||
```bash
|
||
npm run build # 构建产物（输出到 out/）
|
||
npm run build:win # 构建 + 打包 Windows 安装程序（输出到 release/）
|
||
```
|
||
|
||
### 8.4 关键配置说明
|
||
|
||
**`.npmrc`（Electron 国内镜像）**：
|
||
```
|
||
electron_mirror=https://npmmirror.com/mirrors/electron/
|
||
```
|
||
|
||
**`electron-builder` 配置要点**：
|
||
- `npmRebuild: false`：跳过 native 模块编译（ssh2 纯 JS 无需编译）
|
||
- `target: nsis`：Windows NSIS 安装程序
|
||
- `icon: build/icon.png`：256x256 应用图标
|
||
- 国内打包需配置 `ELECTRON_BUILDER_BINARIES_MIRROR` 镜像
|
||
|
||
---
|
||
|
||
## 九、关键设计决策与踩坑记录
|
||
|
||
### 9.1 SSH Channel 并发问题
|
||
|
||
**问题**：概览页 5 张卡片各自独立轮询，同时打开的 channel 数超出服务器上限（通常 10 个），报错 `Channel open failure: open failed`。
|
||
|
||
**方案**：在主进程 `execSsh` 函数增加串行队列（`execQueue`），所有请求逐个执行，同一时刻只占一个 channel。命令轻量，串行执行几乎无感知延迟。
|
||
|
||
### 9.2 React StrictMode 双挂载
|
||
|
||
**问题**：开发模式下 `React.StrictMode` 会执行两次 `useEffect`（mount→unmount→remount），导致终端首次打开输出重复。
|
||
|
||
**方案**：`shellStart` 放入 `setTimeout(0)` 延迟执行并配合 `disposed` 标记，第一次同步 mount→unmount 时被 cleanup 拦截，仅真正 mount 时连接一次。
|
||
|
||
### 9.3 Electron 二进制下载失败
|
||
|
||
**问题**：`npm install` 时 Electron postinstall 从 GitHub 下载二进制，国内网络经常失败。
|
||
|
||
**方案**：项目根目录创建 `.npmrc` 写入 `electron_mirror=https://npmmirror.com/mirrors/electron/`，安装时自动走国内镜像。
|
||
|
||
### 9.4 Docker 环境变量含空格
|
||
|
||
**问题**：Halo 部署时 `JVM_OPTS=-Xmx256m -Xms256m` 中空格导致 `docker run` 拆分参数报 `unknown shorthand flag`。
|
||
|
||
**方案**：环境变量值含空格时自动加单引号包裹（`parts.push('-e', "'${pair}'")`）。
|
||
|
||
### 9.5 部署连接隔离
|
||
|
||
**问题**：部署任务耗时较长（拉取镜像可能数分钟），如果复用主连接的串行队列会阻塞概览监控等常规操作。
|
||
|
||
**方案**：使用独立的第三条 SSH 连接（`deployConnection`），懒创建，部署任务直接 `exec` 不走串行队列，任务内部 `await` 顺序执行，任务间可并行。
|
||
|
||
---
|
||
|
||
## 十、扩展指南
|
||
|
||
### 10.1 新增应用模板
|
||
|
||
在 `appstore-server/init.sql` 中或通过 API 添加新行到 `app_templates` 主表及对应子表即可，前端无需改代码。`mapDbTemplateToFront` 函数自动将数据库格式转换为前端 deploy 格式。
|
||
|
||
### 10.2 新增功能页面
|
||
|
||
1. 在 `src/renderer/src/pages/` 下新建组件目录
|
||
2. 在 `Panel.jsx` 的 `NAV_ITEMS` 数组添加导航项
|
||
3. 在 `Panel.jsx` 的 `<main>` 区域添加条件渲染
|
||
4. 如需主进程支持，在 `src/main/index.js` 添加 IPC handler，在 `src/preload/index.js` 暴露 API
|
||
|
||
### 10.3 新增 IPC 通道
|
||
|
||
```js
|
||
// 主进程 (src/main/index.js)
|
||
ipcMain.handle('my:action', async (event, { param }) => {
|
||
// 业务逻辑
|
||
return { ok: true, data: result }
|
||
})
|
||
|
||
// Preload (src/preload/index.js)
|
||
myAction: (param) => ipcRenderer.invoke('my:action', { param })
|
||
|
||
// 渲染进程
|
||
const result = await window.panel.myAction(param)
|
||
```
|
||
|
||
> AI生成 |