會員資料不見？這不是我沒要求，是外包商沒做完整的 OAuth 2.0

故事的開始：會員資料集體消失事件

最近收到許多會員的反映，問題驚人地一致：

• 📝 「我的日記資料不見了！」
• 👤 「帳號被自動登出，要重新登入」
• ⏳「App 一直轉圈圈，什麼都看不到」
• 😰 「重新開啟 App 也一樣，資料都不見了」

更詭異的是，這些問題似乎沒有規律性，有的使用者正常，有的使用者卻深受其擾。身為技術負責人，這讓我立刻警覺：這不是資料遺失，而是認證機制出問題了。

調查過程：抽絲剝繭找出真相

問題時間軸

gantt
    title 問題調查時程
    dateFormat HH:mm
    section 發現問題
    接獲使用者回報    :a1, 00:00, 30m
    section 初步調查
    檢查資料庫完整性  :a2, 00:30, 20m
    分析回報時間規律  :a3, 00:50, 30m
    section 深入分析
    檢查 JWT 配置     :a4, 01:20, 15m
    確認根本原因      :a5, 01:35, 10m

第一步：確認資料庫完整性

我的第一個懷疑是資料庫是否真的遺失資料。登入後台查詢，發現：

✅ 關鍵發現： 所有會員的日記資料都完好無缺

這代表問題不在資料層，而是在存取權限上。

第二步：檢查使用者行為模式

整理會員回報的時間點，我發現一個規律：

關鍵字：30 天 ⚡

第三步：檢查 JWT Token 配置

翻開 Strapi 後端的配置檔，真相大白：

// Strapi 預設 JWT 設定
jwt: {
  expiresIn: '30d'  // Token 有效期：30 天
}

問題根本原因

flowchart TD
    A[使用者開啟 App] --> B{Token 有效?}
    B -->|有效| C[正常顯示資料]
    B -->|過期| D[API 請求被拒 401]
    D --> E[App 顯示轉圈圈]
    E --> F[最終強制登出]
    F --> G[使用者看不到資料]

    style D fill:#f96,stroke:#333,color:#000
    style F fill:#f96,stroke:#333,color:#000
    style G fill:#f96,stroke:#333,color:#000

💡 關鍵洞察： 使用者以為資料不見了，實際上只是「看不到」而已。資料仍安全地存在資料庫中，只是 Token 過期導致無法存取。

合約檢視：外包商其實該做的事

在確認 Token 過期是問題根源後，我突然想起一件事：

「當初的開發規格書裡，有沒有要求 Token 管理機制？」

翻開合約文件

我打開當初簽訂的《IT 系統設計規格書》，在第 15 頁「共通性要求」找到了這一句：

- OAuth 2.0 (for 第三方登入 / Apple Health & Google Fit)

等等… OAuth 2.0？

OAuth 2.0 標準包含什麼？

flowchart TD
    A[OAuth 2.0 標準規範] --> B[Authorization Code Flow]
    A --> C[Access Token 管理]
    A --> D[Refresh Token 機制 ⭐]
    A --> E[Token 自動更新邏輯]
    A --> F[Token 過期處理]

    D --> G[這就是「記住我」功能！]

    style D fill:#ffa,stroke:#f66,stroke-width:3px,color:#000
    style G fill:#afa,stroke:#6f6,stroke-width:3px,color:#000

合約要求 vs 實際交付

OAuth 2.0 完整實作 vs 外包商交付

sequenceDiagram
    participant User as 使用者
    participant App as App
    participant OAuth as OAuth Provider

    Note over User,OAuth: ✅ 外包商有做的部分

    User->>App: 點擊「LINE 登入」
    App->>OAuth: 授權請求
    OAuth-->>App: Authorization Code
    App->>OAuth: 用 Code 換 Token
    OAuth-->>App: Access Token

    Note over User,OAuth: ❌ 外包商沒做的部分（OAuth 2.0 標準要求）

    OAuth-->>App: Refresh Token (缺失！)

    Note over App: 15 分鐘後...

    App->>OAuth: 用 Refresh Token 刷新 (缺失！)
    OAuth-->>App: 新的 Access Token (缺失！)

    rect rgb(255, 200, 200)
    Note over User: 結果：Token 過期後被登出 ❌
    end

技術規格解讀

根據 OAuth 2.0 標準（RFC 6749），完整的實作應該包含：

1. Authorization（授權） → ✅ 外包商有做

使用者透過第三方（LINE/Google）授權

2. Token Issuance（發放 Token） → ⚠️ 外包商只做一半

應返回：Access Token + Refresh Token
實際只返回：Access Token

3. Token Refresh（刷新 Token） → ❌ 外包商沒做

應該：自動用 Refresh Token 換新 Access Token
實際：無此機制，Token 過期就登出

這不是新需求，是合約範圍內

flowchart LR
    A[合約要求:<br/>OAuth 2.0] --> B{OAuth 2.0<br/>標準包含?}
    B -->|是| C[Refresh Token<br/>機制]
    B -->|是| D[Token 自動更新]
    B -->|是| E[記住登入狀態]

    C --> F[外包商應該做]
    D --> F
    E --> F

    F --> G{實際交付?}
    G -->|否| H[❌ 交付不完整]

    style H fill:#faa,stroke:#f66,stroke-width:3px,color:#000

💡 重要發現： 這不是我「沒有要求」，而是外包商「沒有完整實作 OAuth 2.0」。

為什麼外包商可能省略了 Refresh Token？

可能原因分析：

1. 知識不足

   • 誤以為 OAuth 2.0 只是「第三方登入」
   • 不了解完整的 Token 管理機制

2. 簡化實作

   • Refresh Token 需要額外的後端邏輯
   • 想節省開發時間

3. 驗收不嚴謹

   • 驗收時只測試「能登入」
   • 沒有測試「長期使用」的情境

4. 溝通不良

   • 規格書寫「OAuth 2.0」但沒有詳細展開
   • 雙方對技術理解有落差

緊急處理：治標不治本的應急方案

時間壓力下的決策

由於外包商開發的 App 還需要重新開發並送審（iOS 審核通常要 1-2 週），我必須立即止血。

flowchart LR
    A[發現問題] --> B[評估修復時間]
    B --> C{能快速修復?}
    C -->|否| D[緊急方案: 延長 Token]
    C -->|是| E[正式修復]
    D --> F[爭取開發時間]
    F --> E

    style D fill:#ffa,stroke:#333,color:#000

緊急方案：延長 Token 有效期

// config/server.ts
jwt: {
- expiresIn: '30d'   // 原本：30 天
+ expiresIn: '90d'  // 緊急調整：90 天（3 月）
}

這個方案的利弊分析

⚠️ 重要提醒： 這只是暫時的應急措施，不是長期解決方案。

長期方案探討：如何根治 Token 過期問題

緊急處理後，我開始思考長期解決方案。核心問題是：

如何在 Token 過期時，讓使用者無感知地繼續使用 App？

技術方案決策樹

flowchart TD
    A[Token 過期問題] --> B{修改後端?}
    B -->|願意| C[Refresh Token 機制]
    B -->|不願意| D{儲存密碼?}
    D -->|可以| E[自動重新登入]
    D -->|不行| F[延長 Token 有效期]

    C --> G[業界標準方案 ✅]
    E --> H[折衷方案 ⚠️]
    F --> I[臨時方案 ❌]

    style C fill:#afa,stroke:#333,color:#000
    style E fill:#ffa,stroke:#333,color:#000
    style F fill:#faa,stroke:#333,color:#000

方案一：Refresh Token 機制（業界標準）

運作原理

sequenceDiagram
    participant User as 使用者
    participant App as App
    participant API as Strapi API
    participant DB as 資料庫

    User->>App: 登入
    App->>API: POST /auth/login
    API->>DB: 驗證帳密
    DB-->>API: 驗證成功
    API-->>App: Access Token + Refresh Token

    Note over App: 15 分鐘後...

    App->>API: GET /courses (Access Token)
    API-->>App: 401 Unauthorized

    App->>API: POST /auth/refresh (Refresh Token)
    API-->>App: 新的 Access Token

    App->>API: GET /courses (新 Token)
    API-->>App: 課程資料
    API-->>User: 顯示課程（使用者無感知）

Token 生命週期狀態圖

stateDiagram-v2
    [*] --> Active: 登入成功
    Active --> NearExpiry: 剩餘 < 5 分鐘
    NearExpiry --> Refreshing: 自動刷新
    Refreshing --> Active: 刷新成功
    Refreshing --> Expired: 刷新失敗
    Active --> Expired: 超過有效期
    Expired --> [*]: 需重新登入

Strapi 內建支援

令我驚喜的是，Strapi v5.15.1 已經內建完整的 Refresh Token 系統！

// config/plugins.ts
"users-permissions": {
  config: {
    jwtManagement: 'refresh',  // ✨ 啟用 refresh token 模式
    sessions: {
      accessTokenLifespan: 3600,        // 1 小時
      maxRefreshTokenLifespan: 2592000, // 30 天
      idleRefreshTokenLifespan: 604800, // 7 天
      httpOnly: true,                    // HTTP-Only Cookie
    }
  }
}

方案評估

方案二：Token 快過期前自動更新

核心概念

在 Token 快過期前（例如剩餘 1 天），App 在背景自動用儲存的密碼重新登入，取得新 Token。

flowchart TD
    A[定期檢查 Token] --> B{剩餘天數?}
    B -->|> 1 天| C[繼續使用]
    B -->|< 1 天| D[背景自動登入]
    D --> E{登入成功?}
    E -->|是| F[更新 Token]
    E -->|否| G[提示重新登入]
    F --> C

    style D fill:#afa,stroke:#333,color:#000
    style F fill:#afa,stroke:#333,color:#000
    style G fill:#faa,stroke:#333,color:#000

Token 自動更新流程

sequenceDiagram
    participant Timer as 定時器
    participant Manager as Token 管理器
    participant Storage as 本地儲存
    participant API as Strapi API

    Note over Timer: 每小時檢查一次

    Timer->>Manager: 檢查 Token 有效期
    Manager->>Manager: 計算剩餘天數

    alt 剩餘 < 1 天
        Manager->>Storage: 讀取加密憑證
        Storage-->>Manager: 帳號密碼
        Manager->>API: POST /auth/login
        API-->>Manager: 新的 JWT
        Manager->>Storage: 儲存新 Token
        Note over Manager: ✅ 更新成功，使用者無感知
    else 剩餘 >= 1 天
        Note over Manager: ✅ 繼續使用現有 Token
    end

完整生命週期

第 1 天：登入成功，Token 有效期 30 天
         └─> 加密儲存憑證
         └─> 啟動定時檢查

第 2-28 天：正常使用
         └─> 每小時檢查：剩餘天數 > 1 天 ✅

第 29 天凌晨 3:00：
         └─> 檢查：剩餘天數 < 1 天 ⚠️
         └─> 背景自動登入
         └─> 更新 Token（重新計時 30 天）
         └─> 使用者完全無感知 ✅

第 30-58 天：繼續正常使用...

使用者控制權

App 應該提供「記住我」選項，尊重使用者隱私：

┌─────────────────────────────┐
│  登入                        │
├─────────────────────────────┤
│  帳號: user@example.com      │
│  密碼: ********              │
│                             │
│  ☑ 記住我（自動保持登入）       │
│                             │
│  [ 登入 ]                    │
└─────────────────────────────┘

方案評估

兩種方案深度比較

安全性對比

flowchart LR
    subgraph 自動重新登入
    A1[儲存加密密碼] --> B1{裝置被破解?}
    B1 -->|是| C1[密碼外洩風險 ⚠️]
    B1 -->|否| D1[相對安全 ✅]
    end

    subgraph Refresh Token
    A2[只儲存 Token] --> B2{Token 外洩?}
    B2 -->|是| C2[可立即撤銷 ✅]
    B2 -->|否| D2[安全 ✅]
    end

情境比較

情境一：使用者變更密碼

sequenceDiagram
    participant User as 使用者
    participant WebApp as 網頁端
    participant MobileApp as 手機 App
    participant Server as 伺服器

    User->>WebApp: 變更密碼
    WebApp->>Server: 更新密碼

    Note over MobileApp,Server: 方案 A：自動重新登入

    MobileApp->>Server: 自動登入（舊密碼）
    Server-->>MobileApp: ❌ 401 錯誤
    MobileApp-->>User: 請重新登入

    Note over MobileApp,Server: 方案 B：Refresh Token

    MobileApp->>Server: 使用 Refresh Token
    Server-->>MobileApp: ✅ 新 Access Token
    Note over User: 完全無感知

情境二：帳號安全問題

情境三：第三方登入

LINE 登入流程：

自動重新登入方案：
使用者點擊「LINE 登入」
↓
沒有帳號密碼可以儲存 ❌
↓
Token 過期時：
  → 只能重新點擊「LINE 登入」
  → 使用者需要手動操作

Refresh Token 方案：
使用者點擊「LINE 登入」
↓
返回 Access Token + Refresh Token ✅
↓
Token 過期時：
  → 自動使用 Refresh Token 更新
  → 使用者完全無感知

最終比較表

勝負分數：Refresh Token 8 勝，自動重新登入 2 勝

我的最終決策：分階段實施

經過深思熟慮，我決定採取兩階段策略：

gantt
    title 實作時程規劃
    dateFormat YYYY-MM-DD
    section 緊急處理
    延長 Token 至 90 天     :done, phase1, 2025-12-01, 1d
    section 正式方案
    後端啟用 Refresh Token   :active, phase2a, 2025-12-07, 5d
    前端實作自動刷新        :active, phase2b, 2025-12-12, 5d
    整合測試               :phase2c, 2025-12-17, 3d
    灰度發布（10% 使用者）  :phase2d, 2025-12-20, 3d
    全量上線               :phase2e, 2025-12-23, 1d

為什麼選擇 Refresh Token？

1. 長期來看更安全、更穩定

   • 符合 OAuth 2.0 標準
   • 可撤銷、可追蹤

2. 支援所有登入方式

   • 帳號密碼：✅
   • LINE 登入：✅
   • Google 登入：✅

3. 為未來功能打下基礎

   • 多裝置管理
   • 遠端登出
   • 安全性通知

4. 使用者體驗最佳

   • 完全無感知的 token 更新
   • 密碼變更不影響使用

實作計畫

Week 1：後端開發

• 啟用 Strapi Refresh Token 配置
• 更新自訂登入端點（LINE/Google）
• 實作 /auth/refresh endpoint
• 測試 token 刷新流程

Week 2：前端開發

• 實作 Token 管理器
• 實作自動刷新邏輯（快過期前主動刷新）
• 整合到現有認證流程
• 處理 refresh 失敗情境

Week 3：測試與上線

• 內部測試（QA 團隊）
• 灰度發布（10% 使用者）
• 監控錯誤率和使用者回饋
• 全量上線

寫在最後：技術債與外包管理的教訓

這次事件讓我深刻體會到幾點：

1. 合約條款要具體，不能只寫技術名詞

問題根源：

合約只寫：「OAuth 2.0 (for 第三方登入)」
外包商理解：只要能用第三方登入就好
實際應包含：完整的 OAuth 2.0 流程（含 Refresh Token）

教訓：

⚠️ 不要假設外包商了解技術標準的完整定義。

改進方向：

2. 驗收標準要包含「非功能性需求」

問題：

驗收時測試項目：
✅ 可以登入
✅ 可以看到資料
✅ 可以登出

但沒測試：
❌ Token 30 天後會不會過期？
❌ 過期後使用者體驗如何？
❌ 有沒有自動刷新機制？

教訓：

⚠️ 驗收不只是測「能不能用」，還要測「用得好不好」、「用得久不久」。

改進方向：

驗收測試應包含：

├─ 功能測試（傳統項目）
│  ├─ 登入成功
│  ├─ 登出成功
│  └─ 資料正常顯示
│
├─ 時間測試（容易忽略！）⭐
│  ├─ Token 快過期時的行為
│  ├─ Token 過期後的處理
│  ├─ 長時間閒置後的狀態
│  └─ 模擬 30 天後的使用情境
│
├─ 標準合規性測試（最重要！）⭐⭐
│  ├─ OAuth 2.0 是否完整實作？
│  ├─ 是否有 Refresh Token？
│  ├─ 是否符合 RFC 6749 規範？
│  └─ 請外包商提供技術文件證明
│
└─ 異常情境
   ├─ 網路中斷
   ├─ API 錯誤
   └─ 密碼變更

3. 外包合約要有「技術標準附件」

這次事件最大的教訓是：合約條款和技術理解有落差。

建議做法：

附件一：技術標準清單

## OAuth 2.0 實作標準

依據 RFC 6749 規範，本專案的 OAuth 2.0 實作應包含：

### 必須實作項目（Missing any = 驗收不通過）
- [ ] Authorization Code Flow
- [ ] Access Token 發放
- [ ] Refresh Token 發放 ⭐
- [ ] Token 刷新 API endpoint ⭐
- [ ] Token 自動刷新邏輯（前端）⭐
- [ ] Token 過期處理
- [ ] 錯誤處理（Invalid Token / Expired Token）

### 驗收標準
- Access Token 有效期：不超過 1 小時
- Refresh Token 有效期：至少 30 天
- Token 刷新成功率：> 99.9%
- 使用者無感知刷新：是

### 參考文件
- [RFC 6749 - OAuth 2.0](https://tools.ietf.org/html/rfc6749)
- [OAuth 2.0 Best Practices](https://tools.ietf.org/html/rfc8725)

附件二：驗收測試腳本

## Token 管理驗收測試

### Test Case 1: Refresh Token 存在性
1. 使用者登入
2. 檢查回應是否包含 `refresh_token` 欄位
3. ✅ Pass: 有 / ❌ Fail: 沒有

### Test Case 2: Token 自動刷新
1. 使用者登入
2. 等待 Access Token 過期（或手動設為過期）
3. 發送 API 請求
4. 檢查是否自動刷新（無需使用者重新登入）
5. ✅ Pass: 自動刷新 / ❌ Fail: 要求重新登入

### Test Case 3: 長期使用情境
1. 使用者登入
2. 模擬 30 天後的情境（調整系統時間）
3. 檢查使用者是否仍能正常使用
4. ✅ Pass: 可正常使用 / ❌ Fail: 被登出

4. 後續處理：與外包商溝通策略

發現問題後的應對：

flowchart TD
    A[發現交付不完整] --> B{合約有明確要求?}
    B -->|有| C[收集證據]
    B -->|沒有| D[自行解決]

    C --> E[列出缺失清單]
    E --> F[引用合約條款]
    F --> G[要求補做]

    G --> H{外包商回應?}
    H -->|同意補做| I[✅ 問題解決]
    H -->|拒絕| J[提出技術標準證明]

    J --> K{仍拒絕?}
    K -->|是| L[只好自幹😂]
    K -->|否| I

    style G fill:#ffa,stroke:#333,color:#000
    style I fill:#afa,stroke:#333,color:#000
    style L fill:#faa,stroke:#333,color:#000

溝通要點：

1. 準備證據

   • ✅ 合約條款截圖（「OAuth 2.0」要求）
   • ✅ OAuth 2.0 標準文件（RFC 6749）
   • ✅ 實際交付與標準的對比表
   • ✅ 使用者問題回報記錄

2. 明確訴求

   「根據合約第 15 頁要求實作 OAuth 2.0，
    而 OAuth 2.0 標準（RFC 6749）明確包含 Refresh Token 機制。
    目前交付的系統缺少此功能，請於 X 日前補完。」
   

3. 提供選項

   • 選項 A：外包商補做（最佳）
   • 選項 B：我方自行開發，從尾款扣除相應費用
   • 選項 C：第三方技術鑑定

4. 保留彈性

   • 如果外包商確實不熟悉，可以提供技術指導
   • 設定合理的完成時間（例如 2-3 週）
   • 建立明確的驗收標準

5. 認證機制是基礎建設

Token 管理看似簡單，實則關係到：

• ✅ 使用者體驗（會不會突然被登出）
• ✅ 資料安全（能否撤銷 token）
• ✅ 功能擴展（能否支援多裝置管理）

💡 重要觀念： 基礎建設的品質，決定了系統的天花板。

6. 技術選型要看長遠

「自動重新登入」確實能快速解決問題，但會產生技術債：

技術債累積過程：

第 1 個月：快速上線 ✅
第 3 個月：發現第三方登入不支援 ⚠️
第 6 個月：想實作多裝置管理，發現架構不支援 ❌
第 12 個月：被迫重構整個認證系統 💸💸💸

重構成本 >> 一開始就做對的成本

✅ 最佳實踐： 多花幾天實作正確的方案，勝過日後花數週重構。

總結

從「會員資料不見」的問題，到發現是 Token 過期，再到翻出合約發現外包商沒做完整，這次經驗讓我學到：

技術層面

1. 問題表象不等於真相

   • 資料沒有不見，只是使用者因 Token 過期而看不到
   • 根本原因是 Token 管理機制不完整

2. 緊急處理要果斷

   • 先延長 Token 有效期止血
   • 爭取時間規劃長期方案

3. 長期方案要深思

   • 選擇 Refresh Token（業界標準）
   • 而非自動重新登入（技術債）

管理層面（更重要！）

4. 這不是我沒有要求，是外包商沒做

   • 合約明確寫了「OAuth 2.0」
   • OAuth 2.0 標準就包含 Refresh Token
   • 外包商只做了一半

5. 合約條款要展開技術細節

   • 不能只寫技術名詞（OAuth 2.0）
   • 要列出具體實作項目（Refresh Token、自動刷新等）
   • 附上技術標準文件（RFC 6749）

6. 驗收標準要包含時間維度

   • 不只測「能不能用」
   • 還要測「用得久不久」（30 天後的行為）
   • 標準合規性測試（是否符合 OAuth 2.0 完整規範）

7. 外包管理要有追溯機制

   • 發現缺失時，能回頭查證合約
   • 收集證據（合約、標準文件、交付物）
   • 明確訴求並提供解決選項

給其他技術主管的建議

如果你也在管理外包專案：

✅ Do（該做的）:
- 把技術標準展開成檢查清單
- 驗收時測試長期使用情境
- 保留合約解釋的證據（RFC 文件、業界標準）
- 發現問題時立即溝通，不要拖延

❌ Don't（別做的）:
- 假設外包商了解技術標準的完整定義
- 只測試「能登入」就算驗收通過
- 問題發生後才想起要看合約
- 自己默默修 Bug，放棄向外包商追究

希望這篇文章能幫助到：

• 🎯 遇到相似 Token 問題的開發者
• 📋 需要管理外包專案的技術主管
• 📝 正在撰寫技術合約的 PM

如果有任何問題或建議，歡迎在下方留言討論！

#JWT #OAuth2.0 #RefreshToken #外包管理 #合約管理 #技術驗收 #Strapi #技術債務 #專案管理