github_to_nginx_sync_manual
GitHub 儲存庫同步至 Nginx 伺服器操作手冊
本手冊旨在指導如何設定自動化流程:當開發者將程式碼推送到 GitHub 儲存庫 (git push) 時,透過 GitHub Actions 與 SSH 機制,自動將最新程式碼同步更新至 Hetzner(或任何 Nginx)伺服器的指定網站根目錄中。
📋 系統架構總覽
graph LR
A[本地機器 Local] -->|git push| B[GitHub 倉庫]
B -->|GitHub Actions| C[SSH 安全連線]
C -->|Rsync 同步| D[Nginx 伺服器]- 本機 (Local Machine):撰寫與修改程式碼,透過 Git 推送到 GitHub。
- 遠端倉庫 (GitHub Repository):存放程式碼並作為 CI/CD 自動化的觸發核心。
- 自動化流程 (GitHub Actions):透過 SSH 安全連線至伺服器。
- 目標伺服器 (Hetzner / Nginx):接收同步檔案並透過 Nginx 即時對外提供網頁服務。
🛠️ 第一階段:伺服器端 SSH 金鑰設定
為了讓 GitHub Actions 能夠安全且免密碼地登入你的 Nginx 伺服器,我們必須建立專用的 SSH 部署金鑰。
1. 在本機終端機產生 SSH 金鑰對
打開終端機,執行以下指令(可將 github-actions-deploy 替換為你喜歡的識別名稱):
ssh-keygen -t ed25519 -C "github-actions-deploy" -f ~/.ssh/gh_deploy
提示
過程中若詢問 Passphrase 直接按 Enter 略過即可。
執行後會在 ~/.ssh/ 目錄下產生兩支檔案:
gh_deploy(私鑰 - Private Key,絕對不能外洩)gh_deploy.pub(公鑰 - Public Key)
2. 將公鑰部署至伺服器
- 印出公鑰內容並複製:
cat ~/.ssh/gh_deploy.pub - 透過 SSH 登入你的伺服器:
ssh root@你的伺服器IP - 將剛剛複製的公鑰貼到伺服器的
/root/.ssh/authorized_keys檔案最下方並儲存。 - 確保資料夾與檔案權限正確:
chmod 700 /root/.ssh chmod 600 /root/.ssh/authorized_keys
🔒 第二階段:設定 GitHub Repository Secrets
GitHub Actions 需要透過加密變數來取得伺服器連線資訊。
- 用瀏覽器登入 GitHub,進入你的專案儲存庫(例如
gavintux/yi)。 - 點擊上方的 Settings(設定)分頁。
- 在左側選單找到 Secrets and variables > 點擊 Actions。
- 點擊 New repository secret,依序新增以下三個秘密變數:
| Secret 名稱 | 內容說明 |
|---|---|
SERVER_HOST |
你的伺服器 IP 位址(例如 95.217.152.250) |
SERVER_USER |
伺服器登入帳號(通常為 root) |
SSH_PRIVATE_KEY |
本機產生的 私鑰 內容 (cat ~/.ssh/gh_deploy 的完整文字,包含 -----BEGIN...-----) |
⚙️ 第三階段:建立 GitHub Actions 自動化腳本
在你的專案根目錄下建立 .github/workflows/deploy.yml 檔案,內容如下:
name: Deploy to Hetzner Nginx Server
on:
push:
branches: [ main ] # 當推送到 main 分支時觸發
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup SSH Key
uses: webfactory/ssh-agent@v0.9.0
with:
ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
- name: Deploy to Server via SSH
env:
SERVER_HOST: ${{ secrets.SERVER_HOST }}
SERVER_USER: ${{ secrets.SERVER_USER }}
run: |
# 略過第一次連線的 Host key 詢問
mkdir -p ~/.ssh
echo "StrictHostKeyChecking no" >> ~/.ssh/config
# 使用 rsync 將專案檔案同步到 Nginx 網站根目錄
# 請將 /var/www/html 替換為你伺服器上 Nginx 實際指向的網站資料夾路徑
rsync -avz --delete ./ $SERVER_USER@$SERVER_HOST:/var/www/html/
🚀 第四階段:日常使用與驗證
當上述設定完成後,日後你只需要在本地修改程式碼,並執行標準的 Git 三部曲即可完成自動同步:
# 1. 將所有修改加入暫存區
git add .
# 2. 建立本地版本紀錄
git commit -m "更新網站前端程式碼"
# 3. 推送到 GitHub (會自動觸發 Actions 同步至 Nginx)
git push origin main
如何檢查同步狀態?
- 回到 GitHub 專案頁面的 Actions 分頁。
- 點擊最新的一次推送任務,觀察各個步驟是否出現綠色的 Success 標記。
- 打開你的網頁瀏覽器,重新整理網站,即可看到最新的更新內容已在 Nginx 伺服器上生效。