# 远程 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`。
