c69fb2caba
feat(cluster): 负载均衡改为每节点自主「先撤销本地转发，再丢回环」
...
按用户要求重做：不再由 leader 单独调度，而是**每个节点对自己的转发跑同一条
规则**，超了就自己撤销一条、把任务丢回环上，由环原有的「最闲者认领」决定它
落到哪台。
## 为什么必须是 owner 自己动手（不是洁癖，是实测逼出来的）
真机探针（跑完已删）显示，真实 revoke 之后：
TopologyOwner after revoke = "n1" ← 条目还在（只标记不删除）
n1 Forwards=3 score=310.0 ← 负载根本没降
after step: revoking=true publishing=false
⇒ 一节点的负载**只有它自己的拓扑条目消失时才会下降**，而条目是本地簿记，没有任何
对端可以代它写。leader 从外面只能看见失衡、无法让失衡成为事实——它必须伸手去改
另一个节点的簿记，而这正是这个环到处都在避免的跨节点写（revoke / restart 定向往
owner 也是同一个理由）。
⇒ 而且旧实现**根本跑不起来**：phase 1 判据是「条目消失」，可 mark-don't-remove
让它永远不消失，于是每 120s 打一条 `revoking … timed out; abandoning`，
**phase 2 永不执行，一条转发都不会迁**。开 `W4F_BALANCE_MODE=on` 只会刷日志。
## 规则（替代原来的 ratio 阈值）
当 Forwards >= 2 且 Forwards > ceil(总数/存活节点数) 时，撤销一条
- **自限**：3 条 / 3 台 → owner 2 > 1，卸一条 → 1，`1 > 1` 不成 → 停。
没有上界的话 owner 会把转发**全部卸光**。
- **不会卸空**：低于下限（2）永不撤销。
- 平摊值向上取整（3/3=1，不是 0），否则 1 条 / 3 台的节点也算「超了」。
- **不再用 mem/net 参与判据**：实测 `.30` 空闲时 netPct 能到 55%，Score 会高于
有转发的节点——用 Score 会把纯网络抖动当成负载。
- 节奏用**每节点冷却**（默认 600s）而不是「失衡持续多久」窗口：规则本身已经要求
真实失衡，没有需要平滑的瞬态，只有需要限制的抖动频率。
## 为什么必须是新的 Release 任务类型，不能复用 Revoke
用户停止（Revoke）**保留拓扑条目**作为 disabled 标志的载体；均衡释放必须**删除
条目**，因为 (a) 负载由自己的条目数算出，条目不删负载不降；(b) 每个节点的
duplicate-guard 会拒绝「已有 owner 的转发」的创建任务——保留条目会让**所有节点
都拒领**，转发被永久搁死在刚放弃它的那台机器上。
Release 因此：`Handler.Release`（停 worker，但**不标记 stopped**）→ 删条目 →
`SubmitTask` 以**启用状态**重新发布。它需要自己的 Handler 方法，不能回落到
Revoke：Revoke 会顺手把 link 标成 stopped，而这条转发即将在别的节点上跑。
## 顺带修掉两个既有缺口（实测确认）
1. **`submitMigrate` 发布不出去**：`OnToken` 的 localPending 重合并只保留「从未
publish 过」的本地 pending，而只有 `Add*` 系列会记 `published`。引擎里直接写
`PendingTasks` 的任务会在下一次 adopt 时被静默丢弃。
⇒ 新 `ReleaseTask` 走 `AddPending`。
（`SubmitRestart` 有同样的毛病，但它不在本次范围，未改动——见提交说明末尾。）
2. `Release` 需要绕过 duplicate-claim 守卫（同 Restart），否则「owner 本来就持有
这条转发」这一前提会让每条 Release 都被丢掉。
## 测试（17 条，全绿）
规则：平摊值取整、超了才撤、撤到平摊就停、单节点不撤、低于下限不撤、不撤已停
转发、候选选择确定。
机制：Revoke 留载体 vs Release 删条目（这是两种语义的核心差异）、Release 只由
owner 执行且不消费他人的任务、owner 释放后环的普通认领把它接走。
模式：dry-run 不动任何东西、off 真的什么都不做、未知模式回落 dry-run、
冷却限制抖动频率、确认超时清理。
只读：Report 不变更任何状态、能解释「超了但不动」的原因、均衡节点给出真实答案。
**双向验证 3 条**（改坏→变红→还原→变绿）：
- 去掉 Release 的 duplicate-guard 例外 → `the owner released 0 times, want 1`
- 去掉「不超过平摊值」上界 → `2 owned against share 2 must not release`
- Release 改成只标记不删除 → `n1 should now own 2, got 3`
go build / go vet / go test ./... 全绿（go clean -testcache 后逐包实跑）。
## 未做 / 待办
- `SubmitRestart` 的同类发布缺口未修（同样会被 adopt 丢弃），需要单独确认它
在实机上是否真的丢过 restart。
- UI 尚未跟进新报告结构（下一步）。
2026-10-06 14:03:03 +08:00
7d5bca5b72
feat(cluster): 负载均衡迁移 —— 定向投递 + 两阶段提交
...
承接 875e580（只落决策逻辑）。本提交补齐运行时：周期检查、迟滞判定、
两阶段迁移，以及让迁移任务**定向**到指定节点。
## 为什么必须是定向的（核心安全点）
loadSnapshot() 的 Forwards 来自 ForwardsOwnedBy，所以旧 owner 一旦被摘掉条目，
它立刻变成最闲节点。而普通创建任务是"任何最闲者认领"—— 于是它会把刚迁走的
转发**当场抢回**，迁移变成"只重启一次 worker"的空操作。
故 Task 新增 Migrate + Target 字段，runCommands 的选择循环照 Restart 的范式
处理：Target == 自己才认领，否则 `continue` 让任务随环前进。
## 为什么必须两阶段（不能一次发 revoke + submit）
1. 旧 owner 变最闲后会把未定向的任务抢回（上面那条）；
2. PendingList 按 `t<ID>` **字符串**排序（`t10 < t5`），同轮内两个任务的先后
不可控。
Balancer 因此是显式状态机：phase1 发布 revoke 并等待旧条目真正消失，确认后才
发布 phase2 的定向 migrate。两个超时兜底：revoke 超时则放弃；migrate 超时
（target 没认领）则退回**无定向** SubmitTask，让"任何最闲者"接手 —— 转发不会
被丢，只是延迟。这与环本身的行为一致（实测：只要还有更闲的节点，pending 任务
最终会被认领；只有"全员都更忙"时才滞留）。
## 两个被测试逼出来的设计修正
- **绝对下限 minForwards=2**：只有"超均值倍数"在小集群失真——3 节点 1 条转发时
owner Score≈105 而两台空闲≈5，20 倍于均值会触发迁移，但那是完全正常的分布，
迁它只会断一条活跃连接。倍数负责看形状，下限负责"有没有东西值得搬"。
- **Migrate 也要绕过 duplicate-claim 守卫**，否则旧条目还在时目标节点会拒绝
认领（这条守卫正是为了防止同一 remotePort 注册两次 → frps 报
"proxy already exists"）。
## 测试（本项目第六次假绿的教训）
新增 6 条，全绿。做双向验证时发现
TestMigrateTaskIsAddressedNotClaimedByLightest **删掉定向分支后仍然 PASS**，
查因：`loadSnapshot()每次 OnToken 都用 Handler.RuntimeLoad() 刷新 mem/net，
我手工设的 State.Nodes[].Load 被静默覆盖 ⇒ n2/n3 始终平手 ⇒ "最闲者"恰好
就是 target，定向性从未被验证。
改为**用三个 Handler 的不同 RuntimeLoad 制造真实差异**（n3 最闲、n2 是较重的
target）后，删掉定向分支如期变红：
n3 (the LIGHTEST node) claimed 1 migrate task(s); the task is addressed
to n2 and must ignore load entirely
⇒ 这条纪律再次生效：测试必须制造出能让错误实现暴露的**不对称**，否则"恰好通过"
比"失败"更危险。
go build / go vet / go test ./... 全绿，gofmt 干净。
2026-10-06 11:50:53 +08:00
1c835425de
feat(cluster): 停用改为「标记」语义，让 disabled 真正随令牌环跨节点传播
...
承接用户提问「设计上停用不是本来就会跨节点传输吗」——核实结论：结构上确实
如此（TopoEntry.Link 是完整 store.Link，整个 State 随 token 每轮广播），但
实际路径断了。断点正是「撤销会删掉 topology 条目」：条目是 flag 的载体，
删了就无处传播，于是停用只能靠一次性 revoke 任务投递给 owner，**owner 当时
不在线就收不到**（实测 .60 记 disabled=1 / .106 记 0，就是这么来的）。
## 改为标记而非移除
撤销不再 RemoveTopology，而是 UpdateTopologyDisabled(true)，条目保留、
Link.Disabled=true、Active=false。Active 正是为此存在：OfflineReassign()
只处理 Active 条目，所以停用的转发在 owner 掉线时不会被重新排队。
- 新增 UpdateTopologyDisabled / TopologyDisabled（照 UpdateTopologyGroup 的桥）
- 新增 store.ReconcileLinkDisabled 作接收端：adoption 时把环上的 flag 落进
本地 store；本节点没有该转发时补一条 disabled 占位行（否则日后在本节点被
claim 会复活），enable 则不建行
- SetTopologySync 由单向（store→环）扩为双向：群组仍上行，disabled 下行
- AddTopology 的 Active 跟随 Link.Disabled（原本硬编码 true，认领一个停用
转发就会复活它）
- 审计日志细分 forward.stop / forward.start，与 forward.remove 区分
## 语义变更带出的两个新问题（都已修）
1. **「启动」这条路断了**。条目保留 ⇒ SubmitTask 被去重挡下，而认领路径的
duplicate-claim 防御又会丢弃「已有 owner」的任务 ⇒ 重启任务发不出去，owner
永远收不到，转发**能停不能起**。
修：新增 Task.Restart 这一独立任务类型 + SubmitRestart + Handler.RestartFn，
显式绕过 duplicate-claim 防御并原地复活（不重复建条目、不重跑 claim 簿记）。
SubmitTask 的守卫同时从 HasTask 收窄为新的 HasActiveTask（跳过 disabled 条目
与撤销任务）；saveCanvas 的判断相应改用 HasActiveTask，避免每次保存都对
已标记的转发重复发撤销。
2. 原本两处 RemoveTopologyEntry 调用（ClaimFn/RevokeFn 的 disabled 分支）在
新语义下会把本该保留的条目删掉，改为 UpdateTopologyDisabled。
## 测试（每个都做了「回退修复行→必须变红→还原变绿」双向验证）
- TestStoppedTopologyEntrySurvivesAdoption —— 离线成员也能学到停用，
一次性 revoke 任务永远做不到这一点
- TestStoppedForwardNotRequeuedOnNodeDeparture / TestAddTopologyRespectsDisabledFlag
—— 标记而非删除为何安全
- TestSubmitTaskNotBlockedByStoppedEntry / TestSubmitTaskStillDedupesActiveForward
- TestRestartTaskBypassesDuplicateClaimGuard / TestRestartFlagSurvivesTokenSerialization
- TestStopThenStartPublishesRestartTask（HTTP 端到端，断言**任务真的发出**）
- TestReconcileLinkDisabled*（store 侧三条）
★ 两次踩到**假绿**：第一版只断言 store 层（newTestHandler 的 Ring 为 nil，
坏掉的路根本没执行）；第二版在 re-enable **之后**才调 SubmitTask，此时新旧
谓词结果相同，测不出差异。都是靠「回退修复行看是否变红」抓出来的 —— 这个
双向验证已经是本项目的固定动作。
go build / go vet / go test ./... 全绿，gofmt 干净。
2026-09-26 10:44:04 +08:00
4a41608d94
refactor: 审查修复 — netload 消除重复 /sys 读 + 全项目 gofmt
...
- netload_linux.go: SampleNetLoad 聚合循环不再对每接口重复
readIfaceSpeed (snapshot 已汇总 cur.capMbps), 每次采样省 N 次 /sys 读
- gofmt -w: ring.go/ring_engine.go/auth.go/handlers.go/handlers_logs.go/
handlers_users.go/store.go 结构体字段对齐与注释缩进
- README.md: markdownlint 自动修复 (MD028/MD040)
审查结论: 令牌环本身即互斥协议 — OnToken(收令牌)与 StartRing(发令牌)
在同一节点上由令牌串行化, 不存在需要加锁的竞争; WatchLeader 的读为
良性读, 无需 mutex
2026-08-24 22:24:35 +08:00
2552c14faf
fix: start/stop for ring-only forwards + group sync via ring topology
...
Three issues fixed:
1. Start/stop returned 404 for forwards owned by other nodes:
findLinkByTriple only checked local SQLite store. Added
findLinkFromTopology fallback — startForward/stopForward now look up
ring topology entries when the local store doesn't have the link.
2. Group labels didn't sync through the ring:
handleForwardsAssign only updated local SQLite, never the ring
topology. Added State.UpdateTopologyGroup + Engine.UpdateTopologyGroup
— handleForwardsAssign now updates both. Added topologySync callback
called after every e.state = tk.State (OnToken) and e.state = s
(AdoptState) to re-apply local store group overrides onto the freshly
adopted topology, so they survive state adoption and propagate via
the next token forward. handleForwardsGroupDelete also clears ring
topology entries.
3. Status-merge branch omitted Group field:
ring-only forwards always showed '未分组'. Added Group: t.Link.Group
to the topology-merge forwardStatus.
Verified: 4-node cluster, 5 forwards, group assigned on node-a
propagates to all nodes within one token cycle; stop from non-owning
node succeeds (HTTP 200) and worker stops on the owning node.
2026-08-19 21:52:28 +08:00
eda9bb9597
feat: cluster reliability (leader failover, crash rejoin, key exchange) + auth/users + canvas/forwards enhancements + comprehensive README + API docs
...
- Cluster: forwardToNext offline detection (leader+non-leader), WatchLeader 1s heartbeat fallback, 409 for standalone nodes, Node.NodeKey key exchange via token ring, ClusterPeers persistence + auto-rejoin, Forward delegates to forwardToNext (bugfix)
- Auth: Basic Auth (flag-creds fast path) + bcrypt users (admin/viewer) + Bearer API keys (read/write/admin scope)
- Frontend: UsersView (accounts+API keys), ClusterView (ring/nodeKey/tasks/topology/log), StatusView (group management, per-proxy status), CanvasView (edge toggle/group), PortEdge (disabled/group labels)
- API: handlers split (canvas/forwards/users/logs), canvas export/import, forwards group start/stop/assign/delete, cluster endpoints
- Docs: comprehensive README rewrite (all flags/APIs/auth/cluster), docs/cluster-api.md (cluster management API reference)
- Deploy: run-cluster.sh now 4-node ring + 1 isolated standalone, test-forward.sh updated for 4 nodes
- Removed plan.md (design notes consolidated into README + API docs)
2026-08-19 21:09:24 +08:00
b518a13446
feat: Phase C 完成 — ModelRouter 风格 UI 重设计 + 模拟 frps 测试 + lastSync 修复 + 集群作坊搭建
...
- 主题: sakura×frost 玻璃拟态 (theme.css) + SCSS 变量重映射
- 侧栏: 玻璃侧栏 246px + 渐变品牌区 + 面包屑导航
- 状态页: 玻璃 KPI 卡 + 远程节点/本地服务卡片网格
- 集群页: 英雄玻璃卡 + 横向环拓扑链 + 待办命令/活跃拓扑/日志区
- 令牌环: 新增 lastSync 上次同步时间替代周期计数
- 模拟 frps: frps2/frps3 容器 + test-forward.sh 全链路验证脚本
- 修复: BinaryPath 空导致 worker 不启动, 撤销仅撤第一个 link, 任务复活风暴 (published 追踪)
2026-08-18 23:38:20 +08:00
40980944e5
feat(M6): localOnly forward option (loopback→LAN rewrite for cluster, local direct), canvas diff-based create/revoke commands, revoke task semantics, topology derived canvas on sync nodes, LAN addr helper
2026-08-18 09:44:38 +08:00
bf602016b4
feat(web): cluster page shows token ring — ring topology/leader/load, pending tasks, active forward topology with owner, incremental log sync view (e2e verified)
2026-08-18 09:13:20 +08:00
e59feb82c1
feat(M6): token-ring incremental log sync — append-only op log, delta rides token round-2, nodes converge on identical history (e2e verified join events)
2026-08-18 08:59:59 +08:00
f6c4b91a96
feat(M6): token ring data plane + engine — pending adds disappear on claim, topology written back for full cluster view (per authoritative design)
2026-08-18 08:24:37 +08:00
