FastOG
Chủ đề

Xác thực HMAC & Bảo mật

Bảo mật các URL hình ảnh OG được ký bằng HMAC của bạn với xác thực HMAC-SHA256 của FastOG. Hướng dẫn này bao gồm việc ký, xác thực và xử lý sự cố cho mọi yêu cầu, để bạn có thể phân phối hình ảnh Open Graph động ngay lập tức — giới hạn theo đăng ký, với số lần render không giới hạn (không có hạn mức render hàng tháng và không tính phí vượt hạn mức). Đăng ký, chọn gói API Dynamic, sau đó tạo khóa API và bí mật HMAC trong bảng điều khiển (các lần render API trả phí đều sạch). Ký trên máy chủ của bạn một lần và tích hợp trong vài phút.

🚀 Bắt đầu nhanh

Mới làm quen với chữ ký HMAC? Bắt đầu tại đây:

  1. Hướng dẫn bắt đầu nhanh — Thiết lập và chạy trong 5 phút
  2. Hướng dẫn JavaScript — Hướng dẫn đầy đủ cho nhà phát triển Node.js/Next.js
  3. Tất cả hướng dẫn theo framework — chọn stack của bạn:

📚 Mục lục Tài liệu

Khái niệm cốt lõi

  • Hướng dẫn chữ ký HMAC — Tài liệu tham khảo đầy đủ với chi tiết thuật toán, yêu cầu và ví dụ bằng JavaScript, PHP và Python
  • Xác thực HMAC — Chi tiết triển khai phía máy chủ, tính năng bảo mật và phản hồi lỗi

Hướng dẫn

Tham khảo nhanh

Thuật toán

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>

Tham số truy vấn

Tham số Mô tả Ví dụ
key Khóa API đầy đủ sk_quick_123abc
s Chữ ký HMAC-SHA256 (64 ký tự hex) 9f8a1b2c3d4e...

Mã lỗi

Mã Trạng thái HTTP Mô tả
missing_signature 401 Thiếu tham số key hoặc s
invalid_signature 401 Chữ ký không khớp

🎯 Các trường hợp sử dụng

Bài viết blog

Tạo OG image động cho các bài viết blog:

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

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

Sản phẩm thương mại điện tử

Tạo OG image cho các trang sản phẩm:

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

Lời chứng thực

Tạo OG image cho các trích dẫn lời chứng thực:

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

🔐 Bảo mật

Các phương pháp tốt nhất

  1. Lưu trữ bí mật an toàn — Sử dụng biến môi trường hoặc trình quản lý bí mật
  2. Không bao giờ để lộ bí mật HMAC trong mã phía máy khách — Chỉ ký trên máy chủ
  3. Sử dụng HTTPS — Ngăn chặn các cuộc tấn công MITM
  4. Xoay vòng bí mật định kỳ — Đặc biệt nếu bị xâm phạm
  5. Giám sát các chữ ký thất bại — Các lần thất bại lặp lại có thể cho thấy dấu hiệu tấn công
  6. Cô lập theo từng người dùng — Mỗi khóa API có bí mật HMAC riêng

Lấy bí mật HMAC của bạn

  1. Đi tới Bảng điều khiển → Khóa API
  2. Tạo một khóa API mới
  3. Sao chép Bí mật HMAC (chỉ hiển thị một lần!)
  4. Lưu trữ trong biến môi trường
bash
# .env
FASTOG_HMAC_SECRET=<your-64-char-hex-secret>

🧪 Kiểm thử

Tạo URL kiểm thử

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);
"

Kiểm thử bằng curl

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

Phản hồi dự kiến

  • ✅ Chữ ký hợp lệ → Trả về ảnh OG (hoặc 422 nếu tham số mẫu không hợp lệ)
  • ❌ Chữ ký không hợp lệ → {"code": "invalid_signature"}
  • ❌ Thiếu tham số → {"code": "missing_signature"}

🛠 Xử lý sự cố

Chữ ký không khớp

  1. Xác minh bạn đang sử dụng đúng khóa bí mật HMAC (kiểm tra khóa API trong bảng điều khiển)
  2. Kiểm tra truy vấn chuẩn: mọi tham số truy vấn ngoại trừ s (bao gồm cả key), giá trị được mã hóa theo chuẩn rfc3986, các khóa được sắp xếp theo thứ tự từ điển
  3. Xác minh chữ ký là dạng hex chữ thường (64 ký tự)

📖 Tài Nguyên Bổ Sung

❓ Câu hỏi thường gặp

Q: Tại sao dùng tham số truy vấn thay vì header?
A: Ảnh OG được tải bởi các trình thu thập dữ liệu của mạng xã hội (LinkedIn, Twitter, Facebook) vốn không gửi header tùy chỉnh. Chữ ký BẮT BUỘC phải nằm trong URL.

Q: Tôi có thể dùng cùng một chữ ký cho nhiều yêu cầu không?
A: Có. Chữ ký được tính từ truy vấn chính xác (trừ s), vì vậy URL đã ký vẫn hợp lệ miễn là các tham số không thay đổi. Thay đổi bất kỳ tham số nào (bao gồm cả key) thì bạn phải ký lại.

Q: Tôi có cần ký yêu cầu cho tất cả các mẫu không?
A: Có. Tất cả yêu cầu đến /api/v1/og đều yêu cầu chữ ký HMAC.

Q: Điều gì xảy ra nếu bí mật HMAC của tôi bị lộ?
A: Thu hồi khóa API trong bảng điều khiển và tạo khóa mới. Mỗi khóa API có bí mật HMAC riêng.

Q: Tôi có thể tắt xác thực HMAC cho các dịch vụ nội bộ không?
A: Liên hệ bộ phận hỗ trợ để có giải pháp tùy chỉnh. Xác thực HMAC là bắt buộc đối với tất cả các điểm cuối API công khai.

🆘 Hỗ trợ

Cần trợ giúp?

Dùng thử miễn phí — không cần đăng ký

Xem trước và kiểm tra hình ảnh OG động trong vài giây.

Mở Trình kiểm tra hình ảnh OG miễn phí
LocaFile AI AI localization for games, apps, subtitles & sites SubtoVTT Convert & clean subtitle files BeCaSimulations Indie game studio

A BeCaSimulations site