連線層：從 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 操控圖形桌面等連線本身的問題：除錯與診斷：遠端連線與終端機問題。
• 機器完全沒回應、域名解析不了、虛擬機起不來：機器連不到或起不來。
• 把遠端機器設成無人值守、離開後自己跑完長任務送回成果：讓機器跑無人值守的長任務。

SSH「連不上」本身（Permission denied、Host key verification failed、Connection refused）的判讀與修復，見 外部連入與無 key 的 bootstrap 路徑 的重連段落。這篇處理的是「連上了、但終端機或 session 的狀態不對」的那些情況。

SSH 斷線後本機終端機噴亂碼、狂跳字元

一個嚇人但無害的情況：SSH 連線被中斷後，你本機的終端機開始瘋狂輸出像 <35;80;24M 這樣的序列，尤其在你移動滑鼠時狂跳。這不是遠端機器在打字，是你本機的終端機被卡在滑鼠回報模式。

判讀關鍵在「什麼時候噴」：如果那串亂碼只在你移動滑鼠時出現、而且形如 數字;數字M，那就是滑鼠座標回報。成因是遠端跑的某個全螢幕程式（TUI、編輯器、終端機多工器）啟動時對終端機開了滑鼠追蹤模式，SSH 被硬斷時它來不及送出「關閉滑鼠模式」的序列就死了，於是你本機終端機還停在回報模式，滑鼠一動就把游標座標當輸入送進來。

修復是重置終端機的模式，跟遠端機器無關：

• 最快：開一個新的終端機分頁 / 視窗。模式是「那個終端機 session」的狀態，新視窗是乾淨的。
• 救現有視窗：先把滑鼠移開別動（洪流會停），盲打 reset 再 Enter，送出終端機重置。
• 若 reset 沒清掉，補送關閉滑鼠回報的序列：printf '\033[?1000l\033[?1002l\033[?1003l\033[?1006l'。

同一類的還有「alternate screen 沒還原」——遠端的全螢幕程式異常結束時，本機終端機可能卡在替代畫面緩衝區，看起來像畫面清空或凍結。reset 同樣能救。歸納起來：SSH 被硬斷後本機終端機行為異常，先懷疑「對端程式來不及還原終端機模式」，用 reset 或開新視窗處理本機終端機狀態，不必急著重連遠端。

遠端打字變亂碼、重複、位置錯亂

連上遠端後，如果互動式輸入變得不對——打一個字出現好幾個、游標位置錯亂、畫面重繪殘影——通常是兩層問題之一，判讀方式是分開排除。

第一層是字元編碼（locale）。從某些本機（例如 macOS）SSH 進 Linux 時，本機會把 LC_CTYPE 之類的變數帶過去；如果遠端沒有對應的 locale、就會退回 POSIX/C locale，讓終端機的行編輯（ZLE、readline）對多位元組字元的寬度判斷出錯，表現為輸入重複或錯位。判斷方式是在遠端 locale 看目前值、locale -a 看有沒有裝對應的 UTF-8 locale。修法是在遠端明確設好 LANG / LC_CTYPE 到一個實際存在的 UTF-8 locale，而不是讓它繼承一個遠端不認得的值。

第二層是終端機能力資料庫（terminfo）。你本機終端機的 TERM 值（例如某些新終端機用 xterm-ghostty 之類的自訂值）如果在遠端沒有對應的 terminfo 條目，遠端程式就不知道怎麼正確地清行、移動游標、重繪，畫面就會亂。判斷方式是在遠端 echo $TERM 看值、infocmp $TERM 看遠端認不認得。修法是把本機的 terminfo 條目送過去讓遠端安裝：infocmp -x $TERM | ssh <遠端> 'tic -x -'。

先分清是 locale 還是 terminfo，兩者症狀相似但修法不同：locale 是編碼寬度、terminfo 是繪製指令。查 locale 跟查 $TERM + infocmp 就能分開。

從 SSH 操控遠端的圖形桌面

想從一條純文字的 SSH 連線去操作遠端的 Wayland 圖形桌面（例如啟動應用、截圖、送 IPC 指令）時，會撞到兩類界線，判斷對是哪一類就知道怎麼繞。

第一類是圖形程式需要知道連到哪個顯示。SSH 進來的 shell 預設沒有圖形環境的環境變數，直接跑圖形程式會找不到 display。要對著遠端那個已經在跑的 Wayland session 操作，得補上它的環境變數：XDG_RUNTIME_DIR（通常 /run/user/<uid>）、WAYLAND_DISPLAY（socket 名，如 wayland-1）、必要時還有該 compositor 的 instance 變數與 DBUS_SESSION_BUS_ADDRESS。這些值怎麼撈：socket 名用 ls /run/user/$(id -u)/wayland-* 看；其餘變數直接從那個圖形 session 既有行程的環境複製最準——cat /proc/<compositor-pid>/environ | tr '\0' '\n' | grep -E 'WAYLAND_DISPLAY|XDG_RUNTIME_DIR|DBUS_SESSION|_INSTANCE_'（<compositor-pid> 用 pgrep -x Hyprland 之類找）。撈到後 export 進當前 SSH shell，這條連線就能對遠端的圖形 session 下指令、grim 截圖。

第二類是有些東西必須從實體圖形終端機（VT，即 Ctrl+Alt+F1~F6 切換的那些文字主控台）啟動，SSH 的 pty 起不來。Wayland 的合成器（compositor，畫桌面、把視窗合成到螢幕、管輸入輸出的核心程式，如 Hyprland）需要一個真正的圖形 VT 上的登入 session，拿到 DRM master（對顯示卡的獨佔繪圖控制權）與 logind seat（一組綁在一起的實體螢幕／鍵鼠裝置）才能啟動；從 SSH 的 pty 起它的預設 backend 會直接失敗（例如報 backend 建立失敗），因為預設 backend 要的 DRM master 與 seat 在 SSH 這條連線上不存在。判讀訊號：合成器一啟動就報 seat / DRM / backend 相關的錯，而你是從 SSH 起的——那就是這個界線。（例外：合成器多半有 headless backend，例如設 WLR_BACKENDS=headless 就不要 DRM master、不需 VT，專給 CI、雲端、自動化測試用；nested（跑在另一個 Wayland session 裡）也不需要。所以精確說是「預設 backend 需要圖形 VT」，不是「合成器一定起不來」。）

繞法是回到那台機器的實體圖形終端機去啟動 compositor，但「回到 VT」這件事也可以從 SSH 遠端做：

• sudo chvt <N> 從 SSH 切換那台機器目前顯示的虛擬終端機到第 N 個，比在虛擬機視窗裡跟宿主的 Ctrl+Alt+Fn 快捷鍵搏鬥穩定。
• 切過去卻是空白、沒有登入提示，通常是那個 VT 上沒有 getty 在跑：sudo systemctl start getty@tty<N>（開機時 enabled 但 inactive 是常見狀態，logind 的 autovt 沒觸發）。
• sudo fgconsole 確認目前是哪個 VT 在前景。

還有一個容易混淆的點：一台虛擬機可能同時有「序列主控台」跟「圖形顯示」兩個獨立輸出。在 guest 內 chvt 只切圖形那側，序列主控台看到的畫面不會變。如果你在虛擬機軟體裡看的是序列主控台，圖形桌面得切到顯示輸出那個 view 才看得到。判讀：切了 VT 但畫面沒反應，先確認你正在看的是哪個輸出。

判讀路由

遠端 / 終端機問題的分流：

• 本機終端機噴亂碼、只在動滑鼠時噴 → 滑鼠回報模式沒關（本機終端機狀態），reset 或開新視窗。
• 遠端打字重複 / 錯位 → 分 locale（查 locale）與 terminfo（查 $TERM + infocmp）。
• 圖形程式在 SSH 下找不到 display → 補 WAYLAND_DISPLAY / XDG_RUNTIME_DIR 等環境變數。
• compositor 從 SSH 起不來、報 seat/DRM 錯 → 它需要實體 VT，用 chvt + getty@tty<N> 回到圖形 VT 啟動。
• SSH 連不上（拒絕 / host key / refused）→ 見 外部連入與無 key 的 bootstrap 路徑。

這幾種分流的共同底線是先讀權威狀態（locale、$TERM、runtime 目錄、loginctl、fgconsole）再下判斷；背後的方法論見 診斷心法。

核心：終端機多工器

遠端工作的地基是終端機多工器（tmux / zellij）——它把你的 session 常駐在遠端，SSH 斷了 session 不受影響，重連 attach 就回到原狀。這也是把長任務交給遠端機器無人值守跑的前提。深入配置與比較見 CLI 環境工具 裡的多工器篇：

• tmux 持久化與基礎——最通用的多工器，session 持久化的核心概念。
• zellij 分頁與 pane——較新、開箱即用、內建佈局的多工器。
• zellij 遠端 web 客戶端——從瀏覽器連遠端 session 的路徑。

連線與同步工具

多工器保住 session 之後，還有兩塊獨立的能力：連線層（怎麼接上遠端、斷了怎麼辦）與同步層（本地與遠端的檔案怎麼一致）。這兩塊各有多個工具、解不同弱點，挑錯會很痛——連線存活、可達性、檔案一致是三層不同的問題。

• 遠端連線與同步工具選型——ssh / mosh（漫遊不斷線）/ autossh（自動重連）、tailscale / wireguard（NAT 後可達性）、rsync / sshfs / mutagen（三種同步語義）、IDE remote 模式的定位與取捨。

低頻寬 / 手機連線下的介面

頻寬低或從手機 / 平板連線時，只傳純文字的 TUI 介面（ASCII / Unicode 製圖，不傳影像）最穩。監控、圖表、檔案瀏覽、資料庫操作都有這類工具，整理在 CLI 環境工具。

遠端連線與 session 的除錯

遠端連線本身出問題時（連不上、終端機噴亂碼、要從 SSH 操控圖形桌面），是診斷問題而非工具選擇問題，見 除錯與診斷：遠端連線與終端機問題 與 機器連不到或起不來。

把機器交給遠端無人值守

設好讓遠端機器在你離開後自己跑完長任務、把成果送回來，見 Linux 安裝與機器初始化：讓機器跑無人值守的長任務。

SSH key 是典型例子：管理工具和 shell 配置的知識在模組一和模組二，但實際操作時 SSH key 比這兩者都早——因為 git clone git@github.com:... 本身就需要 SSH key。如果照模組順序走，到模組二才發現 dotfile repo clone 不下來。

這篇是路線圖，告訴你每一步做什麼、為什麼這個順序、以及去哪個模組看具體操作。

階段一：基礎設施（後續所有步驟的前提）

這些步驟在任何配置之前完成，因為它們是 Git、遠端存取、dotfile clone 的前提。

1. 安裝作業系統 + 建立使用者帳號

macOS：開箱即用。Linux：選發行版（Arch 如果要用 Hyprland）、完成安裝、建立非 root 使用者。安裝程式每個選項該怎麼判讀、裝完最小系統缺哪些必要工具（連 sudo 都可能沒有），見 Linux 安裝選項判讀 與 最小安裝後的工具驗證與補足——這一步是整個系列展開最深、卻最常被一句帶過的地基。

2. 生成 SSH key pair

1ssh-keygen -t ed25519 -C "your-email@example.com"

為什麼這麼早做：

• Git 操作：GitHub / GitLab 的 SSH 認證需要 public key。dotfile repo 通常用 SSH URL（git@github.com:...），clone 前要先把 key 部署到 GitHub。用 HTTPS URL 可以繞過 SSH key，但長期來看 SSH key 是更省事的認證方式。還沒有 key、或想用 HTTPS / PAT 把 dotfile 弄進一台新機器的幾種路徑，見 外部連入、SSH key 與無 key 的 bootstrap 路徑。
• 遠端救援：模組七的場景三（GPU hang）依賴 SSH 作為桌面凍結時的救生通道。key 提前設好，出問題時才有路可走。
• 跨機器操作：筆電連桌機、桌機連 VM、VS Code Remote SSH——都靠這把 key。

3. 部署 public key

把 ~/.ssh/id_ed25519.pub 加到需要的服務：

1# 加到 GitHub
2cat ~/.ssh/id_ed25519.pub
3# 複製輸出，貼到 GitHub → Settings → SSH and GPG keys → New SSH key
4
5# 加到另一台機器（可選，用於跨機器 SSH）
6ssh-copy-id user@target-machine

4. Package manager + Git

macOS：先裝 Homebrew（macOS 的套件管理器，後續安裝 stow、tmux 等工具都靠它），再裝 Git：

1# 安裝 Homebrew
2/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
3
4# 安裝 Git（或用 xcode-select --install，會一併裝 Apple 的 Git）
5brew install git

Arch：pacman 隨 OS 安裝已可用，直接裝 Git：pacman -S git。

5. Clone dotfile repo

1git clone git@github.com:yourname/dotfiles.git ~/dotfiles

如果是第一次建 dotfile repo（還沒有 repo），先建一個空的再開始往裡面加配置。具體做法見模組一：管理工具與目錄結構。

階段二：Shell 與終端機（日常操作的基礎）

Shell 是所有操作的介面，終端機是 shell 的容器。這兩層配置好，後續的安裝、設定、除錯效率會高很多。

6. 安裝管理工具（stow / chezmoi）

把 dotfile repo 裡的配置 symlink 到正確位置。具體選型和操作見模組一。

7. Shell 配置（.zshrc / .bashrc）

模組化拆分、PATH 設定、alias、prompt。做完這一步，終端機操作才順手。見模組二：Shell 配置。

8. 終端機 + 編輯器

Terminal emulator 選型、tmux/zellij、neovim 基礎配置。見模組三：終端機與編輯器。

macOS 用戶到階段二完成後就有一個完整的工作環境。下一步依序讀模組一（管理工具選型）、模組二（shell 配置）、模組三（終端機），然後跳到階段四的 bootstrap script。階段三是 Linux 桌面環境的設定，macOS 用戶跳過。

階段三：桌面環境（Linux 限定）

macOS 用戶到階段二就有一個完整的工作環境了。以下步驟是 Linux 桌面環境的設定，macOS 用戶可以跳到階段四。

9. 視窗管理器

平鋪式 vs 浮動式的選型，Hyprland 安裝和核心配置。見模組四和模組五。

10. 桌面配套工具 + Rice

waybar、wofi、mako、配色系統。見模組六：桌面 Rice 設計。

11. 啟用 SSH server + 預防措施

桌面環境可用之後，設定遠端救援通道和預防性配置：

 1# SSH server（出問題時可以從另一台機器救援）
 2sudo systemctl enable sshd
 3sudo systemctl start sshd
 4
 5# 停用密碼登入（確保 SSH key 已設好）
 6# 編輯 /etc/ssh/sshd_config：PasswordAuthentication no
 7
 8# swap（OOM 緩衝）
 9sudo fallocate -l 4G /swapfile
10sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile
11
12# systemd-oomd
13sudo systemctl enable systemd-oomd

為什麼放在桌面設定之後：SSH server 和 swap 是預防措施，桌面能用了才有東西要保護。但 SSH key pair（階段一步驟 2-3）要提前做——key pair 是認證基礎設施，server 只是把門打開。

詳細的故障場景和預防措施見模組七：桌面環境維護與故障排除。

階段四：同步與可攜性

環境建好之後，確保這份配置能搬到下一台機器。

12. Bootstrap script

把階段一到三的操作自動化成 script，下次換機器跑一次就好。見模組八：同步、Bootstrap 與環境重建。

13. Secret 管理

哪些東西該進 repo、哪些要排除（SSH private key、API token、密碼）。同樣見模組八。

依賴關係速查

 1OS 安裝
 2  └─ SSH key pair ← 後續所有 Git / SSH 操作的前提
 3       └─ Git 安裝
 4            └─ dotfile repo clone
 5                 └─ 管理工具（stow link）
 6                      ├─ Shell 配置
 7                      ├─ 終端機 + 編輯器
 8                      └─ 桌面環境（Linux，macOS 到此為止 → 直接跳階段四）
 9                           └─ SSH server + 預防措施
10                                └─ Bootstrap script 自動化

可以亂序的步驟

依賴圖裡同一層級的步驟可以調換順序。具體來說：

• Shell 配置、終端機配置、編輯器配置三者互不依賴，先做哪個都行
• 視窗管理器和桌面配套工具可以交替設定（先裝 Hyprland 再裝 waybar，或反過來）
• swap 和 SSH server 互不依賴，先做哪個都行

跨層級的依賴必須按順序：SSH key 是 clone repo 的前提，repo 是 stow link 的前提，stow link 是 shell 配置生效的前提。

這篇處理三件事：把 sshd 跑起來並從本機連入、設 SSH key 達到免密碼、以及一個容易被卡住的情境——你還沒有 SSH key 時，怎麼把 dotfile 弄進機器、跑完基礎安裝。

啟用 sshd 並從本機連入

讓機器能被 SSH 連入只需要兩步：裝 SSH 伺服器、啟動它的服務。

1pacman -S openssh             # 剛裝好的系統套件資料庫是新的，-S 不必先 -Sy
2systemctl enable --now sshd   # enable 開機自啟、--now 立刻啟動

指令以 Arch 為例。換發行版時套件管理器不同（Fedora dnf、Debian/Ubuntu apt），服務名也可能不同——Debian 系的 OpenSSH 服務叫 ssh 不是 sshd，那邊要 systemctl enable --now ssh。

從本機連的時候用一般使用者、不要用 root：

1ssh user@<機器 IP>            # IP 來自機器上的 ip -brief a

用一般使用者是因為多數發行版的 sshd 預設擋 root 密碼登入（PermitRootLogin prohibit-password）——root 只能用 key、不能用密碼。這個預設是好的安全姿態，順著它走、用你裝系統時建的一般使用者連即可。連進去之後，後續所有需要長指令、需要貼上的操作都在這個 session 裡做，不再回主控台手打。

這裡啟用 sshd 是為了 bootstrap 期間從本機連入操作，跟 操作順序指引 後段把 sshd 當「桌面就緒後的常駐遠端救援通道」是兩個不同的時間點與目的——同一個 systemctl enable sshd 動作，這裡是為了「現在好操作」，那裡是為了「之後好救援」。

SSH key 免密碼

每次連線都打密碼很快會變成阻力，尤其當你要反覆同步檔案或跑自動化時。SSH key 讓本機免密碼連入，做法是生一把金鑰、把公鑰放進機器、本機用私鑰認證。

生 key 時建議生一把專用的、不要佔用本機的預設金鑰槽，並在 SSH 設定裡給它一個好記的別名：

1ssh-keygen -t ed25519 -f ~/.ssh/vm_arch -N "" -C "vm_arch host->target"
2# 在 ~/.ssh/config 加一段別名：
3#   Host vm
4#       HostName <機器 IP>
5#       User <你的使用者>
6#       IdentityFile ~/.ssh/vm_arch
7#       IdentitiesOnly yes

專用 key 的好處是它的權限範圍清楚——這把只給這台機器用，跟你其他身分的金鑰互不牽連。設好別名後，ssh vm 就免密碼連入，後面的 rsync、scp 也跟著免密碼。

把公鑰放進機器有兩條路。標準工具是 ssh-copy-id，它會在本機跑、要你輸入一次目標機的密碼。另一條省一次切換的路是：當你已經用密碼連進機器、且這個 session 在真終端機裡（貼上可用），直接把公鑰內容貼進機器的 authorized_keys：

1mkdir -p ~/.ssh && chmod 700 ~/.ssh
2echo "ssh-ed25519 AAAA... 你的公鑰內容" >> ~/.ssh/authorized_keys
3chmod 600 ~/.ssh/authorized_keys

兩條路等價，選哪條看你當下在哪——還沒連上就用 ssh-copy-id，已經連上就直接貼，少一次切換。

還沒有 SSH key 時，怎麼把 dotfile 弄進去

設 SSH key 是讓「之後」連線變方便，但 bootstrap 的第一步——把 dotfile repo 弄進機器——並不一定需要 key。常見的卡點是把「clone repo」跟「有 SSH key」綁在一起，但 clone 有不需要 key 的路徑。怎麼把 dotfile 弄進去，取決於這份 dotfile 放在哪。

repo 是公開的（在 GitHub 之類）：用 HTTPS clone，公開 repo 的唯讀 clone 不需要任何認證。

1git clone https://github.com/<帳號>/dotfiles ~/dotfiles
2cd ~/dotfiles && ./scripts/install.sh

這是最直接的路——機器只要能上網就能拉到 dotfile，完全繞過 key 的問題。clone URL 裡的帳號要對；用錯帳號（例如把 email handle 當成 GitHub 帳號）會 clone 失敗或抓到別的 repo，這類筆誤在只看 README 範例時很容易漏掉。SSH key 在這個情境只有「之後要從機器 push 回去」才需要，純粹跑部署用不到。

repo 是私有的、但機器能上網：機器可以直接 clone，用 GitHub Personal Access Token（PAT）走 HTTPS——這是私有 repo 免 SSH key 的標準解。clone 時把 PAT 當密碼填進認證，機器就拉得到，一樣不必在它上面設 SSH key。

repo 還沒推到任何遠端、或機器離線：從本機把檔案傳進去。如果本機到機器的 SSH 已經能用（即使只是密碼登入），用 tar over SSH 一次傳進去（跟 scp -r 等價，差別只在 tar 能一次打包、又好控制要不要帶 .git）：

1tar czf - --exclude '.git' . | ssh user@host 'mkdir -p ~/dotfiles && tar xzf - -C ~/dotfiles'

這條只需要兩邊都有的 ssh 跟 tar，不依賴目標機有 rsync。從 macOS 傳的時候要關掉 AppleDouble 中繼檔，否則會夾帶一堆 ._ 開頭的中繼檔到 Linux 上：在指令前加 COPYFILE_DISABLE=1。完全離線、連 SSH 都還沒通時，最後手段是把 repo 放進 USB、掛載到機器上複製出來。

把 dotfile 弄進去之後，跑它的 install.sh 完成基礎安裝。如果安裝腳本一開始就要用 sudo，記得 sudo 必須在工具驗證階段就備好——它是 最小安裝後的工具驗證與補足 的前置，bootstrap 自身補不了。

換一台新機器（或重裝）時，SSH 為什麼突然連不上

SSH 的別名、金鑰、known_hosts 都是綁在「某一台特定機器」上的，所以當你重裝、或換一台新 VM，先前設好的 ssh <別名> 往往會以看似無關的錯誤失敗——那套設定是為舊機器建的，而重裝後是另一台機器：不同的 IP、不同的 SSH host key、還沒裝 sshd、authorized_keys 也是空的。判讀的起點是把重裝後的機器當成全新的一台，重做第一次連線的設定，而不是沿用舊別名。

失敗會以三種形式出現，各對應不同層、各有各的修法：

Permission denied (publickey) 是認證被拒，代表 sshd 有在跑、連線有到（這是進度），卡在金鑰這關。常見於你用的別名設了 IdentitiesOnly yes 只送某一把 key，而新機器的 authorized_keys 還沒有它。修法是改用帳號加 IP 直連、走密碼，繞過那個鎖死金鑰的別名：ssh user@<新 IP>，密碼是「這次安裝」為該使用者設的（每次重裝各自獨立，不是舊機器那個）。連進去後再把公鑰貼回新機器的 authorized_keys、把別名的 HostName 更新成新 IP，免密碼才會恢復。

Host key verification failed（或 REMOTE HOST IDENTIFICATION HAS CHANGED）發生在新機器剛好拿到跟舊機器一樣的 IP 時：你本機 known_hosts 存的是舊機器的 host key，SSH 偵測到同一個 IP 換了 key、當成可能的中間人攻擊而拒連。修法是刪掉那筆舊紀錄，再重連時接受新 key：

1ssh-keygen -R <IP>       # 刪掉該 IP 的舊 host key
2ssh-keygen -R <別名>     # 有用別名的話一併刪

Connection refused 代表沒有 sshd 在監聽，也就是新機器還沒把 SSH server 起來。修法回到最開始——在新機器的 console 裝 openssh、啟動服務（見本篇開頭「啟用 sshd」），這一步在每台全新機器上都要重做。

三個症狀的共同根因是同一件事：SSH 的便利設定（別名、金鑰、host key 快取）綁的是機器身分、不會跟著「重裝」自動轉移。把它們當成「為某一台機器設好的」，換機器就重做第一次連線，能省下對著看似無關的錯誤瞎猜的時間。

連入後可能遇到的兩個終端機問題

SSH 連線本身通了之後，互動 shell 還可能因為終端機環境不對而出現「打字變亂碼、prompt 重繪錯位」。這類問題在你用現代終端機（如 Ghostty、Kitty）連進一台剛裝好的最小 Linux、又跑了 unicode 較重的 prompt（如 Powerlevel10k）時最容易出現，根源是兩個跟字元處理有關的終端機設定，跟你的 shell 配置無關。

第一個是 locale。macOS 的終端機 SSH 連線時常把 LC_CTYPE=UTF-8 送到遠端，但 UTF-8 不是合法的 Linux locale 名稱，Linux 收到後 fallback 成 POSIX/C locale——於是 shell 的行編輯器把輸入當單位元組處理，配上 unicode 字元的 prompt 就重繪成一個字母重複好幾次的累加亂碼。判讀方式是在遠端跑 locale，看 LANG 是不是空的、LC_CTYPE 是不是 POSIX。修法是在 shell 設定裡強制一個合法的 UTF-8 locale（前提是該 locale 已生成，見 安裝選項判讀 的 locale 段）：

1export LANG=en_US.UTF-8
2export LC_CTYPE=en_US.UTF-8

第二個是 terminfo。現代終端機會把 TERM 設成自己的值（Ghostty 是 xterm-ghostty、Kitty 是 xterm-kitty），而一台剛裝好的 Linux 的 terminfo 資料庫沒有這些條目，shell 的行編輯器做「清行重繪」時找不到對應的控制序列、就把畫面畫壞。判讀方式是在遠端 echo $TERM 看是哪個值、toe | grep <值> 看遠端認不認得。修法有兩條：把你終端機的 terminfo 灌進遠端（保留完整功能），或退而求其次強制一個遠端一定有的 TERM：

1# 把本機終端機的 terminfo 灌進遠端的 ~/.terminfo（推薦）
2infocmp -x "$TERM" | ssh remote 'tic -x -'
3
4# 或：連線時強制遠端一定有的 TERM（功能略降，但保證能用）
5ssh -t remote 'TERM=xterm-256color exec zsh -l'

這兩個問題的共同點是：它們在你裝了 unicode 較重的互動 shell 之後才浮現，而陽春的 shell（ASCII prompt）即使 locale 跟 terminfo 都不對也照樣能用。所以排查時，先確認是不是這層、而不是去懷疑剛裝的 shell 配置壞了。

連入、傳輸、安裝的順序

這三件事有一個固定的先後，順序錯了會在中間卡住。先把 sshd 跑起來、從本機連入，取得一個能貼上、可捲動的 session；再把 dotfile 弄進機器（公開 repo 走 HTTPS clone、私有或本地走傳輸）；最後在機器上跑 install.sh 完成安裝。SSH key 是讓「連入」從每次打密碼變成免密碼的優化，可以在任何時候補，不是這條鏈的必要環節、也不是 bootstrap 的前置。

模組零的操作順序指引 把「生成 SSH key、部署公鑰」列為標準流程的一環，那是預設你會建 key 的主路徑。這篇補的是它沒展開的另一面：當你手上還沒有 key、或這台機器的 dotfile 根本不需要 key 就能取得時，怎麼一樣把 bootstrap 跑完。

下一步

連入、傳輸、安裝都跑通之後，真正的考驗是當 install.sh 中途失敗時——而它遲早會撞到失敗——你能不能快速看出哪裡錯了。這取決於安裝腳本有沒有把可觀測性內建進去，可除錯的 bootstrap 談的就是怎麼內建。

底下用一個具體情境當例子：在一台用完即丟的測試 VM 上，讓 Claude Code 這類 agent 自己跑完一段工作、把成果推回 GitHub 給你早上 review。同一組障礙換成 overnight 編譯或 cron 批次也成立。

障礙一：互動提示擋住自動執行

無人值守的程序沒有人在鍵盤前，所以任何「停下來等你輸入」的提示都會讓它卡死，其中最常見的是 sudo 密碼。一個要裝套件、改系統設定的任務，跑到 sudo 那行就停在密碼提示、永遠等不到輸入，整個任務卡在那裡直到你回來。

解法是讓這台機器的 sudo 免密碼（NOPASSWD），但這是一個明確的安全取捨、不是預設該開的東西。設定方式是給 sudoers 加一條 NOPASSWD 規則：

1echo "$(whoami) ALL=(ALL:ALL) NOPASSWD: ALL" | sudo tee /etc/sudoers.d/20-nopasswd  # $(whoami) 會填入你的登入帳號
2sudo chmod 440 /etc/sudoers.d/20-nopasswd

開了 NOPASSWD，等於放棄「sudo 密碼」這道在你被入侵或程序失控時的最後防線。判讀軸是這台機器的爆炸半徑——它持有哪些憑證、能觸及哪些系統，也就是最壞情況下會波及多大範圍。一台範圍受限、沒有任何真實憑證、出事就重建的測試 VM，放棄這道防線換取自動執行是划算的；一台共享主機、生產伺服器、或裝著真實憑證與資料的機器，不該為了方便開 NOPASSWD。關鍵是「可不可丟」不等於「爆炸半徑小」：一台用完即丟的 VM，一旦塞進能碰到生產系統或你帳號的憑證，爆炸半徑就不小了——看的不是機器本身，是它最壞情況能波及什麼。

障礙二：SSH 斷線就把任務一起殺掉

直接在 SSH session 裡跑的程序，會隨著 SSH 連線中斷而一起死掉——你闔上筆電、網路斷一下、或單純關掉終端機，正在跑的任務就沒了。對一個要跑好幾小時的無人值守任務，這條等於「你不能離開」，跟無人值守的目的矛盾。

把任務搬進終端機多工器（zellij、tmux 這類，配置見 模組三）就解決了。多工器的 session 活在那台機器上、獨立於你的 SSH 連線：你在多工器裡啟動任務、然後 detach（卸離），任務繼續在機器上跑，你這頭關掉 SSH 都不影響；之後再連回來 attach（接回）就能看它跑到哪。典型流程是連入機器、起多工器、在裡面啟動任務、detach、走人：

1ssh user@host
2zellij                       # 起多工器（tmux 同理）
3./run-my-long-task.sh        # 在裡面啟動你的長任務（換成你的實際指令）
4# 然後 detach：zellij 預設 Ctrl+o 再按 d（tmux 是 Ctrl+b 再按 d）
5# 此時關掉 SSH 不影響任務，它在 host 上繼續跑
6
7# 之後連回來看進度：再 ssh 進去，然後
8zellij attach                # tmux 是 tmux attach

判讀訊號是「這個任務跑完前，我會不會斷線」。只要會（過夜、跨小時、不穩的網路），就把它放進多工器；幾秒鐘就結束的指令不需要這層。

障礙三：成果推不出去，等於沒做

無人值守任務的產出留在那台機器上，你看不到——除非它能把結果送出去。最常見的形式是把改動 commit 後 push 回 git 遠端，你在別處 pull 來看。但 push 需要認證，而一台剛連入的機器通常還沒設好推送的憑證，於是任務做完了、commit 也建了，卻卡在 push 那步推不出去，你隔天連回來才發現結果根本沒送出去。

先在這台機器上設好推送認證，這個障礙就消失。用 GitHub CLI 是直接的一條路，它認證後會一併把 git 的 credential helper（git 用來自動帶出認證、不必每次手打的機制）設好，後續 git push 就能用——但 gh auth login 本身是互動式的、要你在場完成一次，屬於離開前的人工前置：

1gh auth login    # 選 HTTPS、完成認證、同意設定 git 認證

判讀軸是「這個任務的價值要怎麼回到你手上」。如果你打算從遠端（GitHub）看結果，那 push 認證就是必要前置——沒設好，整段工作就被困在機器裡。連帶的紀律是讓任務頻繁 commit 當檢查點、做完務必確認 push 成功：對一個你不在場的任務，「沒推出去」跟「沒做」對你是一樣的。機器若沒裝 gh，也可以用 PAT 走 HTTPS，見 外部連入篇 的私有 repo 段。

把 push 憑證設進這台機器，等於提高了它的爆炸半徑——它現在能動你的 repo 了。這會回頭讓障礙一的 NOPASSWD、以及下面 agent 段的權限放行更該謹慎：最壞情況從「弄壞這台機器」升級成「污染你的 repo」，而後者不是重建一台 VM 就能還原的。所以設了 push 憑證之後，要連帶重估前面那些「因為機器可丟所以放心」的取捨。

額外一層：宿主暫停會連帶停掉任務

當這台機器是跑在某個宿主上的虛擬機，還有一個容易忽略的中斷源：宿主睡著，VM 跟著暫停，裡面的無人值守任務也一起停。你以為它整夜在跑，回來發現它從你離開那刻就凍在那裡。判讀方式是想一下「這台機器的存在依賴什麼」——VM 依賴宿主醒著、雲端主機依賴帳單沒欠費。對 VM 的情況，離開前確保宿主不會自動睡眠（macOS 用 caffeinate、Linux 宿主用 systemd-inhibit 或停用 suspend、Windows 調電源設定，或直接關掉節能的自動睡眠）。

如果無人值守的工作者是 AI agent

當你放著跑的是一個 AI agent，除了上面三個障礙，還多一個它自己的互動提示要處理：agent 預設會在每個有風險的動作前停下來問你確認，而無人值守時沒人回答，它就卡住。對應的是 agent 的「跳過確認」模式（如 Claude Code 的權限放行旗標），讓它不停下來問。這跟 NOPASSWD 是同一類取捨、判讀軸也一樣：放給一個無人盯著的 agent 在一台範圍受限、用完即丟的機器上自主動作是可接受的；在一台有真實資料或共享的機器上不該這樣。降低風險的兩個做法是把 agent 的工作範圍用清楚的指引限定（只動哪些目錄、別碰系統其他地方），以及讓它在分支上做、產出交給你 review，而不是直接動到你會依賴的東西。

下一步

把這三到四個障礙解決掉，一台機器就能在你離開後自己跑完工作、把成果送回你手上。這篇是 外部連入（怎麼連進去）的延伸——從「我連進去手動操作」進到「我設好讓它自己跑」。而要讓那個無人值守的任務在失敗時還留得下可診斷的痕跡，回到 可除錯的 bootstrap 的原則：無人盯著的任務尤其需要把可觀測性內建進去，因為你不在場、只能事後從 log 重建發生了什麼。

目前推薦使用 Ed25519 演算法，相比 RSA 更安全、金鑰更短、驗證速度更快：

1ssh-keygen -t ed25519 -C "your_email@example.com"

若需相容較舊的系統（不支援 Ed25519），可退而使用 RSA-4096：

1ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

產生時會提示設定 passphrase（密碼短語），強烈建議設定。即使私鑰外洩，攻擊者仍需要密碼才能使用。

1. 寫入金鑰檔案

macOS / Linux

1cat > ~/.ssh/<key_name> << 'EOF'
2（貼上金鑰內容）
3EOF

'EOF' 加單引號 → 防止 shell 解析內容中的特殊字元（如 $、`）

Windows（PowerShell）

1New-Item -Path "$env:USERPROFILE\.ssh" -ItemType Directory -Force
2Set-Content -Path "$env:USERPROFILE\.ssh\<key_name>" -Value @"
3（貼上金鑰內容）
4"@

Windows 的 SSH 金鑰預設路徑為 C:\Users\<使用者>\.ssh\

2. 設定權限

macOS / Linux

1chmod 600 ~/.ssh/<key_name>

chmod 600 → 僅擁有者可讀寫，SSH 要求私鑰權限不可過於開放，否則會拒絕使用。

Windows（PowerShell，以系統管理員執行）

1icacls "$env:USERPROFILE\.ssh\<key_name>" /inheritance:r /grant:r "$($env:USERNAME):(R)"

Windows 需透過 icacls 移除繼承權限，並限制為只有當前使用者可讀取。 若權限過於開放，OpenSSH 同樣會拒絕載入金鑰。

3. 加入 SSH Agent

macOS

1# 啟動 agent（通常 macOS 已自動啟動）
2eval "$(ssh-agent -s)"
3
4# 加入金鑰，並存入 Keychain 避免重開機後失效
5ssh-add --apple-use-keychain ~/.ssh/<key_name>

若要讓金鑰在每次登入時自動載入，可在 ~/.ssh/config 中加入：

1Host *
2  AddKeysToAgent yes
3  UseKeychain yes
4  IdentityFile ~/.ssh/<key_name>

Linux

1# 啟動 agent
2eval "$(ssh-agent -s)"
3
4# 加入金鑰
5ssh-add ~/.ssh/<key_name>

Linux 重開機後 agent 會重置。可將 eval "$(ssh-agent -s)" 加入 ~/.bashrc 或 ~/.zshrc 讓它自動啟動。

Windows（PowerShell，以系統管理員執行）

1# 啟用 ssh-agent 服務（預設為停用）
2Get-Service ssh-agent | Set-Service -StartupType Automatic -PassThru | Start-Service
3
4# 加入金鑰
5ssh-add "$env:USERPROFILE\.ssh\<key_name>"

Windows 的 ssh-agent 是系統服務，啟用後重開機也會自動執行，不需額外設定。

4. 測試連線

三個平台指令相同：

1ssh -i ~/.ssh/<key_name> -T git@<host>

Windows 請在 PowerShell 或 Git Bash 中執行，路徑會自動對應到 $env:USERPROFILE\.ssh\。

備註

安全性建議

優先使用 Ed25519

為私鑰設定 Passphrase

1# 為已存在的金鑰補設或更換 passphrase
2ssh-keygen -p -f ~/.ssh/<key_name>

即使私鑰檔案被他人取得，沒有 passphrase 就無法使用。搭配 SSH Agent 後只需輸入一次，不影響日常使用體驗。

定期輪換金鑰

建議每 1-2 年輪換一次 SSH 金鑰。可在金鑰名稱中加入年份作為提醒，例如 id_ed25519_2026。

其他注意事項

• 不要將私鑰上傳到雲端同步服務（如 iCloud、Google Drive、OneDrive），除非經過加密
• 不要在多台機器之間複製同一把私鑰，應為每台機器各自產生獨立金鑰
• 避免使用已棄用的 DSA 金鑰，部分新版 OpenSSH 已預設拒絕 DSA
• ~/.ssh/ 目錄本身權限應為 700，authorized_keys 應為 600

常見問題排查

Permission denied (publickey)

1. 確認私鑰權限：chmod 600 ~/.ssh/<key_name>
2. 確認 ~/.ssh/ 目錄權限：chmod 700 ~/.ssh
3. 確認上傳的是 公鑰（.pub）而非私鑰
4. 使用 verbose 模式查看詳細錯誤：ssh -vvv user@host

Agent 中沒有金鑰

1# 確認 agent 是否正在運行
2ssh-add -l
3
4# 如果顯示 "Could not open a connection to your authentication agent"
5eval "$(ssh-agent -s)"
6ssh-add ~/.ssh/<key_name>

金鑰類型被伺服器拒絕

部分較新的伺服器已停用 DSA 和較短的 RSA 金鑰。檢查方式：

1ssh -vvv user@host 2>&1 | grep "Offering"

如果你的金鑰類型不在伺服器接受的清單中，需要重新產生 Ed25519 金鑰。