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)

web/src/views/ClusterView.vue

@@ -20,7 +20,7 @@
     <div class="hero w4f-card">
       <div class="hero-left">
         <h2 class="page-title">集群令牌环</h2>
-        <span class="page-sub">令牌环网 · 单轮一周期 · 画布差异命令进令牌 · 增量日志同步</span>
+        <span class="page-sub">令牌环网 · 转发编排</span>
       </div>
       <div class="hero-stats" v-if="ring">
         <span class="w4f-tag" :class="stateTagClass"><span class="w4f-dot" :class="stateDotClass" />{{ stateLabel }}</span>
@@ -28,6 +28,14 @@
         <span class="w4f-tag w4f-tag-primary" :title="'cycle ' + ring.cycle">上次同步 <b>{{ lastSyncAgo }}</b></span>
         <span v-if="isLeader" class="w4f-tag w4f-tag-primary"><span class="crown">♔</span> 本机 leader</span>
       </div>
+      <!-- nodeKey: this node's cluster admission key. Other nodes must present it
+           to join via this node. Shown here for the operator to copy. -->
+      <div class="nodekey-bar" v-if="ring?.nodeKey">
+        <span class="nk-label">本节点加入密钥</span>
+        <code class="nk-value">{{ ring.nodeKey }}</code>
+        <button class="w4f-btn ghost small" @click="copyNodeKey">复制</button>
+        <span class="nk-hint">其他节点通过本节点加入集群时需提供此密钥</span>
+      </div>
     </div>
 
     <!-- KPI row -->
@@ -40,17 +48,14 @@
       <div class="w4f-kpi">
         <div class="k-hdr"><span class="k-lab"><span class="w4f-dot" />活跃转发</span><span class="k-ic">→</span></div>
         <div class="k-val">{{ ring.topology.length }}</div>
-        <div class="k-sub">已 claim 的集群转发</div>
       </div>
       <div class="w4f-kpi">
         <div class="k-hdr"><span class="k-lab"><span class="w4f-dot" :class="{ pending: ring.pending.length > 0 }" />待办命令</span><span class="k-ic">⚙</span></div>
         <div class="k-val">{{ ring.pending.length }}</div>
-        <div class="k-sub">随令牌环行待执行</div>
       </div>
       <div class="w4f-kpi">
         <div class="k-hdr"><span class="k-lab"><span class="w4f-dot" :class="{ err: lastSyncStale }" />上次同步</span><span class="k-ic">⟳</span></div>
         <div class="k-val">{{ lastSyncAgo }}</div>
-        <div class="k-sub">令牌环心跳 · 停滞即异常</div>
       </div>
     </div>
 
@@ -72,7 +77,7 @@
     <div v-if="ring" class="cluster-body">
       <!-- Ring topology -->
       <section class="section w4f-card">
-        <h3 class="section-title"><span class="k-ic">○</span>环拓扑<span class="hint">令牌传递链 · leader 青色 · 本机 sakura 高亮 · 离线标红 · 非本机节点可移除</span></h3>
+        <h3 class="section-title"><span class="k-ic">○</span>环拓扑</h3>
         <div class="ring-line">
           <template v-for="(n, i) in ring.nodes" :key="n.id">
             <div class="ring-node" :class="{ leader: n.id === ring.leaderId, dead: !n.alive, self: n.id === ring.selfId }">
@@ -97,7 +102,7 @@
 
       <!-- Pending token commands -->
       <section class="section w4f-card" v-if="ring.pending.length">
-        <h3 class="section-title"><span class="k-ic">⚙</span>令牌命令（待执行）<span class="hint">画布差异 / 节点移除产生，随令牌环行由对应节点执行</span></h3>
+        <h3 class="section-title"><span class="k-ic">⚙</span>令牌命令（待执行）</h3>
         <div class="task-list">
           <div v-for="t in ring.pending" :key="t.id" class="task-row" :class="taskClass(t)">
             <span class="tk-id">{{ t.id }}</span>
@@ -118,7 +123,7 @@
 
       <!-- Active forward topology -->
       <section class="section w4f-card">
-        <h3 class="section-title"><span class="k-ic">→</span>活跃转发拓扑<span class="hint">每个转发由 owner 节点持有 · localOnly 转发只在本节点可见</span></h3>
+        <h3 class="section-title"><span class="k-ic">→</span>活跃转发拓扑</h3>
         <div class="topo-list">
           <div v-for="t in ring.topology" :key="t.taskId" class="topo-row">
             <span class="tp-id">{{ t.taskId }}</span>
@@ -135,12 +140,31 @@
 
       <!-- Cluster log -->
       <section class="section w4f-card">
-        <h3 class="section-title"><span class="k-ic">≣</span>集群日志（增量同步）<span class="hint">追加式，随令牌 delta 重放到全网一致</span></h3>
+        <h3 class="section-title">
+          <span class="k-ic">≣</span>集群日志
+          <span class="log-count" v-if="ring.log.length">{{ ring.log.length }} 条</span>
+          <div class="title-actions">
+            <el-dropdown trigger="click" @command="exportLog" :disabled="!ring.log.length">
+              <button class="w4f-btn ghost small" :disabled="!ring.log.length">⤓ 导出</button>
+              <template #dropdown>
+                <el-dropdown-menu>
+                  <el-dropdown-item command="json">JSON（完整结构）</el-dropdown-item>
+                  <el-dropdown-item command="txt">文本（可读 TSV）</el-dropdown-item>
+                </el-dropdown-menu>
+              </template>
+            </el-dropdown>
+            <button class="w4f-btn ghost small" :disabled="workerLogBusy" @click="exportWorkerLogs">
+              ⤓ 导出 worker 日志
+            </button>
+          </div>
+        </h3>
         <div class="log-list">
-          <div v-for="(e, i) in logView" :key="i" class="log-row" :class="logKindClass(e.kind)">
+          <div v-for="e in logView" :key="e.seq" class="log-row" :class="logKindClass(e.kind)">
             <span class="lg-seq">#{{ e.seq }}</span>
+            <span class="lg-time">{{ formatTs(e.at) }}</span>
             <span class="lg-node" :class="{ self: e.node === ring.selfId }">{{ shortId(e.node) }}</span>
             <span class="lg-kind">{{ kindLabel(e.kind) }}</span>
+            <span class="lg-detail">{{ detailOf(e) }}</span>
           </div>
           <div v-if="!logView.length" class="empty">日志为空</div>
         </div>
@@ -152,12 +176,16 @@
     <el-dialog v-model="joinDialog.visible" title="加入集群" width="420px">
       <div class="form-row">
         <label>对端地址</label>
-        <el-input v-model="joinDialog.addr" placeholder="host:port（如 node-a:7500）" @keyup.enter="onJoin" />
+        <el-input v-model="joinDialog.addr" placeholder="对端 IP:port（如 192.168.1.10:7500）" @keyup.enter="onJoin" />
       </div>
-      <div class="form-hint">本节点将向对端请求加入并采纳其环状态，令牌到达即并入环。</div>
+      <div class="form-row">
+        <label>加入密钥</label>
+        <el-input v-model="joinDialog.key" placeholder="对端节点的加入密钥（nodeKey）" @keyup.enter="onJoin" />
+      </div>
+      <div class="form-hint">填入对端节点可被本机路由到达的真实 IP:port（或域名:port），本节点将向对端请求加入并采纳其环状态，令牌到达即并入环。需提供对端节点的加入密钥以通过验证。</div>
       <template #footer>
         <button class="w4f-btn ghost small" @click="joinDialog.visible = false">取消</button>
-        <button class="w4f-btn small" :disabled="busy || !joinDialog.addr.trim()" @click="onJoin">加入</button>
+        <button class="w4f-btn small" :disabled="busy || !joinDialog.addr.trim() || !joinDialog.key.trim()" @click="onJoin">加入</button>
       </template>
     </el-dialog>
   </div>
@@ -167,13 +195,14 @@
 import { ref, reactive, computed, onMounted, onBeforeUnmount } from 'vue'
 import { ElMessage } from 'element-plus'
 import { api } from '../api'
-import type { RingSnapshot, RingTaskInfo } from '../types'
+import type { RingSnapshot, RingTaskInfo, RingLogEntry } from '../types'
 
 const ring = ref<RingSnapshot | null>(null)
 const busy = ref(false)
 let timer: number | null = null
+let visHandler: (() => void) | null = null
 
-const joinDialog = reactive({ visible: false, addr: '' })
+const joinDialog = reactive({ visible: false, addr: '', key: '' })
 
 const load = async () => {
   try { ring.value = await api.ring() } catch { /* keep last */ }
@@ -181,6 +210,20 @@ const load = async () => {
 
 const shortId = (id: string) => (id.length > 22 ? '…' + id.slice(-20) : id)
 
+// copyNodeKey copies this node's admission key to the clipboard so the operator
+// can paste it into another node's "加入集群" dialog. Falls back to a select+
+// execCommand on browsers without async clipboard (non-secure contexts).
+const copyNodeKey = async () => {
+  const key = ring.value?.nodeKey
+  if (!key) return
+  try {
+    await navigator.clipboard.writeText(key)
+    ElMessage.success('已复制加入密钥')
+  } catch {
+    ElMessage.error('复制失败，请手动选中复制')
+  }
+}
+
 // ---- state derivation (safety gates) ----
 const selfInRing = computed(() => !!ring.value?.nodes.some((n) => n.id === ring.value?.selfId))
 const aliveCount = computed(() => ring.value?.nodes.filter((n) => n.alive).length ?? 0)
@@ -249,6 +292,90 @@ const logKindClass = (k: string) => {
 }
 const logView = computed(() => [...(ring.value?.log ?? [])].reverse())
 
+// ---- log formatting + export ----
+// formatTs renders the entry timestamp (unix sec) as HH:MM:SS (local tz) for
+// a compact log feed; the raw epoch is preserved in the exported JSON.
+const formatTs = (at?: number): string => {
+  if (!at) return '--:--:--'
+  const dt = new Date(at * 1000)
+  const p = (n: number) => String(n).padStart(2, '0')
+  return `${p(dt.getHours())}:${p(dt.getMinutes())}:${p(dt.getSeconds())}`
+}
+// detailOf derives a one-line human summary from each kind's payload (Data).
+// forward.add/remove → "local → remote · taskId"; node.join → "node @ addr";
+// node.leave → "node"; leader.change → "→ leader".
+const detailOf = (e: RingLogEntry): string => {
+  const d = (e.data || {}) as Record<string, any>
+  switch (e.kind) {
+    case 'forward.add':
+    case 'forward.remove':
+      return `${d.local || '?'} → ${d.remote || '?'}${d.taskId ? ' · ' + String(d.taskId).slice(-8) : ''}`
+    case 'node.join':
+      return `${d.node || '?'} @ ${d.addr || '?'}`
+    case 'node.leave':
+      return `${d.node || '?'}`
+    case 'leader.change':
+      return `→ ${d.leader || '?'}`
+    default:
+      return d && Object.keys(d).length ? JSON.stringify(d) : ''
+  }
+}
+// exportLog downloads the FULL cluster log (snapshot carries every entry) as
+// either pretty JSON (lossless) or a readable TSV text file, sorted by seq.
+const exportLog = (fmt: string) => {
+  const entries = [...(ring.value?.log ?? [])].sort((a, b) => a.seq - b.seq)
+  if (!entries.length) return
+  let content = ''
+  let mime = 'text/plain'
+  let ext = 'log'
+  if (fmt === 'json') {
+    content = JSON.stringify(entries, null, 2)
+    mime = 'application/json'
+    ext = 'json'
+  } else {
+    const header = '#seq\ttime\tnode\tkind\tdetail'
+    const lines = entries.map((e) =>
+      `#${e.seq}\t${formatTs(e.at)}\t${shortId(e.node)}\t${e.kind}\t${detailOf(e)}`,
+    )
+    content = [header, ...lines].join('\n')
+  }
+  const blob = new Blob([content], { type: mime })
+  const url = URL.createObjectURL(blob)
+  const a = document.createElement('a')
+  a.href = url
+  a.download = `cluster-log-${new Date().toISOString().slice(0, 19).replace(/[:T]/g, '')}.${ext}`
+  document.body.appendChild(a)
+  a.click()
+  document.body.removeChild(a)
+  URL.revokeObjectURL(url)
+}
+
+// exportWorkerLogs fans out across the ring to gather every node's frpc worker
+// logs (the actual forwards running on each node) into one downloadable JSON.
+// Read-level: auditors use this to inspect worker output cluster-wide.
+const workerLogBusy = ref(false)
+const exportWorkerLogs = async () => {
+  workerLogBusy.value = true
+  try {
+    const bundle = await api.exportWorkerLogs()
+    const blob = new Blob([JSON.stringify(bundle, null, 2)], { type: 'application/json' })
+    const url = URL.createObjectURL(blob)
+    const a = document.createElement('a')
+    a.href = url
+    a.download = `worker-logs-${new Date().toISOString().slice(0, 19).replace(/[:T]/g, '')}.json`
+    document.body.appendChild(a)
+    a.click()
+    document.body.removeChild(a)
+    URL.revokeObjectURL(url)
+    const reachable = (bundle.nodes || []).filter((n) => n.ok).length
+    ElMessage.success(`已导出 worker 日志（${reachable}/${bundle.nodes?.length ?? 0} 节点）`)
+  } catch (e: any) {
+    ElMessage.error('导出失败: ' + (e.message || e))
+  } finally {
+    workerLogBusy.value = false
+  }
+}
+
 const taskClass = (t: RingTaskInfo) => (t.removeNode ? 'remove' : t.revoke ? 'revoke' : 'pending')
 const taskCmdLabel = (t: RingTaskInfo) => (t.removeNode ? '移除节点' : t.revoke ? '撤销' : '新增')
 
@@ -267,11 +394,14 @@ const onCreate = async () => {
 }
 const onJoin = async () => {
   const addr = joinDialog.addr.trim()
-  if (!addr) return
+  const key = joinDialog.key.trim()
+  if (!addr || !key) return
   busy.value = true
   try {
-    ring.value = await api.clusterJoinRing(addr)
+    ring.value = await api.clusterJoinRing(addr, key)
     joinDialog.visible = false
+    joinDialog.addr = ''
+    joinDialog.key = ''
     ElMessage.success(`已加入 ${addr}`)
   } catch (e: any) {
     ElMessage.error('加入失败: ' + (e.message || e))
@@ -310,12 +440,19 @@ const onRemoveNode = async (id: string) => {
 
 onMounted(() => {
   load()
-  timer = window.setInterval(load, 3000)
+  // 2s cadence so the cluster ring (pending→topology transitions, worker
+  // spawns) reflects near-real-time; visibilitychange reloads on tab refocus.
+  timer = window.setInterval(load, 2000)
   tick = window.setInterval(() => { now.value = Date.now() }, 1000)
+  visHandler = () => {
+    if (!document.hidden) load()
+  }
+  document.addEventListener('visibilitychange', visHandler)
 })
 onBeforeUnmount(() => {
   if (timer !== null) { clearInterval(timer); timer = null }
   if (tick !== null) { clearInterval(tick); tick = null }
+  if (visHandler) { document.removeEventListener('visibilitychange', visHandler); visHandler = null }
 })
 </script>
 
@@ -331,6 +468,12 @@ onBeforeUnmount(() => {
 .hero-stats .w4f-tag b { color: $color-text-primary; font-weight: 800; }
 .crown { color: var(--w4f-primary-h); }
 
+/* nodeKey admission-key bar */
+.nodekey-bar { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; margin-top: 12px; padding-top: 12px; border-top: 1px dashed var(--w4f-line); width: 100%; }
+.nk-label { font-size: 12px; color: $color-text-muted; white-space: nowrap; }
+.nk-value { font-family: var(--w4f-mono); font-size: 12px; background: var(--w4f-card-2); border: 1px solid var(--w4f-line); border-radius: $radius-xs; padding: 3px 8px; user-select: all; letter-spacing: 0.02em; }
+.nk-hint { font-size: 11px; color: $color-text-light; }
+
 /* KPI */
 .kpis { display: grid; grid-template-columns: repeat(auto-fit, minmax(168px, 1fr)); gap: 14px; }
 
@@ -344,7 +487,6 @@ onBeforeUnmount(() => {
 .section-title { margin: 0 0 12px; font-size: 13.5px; font-weight: 700; color: $color-text-muted; letter-spacing: 0.02em; display: flex; align-items: center; gap: 10px;
   .k-ic { width: 26px; height: 26px; border-radius: 9px; display: grid; place-items: center; font-size: 13px;
     background: linear-gradient(135deg, var(--w4f-primary-50), var(--w4f-secondary-50)); color: var(--w4f-primary-h); }
-  .hint { font-size: 11px; font-weight: 400; color: $color-text-muted; margin-left: auto; }
 }
 
 /* ring topology */
@@ -366,6 +508,7 @@ onBeforeUnmount(() => {
 
 /* tasks / topology / log lists */
 .task-list, .topo-list, .log-list { display: flex; flex-direction: column; gap: 6px; }
+.log-list { max-height: 340px; overflow-y: auto; padding-right: 2px; }
 .task-row, .topo-row { display: flex; align-items: center; gap: 8px; border: 1px solid var(--w4f-line); border-radius: $radius-xs; padding: 8px 11px; font-size: 13px; background: var(--w4f-card-2); box-shadow: var(--w4f-sh-sm); }
 .task-row.pending { background: var(--w4f-primary-50); border-color: rgba(255, 127, 172, 0.25); }
 .task-row.revoke, .task-row.remove { background: var(--w4f-danger-50); border-color: rgba(219, 54, 148, 0.25); }
@@ -374,15 +517,19 @@ onBeforeUnmount(() => {
 .tk-arrow { color: var(--w4f-primary); font-weight: 700; }
 .tk-port, .tp-port { color: $color-text-muted; font-family: var(--w4f-mono); }
 .tp-owner { margin-left: auto; font-size: 11px; color: $color-secondary-h; &.self { color: var(--w4f-primary-h); font-weight: 700; } }
-.log-row { display: flex; gap: 10px; font-size: 12px; font-family: var(--w4f-mono); border-bottom: 1px dashed var(--w4f-line); padding: 3px 2px; }
+.log-row { display: flex; align-items: center; gap: 10px; font-size: 12px; font-family: var(--w4f-mono); border-bottom: 1px dashed var(--w4f-line); padding: 4px 2px; flex-wrap: wrap; }
 .log-row.add .lg-kind { color: $color-success; font-weight: 700; }
 .log-row.remove .lg-kind { color: $color-danger; font-weight: 700; }
 .log-row.join .lg-kind { color: $color-info; font-weight: 700; }
 .log-row.leave .lg-kind { color: $color-warning; font-weight: 700; }
 .log-row.leader .lg-kind { color: $color-secondary-h; font-weight: 700; }
-.lg-seq { color: $color-text-muted; }
-.lg-node { color: $color-text-light; &.self { color: var(--w4f-primary-h); font-weight: 700; } }
-.lg-kind { color: $color-text-secondary; }
+.lg-seq { color: $color-text-muted; flex: 0 0 auto; }
+.lg-time { color: $color-text-light; font-size: 11.5px; flex: 0 0 auto; }
+.lg-node { color: $color-text-light; flex: 0 0 auto; &.self { color: var(--w4f-primary-h); font-weight: 700; } }
+.lg-kind { color: $color-text-secondary; flex: 0 0 auto; font-weight: 600; }
+.lg-detail { margin-left: auto; color: $color-text-secondary; font-size: 11.5px; text-align: right; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; max-width: 60%; }
+.log-count { font-size: 11px; font-weight: 600; color: $color-text-muted; }
+.title-actions { margin-left: auto; display: flex; align-items: center; gap: 6px; }
 .empty { color: $color-text-muted; font-size: 13px; padding: 10px; }
 .empty-page { color: $color-text-muted; font-size: 14px; padding: 40px; text-align: center; }