前言：理解整體畫面是非常重要的

您好！在上篇中，我們探討了為什麼要構建利用 GitHub Webhook 的自動部署系統以及所需的準備工作。在這篇文章中，我們將在實際代碼實現之前，花時間設計我們所創建的自動部署系統的整體架構和流程。

每個人的開發環境可能會有所不同。某些人可能會使用 Raspberry Pi，而其他人則可能會使用雲伺服器 VPS，並且即將部署的項目的結構也會各異。在這樣多樣的環境中靈活地構建系統，並能夠在問題發生時自行解決，理解整體流程和背景是至關重要的。

通過這一部分，我們將描繪出要構建的系統的全局視圖，並明確了解每個組件的角色。

自動部署系統流程圖

自動部署工作流程：整體流程概覽

我們實現的自動部署系統將經歷以下一系列過程進行運作。

  1. 在本地工作機上進行代碼更改並推送到 Git：開發者在本地環境中修改代碼，然後將更改推送到 GitHub 儲存庫的特定分支（例如：main 或 develop）。

  2. 在 GitHub 儲存庫中觸發 Webhook 事件：當 GitHub 儲存庫檢測到 push 事件時，通過預設的 Webhook 向指定 URL 發送 HTTP POST 請求。

  3. 請求轉發到暫存伺服器的 Webhook 端點：GitHub 發送的 Webhook 請求將指向我們準備的暫存伺服器的特定 URL（例如：https://deployer.example.com/webhook

  4. 暫存伺服器的 FastAPI 服務接收 Webhook：在暫存伺服器上運行的 FastAPI 應用程序將接收此 Webhook 請求。從這裡開始，FastAPI 服務的角色就開始了。

FastAPI Webhook 服務的核心角色

我們用 FastAPI 實現的 Webhook 服務不僅僅是接收請求，它還會執行以下幾個重要角色。

Webhook 接收及初步處理

FastAPI 應用程序提供了一個可以接收從 GitHub 發送的 HTTP POST 請求的端點（例如：/webhook）。此端點解析請求的 HTTP 標頭和主體（Payload）以提取所需的信息。

Secret 驗證

安全性在自動部署系統中至關重要。GitHub Webhook 通過一個名為 X-Hub-Signature-256 的標頭提供一個 Secret 值，以驗證請求的完整性。我们的 FastAPI 服务需要包含逻辑，使用此 Secret 值来验证从 GitHub 发送的请求是否有效，以及是否在传输过程中未被篡改。如果验证失败，则立即拒绝请求以防止未授权访问。

立即響應及後台作業

如果 GitHub Webhook 在一定時間（默認 10 秒）內未收到回應，將被視為超時，將重試或記錄為失敗。然而，實際的部署過程（Git Pull、Docker 構建/重新啟動等）可能會花費更多時間。

因此，我們的 FastAPI 服務在立即收到 Webhook 請求後，將進行 Secret 驗證等初步處理後，立即發送200 OK 的回應給 GitHub。實際的部署邏輯將設計為利用 FastAPI 的 BackgroundTasks 功能在後台異步執行。這樣可以避免 GitHub 的超時問題，同時穩定地執行部署任務。

部署處理器邏輯詳細

將在後台執行的部署處理器將執行以下幾個核心任務：

多項目管理：讀取儲存庫路徑

我們將設計一個 FastAPI Webhook 服務來處理多個 GitHub 儲存庫（項目）的自動部署。為此，我們會在環境變量或配置文件中管理映射每個項目的 GitHub 儲存庫路徑以及該項目在伺服器內部的本地路徑。在 Webhook 載荷中確認事件發生在哪個儲存庫後，移動到該項目的路徑並執行部署操作。

項目專屬設定：解析 .env 文件（可選）

每個項目可能會有唯一的環境變量或設置值，這在構建或部署時可能是必需的。例如，特定的 Docker 映像標籤、構建選項、服務重啟命令等可能有所不同。為了有效管理，將實現從每個項目的本地儲存庫路徑中的 .env 文件中解析所需值，以便在部署邏輯中使用。這在實現靈活且量身定制的部署邏輯方面會有很大幫助。

代碼更新：執行 git pull

這是最基本的步驟。使用 subprocess 模組，在該項目的本地儲存庫中執行 git pull origin <branch_name> 命令以獲取 GitHub 儲存庫的最新代碼。

Docker 映像重建決策：利用 git diff

對於基於 Docker 的項目，當代碼僅更改時，使用 docker compose up -d 就足夠了，但如果像 Dockerfile 或 requirements.txt（Python 項目的情況）等影響 Docker 映像構建的文件發生了變化，則需要重新構建映像。

我們將利用 git diff 命令來判斷最近推送的提交和之前的提交之間是否有 Dockerfile 或其他構建相關文件的變更。如果檢測到變更，我們將執行 docker compose up -d --build，如果沒有，則只執行 docker compose up -d，以避免不必要的映像重建，縮短部署時間。

執行 Docker Compose：利用 subprocess 模組

在獲取最新代碼並決定映像重建後，使用 subprocess 模組執行 docker compose up -d 或 docker compose up -d --build 命令，以更新 Docker 容器至最新狀態並重啟服務。

日誌記錄：所有過程的記錄

所有的部署過程（Webhook 接收、驗證、Git Pull 結果、Docker 構建/重啟日誌等）都應詳細記錄。這對於在問題發生時確定原因和進行除錯至關重要。我們將利用 Python 的 logging 模組來實現將日誌寫入文件。

FastAPI 服務的部署與運營策略

我們實現的 FastAPI Webhook 服務必須始終在暫存伺服器上穩定運行。

利用 Systemd 服務的重要性

強烈建議將 FastAPI 應用程序作為 Systemd 服務 運行，而不是直接在 Docker 容器內部啟動。原因如下。

  • 資源效率：暫存伺服器上已經可能安裝了 git、docker、docker compose 等部署所需的工具。將 FastAPI Webhook 服務本身設置為 Docker 容器，然後再次在該容器內部安裝 git 或 docker 以控制系統的 docker 守護進程，將不必要地增加容器的大小，並引起 docker-in-docker 或 docker-out-of-docker 等複雜的設置與安全問題。

  • 簡潔管理：Systemd 是 Linux 系統的服務管理標準。將 FastAPI 應用註冊為 Systemd 服務後，實現自動啟動、檢查服務狀態、輕鬆重啟/停止等操作，使得 OS 層面上能夠進行綜合性且簡潔的管理。

  • 系統資源利用：通過 Systemd 啟動 FastAPI 應用程序後，應用可以直接調用系統中安裝的 git 和 docker 命令執行部署任務，最有效地利用系統的現有資源。

在下篇文章中，我們將詳細說明如何將 FastAPI 應用註冊為 Systemd 服務並進行管理。

通過 Nginx/Apache2 進行反向代理及 HTTPS

如同在第一部分中強調的，將 FastAPI 應用直接暴露於互聯網是非常危險的。因此，我們將使用Nginx 或 Apache2 作為反向代理，安全地將 Webhook 請求轉發至 FastAPI 應用程序。

此外，由於 GitHub Webhook 強烈建議使用 HTTPS 通信，我們需要準備像 deployer.example.com 這樣的獨立子域名，並通過 Let's Encrypt 獲取 HTTPS 證書，應用於 Web 伺服器。這樣可以加強所有外部通信的加密安全性。

監控與調試

我們將利用以下兩種方法來確保自動部署系統正常運行，並在發生問題時找到原因。

  • FastAPI 服務日誌文件：我們實現的 FastAPI 服務將在自動部署過程中的每個階段記錄到日誌文件中。通過查看此文件，可以了解部署的成功與否及出現的錯誤信息。

  • Systemd journalctl：由於通過 Systemd 管理 FastAPI 服務，因此可以通過 journalctl -u your-fastapi-service.service 命令實時查看服務的標準輸出和錯誤日誌，方便進行分析。

結語：下篇預告

在這篇文章中，我們詳細探討了利用 GitHub Webhook 的自動部署系統的整體架構，以及 FastAPI 服務的核心角色與部署以及運營策略。希望您能在腦中描繪出整體畫面。

在下一篇中，我們將根據今天設計的內容，撰寫實際的 FastAPI Webhook 服務代碼，設置 GitHub Webhook，並詳細說明如何註冊為 Systemd 服務的實現過程。敬請期待！

利用 GitHub Webhook 搭建個人自動部署系統系列

第一篇 - 為何要自己實現？