DevOps

前言：Tags (173) 的紅燈海 打開 Jenkins 的 Multibranch Pipeline 頁面，映入眼簾的是一整排紅色叉叉——173 個 tag，幾乎全是失敗的歷史建置記錄。這些 tag 從 dev-0.0.74+143 一路排到 dev-0.0.74+181，光是同一個版本就堆了 39 個。 三個 repo（Flutter、Strapi、Vue）加起來超過 1000 個 tag。這不只是視覺上的噪音，更是 Jenkins 每次 scan 都要花時間處理的負擔。 核心觀念：Jenkins 上的 Tag 不是 Jenkins 的 第一個直覺可能是「到 Jenkins 上刪」，但這是錯的。 Jenkins Multibranch Pipeline 的運作方式是定期掃描 Git repository，把發現的 branch 和 tag 當作獨立的 pipeline 來建置。換句話說，Jenkins 頁面上看到的 tag 就是 Git remote 上的 tag——Jenkins 只是一面鏡子。 為什麼不能從 Jenkins 刪？ 因為即使你在 Jenkins UI 手動移除某個 tag 的建置記錄，下一次 scan 時 Jenkins 發現 remote 上 tag 還在，又會重新建立。要斬草除根，必須從 Git remote 下手。 ...

事發：部署成功但服務掛了 一次例行的 Strapi 後端部署，Jenkins build 成功、Docker image 推上 ECR、kubectl set image 也順利執行。但 rollout 等了 300 秒後超時。 以下是整個部署流程，可以看到問題出在最後一步： 具體的錯誤訊息： error: timed out waiting for the condition Jenkins 回報「部署失敗，已自動回滾」。奇怪的是，build 每一步都成功了，問題出在 rollout 階段。 調查：Pod 起不來的真正原因 問題排查的過程如下，從 pod 狀態開始一路追到節點層級： 查看 pod 狀態，發現新 pod 卡在 Pending，舊 pod 卡在 Terminating： $ kubectl get pods NAME READY STATUS AGE strapi-stg-5896c67c-kvrn2 0/1 Pending 88s strapi-stg-69f7c958b7-kcbc7 1/1 Terminating 44h web-stg-7bb99cfb54-x8j99 0/1 Pending 88s 直覺反應是看 pod events： $ kubectl describe pod strapi-stg-5896c67c-kvrn2 Events: Warning FailedScheduling 0/2 nodes are available: 1 node(s) had untolerated taint {node.kubernetes.io/unreachable: } 1 node(s) didn't match Pod's node affinity/selector 兩個節點都不能用。 一個 unreachable，另一個 node selector 不符（env=stg vs env=prod）。 ...

症狀：部署成功，程式碼卻是舊的 一個新功能已經 commit 並推上 Git，Jenkins pipeline 顯示建置成功、部署完成，Kubernetes Pod 也順利啟動。進入 Pod 檢查——程式碼還是舊的。 這不是網路延遲、不是 image pull policy、不是 tag 衝突。問題藏在 Dockerfile 裡一行看起來「很聰明」的快取優化。 背景知識：Docker 建置的關鍵概念 在進入除錯過程之前，先釐清幾個 Docker 建置中的核心概念： Docker Image 與 Layer（映像檔與分層） Docker 映像檔由多個唯讀的「層」（layer）堆疊而成。Dockerfile 裡的每一條指令（如 COPY、RUN）都會產生一層。Docker 會對每一層計算 hash，下次建置時如果指令和輸入都沒變，就直接重用該層——這就是 layer cache。 BuildKit BuildKit 是 Docker 18.09 之後引入的新一代建置引擎（透過 DOCKER_BUILDKIT=1 啟用）。相比傳統引擎，BuildKit 支援平行建置、更聰明的快取策略，以及本文主角——--mount=type=cache（cache mount）語法。 Cache Mount（--mount=type=cache） BuildKit 專有的功能。它在 RUN 指令執行期間，將一個持久化的目錄掛載到容器內的指定路徑。這個目錄由 BuildKit 管理，不會被寫入最終的 image layer，但內容會跨越不同次的 docker build 保留下來。常見用途是快取套件管理器的下載目錄（如 yarn cache），避免每次建置都重新下載。 Inline Cache 與 --cache-from 另一種 BuildKit 快取策略。透過 --build-arg BUILDKIT_INLINE_CACHE=1 把快取 metadata 嵌入產出的 image，再用 --cache-from 從遠端 registry 拉取。這讓不同機器（例如 CI runner）也能共享建置快取。 ...

問題：功能「先在後不在」 我們替 Strapi 後台新增了 MFA（Multi-Factor Authentication）雙因素認證功能。第一次部署到 STG 時一切正常——登入攔截、TOTP 驗證、QR Code 設定流程都運作良好。 但幾天後，因為其他功能的修改推了新的 git tag stg-1.24，部署流程順利完成，Jenkins 顯示綠燈——打開 STG 後台，MFA 的登入流程卻完全不見了。 沒有錯誤訊息、沒有 crash log，功能就這樣無聲無息地消失。 這比「功能從未出現」更令人困惑：明明之前部署是好的，程式碼也沒有人動過 MFA 相關的部分，為什麼會突然不見？ 調查過程：逐層排除 確認 Git Tag 內容 第一個直覺是——程式碼真的有被包進 tag 嗎？ # 確認 tag 指向的 commit 包含 MFA 程式碼 git show stg-1.24:src/index.ts | grep -i mfa 結果確認 src/index.ts 中有 import { registerMfaRoutes } from './mfa/controller'，src/mfa/ 目錄也完整存在。Git tag 本身沒問題。 檢查 Pod 內的實際檔案 既然 tag 正確，問題可能出在建置或部署階段。直接進到 Kubernetes Pod 裡看： # 進入 STG pod 檢查 kubectl exec -it deployment/strapi-stg -- sh # 檢查編譯後的檔案 ls dist/src/mfa/ # 結果：ls: dist/src/mfa/: No such file or directory # 檢查原始碼 ls src/mfa/ # 結果：ls: src/mfa/: No such file or directory MFA 相關檔案完全不存在於 Pod 中。 甚至連原始碼都沒有被複製進 Docker image。 ...

問題發生 在將 Production 環境複製到 Staging 環境後，發現 Strapi CMS 無法上傳圖片到媒體庫，畫面只顯示 Internal Server Error。 Strapi 是一個開源的 Headless CMS（無頭內容管理系統），可以讓開發者快速建立 API，並提供管理後台來管理內容。在這個專案中，我們使用 Strapi 搭配 AWS S3 來儲存上傳的圖片和檔案。 追查過程 第一步：查看 Kubernetes Logs 由於 Strapi 部署在 EKS（Elastic Kubernetes Service，AWS 的託管 Kubernetes 服務）上，我透過 kubectl 指令查看 Pod 的日誌： kubectl logs -f deployment/strapi-stg --tail=100 kubectl 是 Kubernetes 的命令列工具，用來與 Kubernetes 叢集互動。logs 指令可以查看容器的輸出日誌。 第二步：找到錯誤訊息 在日誌中發現關鍵錯誤： error: The bucket does not allow ACLs AccessControlListNotSupported: The bucket does not allow ACLs 這個錯誤訊息指出 S3 Bucket（AWS 的物件儲存服務中的儲存桶）不允許使用 ACL。 ...

問題現象：登入成功卻被拒於門外 最近在 Staging 環境遇到一個詭異的問題：使用者登入成功，拿到了有效的 JWT Token，但存取任何需要認證的 API 都回傳 401 Unauthorized。 # 登入成功，拿到 token POST /api/auth/local → 200 OK { "jwt": "eyJhbGc...xxxxx...your-jwt-token", "user": { "id": 1001, "email": "user@example.com" } } # 但存取個人資料失敗 GET /api/users/me → 401 Unauthorized Token 驗證通過、使用者存在、帳號未被封鎖。問題到底在哪？ 根本原因：遺失的 Link Table 經過一番追查，發現問題出在資料庫同步時漏掉了關聯表（Link Table）。 什麼是 Link Table？ 在關聯式資料庫中，多對多關係需要透過中間表來建立。這個中間表就是 Link Table（也稱為 Junction Table、Join Table、或 Pivot Table）。 使用者與角色的關係： 一個使用者可以有多個角色（User → Roles） 一個角色可以分配給多個使用者（Role → Users） 這是典型的多對多關係 各種 ORM 的 Link Table 命名 不同框架的 Link Table 命名慣例不同，但概念完全相同： ORM/Framework Link Table 範例 備註 Django user_groups, user_permissions 使用 _ 連接 Laravel role_user, permission_role 字母順序排列 TypeORM user_roles_role 較長的命名 Prisma _UserToRole 以 _ 開頭 Sequelize UserRoles 駝峰命名 問題的本質：資料不完整 當我們同步資料庫時，通常會注意主要的資料表： ...

前言：當建置一直紅燈 CI/CD pipeline 亮紅燈是開發日常，但連續遇到三個不同層面的問題，從 iOS codesigning、Android Gradle、到 Google Play API，這就值得記錄下來了。 這篇文章記錄我在同一天內遇到的三個建置失敗，以及逐步排除的過程。每個問題都有其獨特的根因，但也反映出 CI/CD 環境的複雜性。 問題一：iOS Keychain 解鎖失敗 症狀 Jenkins 建置在 iOS 階段失敗，錯誤訊息： [!] Error unlocking keychain at path: fastlane_keychain Command failed with exit status 51 macOS Keychain 運作機制 在深入問題之前，先了解 macOS Keychain 的運作方式： 關鍵概念： macOS 可以有多個 Keychain，每個都有獨立密碼 憑證必須在「已解鎖」的 Keychain 中才能被 codesign 使用 CI 環境通常會建立專用的 Keychain，避免影響系統 Keychain Fastlane Match 與 Keychain 的互動流程 調查過程 Exit status 51 代表「密碼錯誤」。SSH 進 Jenkins Mac mini 確認： ...

接手專案，先看帳單 因為老闆信用卡到期了要換新卡，我順便看了一下 AWS 帳單金額，發現比預期高。之前詢問外包商技術長（已離職），得到的回覆是：「服務都已經從新加坡遷移到台北了，除了 S3 有保留做備份，其他都刪除了。」 身為工程師，最不能接受的就是「應該是這樣」。我決定親自盤點。 名詞解釋 在繼續之前，先解釋一下會提到的 AWS 服務： 服務 說明 費用特性 S3 (Simple Storage Service) 物件儲存服務，用來存放檔案、圖片、影片 按儲存容量和請求次數計費 NAT Gateway 讓私有子網路的資源能存取網際網路 按小時計費，即使沒流量也要錢 Elastic IP 固定的公開 IP 位址 使用中免費，未關聯則收費 VPC (Virtual Private Cloud) 虛擬私有網路，隔離你的雲端資源 VPC 本身免費，但相關資源收費 Network Load Balancer 負載平衡器，分散流量到多台伺服器 按小時和處理的資料量計費 ECR (Elastic Container Registry) Docker 映像檔儲存庫 按儲存容量計費 重點是：有些資源即使沒有流量，只要存在就會收費。NAT Gateway 和未關聯的 Elastic IP 就是典型的「隱形殺手」。 盤點遺留資源 # 檢查 EKS 叢集（Kubernetes 服務） aws eks list-clusters --region ap-southeast-1 # 結果：空的 ✓ # 檢查 RDS（資料庫） aws rds describe-db-instances --region ap-southeast-1 # 結果：空的 ✓ # 檢查 NAT Gateway aws ec2 describe-nat-gateways --region ap-southeast-1 \ --filter "Name=state,Values=available" # 結果：2 個還在跑 完整盤點結果： ...

起因：老闆想省錢 「Staging 環境平常沒人用，每個月還要燒 $45-60 美金，能不能想辦法省一點？」 Staging 環境的成本來自兩個地方：RDS 資料庫（約 $15-20/月）和 EKS 節點（約 $30-40/月）。既然平常沒在用，我想到了一個方案：不用的時候關掉，需要的時候再打開。 於是我寫了兩個腳本： staging-start.sh：啟動 RDS、擴充節點、部署應用 staging-stop.sh：刪除部署、縮減節點、停止 RDS # staging-stop.sh 核心邏輯 kubectl delete deployment app-strapi-stg app-web-stg aws eks update-nodegroup-config \ --cluster-name my-cluster \ --nodegroup-name my-nodegroup \ --scaling-config minSize=0,maxSize=2,desiredSize=1 # 從 2 縮到 1 aws rds stop-db-instance --db-instance-identifier my-stg-rds 看起來很合理，但這裡有個問題：Production 和 Staging 共用同一個 nodegroup。 踩坑：AWS 隨機選擇刪除節點 執行 staging-stop.sh 縮減節點時，AWS 會隨機選擇要終止哪個節點。當時的配置： 節點 A：運行 Production pods 節點 B：運行 Staging pods 我期望刪除節點 B，但 AWS 選了節點 A。Production pods 被強制遷移，觸發了重新調度。 ...

前言：當 Build Failed 成為日常 在過去的 19 個小時裡，我經歷了 15 次 build failed，產生了 15 個 fix commits。如果你覺得這很誇張，讓我告訴你更誇張的：最後一個 bug 是 git describe 在多個 tag 指向同一 commit 時會隨機返回其中一個。 是的，隨機。在 CI/CD Pipeline 裡。 這篇文章完整記錄這場除錯馬拉松，從最初的 Fastlane 版本問題，到 Discord 通知功能的實作與修復，再到 Ruby 相容性地獄，最後揭開 git 鮮為人知的行為。泡杯咖啡，這會是一段旅程。 第一章：Fastlane 與 Bundler 的糾葛 問題 1：Fastlane 版本不一致 Commit: fix(jenkins): use bundle exec for fastlane to ensure version consistency Jenkins 機器上有全域安裝的 Fastlane，但版本與 Gemfile.lock 指定的不同。這導致某些 action 行為不一致。 // Before: 使用全域 fastlane sh 'fastlane ios build' // After: 透過 Bundler 執行，確保版本一致 sh 'bundle exec fastlane ios build' 學習：在 CI 環境中，永遠使用 bundle exec 執行 Ruby 工具，確保版本與 lockfile 一致。 ...