Gateway Chuyên dụng

Người dùng gói Nirvana nhận được gateway IPFS riêng tư tại tên miền phụ duy nhất. Gateway này chỉ phục vụ các tệp được ghim vào tài khoản của bạn -- nó sẽ không phân giải CID từ người dùng khác hoặc mạng IPFS công cộng.

URL gateway của bạn

URL gateway của bạn được hiển thị trên trang Gateway và được trả về bởi endpoint /user/profile:

https://<your-slug>.gw.ipfs.ninja/ipfs/<CID>

Chế độ truy cập

Chế độ	Hành vi
Mở (mặc định)	Bất kỳ ai có URL gateway + CID đều có thể truy cập tệp. Không cần token.
Yêu cầu token	Yêu cầu phải bao gồm token gateway qua tham số truy vấn ?token=gwt_... hoặc tiêu đề X-Gateway-Token.

Giới hạn

• 50 GB/tháng băng thông gateway bao gồm với Nirvana
• Khi đạt giới hạn băng thông, yêu cầu gateway trả về 429 cho đến tháng tiếp theo
• Mức sử dụng dung lượng đặt lại vào ngày đầu tiên của mỗi tháng
• Chỉ phục vụ CID được ghim vào tài khoản của bạn -- yêu cầu CID khác trả về 403

TIP

Gateway công cộng tại ipfs.ninja/ipfs/ vẫn khả dụng trên tất cả các gói và phục vụ bất kỳ CID nào mà không cần xác thực.

Cài đặt Gateway

Cấu hình kiểm soát truy cập cho gateway chuyên dụng của bạn.

Cập nhật Cài đặt

PUT /gateway-settings

Tham số	Kiểu	Bắt buộc	Mô tả
tokenRequired	boolean	Không	Bật/tắt yêu cầu token gateway.
ipWhitelist	string[]	Không	Mảng địa chỉ IP được phép. Tối đa 100. Mảng trống xóa danh sách trắng.
allowedOrigins	string[]	Không	Mảng nguồn gốc được phép cho yêu cầu trình duyệt. Tối đa 100. Phải sử dụng định dạng HTTPS (ví dụ: https://myapp.com). Mảng trống cho phép tất cả nguồn gốc.

Ví dụ

# Bật chế độ yêu cầu token
curl -X PUT https://api.ipfs.ninja/gateway-settings \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"tokenRequired": true}'

# Đặt danh sách trắng IP
curl -X PUT https://api.ipfs.ninja/gateway-settings \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"ipWhitelist": ["203.0.113.1", "198.51.100.0"]}'

# Xóa danh sách trắng IP (cho phép tất cả IP)
curl -X PUT https://api.ipfs.ninja/gateway-settings \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"ipWhitelist": []}'

# Hạn chế theo nguồn gốc cụ thể
curl -X PUT https://api.ipfs.ninja/gateway-settings \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"allowedOrigins": ["https://myapp.com", "https://staging.myapp.com"]}'

# Xóa hạn chế nguồn gốc (cho phép tất cả)
curl -X PUT https://api.ipfs.ninja/gateway-settings \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"allowedOrigins": []}'

Hạn chế Nguồn gốc

Khi allowedOrigins được cấu hình, chỉ các yêu cầu trình duyệt từ nguồn gốc được liệt kê mới được cho phép. Gateway kiểm tra tiêu đề Origin và Referer trên các yêu cầu đến.

• Nếu danh sách trống (mặc định), tất cả nguồn gốc được cho phép.
• Nếu nguồn gốc được chỉ định, yêu cầu với tiêu đề Origin hoặc Referer không khớp sẽ bị từ chối với phản hồi 403.
• Yêu cầu không phải trình duyệt không có tiêu đề Origin (như tìm nạp phía máy chủ hoặc curl) đi qua mà không bị hạn chế.

Điều này hữu ích để nhúng nội dung gateway trong ứng dụng web của bạn đồng thời ngăn các trang khác hotlink tệp của bạn.

Token Gateway

Token gateway (tiền tố gwt_) chỉ đọc và an toàn để nhúng vào ứng dụng frontend. Khác với khóa API, token gateway chỉ có thể truy cập tệp thông qua gateway chuyên dụng -- không thể tải lên, xóa hoặc quản lý tài khoản.

Khả năng	Khóa API (bws_)	Token Gateway (gwt_)
Tải lên / xóa tệp	Có	Không
Liệt kê / lấy siêu dữ liệu tệp	Có	Không
Đọc tệp qua gateway	Không	Có
An toàn để nhúng vào frontend	Không	Có

Tạo Token Gateway

POST /gateway-tokens

Tham số	Kiểu	Bắt buộc	Mô tả
name	string	Không	Nhãn cho token (ví dụ: "Frontend"). Mặc định: "Default".

Phản hồi 201 Created

{
  "token": "gwt_a1b2c3d4e5f6789012345678abcdef01",
  "tokenPrefix": "gwt_a1b2c3d4",
  "tokenName": "Frontend",
  "createdAt": 1711036800000
}

WARNING

Token đầy đủ chỉ được trả về một lần khi tạo. Hãy lưu trữ nó an toàn.

Liệt kê Token Gateway

GET /gateway-tokens

[
  {
    "tokenPrefix": "gwt_a1b2c3d4",
    "tokenName": "Frontend",
    "createdAt": 1711036800000
  }
]

Xóa Token Gateway

DELETE /gateway-tokens/:prefix

Tham số	Kiểu	Bắt buộc	Mô tả
prefix	string	Có	Tiền tố token cần xóa (ví dụ: "gwt_a1b2c3d4").

Sử dụng token gateway

Khi gateway có chế độ yêu cầu token được bật, truyền token dưới dạng tham số truy vấn hoặc tiêu đề:

# Tham số truy vấn
curl "https://a1b2c3d4.gw.ipfs.ninja/ipfs/QmXk7VRz...?token=gwt_your_token"

# Hoặc tiêu đề
curl https://a1b2c3d4.gw.ipfs.ninja/ipfs/QmXk7VRz... \
  -H "X-Gateway-Token: gwt_your_token"