albertshih.net 是一個用 Astro 產生的靜態網站,放在 Amazon S3,前面接 CloudFront。這篇記錄整個架構與每個選擇的理由。
架構總覽
GitHub 推送後由 GitHub Actions 透過 OIDC 取得臨時角色,把建置結果上傳到 S3;使用者經過 CloudFront 讀取,Route 53 與 ACM 負責網域和憑證。
| 元件 | 用途 | 為什麼選它 |
|---|---|---|
| Astro | 產生靜態頁面 | 內容以 Markdown 為主,建置出來就是純 HTML |
| S3(私有) | 存放網站檔案 | 不開靜態網站託管,只讓 CloudFront 透過 OAC 讀取 |
| CloudFront | CDN 與 HTTPS | 全球快取;用 CloudFront Function 處理 index.html 與 www 轉址 |
| ACM(us-east-1) | TLS 憑證 | CloudFront 只接受 us-east-1 的憑證 |
| Route 53 | DNS | 網域也在 Route 53 註冊,Alias 紀錄直接指向 CloudFront |
| GitHub Actions + OIDC | 自動部署 | 不在 GitHub 存放長期 Access Key |
| Lambda Function URL | 寫作後台的 GitHub 登入 | 只在登入時執行,幾乎零成本 |
部署流程
- 推送到
main - GitHub Actions 用 OIDC 換取臨時的 IAM 角色
astro build後用aws s3 sync上傳,HTML 不快取、其他檔案長期快取- 對 CloudFront 建立快取失效
學到的事
整個站從零到上線,真正花時間的不是寫網頁,而是下面這幾個「第一次部署才會發生」的坑。
1. GitHub 的 OIDC subject 不再只是 repo:owner/repo
第一次推送後,GitHub Actions 卡在 Could not assume role with OIDC: Not authorized to perform sts:AssumeRoleWithWebIdentity。IAM 角色的信任政策、OIDC provider 的 audience 都對,最後查 repo 的 OIDC 設定才發現:新的帳號預設改用「不可變 subject」,格式變成 repo:owner@<擁有者 ID>/repo@<repo ID>:ref:refs/heads/main,原本寫死的 repo:owner/repo:ref:refs/heads/main 當然比對不上。
我的做法是信任政策改用 StringLike,同時接受舊格式和帶 ID 的格式(ID 部分用萬用字元)。這樣不用在 template 裡寫死數字,將來 repo 改名重建也不會壞,同時仍然限定只有這個 repo 的 main 分支能拿到部署角色。
2. 最小權限要「跑一次、補一次」
我先替自己的 IAM 使用者寫了一份限定資源名稱的最小權限 policy,結果第一次部署就在建立 CloudFront distribution 時失敗,因為少了 cloudfront:ListTagsForResource。CloudFormation 在建立資源時會順手呼叫一些你沒想到的 API,沒辦法只靠讀 template 列全。
兩個副作用要知道:
- 失敗後 stack 會停在
ROLLBACK_COMPLETE,這個狀態不能更新,必須先刪掉重建。 Retain的 S3 bucket 在回滾時會留下來,下一次部署會多一個新的空 bucket。
我的結論是:最小權限不是一次寫對,而是讓部署失敗、讀錯誤訊息、補權限,重複幾次後把 policy 固定下來;部署完就把這份權限卸掉。
3. NoEcho 的參數留空,CloudFormation 不會告訴你
GitHub OAuth 的 client secret 是用 NoEcho 參數傳進 Lambda。我第一次用 read -s 讀 secret,卻是在沒有鍵盤輸入的環境執行,於是 secret 變成空字串,stack 還是顯示部署成功。直到後台登入時 GitHub 回 The client_id and/or client_secret passed are incorrect 才知道。
查的方式是讀 Lambda 的環境變數,但只看長度和格式(GitHub 的 secret 是 40 個十六進位字元),不把內容印出來。教訓有兩個:
- 部署成功只代表資源建好了,不代表設定是對的,要有一個能驗證的檢查。
- 機密要在自己的終端機輸入,不要經過會被記錄的地方。
4. 部署順序會決定使用者看到的是新站還是沒有樣式的頁面
Astro 的 CSS、JS 檔名帶雜湊,原本的流程是先用 --delete 同步 _astro/,再上傳 HTML。中間有一段時間,舊的 HTML 還在 CloudFront 快取裡,卻去要已經被刪掉的舊檔案,結果是 404、整頁沒有樣式。
修正後的順序是:先上傳新的資產(不刪)、再上傳頁面、建立快取失效並等它完成,最後才刪掉舊資產。這需要給部署角色多一個 cloudfront:GetInvalidation 權限,才能等失效完成。
5. 公開的 Lambda Function URL 要兩條權限
寫作後台的 GitHub 登入用 Lambda Function URL(AuthType: NONE)。lambda:InvokeFunctionUrl 之外,我另外加了一條 lambda:InvokeFunction,並限制成只能「經由 Function URL」呼叫。兩條都放進 template 之後,登入端點一開始就回正常的 302,沒有碰到 Forbidden;沒有加上這個限制的 lambda:InvokeFunction 則等於讓任何人都能直接呼叫函式,不要這樣寫。
6. 一些小地方,不處理就會在上線後才被發現
- 轉址會吃掉 query string:CloudFront Function 做 www 轉址和補斜線時,如果只用
uri組網址,?utm_source=...就消失了。要用querystring物件重組,並處理同名參數出現多次的情況。 - OAuth 的權限範圍:後台一開始要的是
repo,user,等於整個帳號所有私有 repo 的讀寫。拿掉用不到的user;repo 是私有的就必須留repo,只有公開 repo 才能降成public_repo。 - 載入第三方腳本要鎖版本:後台頁面拿得到有寫入權限的 token,卻是從 CDN 用浮動版本載入 CMS。我改成固定版本並加上 SRI,升級時要自己重算雜湊。
- 還沒填完的內容不要上線:在 CI 裡掃
dist/,只要還有方括號包起來的待填文字、空的社群連結這類佔位內容就讓部署失敗,比靠記憶可靠。 - CloudFormation template 盡量只用 ASCII:我在內嵌的 Lambda 程式碼裡放了一個「…」,Windows 上 AWS CLI 用 cp950 讀檔直接報解碼錯誤。
如果重來一次
我會先決定「什麼才算部署完成」:不只是 stack 變綠色,而是首頁、/admin、OAuth 端點、www 轉址、帶參數的連結都能用一條指令驗證完。這次這些檢查是出問題後才一項一項補上的。