連線層：從 SSH 出發，按弱點往上補

連線層的基準是 SSH——它是遠端登入的通用標準，加密、認證、port forwarding 都靠它，多數情況直接用 SSH 就夠。往上補工具的時機，是 SSH 在特定弱點上讓你難受的時候，而不是「有更潮的工具就換」。SSH 的兩個典型弱點是「網路一換就斷」（筆電休眠、Wi-Fi 換點、行動網路切換）和「連線中斷後要手動重連」，mosh 與 autossh 各補一個。

mosh：換網路不掉線、高延遲下還能打字

mosh（mobile shell）解的是「連線的存活與手感」：它在 SSH 之上用 UDP 維持一個跟客戶端 IP 無關的 session，所以你的筆電從家裡 Wi-Fi 換到行動網路、或休眠喚醒換了 IP，連線不會斷。它還做本地回顯預測，高延遲鏈路上打字不會有一個字一個字等回應的黏滯感。從咖啡廳、通勤、跨國高延遲連遠端時，mosh 的體驗明顯優於裸 SSH。

它的代價是走 UDP，要在遠端開一段 UDP port 範圍（防火牆/雲端 security group 要放行），且不做 SSH 的 port forwarding——需要轉發本地端口時還是得另開一條 SSH。所以 mosh 通常跟多工器搭配用：mosh 保住連線手感、多工器保住 session 內容，兩者互補。

autossh：維持一條會自己重連的隧道

autossh 解的是「隧道的自動存活」：它監控一條 SSH 連線，斷了就自動重建，適合需要長期維持的場景——例如把遠端某個服務 port forward 回本地、或維持一條反向隧道讓 NAT 後的機器可被連入。它本身只負責「重連」這個動作，重連後你原本的工作是否還在，取決於你有沒有用多工器把 session 保住。

判讀：autossh 是「基礎設施型」工具，用在你要一條無人值守、掉了要自己回來的隧道；日常互動式登入用 mosh 的漫遊能力更順。兩者不衝突。

網路層：機器根本連不到時，先解可達性

前面的連線工具都假設「遠端機器的 IP 你連得到」。當遠端機器在 NAT 或防火牆後面、沒有公開 IP 時，連不到是可達性問題，要在網路層解，而不是換 SSH 客戶端。WireGuard 是現代的輕量 VPN 協定，讓兩台機器像在同一個私網裡直接互連；Tailscale 建在 WireGuard 之上，把「交換金鑰、打洞穿透 NAT、管理裝置清單」這些麻煩事自動化，通常裝好登入就能讓你的所有裝置互相 SSH，不必自己配 VPN。

判讀：家裡的機器、公司內網的開發機、雲端私網裡的主機，想從外面連進去又不想開公網 port 暴露 SSH，用 Tailscale（要省事）或自建 WireGuard（要完全自主、不依賴第三方協調伺服器）在網路層打通，之後 SSH/mosh 照常用。這一層跟連線層是疊加關係：先有可達性，上面才談連線手感。（機器連不到的診斷——是網路層、服務層還是機器沒起——見機器連不到或起不來。）

同步層：三種語義，依 workflow 選

檔案同步不是一個問題，是三種不同語義的問題，挑錯工具會很痛。核心差異在「同步是單向還是雙向、是一次性快照還是持續即時、檔案存在本地還是遠端」。rsync、sshfs、mutagen 各自代表一種語義：

rsync：單向增量，部署與拉回成果的正典

rsync 解的是「把一批檔案有效率地從 A 複製到 B」：它只傳有變動的部分（增量），可保留權限與時間戳，是單向的一次性動作——你下指令、它同步一次、結束。它適合明確的「推上去」或「拉回來」：把本地建好的東西部署到遠端、把遠端跑完的產出拉回本地、定期備份。它不做「持續盯著兩邊、誰改了就同步」，所以拿它當即時開發同步用會很累（每次改都要手動跑）。

因為單向且明確，rsync 也是三者裡最可預測、最不會意外覆蓋的——你清楚知道哪邊是來源、哪邊被更新。無人值守的成果回收（遠端跑完長任務、把結果 rsync 回本地）用它最穩。

sshfs：把遠端目錄當本地資料夾掛載

sshfs 解的是「我想用本地的工具存取遠端的檔案、但不想先複製下來」：它透過 SSH 把遠端目錄掛載成本地的一個路徑，你用本地的編輯器、檔案管理員直接開，實際檔案仍只在遠端。適合偶爾存取、檔案不宜落地到本地的場景。

它的代價是脆與慢：每次存取都走網路，延遲高時開大目錄、跑 git status 這種大量小檔操作會很卡；連線一斷，掛載點就進入壞狀態要重掛。所以 sshfs 適合「輕度、偶爾」的遠端存取，不適合當重度開發的主力——重度開發本地要有一份真的檔案，那是 mutagen 的場景。

mutagen：雙向即時，本地編輯遠端執行的開發迴圈

mutagen 解的是現代遠端開發最常見的迴圈：「在本地用順手的編輯器改、在遠端（有算力、有環境、有相依）執行」，它在兩邊各保留一份實體檔案並持續雙向即時同步——你本地存檔，遠端幾乎同時更新；遠端產生的檔案也同步回本地。因為兩邊都是本地檔案，git status、搜尋、建置都快，沒有 sshfs 那種每次存取走網路的黏滯。

它的代價是多一個常駐同步 daemon 與初次設定，且雙向同步要處理衝突（兩邊同時改同一檔）。適合「本地機器弱/環境不對、但要在強遠端上跑」的長期開發關係。如果你的需求只是「偶爾拉個檔」，mutagen 是殺雞用牛刀，rsync 或 sshfs 更省。

IDE remote：把編輯器的執行環境整個搬到遠端

VS Code Remote（SSH/Containers/WSL）與 JetBrains Gateway 是另一條路線：它們不同步檔案，而是把編輯器的後端（語言伺服器、終端機、除錯器）整個跑在遠端，本地只留 UI。你在本地視窗編輯，但索引、建置、執行全發生在遠端那台機器上，檔案也只在遠端。這解掉了同步的衝突問題（沒有兩份檔案要對齊），代價是綁定該編輯器、且需要一條夠穩的連線維持 UI 與後端的通訊。

判讀：如果你本來就用 VS Code / JetBrains，remote 模式通常比自己接 mutagen + SSH 更省事、體驗更整合；如果你用終端機編輯器（Vim/Neovim/Emacs）或要編輯器無關的方案，走 mutagen（雙向同步）或直接在遠端多工器裡編輯（檔案只在遠端、靠多工器保住 session）。

在 Arch 上的安裝與依賴（實測 aarch64）

這些工具多數在官方 repo，但有幾個安裝陷阱與部署前提是實機才看得出來的，選好工具後要一起確認：

• mosh：官方 repo（pacman -S mosh）。同一套件同時含 client（mosh）與 server（mosh-server），所以遠端機器也要裝 mosh——遠端是別人的伺服器時這是前提；另外 UDP 埠範圍（預設 60000–61000）要在防火牆 / security group 放行。
• autossh / rsync / sshfs：都在官方 repo（pacman -S autossh rsync sshfs）。sshfs 會自動拉 fuse3 相依，不用手動裝 FUSE；掛載需要 /dev/fuse 可存取（一般環境已就緒）。
• tailscale：官方 repo（pacman -S tailscale），但裝完 daemon 預設沒起——要 sudo systemctl enable --now tailscaled 之後才能 tailscale up。少了這步，tailscale 指令會因 daemon 未運行而失敗。
• wireguard：裝 wireguard-tools（wg / wg-quick）。核心模組在多數發行版是 loadable module，wg-quick 會在需要時自動 modprobe wireguard，日常不用手動處理。
• mutagen：不在官方 repo，且 pacman -S mutagen 會裝到完全無關的 python-mutagen（音訊 metadata 函式庫）。正確安裝是 AUR 的 mutagen.io-bin（paru -S mutagen.io-bin），提供 mutagen 執行檔，aarch64 有官方 binary。這是「以為一句 pacman 就有、實際會裝錯東西」的典型坑。
• VS Code Remote / JetBrains Gateway：綁各自的 IDE，不透過套件管理器單獨裝，隨 IDE 的 remote 擴充啟用。

依情境選

把上面的工具對回你的實際處境：

• 日常從筆電連遠端、常換網路：mosh（漫遊）+ 多工器（保 session）。
• 要一條長期自動維持的隧道 / 反向連接：autossh + 多工器。
• 遠端機器在 NAT 後、根本連不到：先用 Tailscale 或 WireGuard 在網路層打通，再照常 SSH/mosh。
• 部署上去、或把遠端跑完的成果拉回來：rsync（單向、可預測）。
• 偶爾存取遠端幾個檔、不想複製下來：sshfs（掛載）。
• 本地編輯、遠端執行的長期開發迴圈：mutagen（雙向即時）或你的 IDE 的 remote 模式。
• 無人值守跑長任務、跑完自動回收成果：多工器保住任務 + rsync 拉回產出，見讓機器跑無人值守的長任務。

判準是先分清「你缺的是連線存活、可達性、還是檔案一致」，再在對應那一層挑工具——三層各挑各的，不要拿同步工具去解連線問題。

下一步

• 保住遠端 session 的多工器（tmux / zellij）配置與比較：遠端工具總覽 與 CLI 環境工具 的多工器篇。
• 連不上、終端機噴亂碼、要從 SSH 操控圖形桌面等連線本身的問題：除錯與診斷：遠端連線與終端機問題。
• 機器完全沒回應、域名解析不了、虛擬機起不來：機器連不到或起不來。
• 把遠端機器設成無人值守、離開後自己跑完長任務送回成果：讓機器跑無人值守的長任務。

多台機器共用 dotfile repo 時，需要一套同步策略來處理「改了配置後怎麼讓其他機器也更新」。

Git push/pull（手動）

最基本的做法：改了就 commit + push，另一台機器 pull + 重新 apply。優點是簡單、沒有額外依賴。缺點是容易忘記——在公司機器上改了一個 alias，回家忘記 push，隔天公司又改了一版，兩邊 diverge。

適合只有一兩台機器、改動不頻繁的人。

自動同步

chezmoi 內建 chezmoi update 指令（pull + apply 一步完成），搭配 cron 或 systemd timer 定期執行：

 1# ~/.config/systemd/user/chezmoi-update.timer
 2[Unit]
 3Description=Update dotfiles daily
 4
 5[Timer]
 6OnCalendar=daily
 7Persistent=true
 8
 9[Install]
10WantedBy=timers.target

1# ~/.config/systemd/user/chezmoi-update.service
2[Unit]
3Description=chezmoi update
4
5[Service]
6Type=oneshot
7ExecStart=/usr/bin/chezmoi update --no-tty

自動同步減少手動操作，但要注意衝突處理——如果兩台機器同時改了同一個檔案且都 push，後面那台的自動 pull 會遇到 merge conflict。實務上 dotfile 很少有真正的衝突（兩台機器同時改同一行的機率低），但偶爾發生時需要手動介入。

機器差異的處理

推薦的模式是 main branch 放所有共用配置，機器差異用條件判斷處理。

用 shell 的 OS 判斷：

1# ~/.zshrc
2if [[ "$(uname -s)" == "Darwin" ]]; then
3    export PATH="/opt/homebrew/bin:$PATH"
4    alias ls="ls -G"
5else
6    alias ls="ls --color=auto"
7fi

用 chezmoi template（Go template 語法）：

1# chezmoi 管理的 .zshrc.tmpl
2{{ if eq .chezmoi.os "darwin" -}}
3export PATH="/opt/homebrew/bin:$PATH"
4{{ end -}}
5
6{{ if eq .chezmoi.hostname "work-laptop" -}}
7export HTTP_PROXY="http://proxy.corp:8080"
8{{ end -}}

chezmoi template 的優勢是條件判斷發生在 apply 階段，產出的檔案裡看不到 template 語法，乾淨且不依賴 shell 的 runtime 判斷。

不推薦每台機器一個 branch 的做法。短期可行，長期一定 diverge——main 加了新配置，各 branch 要 rebase 或 merge，忘了就漂移。一份 main + template 條件判斷是長期可維護的結構。

Secret 排除與管理

dotfile repo 通常是 public 或至少多人可見的。以下東西進了 repo 等於把鑰匙掛在門口：

• SSH 私鑰（~/.ssh/id_*、*.pem）
• API token、password、.env 檔案
• GPG 私鑰
• cloud provider 的 credential 檔案（~/.aws/credentials、~/.config/gcloud/application_default_credentials.json）
• browser profile 裡的 cookie / session

.gitignore 是第一道防線

# SSH 私鑰
*.pem
id_*
known_hosts
authorized_keys

# 環境變數
.env
.env.*

# Cloud credentials
credentials
application_default_credentials.json

但 .gitignore 只防「不小心 add」，不防「故意 add -f」。更重要的是建立習慣：repo 裡永遠只放「看到了也沒關係」的東西。

SSH config 的特殊處理

~/.ssh/config（host alias、ProxyJump 設定、port forwarding）本身不含 secret，可以進 repo——它記錄的是「連線要怎麼走」而不是「憑證是什麼」。但同一個 ~/.ssh/ 目錄下的私鑰絕對排除。

stow 管理時的目錄結構範例：

1dotfiles/
2└── ssh/
3    └── .ssh/
4        └── config        # 進 repo
5        # id_rsa 不放這裡
6        # known_hosts 不放這裡

三個層級的 secret 管理

層級一：手動。.gitignore 排除 secret 檔案，在 README 記錄「這些東西需要在新機器手動設定」。最低成本、對只有一兩台機器的人足夠。

層級二：密碼管理器整合。chezmoi 支援從 1Password、Bitwarden、pass（Unix password manager）等拉取 secret：

1# chezmoi template 語法
2{{ (onepasswordRead "op://Personal/SSH Key/private key").value }}

配置檔的 template 裡引用密碼管理器的條目，apply 時自動填入。secret 不在 repo 裡，但 repo 知道去哪拉。

層級三：加密存放。用 age 或 sops 把 secret 加密後直接存在 repo 裡。解密需要對應的 key。chezmoi 原生支援 age 加密：

1# 加密一個檔案
2chezmoi add --encrypt ~/.ssh/id_rsa
3
4# repo 裡看到的是加密後的內容
5cat ~/.local/share/chezmoi/private_dot_ssh/id_rsa.age

加密存放的好處是 secret 跟著 repo 走、不用另外設密碼管理器。風險是加密 key 本身變成唯一的依賴——丟了 key，加密的 secret 就拿不回來。

層級選擇取決於安全需求和便利需求的平衡。多數情況從層級一開始，覺得手動處理太煩再往上升級。

環境重建的實際流程

假設拿到一台全新的 Arch Linux 機器，要從零重建完整的 Hyprland 桌面環境。以下是 end-to-end 的步驟，對應 bootstrap script 的每個階段。

階段一：最小可用環境

1# Arch 安裝完成後，base system 只有 bash 和基本工具
2sudo pacman -S git base-devel

這是 bootstrap script 的唯一外部前提：有 Git 能 clone repo、有 base-devel 能編譯 AUR 套件。其他一切由 script 處理。

階段二：取得 dotfile repo

1git clone https://github.com/you/dotfiles ~/dotfiles
2cd ~/dotfiles

如果 repo 是 private，這一步需要先設定 SSH key 或用 HTTPS + token。這是前面提到的 secret 雞生蛋問題——clone 含有 SSH config 的 repo 本身就需要 SSH key。解法通常是：第一次用 HTTPS clone，deploy 完 SSH config 後把 remote 改成 SSH。

階段三：執行 bootstrap

1./scripts/install.sh

script 依序：安裝套件（Hyprland、waybar、rofi、wezterm、zsh、neovim、stow 等）、用 stow 部署配置到 $HOME、執行初始化（換 shell、安裝 neovim plugin）。

階段四：手動處理

bootstrap 處理不了（或不該處理）的部分：

• SSH 私鑰：從備份或密碼管理器取回，放到 ~/.ssh/，設定正確權限（chmod 600）
• Git 簽署用的 GPG key：如果有用 commit signing
• 密碼管理器登入：如果 secret 管理用了層級二或三

階段五：硬體相關調整

Hyprland 的 monitor 設定（解析度、縮放、排列位置）跟實際接的螢幕有關，這部分配置每台機器都不同：

1# ~/.config/hypr/hyprland.conf 的 monitor 段
2# 這幾行在每台機器上都要調
3monitor=DP-1, 2560x1440@144, 0x0, 1
4monitor=HDMI-A-1, 1920x1080@60, 2560x0, 1

處理方式有兩種：把 monitor 設定拆成獨立的 monitor.conf，主配置用 source 引入，monitor.conf 不進 repo（加進 .gitignore）、每台機器本地維護；或者用 chezmoi template 按 hostname 判斷。

顯卡驅動（Intel/AMD 通常自動、NVIDIA 需要額外安裝 nvidia-dkms 和設定環境變數）也是硬體相關的步驟，可以放在 bootstrap script 的 OS 判斷裡，但通常 Arch 安裝階段就已經處理。

階段六：驗證

1# 登出 TTY，重新用 Hyprland 登入
2# 或者直接在 TTY 執行
3Hyprland

登入後確認：視窗管理器正常運作、keybind 正確、狀態列出現、字型正確渲染、終端機配色正常。如果某個元件沒反應，通常是套件沒裝或配置路徑不對——回去檢查 bootstrap 的套件清單和 stow 的 symlink。

時間預估

整個流程在網路順暢的情況下，大約 30 分鐘到 1 小時，取決於套件數量和下載速度。主要時間花在套件安裝（pacman 下載 + 編譯 AUR 套件）。配置 deploy 本身是秒級操作（stow 只建 symlink）。

對比沒有 dotfile 管理時的重建：邊想邊裝、裝了忘記某個工具的名稱、配置靠記憶手打、兩天後還在調某個快捷鍵為什麼不對。差距在「可預期 vs 碰運氣」。

維護節奏

環境重建能力需要持續維護，不是設定完就一勞永逸。

日常習慣：新裝一個工具時，順手更新套件清單（brew bundle dump 或手動加一行到 packages.txt）。改了一個配置後，commit + push。這個習慣的建立成本低，但需要刻意練幾週才會變成反射動作。

定期檢查：每隔幾個月在 VM 或 container 裡跑一次完整的 bootstrap，驗證 script 還能從零跑通。配置會演進、套件會改名或被取代、script 裡硬寫的路徑可能失效——定期驗證才能確保「這份重建指令真的能重建」，而不是一份過期的紀錄。

章節文章

跨分類引用

• → 模組一：管理工具與目錄結構：stow / chezmoi 選型與跨平台三層模型
• → 模組五：Hyprland 配置：環境重建流程裡 monitor 設定的硬體相關調整
• → 模組九：從個人到團隊：個人 bootstrap 的思想怎麼延伸到團隊 onboarding

本文是 SQLite overview 的 implementation-layer deep article。Overview 已說明 SQLite 適合 local-first / offline-first 場景；本文聚焦 SQLite local store 與 multi-device sync protocol 的責任分界。

SQLite local-first sync boundary 的核心責任是把「本機可用」和「多端一致」分成兩個問題。SQLite 很適合保存 device-local state；但它不提供 identity、transport、conflict resolution、delete propagation、server authority 或 audit trail。當資料要跨裝置、跨使用者或跨服務同步時，SQLite 只是 local replica / working copy。

本文的判讀錨點是：local-first 的產品價值來自離線可用，工程成本來自同步語意。SQLite 解的是 local durability；sync layer 解的是資料合併、順序、權威來源與錯誤修復。

Local state taxonomy

Local-first 設計的第一步是標記本機資料角色。不同資料角色對 sync、backup、conflict 與 delete 的要求不同。

這張表的重點是資料角色先於 sync 工具。若所有資料都只是 cache，SQLite + TTL 足夠；若有 pending mutation 或 multi-device edit，就需要 sync protocol。

Authority boundary

Authority boundary 的核心責任是決定衝突時誰說了算。Local-first app 可以讓 device、server、field-level merge 或 CRDT 成為不同層的 authority；SQLite 本身只保存狀態，不替系統決策。

Authority model 要和 product semantics 對齊。庫存、付款、權限這類資料通常需要 server authority；notes、draft、local settings 可以接受更偏 local 的權威模型。

Sync transport 與 local log

Sync transport 的核心責任是把 SQLite local state 轉成可重送、可去重、可驗證的資料流。最常見做法是本地維護 pending mutation table 或 change log，再由 background sync worker 送到 server。

 1CREATE TABLE pending_mutations (
 2  id TEXT PRIMARY KEY,
 3  entity_type TEXT NOT NULL,
 4  entity_id TEXT NOT NULL,
 5  operation TEXT NOT NULL,
 6  payload TEXT NOT NULL,
 7  created_at TEXT NOT NULL,
 8  retry_count INTEGER NOT NULL DEFAULT 0,
 9  last_error TEXT
10);

這裡和 backend queue 概念相通：pending mutation table 是本機版 durable queue。它需要 idempotency、retry 與 replay 思維，而不只是「存一張表」。

Conflict resolution

Conflict resolution 的核心責任是讓兩個合法 local write 合併成可接受狀態。SQLite 可以保存 local write；sync layer 要決定衝突偵測、呈現與合併。

Conflict policy 要在資料模型設計時決定。等衝突發生後才補策略，通常會導致資料修復、客服流程與 audit evidence 同時缺位。

Delete propagation 與 privacy

Delete propagation 的核心責任是讓 server、device、backup 與 sync queue 對「刪除」有一致語意。Local-first app 常見風險是 server 已刪，但 device local DB、pending queue 或 OS backup 還留著資料。

刪除在同步系統裡是一個跨裝置生命週期。若資料跨裝置同步，delete 需要 tombstone、ack、retry、backup retention 與 evidence；這些責任要接到 Data Protection。

Production 踩雷

Case 1：pending mutation 沒有 idempotency key

Pending mutation 沒有 idempotency key 的核心風險是重送造成重複副作用。網路 timeout 後 worker 重送，server 已經處理第一次請求，第二次又建立一筆資料或扣一次庫存。

修正方向是每個 mutation 生成 stable id，server 以 idempotency key 去重，local SQLite 保存 retry state 與 server ack。

Case 2：LWW 覆蓋使用者資料

Last-write-wins 的核心風險是把衝突靜默變成資料遺失。Preference 類資料可接受；草稿、文件、表單、付款資料通常需要更清楚的 conflict handling。

修正方向是依資料價值分層。低價值設定用 LWW；高價值內容用 field merge、manual conflict 或 operation log。

Case 3：delete 沒傳到離線裝置

Delete propagation 失敗的核心風險是 privacy / compliance 失效。使用者刪除 server 資料後，一台長期離線裝置重新上線又把舊資料同步回來。

修正方向是 tombstone + server authority。Server 要能拒絕過期 mutation，device 要能接收 delete tombstone 並 purge local state。

操作檢查清單

Local-first SQLite 設計要回答：

1. 哪些 table 是 local source of truth，哪些是 server replica。
2. Pending mutation 是否有 idempotency key 與 retry state。
3. Conflict policy 是 LWW、field merge、manual merge 還是 operation log。
4. Delete 是否有 tombstone、ack 與 local purge。
5. Sync worker 是否有 backoff、dead-letter、reconciliation。
6. Device backup 是否會保存已刪資料。
7. Server 是否能拒絕過期 local write。

下一步路由

• 上游：Mobile / Desktop Embedded Store
• Sibling：SQLite to D1 / Turso、D1 / Turso / libSQL Comparison
• 卡片：Idempotency、Eventual Consistency、Stale Read
• 跨模組：Data Protection