webui4frpc/plan.md

webui4frpc 开发计划

webui4frpc —— 独立于 frp 源码的可视化 frpc 控制器（单二进制，零 frp 代码依赖，frpc 运行时一键从官方 Releases 下载或手动指定）。

目标

用画布方式把「本地转发项」连到「远程服务器」，自动为每台远程服务器生成 frpc 配置并拉起独立 worker 进程，避免运维反复手写 frpc 配置。

已完成（M0：骨架与核心）

• 独立仓库：module webui4frpc，仅依赖 modernc.org/sqlite，零 frp 源码引用
• 目录结构：cmd / internal/{store,render,process,httpapi,install} + web（Vue3 + VueFlow + Element Plus）
• 画布模型：local / remote / link 多对多连线，节点可编辑、可添加
• 渲染器：tcp/udp/http/https → frpc JSON 配置（http 用 customDomains=<name>.local）
• worker 进程管理：spawn/stop/restart、日志轮转、崩溃自愈（指数退避）
• 一键安装 frpc（GitHub Releases）＋ 手动指定路径
• REST API：status/canvas/settings/remotes/profiles/binary
• 三页 UI：状态（默认）/ 连接配置 / 设置
• 状态页：远程节点状态框 + 本地服务转发表（每 5s 轮询），节点可增删改启停
• 画布可用性检查：端口冲突 / http 域名唯一性，标红 + 弹窗提示，保存前拦截
• 演示环境：3 本地 × 3 远程多对多全连通（tcp + http 转发实测返回数据）
• 后端单元测试：store / render / process / httpapi / install

项目现状核对（代码审查记录 2024-08 单 commit c193688）

• 后端入口 cmd/webui4frpc/main.go：flag 解析（-addr/-user/-password/-workdir/-bin）→ 建数据目录 → store.New → process.NewManager（BinaryPath/AutoRestart/RestartInterval 动态闭包，AutoStartProfiles 启动已启用 worker）→ httpapi.NewServeMux（healthz 免认证，其余 Basic Auth）→ SIGINT/SIGTERM 优雅退出（15s 超时 + StopAll）
• 核心数据流：PUT /api/manager/canvas → store 全量 upsert/删除 + 事务替换 links → SyncWorkers 重启受影响 worker → 每台远程独立 frpc -c configs/<name>.json 进程
• 渲染器当前能力：tcp/udp 用 remotePort，http/https 用 customDomains（默认 <name>.local），重名服务自动加端口后缀；transport 段仅有 protocol 字段且从未填充
• 前端：App.vue 三页手动切换（状态/连接配置/设置），CanvasView/VueFlow 画布 + StatusView 5s 轮询 + SettingsView

已知问题（审查发现，待修复）

1. 设置保存失效（P0） 已修复：server.go 的 NewServeMux 现在对 PUT /api/manager/settings 分发到 handleSettingsPut，新增 TestSettingsPutRoundTrip 回归测试，前端 SettingsView 保存生效。
2. dev proxy 端口不一致 已修复：web/vite.config.ts proxy 指向 127.0.0.1:7500（可用 VITE_PROXY_TARGET 覆盖），与后端默认一致。
3. 冗余依赖：vue-router 在 package.json 依赖中但未被使用（App.vue 以视图 ref 手动切页，无路由）。
4. README 笔误：架构图写 cmds/webui4frpc，实际目录为 cmd/webui4frpc。

里程碑

M1 高级传输参数（P0，建议优先）

目标：让常用 frpc 能力可配置，保持画布简洁（折叠高级区）。

• Local 增加高级字段：useEncryption / useCompression / bandwidthLimit / poolCount / metadatas / annotations（渲染器 + 编辑表单 + 折叠 UI）
• Remote 增加 transport：protocol（tcp/quic/kcp/websocket）、tls.enable、poolCount
• 渲染器补齐 transport 段输出；增加 render 单测覆盖新字段
• 高级字段随 canvas API 持久化（store 表扩展 + 迁移）

M2 HTTP/HTTPS 完善

• local http/https 增加可编辑域名字段（customDomains / subdomain）
• locations（路径路由）多配置
• httpHeaderRewrite / hostHeaderRewrite / basicAuth（站点访问认证）
• frps vhostHTTPPort 的显示与状态映射（状态页展示）

M3 负载均衡与健康检查

• 模型扩展：Local 增加 lbGroup / lbGroupKey / healthCheck* 字段，Remote 增加 adminAddr / adminPort / adminUser / adminPassword（local frpc admin API）
• 渲染器：proxy 输出 loadBalancer + healthCheck 段；worker 配置输出 webServer 段（frpc >= 0.52 支持）
• 状态页：按 admin API GET /api/status 拉取真实 per-proxy 状态（running / check failed / wait start / start error / new / closed），未启用 admin 时回退日志推断
• 前端：LocalNode/RemoteNode 表单 + StatusView per-proxy 状态与 LB 组徽标（vue-tsc 通过）
• CLUSTER 页：展示负载均衡组（group）+ 健康检查状态（e2e 验证：backend 停止→check failed 剔除，恢复→自动收回）

M4 更多代理类型

• tcpmux（HTTP/2 多路复用）
• stcp / sudp（点对点加密穿透）
• xtcp（P2P，需 kcp）
• 按类型动态显示字段的表单

M5 运维与发布

• git init + 首次 commit + .gitignore（排除 node_modules / web/dist；.pi/ 本地代理状态已忽略）
• 一键构建脚本（web→dist→embed→单二进制）
• GitHub Actions：release 构建（linux/windows/mac）
• 配置导出/导入（备份）
• 日志查看页（worker 日志 tail UI）

注：发布类条目已并入 M7 运维与发布（原 M5），本节 M5 保留初始清单。

M6 集群（令牌环网拓扑）

权威设计（用户约定，必须固化）：集群节点间通过**令牌环网（token ring）**通信，两轮为一个周期。

拓扑与角色

• 集群 = 若干 webui4frpc 节点组成的内网协作网络；逻辑上各节点平等，均持有完整集群信息（节点表、转发链、各自配置）与完整 webui。
• leader：唯一特殊角色，负责启动时发送第一个令牌；默认创建集群的节点为初始 leader。
• 转发链（ring）：令牌按固定顺序传递；每个节点记录前驱/后继。

令牌环协议（两轮一周期）

• 第一轮：令牌在环上传递，各节点收到后把自己的信息追加到令牌（地址、负载指标、frpc 缓存、转发能力等）。
• 第二轮：令牌再次环行，各节点按令牌内容同步集群信息（更新自己的完整集群视图）。
• 新转发任务：需要建立转发时，把任务附加在令牌中（而非直接指派）；因每节点都持完整集群信息，由负载最低的节点（内存使用率 + 网络使用率共同判断）自行摘取并创建转发。
• 负载摘取：令牌传递到某节点时，若该节点在上一轮被判定为负载最低，则先主动摘取任务，随后在令牌中更新自身信息。

容错与邻居离线

• 令牌传递超时（未收到回执）→ 判定邻居离线。因每节点持完整集群信息，当前节点可自动修改集群状态，并把邻居负责的转发作为新任务追加到令牌，再传给下一节点。
• leader 检测令牌丢失：发出令牌后超过 (轮次延迟 / 2 + 20ms) 未回传 → 判定令牌丢失（可能某节点接令后崩溃），重发令牌。
• leader 每轮探测后更新一次轮次延迟。

leader 补充/监控

• leader 受其上家邻居监控：二者交换心跳包（因节点都持完整信息，容易做到）。
• 上家邻居探测到 leader 崩溃 → 自身成为新 leader。

新节点加入

• 每个节点都有 webui；用户登录到哪个节点的 webui，就由该节点执行新节点加入：令牌发到自己时，先转发给新节点，并把新节点加入令牌中的集群信息，更新转发链：新节点放在自己后面，自己原本的后继放在新节点之后。

增量日志同步（本机事件 → 令牌 → 全网一致）

• 每个节点维护一份集群事件日志（operation log）：本机发生的变更（创建/删除转发、节点加入/离开、负载变化、leader 变更）以递增序号追加为本机日志条目。
• 令牌第二轮（同步轮）携带本机日志增量：号码 > 上一周期已同步水位（lastSyncedSeq）的条目，随令牌环行时让其它节点按序追加重放到本地日志，从而实现全网增量日志同步。
• 日志条目不可变（追加式）；节点收到增量后校验序号连续性（缺失则请求补齐），因每个节点持有完整集群信息，可从其它节点补拉。
• 集群状态（拓扑/任务/leader）可由日志重放得到：新节点加入时，通过令牌/邻居拉取完整日志并重放，即可获得与其它节点一致的完整视图（满足"每个节点都掌握完整集群信息"）。
• 该机制与"令牌承载中间配置文件/转发拓扑"正交共存：令牌同时携带〔拓扑快照〕与〔日志增量〕，快照用于即时校验，日志用于一致性追补。

实现里程碑（待按上述设计重建）

• 数据面：TypeSet 集群状态（节点表/转发链/leader/轮次延迟/负载指标/待办任务），每节点一份完整副本
• 令牌环传输：HTTP 轮转传递 + 回执；两轮一周期（信息追加 → 同步）
• leader：初始 leader 选择（创建集群者）、首令牌发送、轮次延迟测量、令牌丢失重发
• 新转发任务：挂到令牌 → 各节点负载评估（内存+网络）→ 负载最低节点摘取并创建
• 离线处理：令牌超时 → 改集群状态 → 邻居转发转任务重挂
• leader 监控：上家邻居心跳探测 → 崩溃提升为新 leader
• 新节点加入：入口节点 webui → 令牌插入新节点 + 更新转发链
• 前端：集群页展示环拓扑/令牌轮次/负载/任务摘取；设置页二进制缓存状态

M7 运维与发布（原 M5）

• git init + 首次 commit + .gitignore
• 一键构建脚本 / GitHub Actions release / 配置导入导出 / 日志查看页

建议推进顺序

1. 修复「设置保存失效」——给 PUT /api/manager/settings 补注册（server.go 方法分发 + httpapi 单测）
2. 对齐 dev proxy 端口——vite.config.ts → 7500（支持 VITE_PROXY_TARGET 覆盖）
3. M1 高级传输参数（store 加列 → render 输出 → 前端折叠表单 → 单测回归）
4. M3 负载均衡与健康检查（模型 → 渲染 → admin API 状态 → 集群页）— 进行中
5. M6 集群内 frpc 二进制分发（节点间优先 → 外部 URL 兜底 → 新节点自动传输）

审查结论摘要（详见 FRPC_FEATURES_AUDIT.md）

• 已支持：tcp / http（customDomains）、token 认证、多对多、worker 管理
• 未支持：stcp/sudp/xtcp/tcpmux、OIDC/TLS 证书、加密/压缩/限速/连接池、LB/健康检查、http 路由高级、插件/虚拟 IP
• 优先级：P0 高级传输参数 → P1 域名字段+transport → P2 LB/健康检查 → P3 低频项
• UI 原则：高级字段折叠式 / 按类型动态显示，保画布简洁