CANBAN

CANBAN // 文档 // 远程主机

远程 Linux 主机、Tailscale 与 SSH

单个 Canban.app 桌面端可以同时连接本机(This Mac)和一台或多台远程 Linux / macOS canband 主机,在 Tailscale 直连或 SSH 隧道下无缝工作。

多主机同时在线与离线容灾

每台主机运行独立的 canband 与本地 herdr-core(hc),各自持有 SQLite WAL 数据库、项目、卡片、工作流引擎、调度器与 Git Worktree:

  • 7×24 小时自主推进:即使你的 MacBook 休眠或断网,远程 canband 仍会继续推进卡片、收集 Agent 报告、执行 FIFO Queue Merge 并轮询关联的 GitHub 仓库。
  • 统一看板与通知聚合:桌面客户端通过 HostRegistry 聚合所有主机的项目与终端,按 host_id 自动路由操作,并在全局 ⌘I 面板统一展示跨主机的 Needs you 与进度更新。
  • 离线快照缓存:每次成功拉取的远程快照都会原子缓存到 <local-home>/cache/hosts/<host_id>.json。断网时仍可在 Offline · Cached 只读模式下浏览远程看板与报告。

部署 Headless Linux canband

在没有桌面环境的 Linux(x86_64 / aarch64)服务器上安装无 GTK4 依赖的独立 canban,并注册 systemd --user 常驻服务:

sh
curl -fsSL https://canban.dev/install.sh | bash -s -- --headless
canban service install --tailscale --port 7680
canban service status

canban service install 会尝试开启 loginctl enable-linger,保证退出 SSH 后后台服务与 herdr-core 会话持续存活。

Tailscale 直连 TCP 与 SSH 配对

Canban 采用 Tailscale 优先的数据面,并结合 SSH 完成一键初始化与兜底转发:

  • Tailscale 直连 TCP(推荐):canban serve --tailscale 自动绑定主机 Tailscale IPv4(100.64.0.0/10,默认端口 7680),配置持久化在 <home>/config/server.json,首次开启时在 <home>/server.token(0600)生成 256 位随机 Bearer Token。未鉴权的 host.probe 仅返回非敏感身份信息(server_id、hostname、platform、version、api_version),其余所有 RPC 与 herdr.connect 终端字节流均需常量时间校验 Token。
  • 配对 URI 与引导:在服务器执行 canban pair [--port 7680] 可生成 canban://<addr>:<port>#<token> 配对链接;或在桌面端 Connect a Machine 向导中直接从 tailscale status --json / ~/.ssh/config 发现主机,自动完成 SSH 远程安装与 Token 配对。
  • SSH 隧道兜底:对于未安装 Tailscale 的纯 SSH 主机,Canban.app 会在本地托管后台 ssh -L Unix Socket 转发。

内置诊断中心与远程守护进程升级

在桌面端 Settings → Diagnostics 中可一键端到端排查本地与远程主机:

  • 传输与延迟:检查 Socket / Tailscale TCP / SSH 隧道状态、RTT(ms)与重连记录。
  • Canban 服务与存储:查看守护进程 PID、平台、DESKTOP_API 匹配度、systemd --user / launchd 状态与 SQLite WAL 体积。
  • Herdr 与执行工具链:检测 hc 路径、Core ID、活跃 PTY 数量以及 git、python3、tailscale 和各 Agent 可执行文件状态。
  • 实时日志与更新:在线查阅 server.log / updater.log,并在检测到 ApiMismatch 时直接触发 update.daemon。