Strapi

症狀：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，天生就是為了前後端分離而設計。這意味著： ...

故事的開始：會員資料集體消失事件 最近收到許多會員的反映，問題驚人地一致： 📝 「我的日記資料不見了！」 👤 「帳號被自動登出，要重新登入」 ⏳「App 一直轉圈圈，什麼都看不到」 😰 「重新開啟 App 也一樣，資料都不見了」 更詭異的是，這些問題似乎沒有規律性，有的使用者正常，有的使用者卻深受其擾。身為技術負責人，這讓我立刻警覺：這不是資料遺失，而是認證機制出問題了。 調查過程：抽絲剝繭找出真相 問題時間軸 第一步：確認資料庫完整性 我的第一個懷疑是資料庫是否真的遺失資料。登入後台查詢，發現： ✅ 關鍵發現： 所有會員的日記資料都完好無缺 這代表問題不在資料層，而是在存取權限上。 第二步：檢查使用者行為模式 整理會員回報的時間點，我發現一個規律： 會員 註冊時間 問題發生時間 間隔 會員 A 30 天前 今天 30 天 會員 B 29 天前 今天 29 天 會員 C 3 天前 正常使用 - 關鍵字：30 天 ⚡ 第三步：檢查 JWT Token 配置 翻開 Strapi 後端的配置檔，真相大白： // Strapi 預設 JWT 設定 jwt: { expiresIn: '30d' // Token 有效期：30 天 } 問題根本原因 💡 關鍵洞察： 使用者以為資料不見了，實際上只是「看不到」而已。資料仍安全地存在資料庫中，只是 Token 過期導致無法存取。 ...

「老闆，用戶的解鎖記錄全不見了！」「快把舊資料拉出來灌回去！」在緊急狀況下，我沒想太多就照做了。然後，我不小心埋下了一顆定時炸彈… 🔥 第一幕：災難降臨 2025 年 11 月某日，上午 10:30 Slack 突然炸開： 💬 同事：「完蛋了…我剛剛不小心部署到舊的 commit…」 💬 QA：「欸！為什麼使用者的動畫解鎖記錄都不見了？」 💬 使用者：「我昨天才花金幣解鎖的動畫怎麼不見了？」 💬 老闆：「@所有人 立刻確認影響範圍！」 我打開資料庫一看： SELECT COUNT(*) FROM user_unlocked_animations; -- 結果: 0 😱 所有用戶的解鎖記錄全部消失！ 原因：同事不小心部署了一個舊的 Strapi commit，那個版本的 database migration 把 user_unlocked_animations 相關的表全部清空了。 ⚡ 第二幕：老闆的緊急命令 💬 老闆：「快！把之前的用戶解鎖記錄拉出來，灌回現在的資料庫！」 我心裡想：「舊資料插回去，新資料又同時在進來…會不會有問題？」 但老闆在等，使用者在抱怨，沒時間多想，先恢復資料再說。 緊急恢復資料 // 從備份拉出資料，直接插入（包含原始的 ID） blablablabla } // ⚠️ 直接指定了 id，但沒想到要更新 sequence... 執行完畢： ✅ 資料恢復完成！ QA 測試：「使用者的解鎖記錄都回來了！」 眾人鬆了一口氣。 💣 第三幕：24 小時後，炸彈引爆 隔天下午 💬 客服：「有使用者回報說無法解鎖動畫!!!」 💬 使用者：「我有 3 個金幣，想解鎖動畫，但一直顯示錯誤！金幣被扣了但動畫沒解鎖！」 ...

前言：編輯器與前端的排版不一致之謎 在開發多平台醫療健康應用時，我們採用了現代化的技術棧： 後端 CMS：Strapi v5.15.1（Headless CMS） 前端框架：Vue.js 3 富文本編輯器：CKEditor 5 資料傳輸：GraphQL API 這個組合在大多數情況下運作良好，編輯者可以在 Strapi 後台使用 CKEditor 輕鬆編輯富文本內容，前端 Vue.js 應用透過 GraphQL 獲取並渲染這些內容。 然而，我們遇到了一個令人困惑的問題： 在 Strapi 後台使用 CKEditor 精心排版的水平並排圖片，到了前端網頁卻變成了垂直排列。 這個問題不僅影響了內容的視覺呈現，也破壞了編輯者的排版意圖。更重要的是，這讓非技術背景的內容編輯者感到困惑：「為什麼我在後台看到的排版，到了網站上就變了？」 這篇文章將深入探討這個問題的根本原因，並提供系統性的解決方案。 問題現象與環境說明 內容流程架構 我們的內容從編輯到展示的完整流程如下： 問題的具體表現 預期行為： 在 Strapi CKEditor 後台，編輯者將兩張圖片設定為水平並排： <!-- CKEditor 生成的 HTML 結構 --> <figure class="image" style="float:left"> <img src="/uploads/image1.webp" alt="圖片1"> <figcaption>圖片1說明</figcaption> </figure> <figure class="image" style="float:left"> <img src="/uploads/image2.webp" alt="圖片2"> <figcaption>圖片2說明</figcaption> </figure> 實際現象： 前端 Vue.js 渲染後，圖片變成垂直排列： 兩張圖片沒有並排顯示，而是一張接著一張垂直堆疊。 技術環境詳情 Strapi CKEditor 配置（config/schema.json）： { "kind": "collectionType", "collectionName": "articles", "info": { "singularName": "article", "pluralName": "articles", "displayName": "文章" }, "attributes": { "title": { "type": "string" }, "content": { "type": "customField", "options": { "preset": "defaultHtml" }, "customField": "plugin::ckeditor5.CKEditor" } } } Vue.js 前端渲染組件（ServiceDetailView.vue）： ...

前言：那個令人抓狂的錯誤訊息 在開發前後端分離的 Web 應用時，幾乎每位工程師都曾遇過這個令人頭痛的錯誤： Access to fetch at 'http://localhost:1337/api/auth/local' from origin 'http://localhost:5173' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. 這個錯誤通常發生在最關鍵的時刻： 前端登入功能即將完成，卻無法呼叫後端 API 串接第三方服務時，資料無法正常取得 部署到測試環境後，原本運作正常的功能突然失效 CORS（Cross-Origin Resource Sharing，跨來源資源共用）是現代 Web 開發中的核心安全機制，但也是許多開發者的痛點。這篇文章將從基礎原理到實戰應用，帶你完整理解 CORS 的運作方式，並提供實際可用的解決方案。 為什麼需要 CORS？從同源政策說起 同源政策的誕生 在理解 CORS 之前，我們需要先認識「同源政策」（Same-Origin Policy, SOP）。這是瀏覽器最基本的安全機制，在 1995 年 Netscape Navigator 2.0 引入 JavaScript 時就已經存在。 同源政策的目的：防止惡意網站讀取另一個網站的敏感資料。 想像一個情境：你登入了網路銀行（https://bank.com），此時你的瀏覽器保存了銀行的登入 Cookie。如果沒有同源政策，當你不小心訪問了一個惡意網站（https://evil.com），該網站的 JavaScript 就能透過你的瀏覽器向 https://bank.com 發送請求，並讀取你的帳戶資料。 同源政策阻止了這種攻擊：https://evil.com 的 JavaScript 無法讀取 https://bank.com 的回應內容。 什麼是「同源」？ 兩個 URL 被視為同源，必須滿足以下三個條件： ...