[轉]為 GitLab 啟用 Let's Encrypt 頒發的 SSL 證書

原文地址：https://zzz.buzz/zh/2016/04/03/enable-ssl-for-gitlab-with-letsencrypt/

Let's Encrypt 是一家全新的 SSL 證書頒發機構，為用戶提供免費、自由、自動化的證書頒發流程。我們可以通過 Let's Encrypt 申請 SSL 證書來為我們的 GitLab 提供 HTTPS 接入。

安裝 Let's Encrypt 客戶端

首先，通過 git 下載 Let's Encrypt 的客戶端：

git clone https://github.com/certbot/certbot
cd certbot ./certbot-auto --help 

（注：自 2016 年 5 月起，letsencrypt 項目改名為 certbot，letsencrypt-auto 工具改名為 certbot-auto。不過為了保持兼容性，克隆倉庫時仍可使用 https://github.com/letsencrypt/letsencrypt，使用命令時也仍可用 letsencrypt-auto。）

申請證書

下載完 Let's Encrypt 客戶端后，我們可以借助隨 GitLab 啟動的 nginx 服務器來驗證我們的域名，進而獲得證書。

./certbot-auto --agree-tos --email [e-mail] certonly --webroot -w /opt/gitlab/embedded/service/gitlab-rails/public/ -d www.example.com 

上述命令中：

--agree-tos

同意用戶協議。

--email

首次申請證書時，需要郵箱地址來創建 Let's Encrypt 的賬號。不過，並不會驗證此賬號。

郵箱地址用於接受證書過期提醒。

certonly

只申請證書。

--webroot

通過在當前運行的 web 服務器下存放驗證文件來驗證身份。

-w

指定當前運行的 web 服務器的根目錄。

對於通過 Omnibus 安裝的 GitLab 的默認的 nginx 服務器的根目錄位於 /opt/gitlab/embedded/service/gitlab-rails/public/。

-d

指定要申請證書的域名。

證書申請成功后，會有類似如下輸出：

Requesting root privileges to run certbot...
  /home/zzz.buzz/.local/share/letsencrypt/bin/letsencrypt --agree-tos --email [e-mail] certonly --webroot -w /opt/gitlab/embedded/service/gitlab-rails/public/ -d www.example.com
Saving debug log to /var/log/letsencrypt/letsencrypt.log
Performing the following challenges:
http-01 challenge for www.example.com
Using the webroot path /opt/gitlab/embedded/service/gitlab-rails/public for all unmatched domains.
Waiting for verification...
Cleaning up challenges
Generating key (2048 bits): /etc/letsencrypt/keys/0001_key-certbot.pem
Creating CSR: /etc/letsencrypt/csr/0001_csr-certbot.pem

IMPORTANT NOTES:
 - Congratulations! Your certificate and chain have been saved at
   /etc/letsencrypt/live/www.example.com/fullchain.pem. Your cert
   will expire on 2017-07-22. To obtain a new or tweaked version of
   this certificate in the future, simply run certbot-auto again. To
   non-interactively renew *all* of your certificates, run
   "certbot-auto renew"
 - If you like Certbot, please consider supporting our work by:

   Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate
   Donating to EFF:                    https://eff.org/donate-le

得到的證書及私鑰存放在 /etc/letsencrypt/live/www.example.com/ 目錄下，其中

• cert.pem: 網站自身的證書；
• chain.pem: 網站證書鏈中的上級證書；
• fullchain.pem: 包含了網站自身證書和上級證書的完整證書鏈；
• privkey.pem: 網站自身證書對應的私鑰。

更新證書

由於證書的有效期為三個月，因此我們需要定時執行以下命令來更新證書：

./certbot-auto renew

注意如果證書還有較長時間才會過期，那么證書並不會得到更新，並會得到類似如下輸出：

Requesting root privileges to run certbot...
  /home/zzz.buzz/.local/share/letsencrypt/bin/letsencrypt renew
Saving debug log to /var/log/letsencrypt/letsencrypt.log

-------------------------------------------------------------------------------
Processing /etc/letsencrypt/renewal/gitlab.zzz.buzz.conf
-------------------------------------------------------------------------------
Cert not yet due for renewal

The following certs are not due for renewal yet:
  /etc/letsencrypt/live/gitlab.zzz.buzz/fullchain.pem (skipped)
No renewals were attempted.

而如果證書即將過期（有效期不足 20 天，10 天和 1 天時），用戶卻還未執行命令更新證書，那么 Let's Encrypt 會自動發郵件至申請證書時所留的郵件地址，提醒更新證書。

更新完證書后，還需要讓 nginx 重新加載新證書：

sudo gitlab-ctl hup nginx 

除了手動執行外，也可以把以上命令加入 cron 任務來定時執行。

使用以下命令來編輯 cron 任務：

sudo su - crontab -e 

在打開的文件中，添加以下內容：

0 3 * * 1 /home/zzz.buzz/certbot/certbot-auto renew && gitlab-ctl hup nginx

以上命令會在每周一的 3 點嘗試更新證書，即如果證書將在 30 日內過期，則會被更新，否則將不會被更新；
同時還會發送 HUP 信號給 nginx 進程，以使其加載新證書。

注意將 certbot-auto 的路徑替換為實際的路徑。

在 GitLab 中應用證書

配置 GitLab 使用 HTTPS 協議

修改 /etc/gitlab/gitlab.rb 文件，配置 external_url 為 https 開頭的地址，如：

external_url 'https://gitlab.zzz.buzz' 

如果需要將經過 HTTP 的流量重定向至 HTTPS 還需要在 /etc/gitlab/gitlab.rb 文件中，進行如下配置：

nginx['redirect_http_to_https'] = true 

配置證書

配置 GitLab 將要使用的證書有兩種方式，一種是將之前通過 Let's Encrypt 申請的證書放置到 GitLab 默認要求的配置，如下文鏈接證書所示；另一種則是修改 GitLab 的配置文件，將證書的路徑指向之前通過 Let's Encrypt 申請的證書，如下文修改配置所示。兩種方式選一即可。

配置方法一：鏈接證書

根據通過 Omnibus 安裝的 GitLab 的默認配置，會尋找存放在 /etc/gitlab/ssl/ 目錄下的 www.example.com.key 和 www.example.com.crt 文件，其中的 www.example.com 應當替換為在上文中 external_url 里設置的域名。

我們可以通過如下命令來將之前通過 Let's Encrypt 申請的證書鏈接到所需的位置。

# 切換至 root 用戶（如已是 root 用戶，則無需此步） sudo su - # 使用 root 用戶執行以下命令 mkdir -p /etc/gitlab/ssl chmod 700 /etc/gitlab/ssl cd /etc/gitlab/ssl ln -s ../../letsencrypt/live/www.example.com/fullchain.pem www.example.com.crt ln -s ../../letsencrypt/live/www.example.com/privkey.pem www.example.com.key 

配置方法二：修改配置

修改 GitLab 的配置文件 /etc/gitlab/gitlab.rb，添加以下內容：

nginx['ssl_certificate'] = "/etc/letsencrypt/live/www.example.com/fullchain.pem" nginx['ssl_certificate_key'] = "/etc/letsencrypt/live/www.example.com/privkey.pem" 

啟用新配置

配置完成后，使用如下命令啟用新配置：

sudo gitlab-ctl reconfigure 

參考

Let's Encrypt

• Getting Started - Let's Encrypt - Free SSL/TLS Certificates
• Introduction — Let's Encrypt documentation
• certbot/certbot

GitLab Nginx

• NGINX settings