feat: 原生安装包 — deb/rpm/systemd + NSIS setup.exe + macOS pkg

此前交付的 tar.gz/zip 仅是解压直用包，补齐真正的平台安装包： - Linux: .deb (dpkg-deb) 与 .rpm (rpmbuild)，装 systemd 单元 + 专用系统账号 + /etc/webui4frpc 配置，非 root 运行 + 加固 - Windows: NSIS setup.exe，向导收集监听地址/凭据，注册卸载器 + 防火墙放行（amd64/arm64） - macOS: .pkg（在 Linux 上手工 xar+mkbom 组装 flat package），launchd 开机自启 + env 配置文件（amd64/arm64） - scripts/release.sh 纳入 build_installers.sh 阶段；README 增「安装」章节逐平台说明已知限制：rpmbuild 无法在非 RHEL 主机交叉构建 aarch64（Debian rpm 只有 x86_64 构建 arch），aarch64 rpm 需在原生 ARM 机器构建；Linux/ARM 场景已由 deb-arm64 覆盖。
2026-09-20 08:57:55 +00:00 · 2026-08-28 08:36:55 +08:00
parent 6ee901dc64
commit 15b1dcce8f
14 changed files with 974 additions and 0 deletions
--- a/packaging/windows/LICENSE.txt
+++ b/packaging/windows/LICENSE.txt
@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JianFeeeee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
--- a/packaging/windows/README.md
+++ b/packaging/windows/README.md
@ -0,0 +1,202 @@
+# webui4frpc
+
+> **AI-assisted**: 本项目使用 AI 辅助编程（代码与文档由 AI 协作完成，经人工复核）。
+一个**独立于 frp 源码**的可视化 frpc 控制器。用画布方式把「本地转发项」连到「远程服务器」，自动为每台远程服务器生成 frpc 配置并拉起独立 worker 进程，免去运维反复手写 frpc 配置的麻烦。支持多节点组成令牌环集群，协同分发转发任务。
+
+> 本仓库**不捆绑、不包含任何 frp 源码**。frpc 可执行文件由用户一键从官方 GitHub Releases 下载，或手动指定路径。
+
+## 特性
+
+### 画布配置
+
+- **Scratch 风格画布**：本地转发项（local）与远程服务器（remote）可视化连线，一个 local 可连多个 remote，一个 remote 可连多个 local
+- **曲线连线 + 端口标签**：每条连线独立曲线，标签为远程端口，可拖拽调整曲线位置，端口可点开编辑
+- **画布冲突检查**：保存时自动检测远程端口/域名重复，避免配置冲突
+- **边开关与分组**：画布边上可一键禁用/启用单条转发，可打分组标签（状态页按分组管理、一键启停整组）
+- **Del 键/× 按钮删除**：选中连线按 Delete 键或点击端口标签红 × 删除，确认后标记脏
+- **一键生成配置**：保存画布即渲染每台 remote 的 frpc JSON 配置，自动拉起/重启对应 worker
+- **画布导入导出**：支持 JSON 信封备份/恢复（含 provenance 元数据）
+
+### frpc 能力
+
+- **代理类型**：tcp（完整）、http/https（customDomains / subdomain / locations / basicAuth / headerRewrite）
+- **传输参数**：useEncryption / useCompression / bandwidthLimit / poolCount / transport.protocol（tcp/quic/kcp/websocket）/ TLS
+- **负载均衡与健康检查**：lbGroup + healthCheck 渲染输出；状态页通过 frpc admin API 拉取 per-proxy 真实状态（running / check failed / wait start …）
+- **worker 自愈**：崩溃自动重启（指数退避），随 webui 启停
+- **frpc 一键安装**：从官方 Releases 下载任意版本 frpc，或手动指定二进制路径
+
+### 集群模式（令牌环）
+
+- **令牌环协议**：若干 webui4frpc 节点组成协作网络；令牌按固定顺序传递，每节点持完整集群信息，单轮即全网收敛
+- **负载最低者摘取**：新转发任务附加在令牌中，由负载最低的节点自行摘取并创建 frpc worker
+  - 主负载信号：当前节点拥有的转发数（权重 ×100）
+  - 次级信号：**NIC 网络接口利用率**（从 `/proc/net/dev` 增量 + `/sys/class/net/*/speed` 计算，排除了 lo/docker/veth 等虚拟接口）
+  - 同转发数节点间由内存占用 + 网络饱和度打破平局
+- **per-forward 独立进程**：每条转发拥有独立的 frpc 配置文件和 frpc 进程（worker 键 = `local~remote~port`），单条转发故障不影响兄弟，消除旧模型的多节点 `proxy already exists` 冲突
+- **容错自愈**：leader / 非 leader 节点宕机 → 自动检测 → 环跳过死亡节点、任务重挂；leader 宕机 → 上邻居晋升为新 leader
+- **宕机自动重联**：节点宕机重启后通过缓存的集群拓扑（对端地址 + 准入密钥）自动重联，显式脱离集群的节点不自动重联
+- **准入密钥**：每节点有 nodeKey，新节点加入需提供对端密钥；密钥随令牌环交换，全节点互通
+- **集群二进制分发**：节点间优先互传 frpc 二进制，外部 URL 兜底
+
+### 认证与权限
+
+- **Session-cookie 登录 + Basic Auth**：UI 使用 session-cookie（支持登出），API 保持 Basic Auth + Bearer API Key 兼容
+- **三级角色**：superadmin（账号管理）、admin（全功能除账号）、viewer（只读状态/集群/审计导出）
+- **用户管理**：superadmin 角色创建/管理用户，bcrypt 存储，flag 内置账号为 system 只读
+- **API Key**：read / write / admin 三级 scope，`w4f_` 前缀，sha256 存储，创建时明文仅展示一次
+- **审计导出**：read 级 view 即可导出 CSV（账号登录记录 / API Key 使用记录 / 集群操作日志 / worker 运行日志）
+
+## 构建
+
+### 后端（Go 1.25+）
+
+```bash
+go build -o webui4frpc ./cmd/webui4frpc
+```
+
+### 前端（Node 20+）
+
+```bash
+cd web && npm install && npm run build
+```
+
+前端产物在 `web/dist`，需拷贝到 `internal/httpapi/dist` 以便 Go `embed` 打包进单一二进制：
+
+```bash
+rm -rf internal/httpapi/dist && cp -r web/dist internal/httpapi/dist
+```
+
+一键全量构建（dist 不进入 git，编译前必须构建前端）：
+
+```bash
+cd web && npm run build && rm -rf internal/httpapi/dist && cp -r web/dist internal/httpapi/dist && go build -o webui4frpc ./cmd/webui4frpc
+```
+
+## 运行
+
+```bash
+./webui4frpc -addr 127.0.0.1:7500 -user admin -password admin123 -workdir ./data
+```
+
+打开 <http://127.0.0.1:7500/> ，输入账号密码进入画布。首次使用可到「设置」页一键安装 frpc（或手动指定路径），然后回到画布创建 local / remote 并连线、保存。
+
+### 参数
+
+| 参数 | 默认 | 说明 |
+| --- | --- | --- |
+| `-addr` | `127.0.0.1:7500` | 监听地址 |
+| `-user` / `-password` | `admin` / `admin` | Basic 认证（自动同步为 system 管理员账号） |
+| `-workdir` | `./webui-frpc` | 数据目录（db / 配置 / 日志 / bin） |
+| `-bin` | 空 | 初始 frpc 二进制路径（可选，首次启动写入 settings） |
+| `-frpc` | 空 | worker 默认 frpc 路径（settings 无值时的回退） |
+| `-peer` | 空 | 集群对端地址 `host:port`（可重复，仅首次引导加入用） |
+| `-join-key` | `$W4F_JOIN_KEY` | 集群准入密钥 = 对端节点的 nodeKey（与 `-peer` 配合使用） |
+
+环境变量 `W4F_HOST` 可覆盖节点对外可达的主机名（Docker DNS / 通配监听场景用）。
+
+### 启动行为
+
+节点启动时的集群引导优先级：
+
+1. **缓存拓扑优先**：读取持久化的 `ClusterPeers`（宕机前最后令牌周期保存的对端列表），逐个尝试 rejoin
+2. **`-peer` 引导**：无缓存拓扑时，用 `-peer` + `-join-key` 加入指定对端（10s 重试、5min 超时）
+3. **新建集群**：无缓存无 `-peer` → `CreateCluster` 成为独立 leader
+
+显式脱离集群（detachAsStandalone）会清除 `ClusterPeers` → 重启后不自动重联。
+
+## 数据目录
+
+```
+<workdir>
+├── manager.db                        # SQLite（locals / remotes / links / settings / users / api_keys）
+├── configs/<local>~<remote>~<port>.json  # 每条转发的独立 frpc 配置（per-forward 模型）
+├── logs/<local>~<remote>~<port>.log      # 每条转发的独立 worker 日志（按大小轮转）
+└── bin/frpc-<v>/frpc                 # 一键安装的 frpc
+```
+
+## 架构
+
+```
+webui4frpc（单二进制，无 frp 依赖，前端 go:embed）
+├── cmd/webui4frpc           入口：flag 解析 → store/process/cluster 装配 → HTTP 服务 + 生命周期
+├── internal/
+│   ├── store                SQLite 持久化（locals / remotes / links / settings / users / api_keys / sessions）
+│   ├── canvas               画布模型（local / remote / link 多对多）
+│   ├── render               渲染 frpc JSON 配置（per-forward 单 proxy + 高级参数 + LB/健康检查）
+│   ├── process              worker 进程管理（spawn/stop/restart/自愈/日志轮转，worker 键 = local~remote~port）
+│   ├── install              一键下载官方 frpc（GitHub Releases，含解压安全防护）
+│   ├── cluster              令牌环协议（ring engine / leader 选举 / 容错 / 宕机重联 / 二进制分发 / NIC 负载采样）
+│   └── httpapi              REST API + 静态资源（auth/session / canvas / forwards / cluster / users / audit 导出）
+└── web/                     Vue 3 SPA（Element Plus + VueFlow 画布 + Pinia）
+    └── src/views/           状态总览 / 连接配置（画布）/ 集群 / 设置 / 账号与密钥
+```
+
+## API
+
+所有接口前缀 `/api/manager`。UI 使用 session-cookie 登录（`/login` `/logout`），API 兼容 Basic Auth 或 Bearer API Key。权限分 read / write / admin 三级，角色 superadmin / admin / viewer 映射到不同 UI 可见性与操作能力。
+
+| 类别 | 方法 | 路径 | 权限 | 说明 |
+| --- | --- | --- | --- | --- |
+| **状态** | GET | `/status` | read | 总览（版本/服务/节点/转发/profiles） |
+| **画布** | GET/PUT | `/canvas` | read/write | 读写完整画布 |
+| | GET | `/canvas/export` | read | 导出画布备份 |
+| | POST | `/canvas/import` | write | 导入画布 |
+| **转发** | POST | `/forwards/start\|stop` | write | 启停单条转发 |
+| | POST | `/forwards/group/start\|stop` | write | 启停整组 |
+| | POST | `/forwards/assign` | write | 修改转发分组 |
+| | POST | `/forwards/group/delete` | write | 删除分组 |
+| **单资源** | PUT/DELETE | `/locals[/{name}]` | write | 增删 local |
+| | PUT/DELETE | `/remotes[/{name}]` | write | 增删 remote |
+| | POST/DELETE | `/links[/{id}]` | write | 增删 link |
+| **Profile** | POST | `/profiles/{name}/start\|stop\|restart` | write | worker 启停重启 |
+| | GET | `/profiles/{name}/config\|logs` | read | 配置/日志 |
+| **设置** | GET/PUT | `/settings` | read/write | 运行策略 |
+| | GET | `/binary/status` | read | frpc 路径 |
+| | POST | `/binary/install` | write | 安装 frpc |
+| **集群** | GET | `/cluster/ring` | read | 令牌环快照 |
+| | POST | `/cluster/create` | write | 创建独立集群 |
+| | POST | `/cluster/join-ring` | write | 加入集群（本节点发起） |
+| | POST | `/cluster/join` | write | 接收新节点加入 |
+| | POST | `/cluster/task` | write | 提交转发任务到环 |
+| | POST | `/cluster/node-remove` | write | 移除节点 |
+| | POST | `/cluster/token` | write | 令牌中继 + 心跳 |
+| | GET | `/cluster/nodes` | read | 集群节点 + 缓存 |
+| | GET/POST | `/cluster/cache` | read/write | 二进制缓存管理 |
+| | GET | `/node/logs` | read | 本节点 worker 日志 |
+| | GET | `/cluster/logs/export` | read | 导出全节点 worker 日志（JSON bundle） |
+| **审计导出** | GET | `/audit/users.csv` | read | 账号清单 CSV（含最后登录） |
+| | GET | `/audit/apikeys.csv` | read | API Key 清单 CSV（含最后使用/过期） |
+| | GET | `/audit/cluster-log.csv` | read | 集群操作日志 CSV（时间线 + 原始载荷） |
+| | GET | `/audit/worker-logs.csv` | read | 全节点 worker 运行日志 CSV（逐行展开） |
+| | GET | `/frpc/{version}` | read | 节点间 frpc 二进制分发 |
+| **认证** | POST | `/login` | 无 | 登录（表单凭证 → session cookie） |
+| | POST | `/logout` | 无 | 登出（清除 session） |
+| | GET | `/me` | read | 当前身份 |
+| | GET/POST | `/users` | admin | 用户列表/创建 |
+| | PUT/DELETE | `/users/{name}` | admin | 修改/删除用户 |
+| | GET/POST | `/apikeys` | admin | API Key 列表/创建 |
+| | DELETE | `/apikeys/{id}` | admin | 吊销 API Key |
+
+> 集群管理 API 的详细说明（请求体、响应格式、错误码、示例）见 [docs/cluster-api.md](docs/cluster-api.md)。
+
+## 集群模式
+
+多个 webui4frpc 节点可组成令牌环集群协同工作：
+
+- **创建集群**：首个节点 `CreateCluster` 成为 leader，生成准入密钥（nodeKey）
+- **加入集群**：在集群页复制对端的 nodeKey，填入「加入集群」对话框（对端地址 + 密钥）
+- **任务分发**：在任意节点画布上配置 `localOnly=false` 的转发并保存 → 画布差异判断生成命令 → 令牌携带 → 负载最低节点摘取 → 拉起 frpc worker
+- **容错**：节点宕机 → 自动检测 → 环自愈（跳过死亡节点 / leader failover）；重启 → 自动重联
+- **退出集群**：在集群页「退出集群」→ 本节点脱离为 standalone，不自动重联
+
+集群页展示：环拓扑（self/leader 标记）、令牌轮次、节点负载、待办任务、活跃转发拓扑（含 owner 归属）、增量事件日志。
+
+## 测试
+
+```bash
+# 后端
+go test ./...
+
+# 前端类型检查
+cd web && npm run type-check
+```
--- a/packaging/windows/webui4frpc.nsi
+++ b/packaging/windows/webui4frpc.nsi
@ -0,0 +1,162 @@
+; webui4frpc Windows 安装程序 (NSIS)
+;
+; 由 scripts/build_installers.sh 调用，需在命令行传入:
+;   -DVERSION=0.1.0 -DARCH=amd64 -DBINSRC=<webui4frpc.exe 路径> -DOUTFILE=<输出 exe>
+
+!include "MUI2.nsh"
+!include "LogicLib.nsh"
+
+!ifndef VERSION
+  !define VERSION "0.0.0"
+!endif
+!ifndef ARCH
+  !define ARCH "amd64"
+!endif
+
+Name "webui4frpc ${VERSION}"
+OutFile "${OUTFILE}"
+Unicode true
+RequestExecutionLevel admin
+InstallDir "$PROGRAMFILES64\webui4frpc"
+InstallDirRegKey HKLM "Software\webui4frpc" "InstallDir"
+
+VIProductVersion "${VERSION}.0"
+VIAddVersionKey "ProductName" "webui4frpc"
+VIAddVersionKey "FileDescription" "Visual frpc controller with token-ring cluster"
+VIAddVersionKey "FileVersion" "${VERSION}"
+VIAddVersionKey "ProductVersion" "${VERSION}"
+VIAddVersionKey "LegalCopyright" "JianFeeeee"
+
+!define MUI_ABORTWARNING
+!insertmacro MUI_PAGE_LICENSE "LICENSE.txt"
+!insertmacro MUI_PAGE_DIRECTORY
+Page custom ConfigPage ConfigPageLeave
+!insertmacro MUI_PAGE_INSTFILES
+!insertmacro MUI_PAGE_FINISH
+!insertmacro MUI_UNPAGE_CONFIRM
+!insertmacro MUI_UNPAGE_INSTFILES
+!insertmacro MUI_LANGUAGE "SimpChinese"
+!insertmacro MUI_LANGUAGE "English"
+
+Var Dialog
+Var LblAddr
+Var TxtAddr
+Var LblUser
+Var TxtUser
+Var LblPass
+Var TxtPass
+Var CfgAddr
+Var CfgUser
+Var CfgPass
+
+Function .onInit
+  StrCpy $CfgAddr "0.0.0.0:7500"
+  StrCpy $CfgUser "admin"
+  StrCpy $CfgPass "admin"
+FunctionEnd
+
+Function ConfigPage
+  !insertmacro MUI_HEADER_TEXT "服务配置" "设置监听地址与登录凭据"
+  nsDialogs::Create 1018
+  Pop $Dialog
+  ${If} $Dialog == error
+    Abort
+  ${EndIf}
+
+  ${NSD_CreateLabel} 0 0 100% 12u "监听地址 (host:port)："
+  Pop $LblAddr
+  ${NSD_CreateText} 0 14u 100% 12u "$CfgAddr"
+  Pop $TxtAddr
+
+  ${NSD_CreateLabel} 0 34u 100% 12u "管理员用户名："
+  Pop $LblUser
+  ${NSD_CreateText} 0 48u 100% 12u "$CfgUser"
+  Pop $TxtUser
+
+  ${NSD_CreateLabel} 0 68u 100% 12u "管理员密码（请勿沿用默认值）："
+  Pop $LblPass
+  ${NSD_CreatePassword} 0 82u 100% 12u "$CfgPass"
+  Pop $TxtPass
+
+  nsDialogs::Show
+FunctionEnd
+
+Function ConfigPageLeave
+  ${NSD_GetText} $TxtAddr $CfgAddr
+  ${NSD_GetText} $TxtUser $CfgUser
+  ${NSD_GetText} $TxtPass $CfgPass
+FunctionEnd
+
+Section "webui4frpc" SecMain
+  SetOutPath "$INSTDIR"
+  File "/oname=webui4frpc.exe" "${BINSRC}"
+  File "README.md"
+  File "LICENSE.txt"
+
+  CreateDirectory "$INSTDIR\data"
+
+  ; 启动脚本，承载安装时选择的配置
+  FileOpen $0 "$INSTDIR\start-webui4frpc.cmd" w
+  FileWrite $0 "@echo off$\r$\n"
+  FileWrite $0 "rem webui4frpc 启动脚本（由安装程序生成）$\r$\n"
+  FileWrite $0 "cd /d %~dp0$\r$\n"
+  FileWrite $0 'webui4frpc.exe -addr $CfgAddr -user $CfgUser -password $CfgPass -workdir "%~dp0data"$\r$\n'
+  FileClose $0
+
+  WriteRegStr HKLM "Software\webui4frpc" "InstallDir" "$INSTDIR"
+  WriteRegStr HKLM "Software\webui4frpc" "Version" "${VERSION}"
+
+  ; 添加/删除程序
+  WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\webui4frpc" \
+      "DisplayName" "webui4frpc ${VERSION}"
+  WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\webui4frpc" \
+      "UninstallString" "$\"$INSTDIR\uninstall.exe$\""
+  WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\webui4frpc" \
+      "DisplayVersion" "${VERSION}"
+  WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\webui4frpc" \
+      "Publisher" "JianFeeeee"
+  WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\webui4frpc" \
+      "URLInfoAbout" "https://gitcode.com/JianFeeeee/webui4frpc"
+  WriteRegDWORD HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\webui4frpc" \
+      "NoModify" 1
+  WriteRegDWORD HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\webui4frpc" \
+      "NoRepair" 1
+
+  WriteUninstaller "$INSTDIR\uninstall.exe"
+
+  ; 开始菜单
+  CreateDirectory "$SMPROGRAMS\webui4frpc"
+  CreateShortcut "$SMPROGRAMS\webui4frpc\webui4frpc.lnk" \
+      "$INSTDIR\start-webui4frpc.cmd" "" "$INSTDIR\webui4frpc.exe" 0
+  CreateShortcut "$SMPROGRAMS\webui4frpc\打开管理界面.lnk" \
+      "http://127.0.0.1:7500"
+  CreateShortcut "$SMPROGRAMS\webui4frpc\卸载 webui4frpc.lnk" "$INSTDIR\uninstall.exe"
+
+  ; 防火墙放行（失败不阻断安装）
+  nsExec::ExecToLog 'netsh advfirewall firewall add rule name="webui4frpc" \
+      dir=in action=allow program="$INSTDIR\webui4frpc.exe" enable=yes profile=any'
+SectionEnd
+
+Section "Uninstall"
+  nsExec::ExecToLog 'netsh advfirewall firewall delete rule name="webui4frpc"'
+
+  Delete "$INSTDIR\webui4frpc.exe"
+  Delete "$INSTDIR\start-webui4frpc.cmd"
+  Delete "$INSTDIR\README.md"
+  Delete "$INSTDIR\LICENSE.txt"
+  Delete "$INSTDIR\uninstall.exe"
+
+  ; data 目录保留（含数据库与日志），由用户手动删除
+  MessageBox MB_YESNO|MB_ICONQUESTION \
+      "是否同时删除数据目录 $INSTDIR\data（数据库、转发配置、日志）？" \
+      IDNO KeepData
+  RMDir /r "$INSTDIR\data"
+KeepData:
+  RMDir "$INSTDIR"
+
+  Delete "$SMPROGRAMS\webui4frpc\*.lnk"
+  RMDir "$SMPROGRAMS\webui4frpc"
+
+  DeleteRegKey HKLM "Software\webui4frpc"
+  DeleteRegKey HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\webui4frpc"
+SectionEnd