GitLab and SSH keys · Gitlab 中文文檔

# GitLab and SSH keys > 原文：[https://docs.gitlab.com/ee/ssh/README.html](https://docs.gitlab.com/ee/ssh/README.html) * [Requirements](#requirements) * [Options for SSH keys](#options-for-ssh-keys) * [Review existing SSH keys](#review-existing-ssh-keys) * [Generating a new SSH key pair](#generating-a-new-ssh-key-pair) * [ED25519 SSH keys](#ed25519-ssh-keys) * [RSA SSH keys](#rsa-ssh-keys) * [Common steps for generating an SSH key pair](#common-steps-for-generating-an-ssh-key-pair) * [RSA keys and OpenSSH from versions 6.5 to 7.8](#rsa-keys-and-openssh-from-versions-65-to-78) * [Adding an SSH key to your GitLab account](#adding-an-ssh-key-to-your-gitlab-account) * [Testing that everything is set up correctly](#testing-that-everything-is-set-up-correctly) * [Working with non-default SSH key pair paths](#working-with-non-default-ssh-key-pair-paths) * [Per-repository SSH keys](#per-repository-ssh-keys) * [Multiple accounts on a single GitLab instance](#multiple-accounts-on-a-single-gitlab-instance) * [Deploy keys](#deploy-keys) * [Applications](#applications) * [Eclipse](#eclipse) * [SSH on the GitLab server](#ssh-on-the-gitlab-server) * [Options for Microsoft Windows](#options-for-microsoft-windows) * [Troubleshooting](#troubleshooting) # GitLab and SSH keys[](#gitlab-and-ssh-keys "Permalink") Git 是一個分布式版本控制系統，這意味著您可以在本地工作. 此外，您還可以將更改共享或"推送"到其他服務器. GitLab 支持使用 SSH 密鑰在 Git 及其服務器之間進行安全通信. SSH 協議提供了這種安全性，并允許您向 GitLab 遠程服務器進行身份驗證，而無需每次都提供用戶名或密碼. 該頁面可以幫助您配置安全的 SSH 密鑰，這些密鑰可用于幫助保護與 GitLab 存儲庫的連接. * 如果您需要有關創建 SSH 密鑰的信息，請從我們[的 SSH 密鑰選項](#options-for-ssh-keys)開始. * 如果您有專用于 GitLab 帳戶的 SSH 密鑰，則可能對[使用非默認 SSH 密鑰對路徑](#working-with-non-default-ssh-key-pair-paths)感興趣. * 如果您已經有了 SSH 密鑰對，則可以轉到[將 SSH 密鑰添加到 GitLab 帳戶的方法](#adding-an-ssh-key-to-your-gitlab-account) . ## Requirements[](#requirements "Permalink") 為了支持 SSH，GitLab 需要安裝 OpenSSH 客戶端，該客戶端已預安裝在 GNU / Linux 和 macOS 上，但未預先安裝在 Windows 上. 確保您的系統包括 SSH 6.5 或更高版本，因為它不包括現在不安全的 MD5 簽名方案. 以下命令返回系統上安裝的 SSH 版本： ``` ssh -V ``` 盡管 GitLab 不[支持在 Microsoft Windows 上進行安裝](../install/requirements.html#microsoft-windows) ，但是您可以設置 SSH 密鑰以將 Windows 設置[為客戶端](#options-for-microsoft-windows) . ## Options for SSH keys[](#options-for-ssh-keys "Permalink") GitLab 支持使用 RSA，DSA，ECDSA 和 ED25519 密鑰. * GitLab 在 GitLab 11.0 中已[棄用](https://about.gitlab.com/releases/2018/06/22/gitlab-11-0-released/#support-for-dsa-ssh-keys) DSA 密鑰. * 如[Go 實用密碼術中](https://leanpub.com/gocrypto/read#leanpub-auto-ecdsa)所述，與 DSA 相關的安全性問題也適用于 ECDSA. **提示：**現有文檔表明 ED25519 更安全. 如果使用 RSA 密鑰，則美國國家科學技術研究院[出版物 800-57 第 3 部分（PDF）](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-57Pt3r1.pdf)建議密鑰大小至少為 2048 位. 因此，我們的文檔集中在 ED25519 和 RSA 密鑰的使用上. 管理員可以[限制應允許的密鑰及其最小長度](../security/ssh_keys_restrictions.html) . ## Review existing SSH keys[](#review-existing-ssh-keys "Permalink") 如果您已有 SSH 密鑰，則可以使用它們來幫助保護與 GitLab 存儲庫的連接. 默認情況下，Linux 和 macOS 系統上的 SSH 密鑰存儲在用戶的主目錄中的`.ssh/`子目錄中. 下表包括每種 SSH 密鑰算法的默認文件名： | Algorithm | 公鑰 | 私鑰 | | --- | --- | --- | | ED25519（首選） | `id_ed25519.pub` | `id_ed25519` | | RSA（至少 2048 位密鑰大小） | `id_rsa.pub` | `id_rsa` | | DSA（已棄用） | `id_dsa.pub` | `id_dsa` | | ECDSA | `id_ecdsa.pub` | `id_ecdsa` | 有關建議，請參閱[SSH 密鑰的選項](#options-for-ssh-keys) . ## Generating a new SSH key pair[](#generating-a-new-ssh-key-pair "Permalink") 如果要創建： * ED25519 密鑰，請閱讀[ED25519 SSH 密鑰](#ed25519-ssh-keys) . * RSA 密鑰，請閱讀[RSA SSH 密鑰](#rsa-ssh-keys) . ### ED25519 SSH keys[](#ed25519-ssh-keys "Permalink") The book [Practical Cryptography With Go](https://leanpub.com/gocrypto/read#leanpub-auto-chapter-5-digital-signatures) suggests that [ED25519](https://ed25519.cr.yp.to/) keys are more secure and performant than RSA keys. 隨著 OpenSSH 6.5 在 2014 年引入 ED25519 SSH 密鑰，它們應該在任何當前操作系統上都可用. 您可以使用以下命令創建和配置 ED25519 密鑰： ``` ssh-keygen -t ed25519 -C "<comment>" ``` `-C`標志（帶引號的注釋，例如電子郵件地址）是標記 SSH 密鑰的可選方法. 您將看到類似于以下內容的響應： ``` Generating public/private ed25519 key pair. Enter file in which to save the key (/home/user/.ssh/id_ed25519): ``` 要獲得指導，請繼續執行[常見步驟](#common-steps-for-generating-an-ssh-key-pair) . ### RSA SSH keys[](#rsa-ssh-keys "Permalink") 如果您將 RSA 密鑰用于 SSH，則美國國家標準技術研究院建議您使用[至少 2048 位](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-57Pt3r1.pdf)的密鑰大小. 缺省情況下， `ssh-keygen`命令創建一個 1024 位 RSA 密鑰. 您可以使用以下命令創建和配置 RSA 密鑰，如果需要，可以使用建議的最小密鑰大小`2048`代替： ``` ssh-keygen -t rsa -b 2048 -C "email@example.com" ``` `-C`標志（帶引號的注釋，例如電子郵件地址）是標記 SSH 密鑰的可選方法. 您將看到類似于以下內容的響應： ``` Generating public/private rsa key pair. Enter file in which to save the key (/home/user/.ssh/id_rsa): ``` 要獲得指導，請繼續執行[常見步驟](#common-steps-for-generating-an-ssh-key-pair) . **注意：**如果您具有 7.8 或更低版本的 OpenSSH，請考慮與[編碼](#rsa-keys-and-openssh-from-versions-65-to-78)相關的問題. ### Common steps for generating an SSH key pair[](#common-steps-for-generating-an-ssh-key-pair "Permalink") 無論是創建[ED25519](#ed25519-ssh-keys)還是創建[RSA](#rsa-ssh-keys)密鑰，您都從`ssh-keygen`命令開始. 此時，您將在命令行中看到以下消息（用于 ED25519 鍵）： ``` Generating public/private ed25519 key pair. Enter file in which to save the key (/home/user/.ssh/id_rsa): ``` 如果您還沒有 SSH 密鑰對并且沒有生成[部署密鑰](#deploy-keys) ，請接受建議的文件和目錄. 您的 SSH 客戶端將使用生成的 SSH 密鑰對，而無需其他配置. 或者，您可以將新的 SSH 密鑰對保存在其他位置. 您可以分配您選擇的目錄和文件名. 您還可以將 SSH 密鑰對專用于[特定主機](#working-with-non-default-ssh-key-pair-paths) . 分配文件以保存 SSH 密鑰后，您將有機會為 SSH 密鑰設置[密碼](https://www.ssh.com/ssh/passphrase/) ： ``` Enter passphrase (empty for no passphrase): Enter same passphrase again: ``` 如果成功，您將看到有關`ssh-keygen`命令將標識和私鑰保存在何處的確認. 需要時，可以使用以下命令更新密碼： ``` ssh-keygen -p -f /path/to/ssh_key ``` ### RSA keys and OpenSSH from versions 6.5 to 7.8[](#rsa-keys-and-openssh-from-versions-65-to-78 "Permalink") 在 OpenSSH 7.8 之前，RSA 密鑰的默認公共密鑰指紋基于 MD5，因此不安全. 如果您的 OpenSSH 版本介于 6.5 至 7.8（含）之間，請使用`-o`選項運行`ssh-keygen` ，以更安全的 OpenSSH 格式保存您的私人 SSH 密鑰. 如果您已經具有可用于 GitLab 的 RSA SSH 密鑰對，請考慮對其進行升級以使用更安全的密碼加密格式. 您可以使用以下命令進行操作： ``` ssh-keygen -o -f ~/.ssh/id_rsa ``` 或者，您可以使用以下命令以更安全的加密格式生成新的 RSA 密鑰： ``` ssh-keygen -o -t rsa -b 4096 -C "email@example.com" ``` **注意：**如`ssh-keygen`手冊頁所述，ED25519 已將密鑰加密為更安全的 OpenSSH 格式. ## Adding an SSH key to your GitLab account[](#adding-an-ssh-key-to-your-gitlab-account "Permalink") 現在，您可以將創建的 SSH 密鑰復制到您的 GitLab 帳戶. 這樣做，請按照下列步驟操作： 1. 將您的**公共** SSH 密鑰復制到以文本格式保存信息的位置. 以下選項將 ED25519 鍵的信息保存到指定操作系統的剪貼板中： **macOS:** ``` pbcopy < ~/.ssh/id_ed25519.pub ``` **Linux（需要 xclip 軟件包）：** ``` xclip -sel clip < ~/.ssh/id_ed25519.pub ``` **Windows 上的 Git Bash：** ``` cat ~/.ssh/id_ed25519.pub | clip ``` 如果您使用的是 RSA 密鑰，請相應地進行替換. 2. 導航到`http://gitlab.com`并登錄. 3. 選擇右上角的頭像，然后單擊**設置** 4. Click **SSH 密鑰**. 5. 將復制的公共密鑰粘貼到" **密鑰"**文本框中. 6. 確保您的密鑰在" **標題"**文本框中包含描述性名稱，例如" *工作筆記本電腦"*或" *家用工作站"* . 7. 在"過期時間"部分下包含密鑰的（可選）過期日期. （在[GitLab 12.9 中](https://gitlab.com/gitlab-org/gitlab/-/issues/36243)引入.） 8. 單擊**添加鍵**按鈕. 使用此過程"過期"的 SSH 密鑰在 GitLab 工作流程中仍然有效. 由于 GitLab 配置的到期日期不包含在 SSH 密鑰本身中，因此您仍然可以根據需要導出公共 SSH 密鑰. **注意：**如果您手動復制了公共 SSH 密鑰，請確保復制了整個密鑰，以`ssh-ed25519` （或`ssh-rsa` ）開頭，并以您的電子郵件地址結尾. ## Testing that everything is set up correctly[](#testing-that-everything-is-set-up-correctly "Permalink") 要測試是否正確添加了 SSH 密鑰，請在終端中運行以下命令（將`gitlab.com`替換為 GitLab 的實例域）： ``` ssh -T git@gitlab.com ``` The first time you connect to GitLab via SSH, you will be asked to verify the authenticity of the GitLab host that you’re connecting to. For example, when connecting to GitLab.com, answer `yes` to add GitLab.com to the list of trusted hosts: ``` The authenticity of host 'gitlab.com (35.231.145.151)' can't be established. ECDSA key fingerprint is SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw. Are you sure you want to continue connecting (yes/no)? yes Warning: Permanently added 'gitlab.com' (ECDSA) to the list of known hosts. ``` **注意：**對于 GitLab.com，請查閱[SSH 主機密鑰指紋](../user/gitlab_com/index.html#ssh-host-keys-fingerprints)一節，以確保您連接到正確的服務器. 例如，您會在鏈接的部分中看到上面顯示的 ECDSA 密鑰指紋. 一旦添加到已知主機列表中，將不再要求您再次驗證 GitLab 主機的真實性. 再次運行以上命令，您將只收到*歡迎使用 GitLab 的`@username` ！* 信息. 如果未出現歡迎消息，則可以通過使用以下命令在詳細模式下運行`ssh`來解決問題： ``` ssh -Tvvv git@gitlab.com ``` ## Working with non-default SSH key pair paths[](#working-with-non-default-ssh-key-pair-paths "Permalink") 如果您為 GitLab SSH 密鑰對使用了非默認文件路徑，請配置 SSH 客戶端以指向 GitLab 私有 SSH 密鑰. 要進行這些更改，請運行以下命令： ``` eval $(ssh-agent -s) ssh-add <path to private SSH key> ``` 現在將這些設置保存到`~/.ssh/config`文件中. 這里顯示了兩個專用于 GitLab 的 SSH 密鑰示例： ``` # GitLab.com Host gitlab.com Preferredauthentications publickey IdentityFile ~/.ssh/gitlab_com_rsa # Private GitLab instance Host gitlab.company.com Preferredauthentications publickey IdentityFile ~/.ssh/example_com_rsa ``` 公用 SSH 密鑰對于 GitLab 必須是唯一的，因為它們將綁定到您的帳戶. SSH 密鑰是通過 SSH 推送代碼時唯一的標識符，這就是為什么它需要唯一地映射到單個用戶的原因. ## Per-repository SSH keys[](#per-repository-ssh-keys "Permalink") 如果要根據正在使用的存儲庫使用不同的密鑰，則可以在存儲庫中發出以下命令： ``` git config core.sshCommand "ssh -o IdentitiesOnly=yes -i ~/.ssh/private-key-filename-for-this-repository -F /dev/null" ``` 這將不使用 SSH 代理，并且至少需要 Git 2.10. ## Multiple accounts on a single GitLab instance[](#multiple-accounts-on-a-single-gitlab-instance "Permalink") [每個存儲庫](#per-repository-ssh-keys)方法還適用于在單個 GitLab 實例中使用多個帳戶. 或者，可以直接在`~.ssh/config`為主機分配別名. 如果在`.ssh/config`中的`Host`塊之外設置了`IdentityFile` ，則 SSH 和作為擴展的 Git 將無法登錄. 這是由于 SSH 組裝`IdentityFile`條目的方式，因此不能通過將`IdentitiesOnly`設置為`yes`來更改. `IdentityFile`條目應指向 SSH 密鑰對的私鑰. **注意：**私鑰和公用密鑰應僅由用戶讀取. 通過運行以下`chmod 0400 ~/.ssh/<example_ssh_key>`在 Linux 和 macOS 上完成此操作： `chmod 0400 ~/.ssh/<example_ssh_key>`和`chmod 0400 ~/.ssh/<example_sh_key.pub>` . ``` # User1 Account Identity Host <user_1.gitlab.com> Hostname gitlab.com PreferredAuthentications publickey IdentityFile ~/.ssh/<example_ssh_key1> # User2 Account Identity Host <user_2.gitlab.com> Hostname gitlab.com PreferredAuthentications publickey IdentityFile ~/.ssh/<example_ssh_key2> ``` **注意：**為提高效率和透明度，示例`Host`別名定義為`user_1.gitlab.com`和`user_2.gitlab.com` . 高級配置更難以維護. 使用這種別名使使用其他工具（如`git remote`子命令）時更容易理解. SSH 可以將任何字符串理解為`Host`別名，因此`Tanuki1`和`Tanuki2`盡管提供了很少的上下文指向它們，也可以使用. 克隆`gitlab`存儲庫通常如下所示： ``` git clone git@gitlab.com:gitlab-org/gitlab.git ``` 要為`user_1`克隆它，請將`gitlab.com`替換為 SSH 別名`user_1.gitlab.com` ： ``` git clone git@<user_1.gitlab.com>:gitlab-org/gitlab.git ``` 使用`git remote`命令修復以前克隆的存儲庫. 下面的示例假定遠程存儲庫被別名為`origin` . ``` git remote set-url origin git@<user_1.gitlab.com>:gitlab-org/gitlab.git ``` ## Deploy keys[](#deploy-keys "Permalink") 閱讀[有關部署密鑰](../user/project/deploy_keys/index.html)的[文檔](../user/project/deploy_keys/index.html) . ## Applications[](#applications "Permalink") ### Eclipse[](#eclipse "Permalink") 如果使用的是[EGit](https://www.eclipse.org/egit/) ，則可以[將 SSH 密鑰添加到 Eclipse](https://wiki.eclipse.org/EGit/User_Guide#Eclipse_SSH_Configuration) . ## SSH on the GitLab server[](#ssh-on-the-gitlab-server "Permalink") GitLab 與系統安裝的 SSH 守護程序集成，指定一個用戶（通常名為`git` ）來處理所有訪問請求. 通過 SSH 連接到 GitLab 服務器的用戶由其 SSH 密鑰而不是其用戶名標識. 在 GitLab 服務器上執行的 SSH *客戶端*操作將以該用戶身份執行. 盡管可以修改此用戶的 SSH 配置，例如提供專用 SSH 密鑰來驗證這些請求，但是這種做法**不受支持** ，并且強烈建議這樣做，因為這樣做會帶來重大的安全風險. GitLab 檢查過程包括對這種情況的檢查，如果您的服務器配置如下，它將引導您進入本節，例如： ``` $ gitlab-rake gitlab:check Git user has default SSH configuration? ... no Try fixing it: mkdir ~/gitlab-check-backup-1504540051 sudo mv /var/lib/git/.ssh/id_rsa ~/gitlab-check-backup-1504540051 sudo mv /var/lib/git/.ssh/id_rsa.pub ~/gitlab-check-backup-1504540051 For more information see: doc/ssh/README.md in section "SSH on the GitLab server" Please fix the error above and rerun the checks. ``` 盡快刪除自定義配置. 這些自定義項*明確不受支持，*并且可能隨時停止工作. ### Options for Microsoft Windows[](#options-for-microsoft-windows "Permalink") 如果您運行的是 Windows 10， [適用于 Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10)的[Windows 子系統（WSL）](https://docs.microsoft.com/en-us/windows/wsl/install-win10)及其最新的[WSL 2](https://docs.microsoft.com/en-us/windows/wsl/install-win10#update-to-wsl-2)版本，則支持安裝不同的 Linux 發行版，其中包括 Git 和 SSH 客戶端. 對于當前版本的 Windows，您還可以通過[Git for Windows](https://gitforwindows.org)安裝 Git 和 SSH 客戶端. 替代工具包括： * [Cygwin](https://www.cygwin.com) * [PuttyGen](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html) ## Troubleshooting[](#troubleshooting "Permalink") 如果在 Git 克隆上，系統會提示您輸入密碼，例如`git@gitlab.com's password:` SSH 設置有問題. * 確保您正確生成了 SSH 密鑰對，并將公共 SSH 密鑰添加到了 GitLab 配置文件 * 嘗試使用`ssh-agent`手動注冊您的私有 SSH 密鑰，如本文檔前面所述 * 嘗試通過運行`ssh -Tv git@example.com`調試連接（將 GitLab 域替換為`example.com` ）