HMAC 驗證與安全性

使用 FastOG 的 HMAC-SHA256 驗證來保護您的 HMAC 簽名 OG 圖片 URL。本指南涵蓋每個請求的簽署、驗證與疑難排解，讓您能即時提供動態 Open Graph 圖片——支援訂閱門檻，且渲染次數無上限（無每月渲染配額，也無超量計費）。註冊後，選擇 Dynamic API 方案，接著在儀表板中建立您的 API 金鑰與 HMAC 密鑰（付費 API 渲染乾淨無瑕）。在您的伺服器上簽署一次，幾分鐘內即可整合完成。

🚀 快速入門

第一次接觸 HMAC 簽章？ 從這裡開始：

1. 快速入門指南 — 5 分鐘內完成設定並開始使用
2. JavaScript 教學 — 適用於 Node.js/Next.js 開發者的完整指南
3. 所有框架教學 — 選擇您的技術棧：
   • Next.js App Router
   • Next.js Pages Router
   • React
   • SvelteKit
   • Vue/Nuxt
   • Astro
   • Express
   • 原生 Node.js
   • JavaScript
   • PHP/Laravel
   • Python
   • Ruby/Rails

📚 文件索引

核心概念

• HMAC 簽章指南 — 完整參考資料，包含演算法細節、需求，以及 JavaScript、PHP 和 Python 的範例
• HMAC 驗證 — 伺服器端實作細節、安全性功能與錯誤回應

教學課程

• JavaScript/Node.js 教學 — 綜合指南，涵蓋：

  • 快速入門（5 分鐘）
  • Next.js App Router（3 種模式）
  • Next.js Pages Router
  • Express.js 後端
  • 原生 Node.js
  • 前端整合模式（SSG、SSR、Client-Side）
  • 測試與除錯
  • 常見陷阱

• Next.js App Router

• Next.js Pages Router

• React

• SvelteKit

• Vue/Nuxt

• Astro

• Express

• 原生 Node.js

• PHP/Laravel

• Python

• Ruby/Rails

快速參考

演算法

method = "GET"
path = "/api/v1/og"
canonicalQuery = every query param EXCEPT `s` (including `key`): array values sorted too; each pair rfc3986Encode(key)=rfc3986Encode(value); pairs sorted lexicographically and joined with "&"

message = method + path + "\n" + canonicalQuery
signature = hex(HMAC-SHA256(message, hmac_secret))

URL: /api/v1/og?title=Hello&key=sk_quick_123abc&s=<signature>

查詢參數

錯誤代碼

🎯 使用情境

部落格文章

為部落格文章產生動態 OG 圖片：

const ogUrl = generateSignedOgUrl({
    template: "blog",
    title: post.title,
    subtitle: post.excerpt,
    author: post.author.name,
});

// <meta property="og:image" content="{ogUrl}" />

電子商務商品

為商品頁面建立 OG 圖片：

const ogUrl = generateSignedOgUrl({
    template: "ecommerce",
    title: product.name,
    price: product.price,
    image: product.image,
});

客戶見證

為客戶見證引言產生 OG 圖片：

const ogUrl = generateSignedOgUrl({
    template: "testimonial",
    author_name: user.name,
    author_avatar: user.avatarUrl,
    quote: user.bio,
});

🔐 安全性

最佳實務

1. 安全儲存密鑰 — 使用環境變數或密鑰管理服務
2. 切勿在客戶端程式碼中暴露 HMAC 密鑰 — 僅在伺服器端簽章
3. 使用 HTTPS — 防止中間人攻擊
4. 定期輪換密鑰 — 特別是在可能遭到入侵時
5. 監控簽章失敗 — 重複失敗可能表示遭受攻擊
6. 每位使用者隔離 — 每個 API 金鑰都有各自的 HMAC 密鑰

取得您的 HMAC 密鑰

1. 前往 儀表板 → API 金鑰
2. 建立新的 API 金鑰
3. 複製 HMAC 密鑰（僅顯示一次！）
4. 儲存於環境變數中

# .env
FASTOG_HMAC_SECRET=<your-64-char-hex-secret>

🧪 測試

產生測試 URL

# Node.js
node -e "
const crypto = require('crypto');
const enc = (s) => encodeURIComponent(s).replace(/[!'()*]/g, (c) => '%' + c.charCodeAt(0).toString(16).toUpperCase());
const all = { title: 'Test', key: 'sk_quick_123abc' };
const pairs = [];
for (const [k, v] of Object.entries(all)) for (const vv of Array.isArray(v) ? v : [v]) pairs.push(enc(k) + '=' + enc(vv));
pairs.sort();
const canonical = pairs.join('&');
const sig = crypto.createHmac('sha256', 'YOUR_HMAC_SECRET').update('GET/api/v1/og\n' + canonical).digest('hex');
console.log('https://fastog.com/api/v1/og?title=Test&key=sk_quick_123abc&s=' + sig);
"

使用 curl 測試

curl "https://fastog.com/api/v1/og?title=Test&key=sk_quick_123abc&s=<signature>"

預期回應

• ✅ 有效的簽章 → 回傳 OG 圖片（若模板參數無效則回傳 422）
• ❌ 無效的簽章 → {"code": "invalid_signature"}
• ❌ 缺少參數 → {"code": "missing_signature"}

🛠 疑難排解

簽章不符

1. 確認您使用的是正確的 HMAC 密鑰（請在儀表板中檢查 API 金鑰）
2. 檢查正規化查詢字串：除了 s 以外的所有查詢參數（包含 key），值需以 rfc3986 編碼，金鑰需依字典序排序
3. 確認簽章為小寫十六進位格式（64 個字元）

📖 其他資源

• API 參考文件 — 完整的 API 文件
• 安全性最佳做法 — 詳細的安全指南
• 知識庫 — 技術實作細節

❓ 常見問題

問：為什麼使用查詢參數而不是標頭？
答：OG 圖片是由社群網路爬蟲（LinkedIn、Twitter、Facebook）擷取的，這些爬蟲不會傳送自訂標頭。簽章必須放在 URL 中。

問：我可以對多個請求使用相同的簽章嗎？
答：可以。簽章是根據確切的查詢（不含 s）計算出來的，因此只要參數不變，相同的簽署 URL 就會持續有效。若變更任何參數（包括 key），就必須重新簽署。

問：我是否需要為所有範本簽署請求？
答：需要。所有對 /api/v1/og 的請求都需要 HMAC 簽章。

問：如果我的 HMAC 密鑰遭到洩露，會發生什麼事？
答：請在儀表板中撤銷該 API 金鑰並建立新的金鑰。每個 API 金鑰都有各自的 HMAC 密鑰。

問：我可以為內部服務停用 HMAC 驗證嗎？
答：請聯絡支援團隊以取得客製化解決方案。HMAC 驗證是所有公開 API 端點的必要條件。

🆘 支援

需要協助嗎？

• 請參閱 JavaScript 教學 取得完整的程式碼範例
• 請檢視 HMAC 簽章指南 了解演算法細節
• 請聯絡支援團隊：[email protected]

相關資訊

• 文件 — 所有 FastOG 指南與參考資料
• 免費 OG 圖片測試工具 — 無需帳號即可預覽
• 快速入門指南 — 5 分鐘內開始使用
• HMAC 簽章指南 — 演算法詳細說明
• HMAC 驗證 — 伺服器端驗證