HMAC 簽章指南
本 HMAC 簽章指南將引導您為 FastOG 建立 HMAC-SHA256 簽章，以便您能即時產生動態的 Open Graph 圖片——採用訂閱制，提供免費帳戶與 Dynamic API 方案（付費渲染為乾淨版本）。您可以在此以任何語言手動撰寫簽章，或先使用免費的 OG 圖片測試工具來查看 URL 格式的實際運作方式。
總覽
所有對 /api/v1/og 的請求都必須包含 HMAC-SHA256 簽章，以證明請求來自合法的網站。這可防止未經授權的第三方使用您的 API 配額。
兩層驗證機制：
- API 金鑰（位於查詢參數：
key=sk_quick_123abc）— 識別使用者帳戶（用於渲染配額計算） - HMAC 簽章（位於查詢參數：
s=<signature>）— 證明請求來自您的網站
兩者皆須通過驗證。僅有 API 金鑰並不足夠。
為何使用查詢參數？ OG 圖片是由社群網路爬蟲（LinkedIn、Twitter、Facebook）擷取的，這些爬蟲不會傳送自訂標頭。簽章必須包含在 URL 中。
產生簽章
演算法
method = "GET"
path = "/api/v1/og"
canonicalQuery = for every query param EXCEPT `s` (including `key`):
- array values are 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))
Query parameters:
key=<apiKey>
s=<signature>
需求
- 簽章格式：64 字元的十六進位字串（SHA256）
- 使用
hash_equals()進行常數時間比較（防止時間攻擊） - 每位使用者專屬密鑰：每個 API 金鑰都有各自的
hmac_secret欄位
範例實作
如需包含多種框架與模式之完整教學，請參閱：
- JavaScript/Node.js 教學 - Next.js、Express、原生 Node.js
- Next.js App Router
- Next.js Pages Router
- React
- SvelteKit
- Vue/Nuxt
- Astro
- Express
- 原生 Node.js
- PHP/Laravel
- Python
- Ruby/Rails
JavaScript（Node.js / 前端）
javascript
const crypto = require("crypto");
// rfc3986-encode: everything except A-Za-z0-9-._~
const enc = (s) =>
encodeURIComponent(s).replace(
/[!'()*]/g,
(c) => "%" + c.charCodeAt(0).toString(16).toUpperCase(),
);
function generateOgImageUrl(baseUrl, params, apiKey, hmacSecret) {
// every query param except `s`; key included; arrays expand to one pair each
const all = { ...params, key: apiKey };
const pairs = [];
for (const [k, v] of Object.entries(all)) {
for (const vv of Array.isArray(v) ? [...v].sort() : [v]) {
pairs.push(`${enc(k)}=${enc(vv)}`);
}
}
pairs.sort();
const canonical = pairs.join("&");
const signature = crypto
.createHmac("sha256", hmacSecret)
.update(`GET/api/v1/og\n${canonical}`)
.digest("hex");
const url = new URL(baseUrl);
for (const [k, v] of Object.entries(all)) {
const isArray = Array.isArray(v);
for (const vv of isArray ? v : [v]) {
url.searchParams.append(isArray ? `${k}[]` : k, vv);
}
}
url.searchParams.set("s", signature);
return url.toString();
}
// Usage in meta tag:
const ogUrl = generateOgImageUrl(
"https://fastog.com/api/v1/og",
{ title: "Como criar um SaaS", template: "default" },
"sk_quick_123abc",
process.env.HMAC_SECRET,
);
// <meta property="og:image" content="{ogUrl}" />
PHP（Laravel）
php
function generateOgImageUrl(string $baseUrl, array $params, string $apiKey, string $hmacSecret): string
{
// every query param except `s`; key included; array values sorted too
$all = array_merge($params, ['key' => $apiKey]);
$pairs = [];
foreach ($all as $k => $v) {
$values = is_array($v) ? $v : [$v];
sort($values, SORT_STRING);
foreach ($values as $vv) {
$pairs[] = rawurlencode((string)$k) . '=' . rawurlencode((string)$vv);
}
}
sort($pairs, SORT_STRING);
$canonical = implode('&', $pairs);
$signature = hash_hmac('sha256', 'GET/api/v1/og' . "\n" . $canonical, $hmacSecret);
// URL uses bracket keys for arrays (features[]=a&features[]=b); canonical signs plain keys
$urlPairs = [];
foreach ($all as $k => $v) {
$isArray = is_array($v);
$values = $isArray ? $v : [$v];
$urlKey = $isArray ? $k . '[]' : $k;
foreach ($values as $vv) {
$urlPairs[] = rawurlencode($urlKey) . '=' . rawurlencode((string)$vv);
}
}
return $baseUrl . '?' . implode('&', $urlPairs) . '&s=' . $signature;
}
// Usage in Blade template:
$ogUrl = generateOgImageUrl(
'https://fastog.com/api/v1/og',
['title' => 'Como criar um SaaS'],
'sk_quick_123abc',
env('HMAC_SECRET')
);
// <meta property="og:image" content="{{ $ogUrl }}" />
Python
python
import hmac
import hashlib
from urllib.parse import quote
def _enc(s):
return quote(str(s), safe='-._~')
def generate_og_image_url(base_url, params, api_key, hmac_secret):
# every query param except `s`; key included; array values sorted too
all_params = {**params, 'key': api_key}
pairs = []
for k, v in all_params.items():
for vv in sorted(v if isinstance(v, list) else [v]):
pairs.append(f"{_enc(k)}={_enc(vv)}")
canonical = '&'.join(sorted(pairs))
signature = hmac.new(
hmac_secret.encode(),
f"GET/api/v1/og\n{canonical}".encode(),
hashlib.sha256
).hexdigest()
# URL uses bracket keys for arrays (features[]=a&features[]=b); canonical signs plain keys
url_pairs = []
for k, v in all_params.items():
if isinstance(v, list):
for vv in v:
url_pairs.append(f"{_enc(f'{k}[]')}={_enc(vv)}")
else:
url_pairs.append(f"{_enc(k)}={_enc(v)}")
return f"{base_url}?{'&'.join(url_pairs)}&s={signature}"
# Usage:
og_url = generate_og_image_url(
'https://fastog.com/api/v1/og',
{'title': 'Como criar um SaaS', 'template': 'default'},
'sk_quick_123abc',
os.environ['HMAC_SECRET']
)
# <meta property="og:image" content="{{ og_url }}" />
完整範例：Laravel Blade 模板
blade
{{-- In your blog post view --}}
@php
$apiKey = 'sk_quick_123abc'; // Your full API key
$hmacSecret = env('OG_RENDER_HMAC_SECRET');
$params = [
'template' => 'blog',
'title' => $post->title,
'subtitle' => $post->excerpt,
'key' => $apiKey,
];
// canonical query: sorted "k=v" pairs, rfc3986-encoded, every param except `s`
$pairs = [];
foreach ($params as $k => $v) {
$pairs[] = rawurlencode((string)$k) . '=' . rawurlencode((string)$v);
}
sort($pairs, SORT_STRING);
$canonical = implode('&', $pairs);
$signature = hash_hmac('sha256', 'GET/api/v1/og' . "\n" . $canonical, $hmacSecret);
$ogImageUrl = 'https://fastog.com/api/v1/og?' . $canonical . '&s=' . $signature;
@endphp
<head>
<meta property="og:image" content="{{ $ogImageUrl }}" />
<meta property="og:title" content="{{ $post->title }}" />
<meta property="og:description" content="{{ $post->excerpt }}" />
</head>
安全性最佳實務
- 安全儲存機密 — 使用環境變數或機密管理工具
- 切勿在用戶端程式碼中暴露機密 — 僅在伺服器端簽署 URL
- 使用 HTTPS — 防止中間人攻擊
- 定期輪換機密 — 特別是在可能遭到入侵時
- 監控簽署失敗 — 重複失敗可能表示遭受攻擊
- 每位使用者隔離 — 每個 API 金鑰都有各自的 HMAC 機密
錯誤回應
缺少簽章
json
{
"error": "Missing signature parameters",
"code": "missing_signature",
"required_params": ["s", "key"],
"example": "/api/v1/og?title=Hello&key=sk_quick_123abc&s=<signature>"
}
無效簽章
json
{
"error": "Invalid signature",
"code": "invalid_signature"
}
測試
產生一個測試 URL：
bash
# 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);
"
# Test with curl
curl "https://fastog.com/api/v1/og?title=Test&key=sk_quick_123abc&s=<signature>"
預期的回應：
- ✅ 有效的簽章 → 回傳 OG 圖片（若缺少範本參數則回傳驗證錯誤）
- ❌ 無效的簽章 →
{"error": "...", "code": "invalid_signature"} - ❌ 缺少參數 →
{"error": "...", "code": "missing_signature"}
疑難排解
簽章不符
- 請確認您使用的是正確的 HMAC 密鑰（請在儀表板中檢查 API 金鑰）
- 請檢查正規化查詢字串：除了
s以外的所有查詢參數（包含key），值需以 rfc3986 編碼，金鑰需依字典序排序 - 請確認簽章為小寫十六進位格式（64 個字元）
取得您的 HMAC 密鑰
- 前往 儀表板 → API 金鑰
- 建立新的 API 金鑰（或使用現有的金鑰）
- 複製 API 金鑰旁顯示的 HMAC 密鑰（僅顯示一次！）
- 將其安全地儲存在您的環境變數中
bash
# Add to .env
OG_RENDER_HMAC_SECRET=<your-64-char-hex-secret>
使用 curl 進行測試
bash
# Bash script to generate signed URL
SECRET="your-hmac-secret-here"
API_KEY="sk_quick_123abc" # Your full API key
# canonical query: sorted "k=v" pairs, every param except `s` (key included)
CANONICAL="key=${API_KEY}&template=default&title=Test"
MESSAGE=$(printf 'GET/api/v1/og\n%s' "$CANONICAL")
SIGNATURE=$(printf '%s' "$MESSAGE" | openssl dgst -sha256 -hmac "$SECRET" | cut -d' ' -f2)
curl "http://localhost:8000/api/v1/og?template=default&title=Test&key=${API_KEY}&s=${SIGNATURE}"
預期結果：200 OK 包含圖片資料（若模板參數無效則回傳 422）。