Git 與 SSH Key 設定教學：在 VPS 上安全拉程式、部署與接 AI 開發工具

Git 和 SSH Key 看起來像很基礎，但它其實是很多後續流程的地基。你不管是要 git clone、讓 VPS 自己拉程式碼、接 CI/CD，還是讓 Claude Code / Gemini CLI 在 repo 裡正常工作，最後都會碰到這一題。

很多人真正卡住的點不是不知道要輸入 ssh-keygen，而是搞不清楚金鑰該放哪裡、權限怎麼設、為什麼 GitHub 一直拒絕連線、或是同一台機器要怎麼管多組帳號。這篇就是把這些實務問題一起補齊。

先把這三件事釐清

• 先把 Git 與 SSH 打穩，後面才有資格談自動部署、AI agent 協作與多人維護
• 現在新建 SSH Key 比較常用 ed25519
• 做完後一定要實測 ssh -T 或實際 clone，不然很多人其實只完成一半

哪些使用情境最適合先看

• 想在 VPS 上拉 GitHub / GitLab 專案的人
• 想把部署從帳密登入改成比較乾淨、比較安全的 SSH 流程的人
• 想讓 AI CLI 在 repo 裡做事，但先把版本控制與權限邊界整理好的人
• 需要在同一台機器上管理多個 Git 帳號的人

動手設定前先確認

• 先確認你有要連的 GitHub 或 GitLab 帳號
• 決定這台機器是個人開發機、共享伺服器，還是正式部署機，因為 SSH key 管理方式會不太一樣
• 若一台機器要接多個帳號，最好一開始就規劃 ~/.ssh/config

詳細教學與操作步驟

如果你準備在 VPS 上長期維護專案，SSH Key 幾乎是標配。它讓你不用在每次部署時重複輸入帳密，也比較適合放進自動化流程。更重要的是，像 Claude Code 或 Gemini CLI 這類會直接在 repo 內工作的工具，背後也需要一個乾淨可用的 Git 環境。

為什麼這題不能只靠 HTTPS 帳密帶過？

因為 VPS 很少只用一次。當你開始做自動部署、排程更新或讓多個工具一起碰 repo 時，SSH 會比手動輸入帳密穩很多。它也比較容易管理權限、輪替金鑰與做帳號隔離。

GitHub 在 2021 年已經停止支援密碼認證來做 Git 操作，所以 SSH key 或 Personal Access Token 已經是必選項，不是「進階選項」。

步驟一：安裝 Git

在 Ubuntu 或 Debian 系統上，安裝 Git 非常簡單：

sudo apt update
sudo apt install git -y
git --version

安裝後，請設定你的使用者資訊（這會顯示在 commit 紀錄中）：

git config --global user.name "Your Name"
git config --global user.email "your_email@example.com"

如果這台機器是部署機，不一定要填你私人信箱，但至少要有一組清楚可辨識的名稱，避免未來看 commit 紀錄時完全不知道是誰或哪台機器做的。

其他建議一起設定的 Git 選項：

# 預設分支名稱改用 main
git config --global init.defaultBranch main

# 處理跨平台換行問題
git config --global core.autocrlf input

# 更好的 diff 演算法
git config --global diff.algorithm histogram

# 預設的 pull 行為改為 rebase
git config --global pull.rebase true

步驟二：產生 SSH Key

現在比較常見的是用 ed25519：

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

系統會詢問儲存路徑與 passphrase。若你是一人使用的開發機，可以依需求設定 passphrase；若是正式自動化機器，就要評估自動流程能不能承受互動式輸入。完成後，金鑰通常會放在 ~/.ssh/。

為什麼選 ed25519 而不是 RSA？

除非你要連線的是非常老舊的系統，否則 ed25519 是目前的最佳選擇。

步驟三：將公鑰加入 GitHub/GitLab

1. 讀取你的公鑰內容：cat ~/.ssh/id_ed25519.pub
2. 將顯示出的整串字串（以 ssh-ed25519 開頭）複製起來。
3. 登入 GitHub → Settings → SSH and GPG keys → New SSH key。
4. 將內容貼入並儲存。

如果你用的是 GitLab，位置不同但概念完全一樣。記得替每把金鑰取清楚名稱，例如「taipei-vps-prod-01」，不要全部都叫 default。

步驟四：測試連線

最後，測試看看是否能成功連線到 GitHub：

ssh -T git@github.com

如果看到成功認證的提示，代表 SSH 通了。接著建議你真的執行一次 git clone git@github.com:... 或進 repo 跑一次 git fetch，這樣才算完整驗證。

步驟五：SSH Agent — 免重複輸入 passphrase

如果你設了 passphrase（建議在個人開發機上設），每次 git 操作都要輸入會很煩。SSH agent 可以幫你記住 passphrase：

# 啟動 ssh-agent
eval "$(ssh-agent -s)"

# 把金鑰加入 agent
ssh-add ~/.ssh/id_ed25519

如果你希望每次登入自動啟動 agent，可以把以下內容加進 ~/.bashrc 或 ~/.zshrc：

# 自動啟動 ssh-agent
if [ -z "$SSH_AUTH_SOCK" ]; then
  eval "$(ssh-agent -s)" > /dev/null
  ssh-add ~/.ssh/id_ed25519 2> /dev/null
fi

macOS 使用者可以用 Keychain 整合：

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

步驟六：多帳號管理 — 同一台機器接多個 GitHub/GitLab

如果你同時有個人帳號和公司帳號，或需要在同一台機器上操作多個 GitHub 帳號，SSH config 是最乾淨的做法：

# ~/.ssh/config

# 個人帳號
Host github-personal
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_personal

# 公司帳號
Host github-company
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_company

# GitLab
Host gitlab.com
    HostName gitlab.com
    User git
    IdentityFile ~/.ssh/id_ed25519_gitlab

使用時，clone 的 URL 要改用你定義的 Host 名稱：

# 個人帳號
git clone git@github-personal:your-username/repo.git

# 公司帳號
git clone git@github-company:company/repo.git

也可以在 repo 層級覆蓋 Git 設定：

# 在公司專案的 repo 內
cd company-project
git config user.name "Your Company Name"
git config user.email "you@company.com"

步驟七：權限排錯 — SSH 連線被拒怎麼辦

SSH 對權限非常嚴格，以下是最常見的權限問題：

# 檢查並修正權限
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub
chmod 644 ~/.ssh/config       # 如果有 config 檔
chmod 644 ~/.ssh/known_hosts

如果連線還是有問題，可以用 verbose 模式查看詳細資訊：

ssh -vT git@github.com

常見的錯誤和解法：

步驟八：GPG 簽章（選用）— 讓 commit 有驗證標記

如果你想讓你的 commit 在 GitHub 上顯示「Verified」標記，可以設定 GPG 簽章：

# 產生 GPG key
gpg --full-generate-key

# 列出 GPG key
gpg --list-secret-keys --keyid-format=long

# 設定 Git 使用 GPG 簽章
git config --global user.signingkey YOUR_KEY_ID
git config --global commit.gpgsign true

GPG 簽章對開源專案和團隊協作特別有用，可以驗證 commit 確實是你本人做的。

步驟九：讓 AI CLI 工具在 Git 環境中正常工作

如果你打算在同一台機器上使用 Claude Code、Gemini CLI 或 Codex CLI，有幾件事要先確認：

1. Git 設定完整 — AI CLI 工具在 repo 內工作時，會需要 user.name 和 user.email 來建立 commit
2. SSH 連線正常 — AI 工具可能會執行 git fetch、git push 等操作
3. 權限邊界清楚 — 確定 AI 工具可以讀寫哪些 repo，不要讓它碰到不該動的專案

常見問題

Q：權限不足無法 clone？ 先檢查 ~/.ssh 是否為 700，私鑰是否為 600。權限太寬鬆時，SSH 會直接拒絕使用這把 key。

Q：同一台機器要接多個 Git 帳號怎麼辦？ 用 ~/.ssh/config 幫不同 host alias 指到不同私鑰，這會比硬共用一把 key 乾淨很多。詳細做法請看步驟六。

Q：公鑰加了但還是連不上？ 用 ssh -vT git@github.com 查看詳細連線過程，通常可以看到是哪一步卡住。常見原因是 SSH 讀到了錯的 key，或 agent 沒有載入正確的金鑰。

Q：Deploy key 跟個人 SSH key 有什麼不同？ Deploy key 是綁定在單一 repo 上的，適合部署機器人或 CI/CD 服務。個人 SSH key 則可以存取你帳號下所有有權限的 repo。

做完後怎麼確認自己真的設好了

• 跑一次 ssh -T git@github.com 或對應平台的測試連線
• 實際 clone 一個私有 repo，或在既有 repo 裡執行 git fetch
• 檢查 git config --global --list，確認 commit 身分資訊沒有填錯
• 如果有設多帳號，分別測試每個 Host alias 的連線
• 如果有設 SSH agent，重開 shell 後確認 agent 有自動啟動

這一題最常踩的坑

• 有產生 key，但忘了把公鑰貼上 GitHub / GitLab
• .ssh 權限太鬆，SSH 出於安全理由直接不認這把鑰匙
• 多帳號共用同一組設定，最後 clone、push 都連到錯的身分
• 設了 passphrase 卻沒用 SSH agent，每次操作都要重複輸入
• 在公司 VPS 上用個人 SSH key，帳號隔離沒做好
• AI CLI 工具跑 git 操作時失敗，因為 SSH 設定不完整

如果你要往下一步走

把 Git 跟 SSH Key 設好後，下一步通常就是把 Node.js 與 NVM 補好，然後再接著裝 Claude Code、Gemini CLI 或 Codex CLI。因為 AI 開發工具如果沒有乾淨的 Git 工作區，後面 review、commit、部署都會很難順。

如果你要在 VPS 上建立完整的 AI 開發環境，也可以參考 OpenAI API (Python) 開發環境安裝教學 和 Gemini API Node.js 教學。