Strapi

症狀：資料明明在，前端就是拿不到 一個 CMS 系統的文件列印預覽，每份文件 header 都固定顯示「上傳者：—」。DB 裡明明有資料，API 回 HTTP 200 OK，回應裡的其他欄位（日期、文件類型、附件）都對——唯獨 uploadedBy 是 null。 沒錯誤、沒警告，伺服器 log 也乾淨。前端碰到 uploadedBy?.realName || '-' 就乖乖畫 dash。使用者以為這份文件沒指派擁有者，作者本人以為畫面壞了。大家都錯，但系統看起來好好的。 這是最難纏的 bug——靜默失敗。 先看 ORM 層在整個架構哪裡 要理解為什麼這類 bug 發生、也為什麼解法是「繞過 ORM」，先把架構分層看清楚： 為什麼 bug 只會發生在 ORM 層？ 上面的業務邏輯只負責說「給我文件，順便帶上傳者」——它不知道要怎麼 JOIN。下面的 DB 只回應被問到的 SQL——你沒 SELECT 的欄位它不會主動給你。只有 ORM 層有權力決定「要翻譯成什麼 SQL」，也只有它遇到不會處理的組合時，會選擇「悄悄回你 null」而不是「拋錯給你看」。 這就是為什麼靜默失敗只會出現在這一層。 用 curl 逼它露餡 把 query 簡化到只剩 filter + populate 兩件事，一個一個比對： # A: 用 id filter → 關聯欄位變 null ❌ curl "$URL?filters[owner][id][\$eq]=3807&populate[uploadedBy]=true" # { "uploadedBy": null } # B: 用 documentId filter → 關聯正常回來 ✅ curl "$URL?filters[owner][documentId][\$eq]=abc123&populate[uploadedBy]=true" # { "uploadedBy": { "id": 85, "realName": "J. Chen" } } 同樣的 populate、同樣的文件集合，差別只在「怎麼辨認 owner」。這種事應該是 ORM 內部細節，對使用者不該有差。但就是有。 ...

Symptom: A Relation Everyone Believes Is Empty A document management print preview kept rendering “Uploader: —” for every report. The database had the data. The API returned HTTP 200 OK. Yet the uploadedBy relation came back as null, with no error or warning anywhere. Users assumed reports had no uploader assigned. Authors assumed the UI was broken. Nobody suspected the API, because it was perfectly silent. Where the Bug Lives in the Stack Before the curl session, it helps to fix where the failure happens: ...

問題現場：一個「成功」卻收不到信的忘記密碼 某個週一下午，QA 回報：在一個 Flutter + Strapi 架構的 App 上，用測試帳號 testuser@example.com 點「忘記密碼」，畫面跳出 Success: Reset password link sent successfully on your email account.，但信箱（包含垃圾郵件匣）一封信都沒有。 直覺先排除幾個明顯可能：SMTP 設定壞掉、用戶被 block、信件被 Gmail 擋。但真正的答案比這些都有趣 — 這不是 bug，是 Strapi 一個刻意的安全設計，只是 App 前端把它翻譯錯了。 kubectl 診斷：20ms 與 800ms 的兩種人生 進 Strapi pod 撈 log，找 forgot-password 請求： kubectl logs -n default strapi-prod-xxxxxxxxx-xxxxx --since=6h \ | grep -E 'forgot-password|Reset password URL' 抽出的關鍵幾行： 04:04:52 info: Reset password URL generated: https://example.com/... 04:04:53 http: POST /api/auth/forgot-password (948 ms) 200 05:15:44 http: POST /api/auth/forgot-password (20 ms) 200 05:16:53 info: Reset password URL generated: https://example.com/... 05:16:54 http: POST /api/auth/forgot-password (664 ms) 200 05:17:30 http: POST /api/auth/forgot-password (26 ms) 200 一眼看出兩種節奏：800ms 級別的請求伴隨「Reset password URL generated」log，而 20-30ms 的請求則完全沒有。同一支 API，為什麼耗時差 30 倍？ ...

症狀：選完手機照片，畫面卻還是貼圖 使用者回報的步驟很簡單：點頭像 → 選「從手機圖庫」→ 選張照片 → 儲存。跳回會員中心，頭像還是原本的系統貼圖。 再點進去編輯頁，看到的又是手機照片。明明存成功了，為什麼 UI 顯示不一致？ 這個 bug 表面上是前端畫面問題，但用 log 逼出來的真相，藏在三層之外——包括一個會在幾乎所有 admin-panel 型後端都出現的經典陷阱。 偵錯：跟著 log 走，別信錯誤訊息 第一步是打開前端 log 重現流程。關鍵幾行： StickerService -> Deactivating all stickers StickerService -> Error: status code of 403 StickerService -> Error Response: {status: 403, message: Forbidden} StickerService -> Deactivate all failed: You do not own this sticker 最後這句「You do not own this sticker」幾乎讓我停在錯誤方向——去查使用者到底擁有哪幾個貼圖。但翻前端程式碼才發現：那不是後端回的訊息，是前端 _handleDioError 把「403 Forbidden」硬翻譯成這句。 **這是第一個教訓：HTTP 狀態碼與文字訊息之間的語意對應是會說謊的。**真正的錯誤只有一個字——Forbidden。跟 ownership 無關，純粹是權限問題。 第一層根因：Admin Panel 的權限設定漂移 翻 Strapi admin → Settings → Users & Permissions → Roles → Authenticated → Sticker section，發現 deactivateAll 這支 route 的權限沒勾。 ...

症狀：App 開啟 15 分鐘後被強制登出 使用者回報一個詭異的問題：App 正常使用一段時間後，突然被強制登出。重新登入後又好了，但過一陣子又被踢出去。 時間規律很明確——正好 15 分鐘。這恰好是我們 JWT 的過期時間。 直覺反應是去查前端的 token refresh 邏輯：interceptor 有沒有正確攔截 401？refresh token 有沒有正確儲存？重試機制有沒有 bug？ 查了一輪，全部正常。 錯誤的除錯方向 這個問題前前後後花了不少時間，方向一直在前端打轉： 排查方向 結果 Flutter interceptor 邏輯 正常，有攔截 401 並觸發 refresh Token 儲存機制（SecureStorage） 正常，refresh token 有正確保存 JWT 過期時間設定 確認是 15 分鐘，符合預期 網路連線問題 排除，其他 API 都正常 每個環節看起來都沒問題，但結果就是 refresh 失敗。問題出在哪？ 轉折點：看 HTTP Status Code 直到有人（或者說，終於有人）去看了 /auth/refresh 實際回傳的 HTTP status code： # JWT 過期後呼叫 refresh curl -X POST https://api.example.com/api/auth/refresh \ -H "Content-Type: application/json" \ -d '{"refreshToken": "valid-refresh-token-here"}' # 預期：200 OK（新的 JWT） # 實際：403 Forbidden 403，不是 401。 ...

問題發生 在將 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。 ...

前言：一個看似簡單的需求 需求很單純：讓 Email 驗證信中的連結顯示前端網址（www.example.com），而不是後台網址（api.example.com）。這樣用戶不會看到內部系統架構。 外包商寫了這段程式碼： // ❌ 看起來合理，但完全沒效果 plugin.services.user.sendConfirmationEmail = async function(user) { // 自訂邏輯... } 部署後，Email 中的連結依然指向後台。為什麼？ 問題根源：Factory Function 陷阱 翻開 Strapi 原始碼，發現 plugin.services.user 不是一個物件，而是一個 factory function： // Strapi 內部實作（簡化版） plugin.services.user = (context) => { return { sendConfirmationEmail: async (user) => { /* 原始邏輯 */ }, // 其他方法... } } 這意味著什麼？ 每次 Strapi 需要 user service 時，它會呼叫這個 factory function 來取得一個新的 service 實例。你直接覆蓋 sendConfirmationEmail 屬性，等於在一個 function 物件上加屬性——factory 被呼叫時根本不會讀取這個屬性。 不這樣理解會怎樣？ 你會像外包商一樣，花兩天 debug 卻找不到原因，因為程式碼完全沒有報錯，只是靜靜地被忽略。 解決方案：Factory Wrapper 模式 正確的做法是包裝原本的 factory function： // ✅ Factory Wrapper 模式 const originalUserServiceFactory = plugin.services.user; plugin.services.user = (context) => { // 先取得原始 service 實例 const originalUserService = originalUserServiceFactory(context); return { ...originalUserService, // 保留所有原始方法 // 覆寫特定方法 async sendConfirmationEmail(user) { // 你的自訂邏輯 const confirmationUrl = `${FRONTEND_URL}/verifyEmail`; // ... }, }; }; 為什麼這樣有效？ ...

接手專案，先看帳單 因為老闆信用卡到期了要換新卡，我順便看了一下 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 個還在跑 完整盤點結果： ...

前言：當 Banner 在眾目睽睽下消失 如果你曾經盯著一個「昨天還好好的」功能，然後花了幾小時才發現問題根本不在你想的地方——恭喜你，你已經正式成為資深工程師了。 這次的主角是一個 Flutter App 的首頁輪播 Banner。用戶回報說「Banner 不見了」，而我的第一反應是：「一定是最近的 commit 搞壞的！」 （劇透：不是。） 第一階段：追蹤嫌疑犯 嫌疑人一號：最近的 Git Commit 最近剛好有一個 commit 修改了後端的 middleware，用來處理認證相關的端點。自然而然，我先從這裡開始查： git show abc123 # fix: add middleware to strip auth header for public endpoints 看起來這個 middleware 只處理 /api/auth/forgot-password 這類認證端點，跟 Banner API 完全無關。 結論：無罪釋放。 嫌疑人二號：Strapi 權限設定 接下來檢查 Strapi Admin 的權限設定。Public 角色的 app-home-page 權限： 角色 find 權限 Authenticated ✅ 已開啟 Public ✅ 已開啟 權限設定完全正確。 結論：也不是兇手。 第二階段：真相大白 測試 REST API 直接用 curl 測試 REST API： ...

引言：一個技術選型的起點 2024 年 6 月，我坐在會議室裡，面對著老闆和行銷總監，準備報告我對公司新系統 CMS 的技術選型建議。這不是一個輕鬆的決定——選錯了，可能浪費數百萬的開發成本；選對了，能為公司省下可觀的人力支出。 經過數週的研究與分析，作為一個架構規劃師同時也是技術決策者，我最終選擇了 Strapi 作為我們的 Headless CMS 解決方案。這篇文章將分享我的決策過程、考量因素，以及最重要的——這個選擇如何為公司省下大筆預算。 什麼是 Headless CMS？ 在深入 Strapi 之前，先理解 Headless CMS 的核心概念。 傳統 CMS vs Headless CMS 傳統 CMS 將前端與後端緊密耦合，網站的外觀和內容管理綁在一起。而 Headless CMS 則專注於內容管理和 API 提供，讓前端團隊可以使用任何技術框架來消費這些 API。 Headless CMS 的核心優勢 特性 傳統 CMS Headless CMS 前後端耦合 緊密耦合 完全分離 前端技術選擇 受限於 CMS 模板 任意框架（Vue、React、Flutter） 多平台支援 僅限網頁 Web、App、IoT 皆可 擴展性 中等 極高 API 優先 否 是 為什麼選擇 Strapi？三大核心原因 原因一：前後端完全分離 Strapi 作為 Headless CMS，天生就是為了前後端分離而設計。這意味著： ...