webui4frpc/README.md

webui4frpc

一个独立于 frp 源码的可视化 frpc 控制器。用画布方式把「本地转发项」连到「远程服务器」，自动为每台远程服务器生成 frpc 配置并拉起独立 worker 进程，免去运维反复手写 frpc 配置的麻烦。支持多节点组成令牌环集群，协同分发转发任务。

本仓库不捆绑、不包含任何 frp 源码。frpc 可执行文件由用户一键从官方 GitHub Releases 下载，或手动指定路径。

特性

画布配置

• Scratch 风格画布：本地转发项（local）与远程服务器（remote）可视化连线，一个 local 可连多个 remote，一个 remote 可连多个 local
• 曲线连线 + 端口标签：每条连线独立曲线，标签为远程端口，可拖拽调整曲线位置，端口可点开编辑
• 边开关与分组：画布边上可一键禁用/启用单条转发，可打分组标签（状态页按分组管理、一键启停整组）
• 一键生成配置：保存画布即渲染每台 remote 的 frpc JSON 配置，自动拉起/重启对应 worker
• 画布导入导出：支持 JSON 备份/恢复

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
• 容错自愈：leader / 非 leader 节点宕机 → 自动检测 → 环跳过死亡节点、任务重挂；leader 宕机 → 上邻居晋升为新 leader
• 宕机自动重联：节点宕机重启后通过缓存的集群拓扑（对端地址 + 准入密钥）自动重联，显式脱离集群的节点不自动重联
• 准入密钥：每节点有 nodeKey，新节点加入需提供对端密钥；密钥随令牌环交换，全节点互通
• 集群二进制分发：节点间优先互传 frpc 二进制，外部 URL 兜底

认证与权限

• Basic Auth：启动参数配置管理员账号密码（flag-creds 快速路径，不走 bcrypt）
• 用户管理：admin / viewer 两种角色，bcrypt 存储，webui 管理
• API Key：read / write / admin 三级 scope，w4f_ 前缀，sha256 存储，创建时明文仅展示一次
• 三级权限：read（查看）< write（修改）< admin（用户/密钥管理）

构建

后端（Go 1.25+）

go build -o webui4frpc ./cmd/webui4frpc

前端（Node 20+）

cd web && npm install && npm run build

前端产物在 web/dist，需拷贝到 internal/httpapi/dist 以便 Go embed 打包进单一二进制：

rm -rf internal/httpapi/dist && cp -r web/dist internal/httpapi/dist

一键全量构建：

cd web && npm run build && cd .. && cp -r web/dist/* internal/httpapi/dist/ && go build -o deploy/artifacts/webui4frpc ./cmd/webui4frpc

运行

./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/<name>.json     # 每台 remote 渲染的 frpc 配置
├── logs/<name>.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）
│   ├── canvas               画布模型（local / remote / link 多对多）
│   ├── render               渲染 frpc JSON 配置（tcp/udp/http/https + 高级参数 + LB/健康检查）
│   ├── process              worker 进程管理（spawn/stop/restart/自愈/日志轮转）
│   ├── install              一键下载官方 frpc（GitHub Releases，含解压安全防护）
│   ├── cluster              令牌环协议（ring engine / leader 选举 / 容错 / 宕机重联 / 二进制分发）
│   └── httpapi              REST API + 静态资源（auth / canvas / forwards / cluster / users）
└── web/                     Vue 3 SPA（Element Plus + VueFlow 画布 + Pinia）
    └── src/views/           状态总览 / 连接配置（画布）/ 集群 / 设置 / 账号与密钥

API

所有接口前缀 /api/manager，使用 Basic Auth 或 Bearer API Key 认证。权限分 read / write / admin 三级。

类别	方法	路径	权限	说明
状态	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 日志
	GET	/frpc/{version}	read	节点间 frpc 二进制分发
账号	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。

集群模式

多个 webui4frpc 节点可组成令牌环集群协同工作：

• 创建集群：首个节点 CreateCluster 成为 leader，生成准入密钥（nodeKey）
• 加入集群：在集群页复制对端的 nodeKey，填入「加入集群」对话框（对端地址 + 密钥）
• 任务分发：在任意节点画布上配置 localOnly=false 的转发并保存 → 画布差异判断生成命令 → 令牌携带 → 负载最低节点摘取 → 拉起 frpc worker
• 容错：节点宕机 → 自动检测 → 环自愈（跳过死亡节点 / leader failover）；重启 → 自动重联
• 退出集群：在集群页「退出集群」→ 本节点脱离为 standalone，不自动重联

集群页展示：环拓扑（self/leader 标记）、令牌轮次、节点负载、待办任务、活跃转发拓扑（含 owner 归属）、增量事件日志。

集群演示

# 构建
go build -o deploy/artifacts/webui4frpc ./cmd/webui4frpc

# 拉起 4 节点集群 + 1 孤立节点（Docker）
cd deploy && bash run-cluster.sh

# 运行转发测试（提交 4 条转发 → 验证分发 → 撤销）
bash test-forward.sh

节点端口映射：

节点	端口	角色
node-a	7501	集群 leader（seed，有 frpc 缓存）
node-b	7502	集群成员
node-c	7503	集群成员
node-d	7504	集群成员
node-e	7505	孤立节点（standalone，未加入集群）

所有节点 -user=admin -password=admin123。

测试

# 后端
go test ./...

# 前端类型检查
cd web && npm run type-check