webui4frpc/plan.md

# webui4frpc 开发计划

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

## 目标

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

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

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

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

### M2 HTTP/HTTPS 完善

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

### M3 负载均衡与健康检查

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

### M4 更多代理类型

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

### M5 运维与发布

- [x] 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 集群内 frpc 二进制分发（节点间优先，外部 URL 兜底）

> 诉求：集群内 frpc 二进制**优先通过集群节点间交换**获得，无法交换时才走外部 URL 下载；新节点加入集群时，**自动由邻居节点向其传输二进制**。

- [x] 二进制来源优先级：本地已有缓存 > 集群节点间交换（HTTP/Chunked 拉取） > 外部 URL（GitHub Releases）
- [x] 节点注册表：Registry（peers/nodeInf 内存态）+ EnsureVersion 优先级分发
- [x] 传输通道：节点间 HTTP GET /frpc/{version}（Basic Auth + 256MiB 上限 + SHA-256 校验），回退 GitHub URL
- [x] 入网引导：new node joins with -peer and auto-pulls binary from neighbors (verified e2e)
- [x] 失败回退：EnsureVersion 内建回退外部 URL（单测覆盖 peer 优先 + 回退）
- [ ] Cache 管理：版本保留策略（LRU / 仅保留常用）、可用性标记（黑名单失效节点）
- [ ] UI：设置页展示二进制来源与缓存状态，集群页展示节点间传输进度

### M7 运维与发布（原 M5）

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

## 建议推进顺序

1. [x] 修复「设置保存失效」——给 `PUT /api/manager/settings` 补注册（server.go 方法分发 + httpapi 单测）
2. [x] 对齐 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 原则：高级字段折叠式 / 按类型动态显示，保画布简洁