docs: 更新 README 与 cluster-api — per-forward 模型/网络负载/审计CSV/三级角色/session登录

README:
- 特性: per-forward 独立进程、NIC 负载采样、冲突检查、Del 键删除
- 认证: session-cookie 登录 + 三级角色 (superadmin/admin/viewer)
- 审计: 4 个 CSV 导出端点说明
- 构建: dist 不再进 git (编译前需 cp -r)
- 数据目录: 配置/日志路径改为 per-forward 键式
- 架构: 更新模块说明 (worker_key/session/audit)
- API 表: 新增 login/logout + 审计导出 4 端点
- gofmt: store.go 注释对齐

docs/cluster-api.md:
- §9 审计 CSV 导出: 四个端点用法、示例行、公式注入防御说明
This commit is contained in:
JianFeeeee
2026-08-24 23:52:16 +08:00
parent f90627f542
commit 94b6396738
3 changed files with 107 additions and 24 deletions

View File

@ -11,9 +11,11 @@
- **Scratch 风格画布**:本地转发项(local)与远程服务器(remote)可视化连线,一个 local 可连多个 remote,一个 remote 可连多个 local
- **曲线连线 + 端口标签**:每条连线独立曲线,标签为远程端口,可拖拽调整曲线位置,端口可点开编辑
- **画布冲突检查**:保存时自动检测远程端口/域名重复,避免配置冲突
- **边开关与分组**:画布边上可一键禁用/启用单条转发,可打分组标签(状态页按分组管理、一键启停整组)
- **Del 键/× 按钮删除**:选中连线按 Delete 键或点击端口标签红 × 删除,确认后标记脏
- **一键生成配置**:保存画布即渲染每台 remote 的 frpc JSON 配置,自动拉起/重启对应 worker
- **画布导入导出**:支持 JSON 备份/恢复
- **画布导入导出**:支持 JSON 信封备份/恢复(含 provenance 元数据)
### frpc 能力
@ -27,6 +29,10 @@
- **令牌环协议**:若干 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,新节点加入需提供对端密钥;密钥随令牌环交换,全节点互通
@ -34,10 +40,11 @@
### 认证与权限
- **Basic Auth**:启动参数配置管理员账号密码(flag-creds 快速路径,不走 bcrypt)
- **用户管理**:admin / viewer 两种角色,bcrypt 存储,webui 管理
- **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(查看)< write(修改)< admin(用户/密钥管理)
- **审计导出**:read 级 view 即可导出 CSV(账号登录记录 / API Key 使用记录 / 集群操作日志 / worker 运行日志)
## 构建
@ -59,10 +66,10 @@ cd web && npm install && npm run build
rm -rf internal/httpapi/dist && cp -r web/dist internal/httpapi/dist
```
一键全量构建:
一键全量构建(dist 不进入 git,编译前必须构建前端):
```bash
cd web && npm run build && cd .. && cp -r web/dist/* internal/httpapi/dist/ && go build -o webui4frpc ./cmd/webui4frpc
cd web && npm run build && rm -rf internal/httpapi/dist && cp -r web/dist internal/httpapi/dist && go build -o webui4frpc ./cmd/webui4frpc
```
## 运行
@ -101,10 +108,10 @@ cd web && npm run build && cd .. && cp -r web/dist/* internal/httpapi/dist/ && g
```
<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
├── 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
```
## 架构
@ -113,20 +120,20 @@ cd web && npm run build && cd .. && cp -r web/dist/* internal/httpapi/dist/ && g
webui4frpc(单二进制,无 frp 依赖,前端 go:embed)
├── cmd/webui4frpc 入口:flag 解析 → store/process/cluster 装配 → HTTP 服务 + 生命周期
├── internal/
│ ├── store SQLite 持久化(locals / remotes / links / settings / users / api_keys)
│ ├── store SQLite 持久化(locals / remotes / links / settings / users / api_keys / sessions)
│ ├── canvas 画布模型(local / remote / link 多对多)
│ ├── render 渲染 frpc JSON 配置(tcp/udp/http/https + 高级参数 + LB/健康检查)
│ ├── process worker 进程管理(spawn/stop/restart/自愈/日志轮转)
│ ├── render 渲染 frpc JSON 配置(per-forward 单 proxy + 高级参数 + LB/健康检查)
│ ├── process worker 进程管理(spawn/stop/restart/自愈/日志轮转,worker 键 = local~remote~port)
│ ├── install 一键下载官方 frpc(GitHub Releases,含解压安全防护)
│ ├── cluster 令牌环协议(ring engine / leader 选举 / 容错 / 宕机重联 / 二进制分发)
│ └── httpapi REST API + 静态资源(auth / canvas / forwards / cluster / users)
│ ├── 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`,使用 Basic Auth 或 Bearer API Key 认证。权限分 read / write / admin 三级。
所有接口前缀 `/api/manager`。UI 使用 session-cookie 登录(`/login` `/logout`),API 兼容 Basic Auth 或 Bearer API Key。权限分 read / write / admin 三级,角色 superadmin / admin / viewer 映射到不同 UI 可见性与操作能力。
| 类别 | 方法 | 路径 | 权限 | 说明 |
| --- | --- | --- | --- | --- |
@ -156,9 +163,15 @@ webui4frpc(单二进制,无 frp 依赖,前端 go:embed)
| | GET | `/cluster/nodes` | read | 集群节点 + 缓存 |
| | GET/POST | `/cluster/cache` | read/write | 二进制缓存管理 |
| | GET | `/node/logs` | read | 本节点 worker 日志 |
| | GET | `/cluster/logs/export` | 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 二进制分发 |
| **账号** | GET | `/me` | read | 当前身份 |
| **认证** | 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 列表/创建 |