cofluxd 0.3.0 → 0.5.0

package/README.md

@@ -11,25 +11,45 @@ npm i -g cofluxd
 ## 用法
 
 ```sh
-cofluxd                 # 首次=交互式引导（问登记密钥/设备名，不问服务器地址），之后=看状态
-cofluxd onboard         # 显式重新走交互式配置
-cofluxd up              # 零参数即可：起服务后打印浏览器授权链接，登录确认即完成登记
-cofluxd up --enroll-key <KEY>   # 走存量登记密钥流程（web「添加设备」给的命令）
-cofluxd status          # 服务器/登记（含"等待授权"）/服务状态
+cofluxd                 # 首次=up（起服务后打印浏览器授权链接），之后=看状态
+cofluxd up              # 幂等：零参数即可装/起；已装则按当前配置重装服务并重启
+cofluxd status          # 服务器/登记（含"等待授权"）/服务/连接状态
+cofluxd doctor          # 中心网络 + gateway/grant/loopback + daemon 状态分层自检
 cofluxd logs -f         # 看 daemon 日志
-cofluxd update          # 更新二进制并重启（worker 另可由 server 远程热升级）
-cofluxd reload          # 改了 settings.json 后重启生效
+cofluxd update          # 更新本地 supervisor 二进制并重启（worker 由 server 自动热升级）
 cofluxd down            # 停止
 cofluxd uninstall [--purge]   # 卸载（--purge 连二进制/配置/凭证一并删）
 ```
 
 默认连公共服务 `wss://api.coflux.dev/daemon`（自托管用 `--server` 改；已保存的地址继续生效，非默认时会有醒目提示）。
 
-不带 `--enroll-key` 时（推荐、默认）：`cofluxd up` 起服务后会打印一个一次性授权链接，在浏览器用已登录的账号打开确认即可，无需先去 web 控制台生成密钥。仍可用 `--enroll-key`（从 web 控制台「添加设备」获取）走无头/脚本化登记。
+`cofluxd up` 起服务后会打印一个一次性授权链接，在浏览器用已登录的账号打开确认即可（链接可在任意设备打开，包括无头设备），无需先去 web 控制台生成密钥。已登记设备重跑 `up` 不会重新触发授权。
+
+## 本地优先与 doctor
+
+desktop web 与 daemon 同机时，terminal/普通 Device RPC 优先连接本机固定 gateway（默认
+`127.0.0.1:8788`）；失败会自动走中心 opaque relay。远端访问始终可走 relay。`cofluxd doctor` 把两条
+路径分开诊断：
+
+```text
+中心：DNS → TCP → TLS → WebSocket
+本地：gateway bind → 持久 grant/Origin → loopback WebSocket
+状态：daemon → 中心的实际连接状态
+```
+
+- 本地项失败：结论是“直连降级”，只影响同机低延迟路径；中心 relay 正常时 daemon 仍在线可用。
+- 中心项失败：已经加载、已经配对且 cached direct 可用的页面仍能控制存活 session；刷新/冷启动不保证。
+- 网络层都通但 daemon 未连接：查看 `cofluxd logs`，通常是认证、版本或服务进程问题。
+
+doctor 只读取 gateway store 的结构、grant/Origin 数量和 bind 状态，不打印 browser 私钥、grant id、
+device token 或其它凭证。它的 loopback 检查只做主机侧 WebSocket upgrade；浏览器自身的 LNA/permission
+仍以 Chrome/Safari/Firefox 页面实测为准。
+
+> `onboard`、`reload` 命令已移除：onboard 并入零参数 `up`，reload 并入幂等化后的 `up`（重跑 `up` 即按 settings.json 重装服务并重启）。
 
 ## 配置
 
-所有配置在 `~/.coflux/settings.json`（`serverUrl` / `enrollKey` / `deviceName` / `shell`，含密钥故权限 600），**daemon 直接读这个文件**。手改后 `cofluxd reload` 生效。
+所有配置在 `~/.coflux/settings.json`（`serverUrl` / `deviceName` / `shell`），**daemon 直接读这个文件**。手改后重跑 `cofluxd up` 生效。
 
 支持 macOS（launchd）/ Linux（systemd user service）；服务崩溃自启、开机自启。
 

package/cofluxd.mjs

@@ -8,6 +8,10 @@ import { join, dirname } from "node:path";
 import { createInterface } from "node:readline/promises";
 import fs from "node:fs";
 import { spawnSync } from "node:child_process";
+import dns from "node:dns/promises";
+import net from "node:net";
+import tls from "node:tls";
+import crypto from "node:crypto";
 
 // 默认中心服务（公共 SaaS）；自托管用 --server 覆盖。
 const DEFAULT_SERVER = "wss://api.coflux.dev/daemon";
@@ -15,10 +19,12 @@ const DEFAULT_SERVER = "wss://api.coflux.dev/daemon";
 const REPO = "myWsq/coflux";
 const HOME = process.env.COFLUX_HOME || join(homedir(), ".coflux");
 const BIN_DIR = join(HOME, "bin");
-const SETTINGS = join(HOME, "settings.json"); // 用户配置（含一次性登记密钥）→ daemon 直接读；含密钥故 600
+const SETTINGS = join(HOME, "settings.json"); // 用户配置（serverUrl/deviceName/shell）→ daemon 直接读；600 权限防同机其他用户窥探
 const LOG_FILE = join(HOME, "daemon.log");
 const CRED = join(HOME, "credentials.json");
 const PENDING_AUTH = join(HOME, "pending-auth.json"); // worker 落盘的待授权链接（daemon.authorizePending）
+const CONN_STATE = join(HOME, "conn-state.json"); // worker 落盘的连接态快照（plan 033，见 crates/worker/src/conn_state.rs）
+const LOCAL_GATEWAY_STORE = join(HOME, "local-gateway.json"); // gateway key/origin/grant；doctor 只读结构与数量，绝不打印秘密
 const FDA_STATUS = join(HOME, "fda-status"); // supervisor 启动时探测落盘（仅 macOS，见 crates/supervisor/src/fda.rs）
 const SUP_BIN = join(BIN_DIR, "coflux-supervisor");
 const WRK_BIN = join(BIN_DIR, "coflux-worker");
@@ -26,6 +32,7 @@ const IS_MAC = platform() === "darwin";
 const IS_LINUX = platform() === "linux";
 const PLIST = join(homedir(), "Library", "LaunchAgents", "com.coflux.daemon.plist");
 const UNIT = join(homedir(), ".config", "systemd", "user", "coflux-daemon.service");
+const DEFAULT_LOCAL_GATEWAY_PORT = 8788; // 与 packages/crates protocol 的 LOCAL_GATEWAY_PORT 保持一致
 
 const die = (m) => { console.error("✗ " + m); process.exit(1); };
 const run = (cmd, args, opts = {}) => spawnSync(cmd, args, { encoding: "utf8", ...opts });
@@ -45,6 +52,59 @@ function readPendingAuth() {
   try { return JSON.parse(fs.readFileSync(PENDING_AUTH, "utf8")); } catch { return null; }
 }
 
+function readConnState() {
+  try { return JSON.parse(fs.readFileSync(CONN_STATE, "utf8")); } catch { return null; }
+}
+
+function readLocalGatewaySummary() {
+  let store;
+  try { store = JSON.parse(fs.readFileSync(LOCAL_GATEWAY_STORE, "utf8")); }
+  catch {
+    return {
+      ok: false,
+      ready: false,
+      // JSON.parse 的错误在部分 Node 版本会带原文片段；store 含私钥，诊断输出绝不能回显。
+      error: fs.existsSync(LOCAL_GATEWAY_STORE) ? "grant store 无法解析" : "grant store 尚未创建",
+    };
+  }
+  if (store?.version !== 1 || !Array.isArray(store.origins) || !Array.isArray(store.grants)) {
+    return { ok: false, ready: false, error: "grant store 结构/版本无效" };
+  }
+  const origins = store.origins.filter((origin) => typeof origin === "string" && origin.length > 0);
+  const grants = store.grants.filter((grant) => grant && typeof grant.origin === "string" && grant.origin.length > 0);
+  const origin = grants.find((grant) => origins.includes(grant.origin))?.origin || origins[0];
+  const ready = grants.length > 0 && !!origin;
+  const summary = ready
+    ? `${grants.length} 个持久 grant / ${origins.length} 个 Origin`
+    : `${grants.length} 个 grant / ${origins.length} 个 Origin（尚无可用浏览器配对）`;
+  return {
+    ok: ready,
+    ready,
+    origin,
+    detail: ready ? summary : undefined,
+    error: ready ? undefined : summary,
+  };
+}
+
+function localGatewayPort() {
+  const raw = process.env.COFLUX_LOCAL_GATEWAY_PORT;
+  if (raw === undefined || raw === "") return { ok: true, port: DEFAULT_LOCAL_GATEWAY_PORT };
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    return { ok: false, error: `COFLUX_LOCAL_GATEWAY_PORT=${raw} 无法定位固定监听端口` };
+  }
+  return { ok: true, port };
+}
+const CONN_STATE_LABEL = { connecting: "连接中", connected: "已连接", reconnecting: "重连中" };
+function formatDuration(ms) {
+  const s = Math.max(0, Math.round(ms / 1000));
+  if (s < 60) return `${s}秒`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}分钟`;
+  const h = Math.floor(m / 60);
+  return `${h}小时${m % 60}分钟`;
+}
+
 // "granted" | "denied" | "unknown" | null（文件不存在——supervisor 还没起过/还没写）
 function readFdaStatus() {
   try { return fs.readFileSync(FDA_STATUS, "utf8").trim(); } catch { return null; }
@@ -74,7 +134,9 @@ async function resolveLatestTag() {
   }
 }
 
-async function ensureBinaries({ version, binDir }) {
+// skipIfPresent：up 的幂等语义——二进制已存在且调用方未显式传 version 时跳过下载，
+// 避免重跑 up 变成隐式升级（用户拍板，见 plan 035 Decisions）。update/--bin-dir/显式 --version 不受影响。
+async function ensureBinaries({ version, binDir, skipIfPresent }) {
   fs.mkdirSync(BIN_DIR, { recursive: true });
   if (binDir) {
     for (const b of ["coflux-supervisor", "coflux-worker"]) {
@@ -86,9 +148,13 @@ async function ensureBinaries({ version, binDir }) {
     console.log(`✓ 用本地二进制（${binDir}）`);
     return;
   }
+  if (skipIfPresent && !version && fs.existsSync(SUP_BIN) && fs.existsSync(WRK_BIN)) {
+    console.log(`✓ 二进制已存在（${BIN_DIR}），跳过下载（用 cofluxd update 升级）`);
+    return;
+  }
   const t = rustTarget();
   let base;
-  if (version === "latest") {
+  if (!version || version === "latest") {
     const tag = await resolveLatestTag();
     if (tag) console.log(`最新版本: ${tag}`);
     base = tag ? `https://github.com/${REPO}/releases/download/${tag}` : `https://github.com/${REPO}/releases/latest/download`;
@@ -102,12 +168,11 @@ async function ensureBinaries({ version, binDir }) {
   }
 }
 
-// 写 settings.json（daemon 直接读；含一次性登记密钥 → 600）。未提供 enrollKey 时保留旧值。
-function applyConfig({ serverUrl, enrollKey, deviceName, shell }) {
+// 写 settings.json（daemon 直接读）。
+function applyConfig({ serverUrl, deviceName, shell }) {
   fs.mkdirSync(HOME, { recursive: true });
   fs.chmodSync(HOME, 0o700);
-  const old = readSettings();
-  const settings = { serverUrl, deviceName, enrollKey: enrollKey || old.enrollKey || "" };
+  const settings = { serverUrl, deviceName };
   if (shell) settings.shell = shell;
   fs.writeFileSync(SETTINGS, JSON.stringify(settings, null, 2) + "\n", { mode: 0o600 });
   return settings;
@@ -169,17 +234,17 @@ function stopService() {
   else if (IS_LINUX) run("systemctl", ["--user", "stop", "coflux-daemon.service"]);
 }
 
-async function applyAndStart({ serverUrl, enrollKey, deviceName, shell, version, binDir, noStart }) {
-  await ensureBinaries({ version, binDir });
-  const settings = applyConfig({ serverUrl, enrollKey, deviceName, shell });
+async function applyAndStart({ serverUrl, deviceName, shell, version, binDir, noStart }) {
+  await ensureBinaries({ version, binDir, skipIfPresent: true });
+  applyConfig({ serverUrl, deviceName, shell });
   // 非默认服务器醒目提示：保存值/--server 仍生效（不强制覆盖），但防止 staging 之类残留值静默错连。
   if (serverUrl !== DEFAULT_SERVER) {
     console.log(`⚠ 使用非默认服务器: ${serverUrl}`);
   }
   installService(!noStart);
   console.log(noStart ? "已安装（未启动）。" : `✓ daemon 已启动 → ${serverUrl}`);
-  if (!noStart && !settings.enrollKey && !fs.existsSync(CRED)) {
-    // 默认流程（零参数 up）：无登记密钥、未登记 → 走浏览器授权，轮询 daemon 落盘的链接/凭证文件。
+  if (!noStart && !fs.existsSync(CRED)) {
+    // 未登记 → 走浏览器授权，轮询 daemon 落盘的链接/凭证文件。
     await waitForAuthorization();
   } else {
     cmdStatus();
@@ -222,47 +287,37 @@ async function cmdUp(v) {
   const s = readSettings();
   await applyAndStart({
     serverUrl: v.server || s.serverUrl || DEFAULT_SERVER,
-    enrollKey: v["enroll-key"],
     deviceName: v.name || s.deviceName || hostname(),
     shell: v.shell || s.shell,
     version: v.version, binDir: v["bin-dir"], noStart: v["no-start"],
   });
 }
 
-async function cmdOnboard(v) {
-  const s = readSettings();
-  // 服务器地址不再交互询问（用户拍板 2026-07-04）：--server > 已保存值 > 默认公共服务；
-  // 优先级与 cmdUp 一致（见 packages/cli/cofluxd.mjs 里 applyAndStart 的非默认提示）。
-  const serverUrl = v.server || s.serverUrl || DEFAULT_SERVER;
-  console.log("\n  欢迎使用 coflux —— 配置这台设备\n  ──────────────────────────────\n");
-  console.log(`  服务器: ${serverUrl}\n`);
-  console.log("  登记方式：留空走浏览器授权（推荐，起服务后打印链接，登录确认即可）；\n  已有登记密钥可直接粘贴。\n");
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    const enrollKey = (v["enroll-key"] ?? (await rl.question("登记密钥（可留空）: "))).trim();
-    const deviceName = (await rl.question(`设备名 [${s.deviceName || hostname()}]: `)).trim() || s.deviceName || hostname();
-    rl.close();
-    console.log("");
-    await applyAndStart({ serverUrl, enrollKey, deviceName, shell: s.shell, version: v.version, binDir: v["bin-dir"], noStart: v["no-start"] });
-  } finally {
-    rl.close();
-  }
-}
-
-function cmdReload() {
-  if (!fs.existsSync(SETTINGS)) die("无 settings.json，先 cofluxd up 或 cofluxd onboard");
-  restartService(); // daemon 重启时重新读 settings.json
-  console.log("✓ 已重启（daemon 重新读取 settings.json）");
-}
-
 function cmdDown() { stopService(); console.log("✓ 已停止"); }
 
+// 只有 supervisor 真正靠这条命令更新——它不自动升级（持 PTY，重启会杀会话，见 plan 017）。
+// worker 运行中会被 server 自动热升级到最新 stable（无需停服）；这里顺带刷新的是 worker 的
+// "内置兜底二进制"（supervisor 冷启动/热升级缓存皆无时的 fallback），日常可不管。
 async function cmdUpdate(v) {
-  if (!fs.existsSync(SETTINGS)) die("尚未安装，先 cofluxd up / onboard");
-  await ensureBinaries({ version: v.version, binDir: v["bin-dir"] });
+  if (!fs.existsSync(SETTINGS)) die("尚未安装，先 cofluxd up");
+  const version = v.version || "latest";
+  await ensureBinaries({ version, binDir: v["bin-dir"] });
   restartService();
-  console.log(`✓ 已更新到 ${v["bin-dir"] ? "本地产物" : v.version} 并重启（supervisor）`);
-  console.log("  注：worker 还可由 server 远程热升级，无需停服。");
+  console.log(`✓ supervisor 已更新到 ${v["bin-dir"] ? "本地产物" : version} 并重启`);
+  console.log("  worker 由 server 自动热升级，通常无需手动更新；此命令只更新 supervisor（及其兜底 worker 二进制）。");
+}
+
+// launchd(macOS) / systemd --user(Linux) 服务活跃态查询，status 与 doctor 共用。
+function serviceRunningInfo() {
+  if (IS_MAC) {
+    const running = run("launchctl", ["list", "com.coflux.daemon"]).status === 0;
+    return { running, active: running ? "运行中" : "未运行" };
+  }
+  if (IS_LINUX) {
+    const active = (run("systemctl", ["--user", "is-active", "coflux-daemon.service"]).stdout || "").trim() || "未运行";
+    return { running: active === "active", active };
+  }
+  return { running: false, active: "未运行" };
 }
 
 function cmdStatus() {
@@ -280,19 +335,21 @@ function cmdStatus() {
   } else {
     console.log("凭证:   未登记");
   }
-  let running = false, active = "未运行";
-  if (IS_MAC) {
-    running = run("launchctl", ["list", "com.coflux.daemon"]).status === 0;
-    active = running ? "运行中" : "未运行";
-  } else if (IS_LINUX) {
-    active = (run("systemctl", ["--user", "is-active", "coflux-daemon.service"]).stdout || "").trim() || "未运行";
-    running = active === "active";
-  }
+  const { running, active } = serviceRunningInfo();
   let pid = "";
   if (running) {
     try { pid = ` (worker pid ${fs.readFileSync(join(HOME, "worker.pid"), "utf8").trim()})`; } catch { /* */ }
   }
   console.log(`服务:   ${active}${pid}`);
+  // conn-state.json 是 worker 生前写的快照：进程不在时是 stale 数据，忽略——不能让"进程活着"
+  // 误当成"在线"，也不能让 stale 文件在进程死后继续显示假的连接态。
+  if (running) {
+    const conn = readConnState();
+    if (conn?.state && CONN_STATE_LABEL[conn.state]) {
+      const dur = Number.isFinite(conn.since) ? formatDuration(Date.now() - conn.since) : null;
+      console.log(`连接:   ${CONN_STATE_LABEL[conn.state]}${dur ? `（已 ${dur}）` : ""}`);
+    }
+  }
   if (IS_MAC) {
     const fda = readFdaStatus();
     const hint = fda === "granted" ? "" : "（`cofluxd fda` 引导授权，避免弹窗卡住 PTY 会话）";
@@ -300,6 +357,235 @@ function cmdStatus() {
   }
 }
 
+/* ------------------------------ doctor：中心 + 本地直连分层自检 ------------------------------ */
+// 中心与 loopback 都只做传输层探测，不解析 coflux 协议消息——CLI 保持零协议。中心 WS
+// 成功升级后立即断开；loopback 只验证已持久 Origin 能拿到 101，不发送 browser 私钥或 grant。
+const DOCTOR_TIMEOUT_MS = 5000;
+
+function parseServerUrl(serverUrl) {
+  const u = new URL(serverUrl);
+  const useTls = u.protocol === "wss:";
+  if (!useTls && u.protocol !== "ws:") throw new Error(`不支持的协议: ${u.protocol}（需 ws:// 或 wss://）`);
+  const port = u.port ? Number(u.port) : (useTls ? 443 : 80);
+  const path = u.pathname || "/";
+  return { host: u.hostname, port, path, useTls };
+}
+
+async function timed(fn) {
+  const t0 = Date.now();
+  try { return { ok: true, ms: Date.now() - t0, ...(await fn()) }; }
+  catch (e) { return { ok: false, ms: Date.now() - t0, error: e?.message || String(e) }; }
+}
+
+function probeDns(host) {
+  return timed(async () => {
+    const addrs = await dns.lookup(host, { all: true });
+    return { detail: addrs.map((a) => a.address).join(", ") };
+  });
+}
+
+function probeTcp(host, port) {
+  return new Promise((resolve) => {
+    const t0 = Date.now();
+    const socket = net.connect({ host, port, timeout: DOCTOR_TIMEOUT_MS });
+    const done = (ok, extra) => { socket.destroy(); resolve({ ok, ms: Date.now() - t0, ...extra }); };
+    socket.once("connect", () => done(true, {}));
+    socket.once("timeout", () => done(false, { error: `连接超时（>${DOCTOR_TIMEOUT_MS}ms）` }));
+    socket.once("error", (e) => done(false, { error: e.message }));
+  });
+}
+
+function probeTls(host, port) {
+  return new Promise((resolve) => {
+    const t0 = Date.now();
+    const socket = tls.connect({ host, port, servername: host, timeout: DOCTOR_TIMEOUT_MS }, () => {
+      const detail = socket.authorized ? socket.getProtocol() : `${socket.getProtocol()}（证书未验证: ${socket.authorizationError}）`;
+      socket.destroy();
+      resolve({ ok: true, ms: Date.now() - t0, detail });
+    });
+    socket.once("timeout", () => { socket.destroy(); resolve({ ok: false, ms: Date.now() - t0, error: `握手超时（>${DOCTOR_TIMEOUT_MS}ms）` }); });
+    socket.once("error", (e) => resolve({ ok: false, ms: Date.now() - t0, error: e.message }));
+  });
+}
+
+// 手写一条最小 HTTP/1.1 Upgrade 请求，只看是否拿到 101——不建立真实 WebSocket 帧连接。
+function probeWsUpgrade({ host, port, path, useTls, origin }) {
+  return new Promise((resolve) => {
+    const t0 = Date.now();
+    const key = crypto.randomBytes(16).toString("base64");
+    const hostHeader = host.includes(":") ? `[${host}]:${port}` : `${host}:${port}`;
+    const originHeader = origin ? `Origin: ${origin}\r\n` : "";
+    const req = `GET ${path} HTTP/1.1\r\nHost: ${hostHeader}\r\n${originHeader}Connection: Upgrade\r\nUpgrade: websocket\r\nSec-WebSocket-Version: 13\r\nSec-WebSocket-Key: ${key}\r\n\r\n`;
+    let settled = false;
+    const finish = (r) => {
+      if (settled) return;
+      settled = true;
+      resolve({ ms: Date.now() - t0, ...r });
+    };
+    const onOpen = (socket) => {
+      let buf = "";
+      const timer = setTimeout(() => { socket.destroy(); finish({ ok: false, error: `升级响应超时（>${DOCTOR_TIMEOUT_MS}ms）` }); }, DOCTOR_TIMEOUT_MS);
+      socket.on("data", (chunk) => {
+        buf += chunk.toString("latin1");
+        if (!buf.includes("\r\n\r\n")) return;
+        clearTimeout(timer);
+        const statusLine = buf.split("\r\n")[0];
+        socket.destroy();
+        const ok = /^HTTP\/1\.\d 101\b/.test(statusLine);
+        finish(ok ? { ok, detail: statusLine } : { ok, error: `未收到 101 切换协议响应: ${statusLine}` });
+      });
+      socket.once("error", (e) => { clearTimeout(timer); finish({ ok: false, error: e.message }); });
+      socket.write(req);
+    };
+    const socket = useTls
+      ? tls.connect({ host, port, servername: host, timeout: DOCTOR_TIMEOUT_MS })
+      : net.connect({ host, port, timeout: DOCTOR_TIMEOUT_MS });
+    socket.once(useTls ? "secureConnect" : "connect", () => onOpen(socket));
+    socket.once("timeout", () => { socket.destroy(); finish({ ok: false, error: `连接超时（>${DOCTOR_TIMEOUT_MS}ms）` }); });
+    socket.once("error", (e) => finish({ ok: false, error: e.message }));
+  });
+}
+
+function printLayer(name, r) {
+  const mark = r.ok ? "✓" : "✗";
+  const msg = r.ok ? (r.detail ? `→ ${r.detail}` : "") : (r.error || "");
+  console.log(`  ${mark} ${name} (${r.ms}ms)${msg ? `  ${msg}` : ""}`);
+}
+
+function printLocalLayer(name, r) {
+  const mark = r.ok ? "✓" : "⚠";
+  const msg = r.ok ? (r.detail ? `→ ${r.detail}` : "") : (r.error || "");
+  const elapsed = Number.isFinite(r.ms) ? ` (${r.ms}ms)` : "";
+  console.log(`  ${mark} ${name}${elapsed}${msg ? `  ${msg}` : ""}`);
+}
+
+// 本地事实汇总：服务进程存活、conn-state.json 连接态、凭证有无、FDA。返回连接态三态：
+// "connected" | "not-connected"（有快照但非 connected，如 connecting/reconnecting）
+// | "unknown"（服务未运行，或无快照——daemon 版本较旧还没写、或刚启动）。
+// 三态区分是因为"无快照"不等于"未连接"：旧版 worker 不写 conn-state.json，把它当"未连接"
+// 会把"连接态未知"误报成"认证/授权层有问题"（2026-07-23 实操验收发现）。
+function printLocalFacts() {
+  console.log("\n  Daemon 状态\n  ───────────");
+  const registered = fs.existsSync(CRED);
+  console.log(`  凭证:   ${registered ? "已登记" : "未登记"}`);
+  const { running, active } = serviceRunningInfo();
+  console.log(`  服务:   ${active}`);
+  let connState = "unknown";
+  if (running) {
+    const conn = readConnState();
+    if (conn?.state && CONN_STATE_LABEL[conn.state]) {
+      console.log(`  中心:   ${CONN_STATE_LABEL[conn.state]}`);
+      connState = conn.state === "connected" ? "connected" : "not-connected";
+    } else {
+      console.log("  中心:   (无连接态快照)");
+    }
+  } else {
+    console.log("  中心:   未探测（服务未运行）");
+  }
+  if (IS_MAC) console.log(`  FDA:    ${fdaLabel(readFdaStatus())}`);
+  console.log("");
+  return { registered, running, connState };
+}
+
+function printConclusion(level, msg) {
+  const mark = level === "ok" ? "✓" : level === "warning" ? "⚠" : "✗";
+  console.log(`  ${mark} ${msg}\n`);
+}
+
+async function probeCenter(target) {
+  const { host, port, useTls } = target;
+  const dnsR = await probeDns(host);
+  printLayer("DNS 解析", dnsR);
+  if (!dnsR.ok) {
+    return { ok: false, reason: "DNS 解析失败——检查网络连接/DNS 配置，或该域名是否可达。" };
+  }
+
+  const tcpR = await probeTcp(host, port);
+  printLayer(`TCP 连接 (${host}:${port})`, tcpR);
+  if (!tcpR.ok) {
+    return { ok: false, reason: "DNS 可解析但 TCP 连不上——防火墙/代理拦截，或目标端口未开放。" };
+  }
+
+  if (useTls) {
+    const tlsR = await probeTls(host, port);
+    printLayer("TLS 握手", tlsR);
+    if (!tlsR.ok) {
+      return { ok: false, reason: "TCP 可连但 TLS 握手失败——可能是企业代理 MITM 证书、系统时间错误，或服务端证书问题。" };
+    }
+  }
+
+  const wsR = await probeWsUpgrade(target);
+  printLayer("WS 升级握手", wsR);
+  if (!wsR.ok) {
+    return { ok: false, reason: "网络层通但 WebSocket 升级被拒——可能是反代/负载均衡未正确转发 Upgrade 头，或路径不对。" };
+  }
+  return { ok: true };
+}
+
+async function probeLocalDirect() {
+  const portResult = localGatewayPort();
+  if (!portResult.ok) {
+    printLocalLayer("Gateway bind", { ok: false, error: portResult.error });
+    printLocalLayer("Loopback WS", { ok: false, error: "固定 gateway 端口未知，无法探测" });
+    const grant = readLocalGatewaySummary();
+    printLocalLayer("本地 grant", grant);
+    return { ready: false };
+  }
+
+  const bind = await probeTcp("127.0.0.1", portResult.port);
+  printLocalLayer(`Gateway bind (127.0.0.1:${portResult.port})`, bind);
+  const grant = readLocalGatewaySummary();
+  printLocalLayer("本地 grant", grant);
+
+  let loopback;
+  if (!bind.ok) {
+    loopback = { ok: false, error: "gateway 未监听，跳过 WS 握手" };
+  } else {
+    loopback = await probeWsUpgrade({
+      host: "127.0.0.1",
+      port: portResult.port,
+      path: "/device",
+      useTls: false,
+      // 没有持久 Origin 时仍发一个合法 Origin；403 能区分“coflux gateway 可达但未配对”。
+      origin: grant.origin || "http://127.0.0.1",
+    });
+  }
+  printLocalLayer("Loopback WS（主机侧）", loopback);
+  return { ready: bind.ok && grant.ready && loopback.ok };
+}
+
+async function cmdDoctor() {
+  const s = readSettings();
+  const serverUrl = s.serverUrl || DEFAULT_SERVER;
+  console.log(`\n  中心网络 —— ${serverUrl}\n  ────────────────────────────`);
+  let center;
+  try {
+    center = await probeCenter(parseServerUrl(serverUrl));
+  } catch (error) {
+    printLayer("server URL", { ok: false, ms: 0, error: `${serverUrl}（${error.message}）` });
+    center = { ok: false, reason: "中心地址配置无效。" };
+  }
+
+  console.log("\n  本地直连\n  ────────");
+  const direct = await probeLocalDirect();
+  const facts = printLocalFacts();
+  const relayReady = center.ok && facts.running && facts.connState === "connected";
+
+  if (direct.ready && relayReady) {
+    printConclusion("ok", "本地直连与中心 relay 均可用。");
+  } else if (!direct.ready && relayReady) {
+    printConclusion("warning", "直连降级：中心 relay 仍可用，daemon 不是离线；检查上面的 gateway/grant/loopback 项。");
+  } else if (direct.ready && !center.ok) {
+    printConclusion("warning", "中心不可达，但本地直连可用；已加载且已配对页面可继续会话，刷新/冷启动不保证。");
+  } else if (direct.ready) {
+    printConclusion("warning", "本地直连可用；中心网络可达，但 daemon→中心连接未确认，relay 状态未知。");
+  } else if (center.ok) {
+    printConclusion("warning", "直连降级；中心网络可达，但 daemon→中心连接未确认。不要据此把 daemon 判为离线，查 `cofluxd logs`。");
+  } else {
+    printConclusion("error", `${center.reason || "中心不可达"} 同时本地直连降级；当前两条路径都未确认可用。`);
+  }
+}
+
 function cmdLogs(v) {
   if (IS_MAC) {
     if (!fs.existsSync(LOG_FILE)) die(`暂无日志 ${LOG_FILE}`);
@@ -341,29 +627,34 @@ function cmdUninstall(v) {
 
 const HELP = `cofluxd —— coflux daemon 管理
 
-  cofluxd                 首次=交互式配置(onboard)，已配置=status
-  cofluxd onboard         交互式配置并启用
-  cofluxd up [flags]      非交互装/起，零参数即可（不带 --enroll-key 时打印浏览器授权链接）
-  cofluxd reload          按 ~/.coflux/settings.json 重载并重启
-  cofluxd update          更新二进制并重启（worker 另可远程热升级）
-  cofluxd status          服务器/登记（含"等待授权"）/服务状态
+  cofluxd                 首次=up（打印浏览器授权链接），已配置=status
+  cofluxd up [flags]      幂等：首次装+起，已装则按当前 settings.json 重装服务并重启
+  cofluxd status          服务器/登记（含"等待授权"）/服务/连接状态
+  cofluxd doctor          中心网络 + gateway bind/grant/loopback + daemon 状态分层自检
+  cofluxd update          更新本地 supervisor 二进制并重启（worker 由 server 自动热升级）
   cofluxd fda             [仅 macOS] 引导授予完全磁盘访问权限（避免 PTY 因 TCC 弹窗卡住）
   cofluxd logs [-f]       看 daemon 日志
   cofluxd down            停止
   cofluxd uninstall [--purge]   卸载（--purge 连二进制/配置/凭证一并删）
 
-up flags: --server <ws://.../daemon>  --enroll-key <KEY>（留空则走浏览器授权）  --name <名>  --shell <路径>
-通用: --version <vX|latest>(默认 latest)  --bin-dir <dir>(用本地 cargo 产物)  --no-start
-配置都在 ~/.coflux/settings.json（serverUrl/enrollKey/deviceName/shell，含密钥故 600），daemon 直接读；改后 cofluxd reload 生效。`;
+up flags: --server <ws://.../daemon>  --name <名>  --shell <路径>
+通用: --version <vX|latest>(不传时 up 沿用已有二进制，update 默认 latest)  --bin-dir <dir>(用本地 cargo 产物)  --no-start
+配置都在 ~/.coflux/settings.json（serverUrl/deviceName/shell），daemon 直接读；改后重跑 cofluxd up 生效。`;
+
+// onboard/reload 已在命令面重梳中移除（用户拍板 2026-07-23，见 plans/035）：onboard 的交互
+// 问答只剩"问设备名"，价值不足以撑一个命令；reload 与幂等化后的 up 语义重复。
+const MIGRATED = {
+  onboard: "onboard 已并入 up，直接运行 `cofluxd up`",
+  reload: "reload 已并入 up（up 现幂等，会按 settings.json 重装服务并重启），直接运行 `cofluxd up`",
+};
 
 const { values, positionals } = parseArgs({
   allowPositionals: true,
   options: {
     server: { type: "string" },
-    "enroll-key": { type: "string" },
     name: { type: "string" },
     shell: { type: "string" },
-    version: { type: "string", default: "latest" },
+    version: { type: "string" },
     "bin-dir": { type: "string" },
     "no-start": { type: "boolean", default: false },
     purge: { type: "boolean", default: false },
@@ -374,9 +665,9 @@ const { values, positionals } = parseArgs({
 
 let cmd = positionals[0];
 if (values.help || cmd === "help") { console.log(HELP); process.exit(0); }
-if (!cmd) cmd = fs.existsSync(SETTINGS) ? "status" : "onboard"; // 首次裸跑 → 引导
+if (!cmd) cmd = fs.existsSync(SETTINGS) ? "status" : "up"; // 首次裸跑 → 引导
 
-const handlers = { up: cmdUp, onboard: cmdOnboard, reload: cmdReload, update: cmdUpdate, down: cmdDown, status: cmdStatus, fda: cmdFda, logs: cmdLogs, uninstall: cmdUninstall };
+const handlers = { up: cmdUp, update: cmdUpdate, down: cmdDown, status: cmdStatus, doctor: cmdDoctor, fda: cmdFda, logs: cmdLogs, uninstall: cmdUninstall };
 const h = handlers[cmd];
-if (!h) die(`未知命令: ${cmd}\n\n${HELP}`);
+if (!h) die(`未知命令: ${cmd}${MIGRATED[cmd] ? `\n${MIGRATED[cmd]}` : ""}\n\n${HELP}`);
 await h(values);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cofluxd",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "coflux daemon 管理 CLI：装/起/停/升级 Rust daemon（supervisor + worker）",
   "type": "module",
   "bin": {