高效 AI 駕馭術
2026 GitHub Actions 自動部署到 Oracle Cloud 免費主機:push 到 main 就上線(SSH、systemd、Caddy)
用 GitHub Actions 把 Node.js 服務部署到 Oracle Cloud Always Free Ampere A1:設定部署專用 SSH 金鑰與 known_hosts,建置後切換版本、重啟 systemd,再用健康檢查決定保留新版或回滾,前面由 Caddy 提供 HTTPS。
Kelvin Wang · · 12 分鐘閱讀
重點整理
- 小網站用 GitHub 的主機 SSH 進去部署最單純;自架 runner 適合私人 repo、建置又吃資源的情況。
- 部署金鑰要獨立;restrict 和 command= 限制 SSH 入口,但部署程式碼仍會以 deploy 的權限執行。
- 建置成功才切換 current;新版通過健康檢查後才清理舊版,保留 current 和 previous 供回滾。
- Oracle 的 Ubuntu 映像除了 OCI 的 Security List,主機裡還有 iptables 規則,80、443 兩邊都要開,Caddy 才拿得到憑證。
我在東京區(ap-tokyo-1)有一台 A1 主機,上面已經用 systemd 常駐 Claude Code Remote Control。下面以 Ubuntu 上需要建置、持續執行的 Node.js 服務為例,整理另一個用途:讓 GitHub Actions 在 push 到 main 後部署網站。
這套部署流程依官方文件整理,尚未在這台主機實跑。指令裡的 <...>、example.com、myapp 要換成自己的值;建置指令、啟動檔和健康檢查端點也要配合專案調整。
用 GitHub 的主機 SSH 進去,還是在自己主機上跑 runner?
GitHub Actions 的工作要在某台機器上跑,這台機器叫 runner。部署到自己的主機有兩種常見做法:用 GitHub 提供的 runner,跑完後 SSH 進你的主機;或是把 runner 裝在你的主機上,工作直接在主機裡跑。
| 項目 | GitHub 的 runner + SSH | 主機上自架 runner |
|---|---|---|
| 工作在哪跑 | GitHub 的機器,跑完 SSH 進主機 | 你的主機 |
| 主機要開什麼 | SSH(22 埠)要讓 GitHub 連得進來 | runner 主動連 GitHub,主機要能對外連 443 |
| 費用 | 公開 repo 免費;私人 repo 先用方案內含的分鐘數,超過按分鐘計費 | GitHub 不收費,主機自己負擔 |
| 公開 repo | 可以用 | GitHub 建議只用在私人 repo |
| 維護 | GitHub 維護 runner | 主機的系統和軟體更新都要自己顧 |
| 適合 | 小網站、偶爾部署 | 私人 repo、建置很吃資源或要用主機上的檔案 |
這篇用第一種,主機不用常駐 runner 程式。GitHub 的 runner IP 清單每週更新,GitHub 也不建議拿它們當白名單4,因此這裡使用獨立的部署帳號和 SSH 金鑰。公開 repo 不建議接自架 runner,是因為別人 fork repo 後開 PR,可能讓 runner 執行他寫的程式6。
想深入 2026 GitHub Actions 自架 Runner 教學:用 Oracle Cloud 免費 ARM 主機跑 arm64 CI 想讓工作直接在 A1 主機上跑,看這篇。部署會用到哪些東西?
整個流程只有幾個角色,先看清楚誰在哪裡:
deploy使用者:主機上專門給部署用的 Linux 帳號,不是你平常登入的ubuntu。- 部署金鑰:一把新的 SSH 金鑰。私鑰存在 GitHub 的 Actions secret,公鑰放在
deploy的authorized_keys。 - 部署腳本:
/usr/local/bin/deploy-myapp,這把 SSH 金鑰登入後的固定入口。 - 版本資料夾:先在
/srv/myapp/staging建置,成功後移到releases;current指向目前版本,previous保留前一個通過健康檢查的版本。 - systemd 服務:
myapp.service,從current啟動你的程式。 - Caddy:對外聽 80 和 443,自動申請 HTTPS 憑證,把請求轉給
localhost:3000。
建置在主機上做,不在 GitHub 的機器上做。A1 是 ARM,GitHub 預設的 ubuntu-latest 是 x644,套件裡有原生模組時,在主機上建才不會拿到錯的架構。
主機上怎麼建一個只能部署的帳號?
這裡建立的是部署專用帳號,限制它的 SSH 入口和 sudo 授權。建置與應用程式仍以這個帳號執行,並沒有被隔離在沙箱內。
-
建
deploy使用者和資料夾:sudo adduser --disabled-password --gecos "" deploy sudo mkdir -p /srv/myapp/releases /srv/myapp/staging /srv/myapp/shared sudo chown -R deploy:deploy /srv/myappsudo -u deploy touch /srv/myapp/shared/.env sudo chmod 600 /srv/myapp/shared/.envshared放每一版都要共用的東西,例如.env;它不在版本資料夾裡,切換版本不會不見。沒有環境變數也先建一個空檔,後面的 systemd 服務會讀它。 -
在你自己的電腦產生部署金鑰,不要拿你平常登入用的那把:
ssh-keygen -t ed25519 -f deploy_key -N "" -C "github-actions-deploy"會產生
deploy_key(私鑰)和deploy_key.pub(公鑰)。 -
把公鑰放進
deploy的authorized_keys,前面加限制:sudo -u deploy mkdir -p -m 700 /home/deploy/.ssh sudo -u deploy tee /home/deploy/.ssh/authorized_keys > /dev/null <<'EOF' restrict,command="/usr/local/bin/deploy-myapp" ssh-ed25519 AAAA...(deploy_key.pub 的內容) github-actions-deploy EOF sudo chmod 600 /home/deploy/.ssh/authorized_keysrestrict關掉 port、agent、X11 轉發與 PTY;command=固定 SSH 登入後的指令,客戶端傳來的指令只會放進SSH_ORIGINAL_COMMAND8。但這不代表金鑰外洩後只能重跑既有版本:腳本會接收上傳的程式碼,npm ci和npm run build又會執行其中的 scripts18。拿到金鑰的人仍能以deploy權限執行程式、讀取.env,甚至改掉自己擁有的authorized_keys。這把金鑰必須當成部署帳號的存取憑證保管。 -
只授權
deploy重啟、停止這一個服務。第一次部署失敗、沒有舊版可回復時需要停止服務。用visudo建 sudoers 檔,檔名不要有點,sudo 會略過含.的檔名10:sudo visudo -f /etc/sudoers.d/deploy-myapp填入這兩行;指令寫了參數,授權就只涵蓋這組參數10:
deploy ALL=(root) NOPASSWD: /usr/bin/systemctl restart myapp.service deploy ALL=(root) NOPASSWD: /usr/bin/systemctl stop myapp.service
部署腳本怎麼寫才能隨時回滾?
GitHub 把 commit 的程式碼打包成 tar,透過 SSH 傳進來,再把 SHA 當成「指令」送過來。因為有 command=,SHA 只會出現在 SSH_ORIGINAL_COMMAND,不會當成 shell 指令執行。這裡只檢查 SHA 格式,並未驗證 tar 內容來自該 commit;使用前提是信任能部署的人與程式碼。
腳本先建置,再切換版本、重啟服務。/health 必須在應用程式準備好接請求時回 HTTP 200;每次請求最多等 2 秒,最多試 10 次,每次失敗等 2 秒22。新版檢查失敗就嘗試回復舊版,整次部署仍以失敗結束。flock 防止兩個部署同時改版本23。
#!/usr/bin/env bash
set -euo pipefail
APP=/srv/myapp
SHA=${SSH_ORIGINAL_COMMAND:-}
[[ $SHA =~ ^[0-9a-f]{40}$ ]] || { echo "expected a commit SHA" >&2; exit 2; }
exec 9>"$APP/deploy.lock"
flock -n 9 || { echo "another deploy is running" >&2; exit 1; }
healthy() {
local status
for attempt in {1..10}; do
if status=$(curl -sS --max-time 2 -o /dev/null -w '%{http_code}' \
http://127.0.0.1:3000/health) && [[ $status == 200 ]]; then
return 0
fi
sleep 2
done
return 1
}
BUILD=$(mktemp -d "$APP/staging/${SHA:0:7}.XXXXXX")
trap 'rm -rf -- "$BUILD"' EXIT
tar -x -f - -C "$BUILD"
cd "$BUILD"
rm -f .healthy
ln -s "$APP/shared/.env" .env
npm ci
npm run build
OLD=$(readlink -f "$APP/current" || true)
REL=$APP/releases/$(date -u +%Y%m%d%H%M%S)-${BUILD##*/}
mv "$BUILD" "$REL"
cd "$APP"
ln -sfn "$REL" "$APP/current"
if ! sudo /usr/bin/systemctl restart myapp.service || ! healthy; then
echo "new release failed; attempting recovery" >&2
if [[ -n $OLD && -f "$OLD/.healthy" ]]; then
ln -sfn "$OLD" "$APP/current"
if sudo /usr/bin/systemctl restart myapp.service && healthy; then
rm -rf -- "$REL"
echo "previous release restored" >&2
else
echo "rollback failed; inspect the service logs" >&2
fi
elif sudo /usr/bin/systemctl stop myapp.service; then
rm -f "$APP/current"
rm -rf -- "$REL"
echo "no healthy previous release; service stopped" >&2
else
echo "could not stop the failed service; inspect it manually" >&2
fi
exit 1
fi
touch "$REL/.healthy"
if [[ -n $OLD && -f "$OLD/.healthy" ]]; then
ln -sfn "$OLD" "$APP/previous"
fi
PREVIOUS=$(readlink -f "$APP/previous" || true)
kept=0
while IFS= read -r candidate; do
[[ -f "$candidate/.healthy" ]] || continue
[[ $candidate == "$REL" || $candidate == "$PREVIOUS" ]] && continue
kept=$((kept + 1))
if (( kept > 3 )); then
rm -rf -- "$candidate"
fi
done < <(find "$APP/releases" -mindepth 1 -maxdepth 1 -type d | LC_ALL=C sort -r)
echo "deployed $SHA -> $REL"
主機上要先裝好 Node.js、npm、curl 和提供 flock 的 util-linux,並確認 deploy 的非互動 shell 找得到它們。把腳本存成 deploy.sh,用 root 安裝到固定位置,避免 deploy 直接修改入口腳本:
sudo install -o root -g root -m 755 deploy.sh /usr/local/bin/deploy-myapp
建置失敗時,腳本不切換 current,並清掉 staging 目錄;錯誤輸出留在 Actions log。新版通過健康檢查才寫入 .healthy 標記,清理時保留 current、previous,再留最近 3 個其他已通過檢查的版本。回滾也失敗時,腳本會保留相關版本供排查,不會印成功。若主機斷電或程序被強制終止,仍須檢查 symlink、服務與殘留目錄;這不是跨資料庫、檔案與程序的交易式回滾。
systemd 服務怎麼指到 current?
存成 /etc/systemd/system/myapp.service:
[Unit]
Description=myapp
After=network.target
[Service]
Type=exec
User=deploy
WorkingDirectory=/srv/myapp/current
EnvironmentFile=/srv/myapp/shared/.env
ExecStart=/usr/bin/node server.js
Restart=always
RestartSec=2
TimeoutStartSec=30
TimeoutStopSec=30
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable myapp.service
WorkingDirectory 指向 current,重啟時會從它目前指向的版本啟動。ExecStart 要換成專案實際的啟動指令,程式綁定 127.0.0.1:3000。Type=exec 能回報執行檔啟動失敗,但不代表 HTTP 已就緒,因此部署仍要檢查 /health19。這裡只 enable,第一次部署才啟動服務。
Caddy 怎麼自動上 HTTPS?
-
DNS 先指過來。在你的網域商把
example.com的 A 記錄設成主機的固定 IP(<SERVER_IP>)。Caddy 自動申請憑證的前提是網域指到這台主機、80 和 443 從外面連得到、資料夾可以寫13。 -
在 OCI 的 Security List 開 80、443。Console → Networking → Virtual Cloud Networks → 你的 VCN → 子網路用的 Security List → Add Ingress Rules:Source CIDR
0.0.0.0/0、IP Protocol TCP、Destination Port Range 分別填80和44311。 -
在主機裡的 iptables 也開 80、443(見下方提示框)。
-
裝 Caddy,照官方的 Ubuntu 指令,裝完會自動以
caddy這個 systemd 服務啟動14:sudo apt install --yes debian-keyring debian-archive-keyring apt-transport-https curl curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list sudo chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg sudo chmod o+r /etc/apt/sources.list.d/caddy-stable.list sudo apt update sudo apt install caddy -
寫
/etc/caddy/Caddyfile,把網域轉給你的服務15:example.com { reverse_proxy localhost:3000 } -
重新載入設定。用 reload 不用 stop,網站不會中斷16:
sudo systemctl reload caddy
Caddy 預設會把 HTTP 轉到 HTTPS,也會自動續證13。純靜態網站可用 root /srv/myapp/current/dist 搭配 file_server17;Caddy 以 caddy 使用者執行,要讓它讀得到成品目錄16。若改用靜態網站,部署腳本也要一起移除 myapp 的 restart/stop,並把健康檢查改成透過 Caddy 取得已知的靜態檔案,不能只刪掉一行重啟指令。
怎麼讓 GitHub 只認你的主機?
SSH 第一次連一台主機時會問你要不要信任它的主機金鑰。在 GitHub 的機器上沒人能回答,常見的偷懶做法是關掉檢查,但那樣有人冒充你的主機也不會發現。正確做法是先把主機金鑰存成 secret,連線時強制比對。
-
從主機本身拿主機公鑰。用你平常的 SSH 連線登入主機,這條連線你已經信任過:
cat /etc/ssh/ssh_host_ed25519_key.pub -
組成 known_hosts 的一行:主機 IP、金鑰類型、金鑰內容,用空白隔開8:
<SERVER_IP> ssh-ed25519 AAAA...用
ssh-keyscan -t ed25519 <SERVER_IP>也拿得到同一行,但它不驗證金鑰真假,結果要和上面主機裡的檔案對過才算數9。 -
把三個值存成 repo 的 Actions secret。可以在 repo 的 Settings → Secrets and variables → Actions 新增,或用
gh secret set3:gh secret set DEPLOY_SSH_KEY < deploy_key gh secret set DEPLOY_KNOWN_HOSTS --body "<SERVER_IP> ssh-ed25519 AAAA..." gh secret set DEPLOY_HOST --body "<SERVER_IP>"存好後把電腦上的
deploy_key刪掉,需要時重產一把就好。從 fork 觸發的 workflow 拿不到這些 secret3。
GitHub Actions 的 workflow 怎麼寫?
存成 repo 裡的 .github/workflows/deploy.yml:
name: Deploy
on:
push:
branches: [main]
concurrency:
group: deploy-production
cancel-in-progress: false
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- name: Set up SSH
env:
DEPLOY_SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
DEPLOY_KNOWN_HOSTS: ${{ secrets.DEPLOY_KNOWN_HOSTS }}
run: |
install -m 700 -d ~/.ssh
printf '%s\n' "$DEPLOY_SSH_KEY" > ~/.ssh/deploy_key
chmod 600 ~/.ssh/deploy_key
printf '%s\n' "$DEPLOY_KNOWN_HOSTS" > ~/.ssh/known_hosts
- name: Ship and deploy
env:
DEPLOY_HOST: ${{ secrets.DEPLOY_HOST }}
run: |
git archive --format=tar HEAD | ssh -i ~/.ssh/deploy_key \
-o IdentitiesOnly=yes -o StrictHostKeyChecking=yes \
"deploy@$DEPLOY_HOST" "$GITHUB_SHA"
幾個地方值得注意:
concurrency讓部署排隊。同一個 group 同時只會有一個在跑,另外最多一個在等,更新的那個會取代原本在等的7。cancel-in-progress: false不砍掉正在跑的部署,避免建到一半被中斷。StrictHostKeyChecking=yes不接受陌生主機。主機金鑰和 secret 裡的對不上,SSH 直接失敗,不會把程式碼送出去。- 最後的
$GITHUB_SHA不會被執行。它只是傳給部署腳本的參數,主機那邊因為command=永遠只跑deploy-myapp。
設定完成後 push 一個 commit 到 main,再到 Actions 看結果。deployed <SHA> -> ... 表示建置、重啟與本機 /health 檢查已通過;還要從外部開啟網站,確認 DNS、HTTPS 和實際頁面。健康端點通過不代表所有功能都正確。
部署壞了怎麼回滾?
新版上線後才發現問題,有兩種回法:
-
馬上回到上一版。先在 Actions 停用自動部署 workflow;停用不會取消既有 run,所以還要取消 pending 部署,並等所有 running 部署結束24。回滾、檢查網站和準備 Git revert 期間都保持停用。接著用平常的帳號登入,確認選定版本有
.healthy標記後,把current指回去並重啟:ls -1 /srv/myapp/releases sudo -u deploy ln -sfn /srv/myapp/releases/<上一版的資料夾> /srv/myapp/current sudo systemctl restart myapp.service這不需要重新建置,但重啟後仍要檢查
/health和網站;若新版改過共用資料或資料庫,換回程式碼不會撤銷那些變更。 -
在 Git 裡把壞掉的 commit 還原。先在本機完成
git revert <壞掉的 commit>並確認修正。如果前一步停用了 workflow,等回滾檢查完成、revert 已準備好推送時,再重新啟用 workflow,然後 push 到 main,讓修正照正常流程部署24。
第一種只是先止血。只做第一種的話,下一次有人 push 到 main,壞掉的程式又會跟著部署上去,所以之後還是要做第二種。
要不要加上 environment 審核?
GitHub 的 environment 可以替部署加關卡:job 寫上 environment: production,就要先通過這個 environment 的保護規則才會開始跑,等待期間也拿不到這個 environment 的 secret1。常用的規則:
- Required reviewers:指定最多 6 個人或團隊,其中一人按核准才部署,也可以勾選不能核准自己觸發的部署1。
- Deployment branches:限制只有 main 能部署到 production。
- Wait timer:觸發後先等幾分鐘才開始。
加法是在 job 裡多一行:
jobs:
deploy:
runs-on: ubuntu-latest
environment: production
方案限制要先看清楚:免費方案只有公開 repo 能設定 environment;Pro、Team 可以在私人 repo 用 environment 和 deployment branches,但 required reviewers 與 wait timer 在 Free、Pro、Team 都只限公開 repo2。Free 私人 repo 也沒有分支保護;需要這項功能得使用支援的付費方案20。branches: [main] 只限制 workflow 的觸發分支,不能代替審核或阻止有寫入權限的人推送程式碼。
常見問題
部署金鑰可以加 from= 只允許 GitHub 的 IP 嗎?
from= 可以限制來源 IP8,但 GitHub 的 runner IP 清單每週更新,官方不建議用一般 hosted runner 的範圍做白名單4。若需要固定來源,可評估有固定 IP 的 larger runner 或自架 runner。restrict 和 command= 不會消除部署金鑰外洩後執行任意應用程式碼的風險。
可以直接在 GitHub 的機器上建置,只傳成品過去嗎?
可以,部署腳本把建置那兩行拿掉,workflow 改成先建置、再把成品打包送過去。要注意架構:ubuntu-latest 是 x64,GitHub 另外有 ubuntu-24.04-arm 這個 arm64 runner4,成品裡有原生程式時要選和主機一樣的架構。
第一次部署時 current 還不存在怎麼辦?
ln -sfn 會建立 current。依上面的步驟,服務先 enable,第一次部署才啟動;若第一次健康檢查失敗,沒有舊版可回復,腳本會嘗試停止服務並移除 current,以失敗狀態結束。
主機 IP 換了怎麼辦?
要一起更新 DNS、DEPLOY_HOST 和 DEPLOY_KNOWN_HOSTS。OCI 的 Reserved Public IP 可以保留,再指派給重建後的主機21,但固定 IP 不會保存 SSH host key。重建後若金鑰改變,仍須透過可信管道核對新的公鑰,再更新 DEPLOY_KNOWN_HOSTS;不要為了讓 workflow 通過而關掉檢查89。
資料來源
- 1. Managing environments for deployment
- 2. Deployments and environments
- 3. Using secrets in GitHub Actions
- 4. GitHub-hosted runners reference
- 5. Self-hosted runners
- 6. Adding self-hosted runners
- 7. Control the concurrency of workflows and jobs
- 8. sshd(8)
- 9. ssh-keyscan(1)
- 10. Sudoers Manual
- 11. Install Apache and PHP on an Ubuntu Instance
- 12. Best Practices for Your Compute Instance
- 13. Automatic HTTPS
- 14. Install
- 15. reverse_proxy (Caddyfile directive)
- 16. Keep Caddy Running
- 17. file_server (Caddyfile directive)
- 18. Scripts
- 19. systemd.service
- 20. About protected branches
- 21. Public IP Addresses
- 22. curl man page
- 23. flock manual
- 24. Disabling and enabling a workflow