FAQ

Các câu hỏi thường gặp về IPFS Ninja.

Tổng quan

IPFS Ninja là gì?

IPFS Ninja là một dịch vụ ghim IPFS được quản lý. Bạn tải lên bất kỳ tệp nào qua API REST đơn giản, hoặc ghim các CID hiện có từ mạng IPFS. Mỗi tệp nhận được một mã định danh nội dung vĩnh viễn (CID) và có thể truy cập thông qua gateway của chúng tôi tại ipfs.ninja/ipfs/<CID>.

ipfs.ninja/ipfs/<CID> có phục vụ bất kỳ CID nào trên mạng IPFS không?

Không. Cổng apex chỉ phục vụ các CID đã được tải lên hoặc ghim bởi người dùng IPFS Ninja. Các yêu cầu cho CID không xác định trả về HTTP 410 Gone với con trỏ đến các cổng IPFS công cộng (ipfs.io, dweb.link). Để phục vụ CID của bên thứ ba qua cổng của chúng tôi, hãy thực hiện POST /pin vào tài khoản của bạn trước — sau khi ghim, CID có thể truy cập được tại cả URL apex và URL cổng chuyên dụng của bạn.

Sự khác biệt giữa cổng apex và cổng chuyên dụng là gì?

Khía cạnh	Apex ipfs.ninja/ipfs/<CID>	Chuyên dụng <slug>.gw.ipfs.ninja/ipfs/<CID>
Phạm vi	Chia sẻ giữa tất cả người dùng	Chỉ CID của bạn
Xác thực	Không	Token tùy chọn / IP allowlist / origin allowlist
SLA	Best-effort	SLA đầy đủ
Được khuyến nghị cho	Liên kết thông thường	Nhúng sản xuất (NFT, video, trang web)
Giới hạn tốc độ	Chia sẻ theo IP + theo CID	Theo gói, có thể cấu hình

Cả hai phục vụ nội dung giống hệt nhau. Đối với lưu lượng sản xuất, hãy sử dụng cổng chuyên dụng.

Những loại tệp nào được hỗ trợ?

Tất cả các loại tệp đều được hỗ trợ. Đối tượng và mảng JSON có thể được gửi trực tiếp. Tất cả các tệp khác (hình ảnh, PDF, HTML, video, audio, tệp nhị phân) được gửi dưới dạng nội dung mã hóa base64.

Có giới hạn kích thước tệp không?

Các lần tải lên riêng lẻ bị giới hạn bởi dung lượng lưu trữ của gói đăng ký. Không có giới hạn kích thước cho mỗi tệp ngoài dung lượng lưu trữ khả dụng của bạn.

Tôi có thể ghim nội dung đã tồn tại trên IPFS không?

Có. Sử dụng POST /pin với bất kỳ CID hợp lệ nào. Cụm của chúng tôi sẽ tìm nạp nội dung từ mạng IPFS và ghim nó vào tài khoản của bạn. Xem tài liệu API Ghim để biết chi tiết.

Ghim mất bao lâu?

Phụ thuộc vào kích thước tệp và số lượng nút IPFS có nội dung. Các tệp nhỏ, phân phối tốt được ghim trong vài giây. Nội dung lớn hoặc hiếm khi được ghim có thể mất vài phút. Endpoint ghim trả về ngay lập tức với trạng thái pinning -- thăm dò GET /pin/:cid để kiểm tra tiến trình.

Điều gì xảy ra nếu không tìm thấy CID?

Trạng thái chuyển sang failed. Điều này có nghĩa là CID không hợp lệ hoặc nội dung không còn khả dụng trên bất kỳ nút IPFS nào có thể truy cập được.

Dữ liệu tải lên IPFS có công khai không?

Có. Tất cả nội dung được ghim trên IPFS đều có thể truy cập công khai qua CID của nó thông qua bất kỳ gateway IPFS nào. Nếu bạn cần truy cập riêng tư, hãy sử dụng gateway chuyên dụng với chế độ yêu cầu token -- điều này hạn chế truy cập thông qua gateway của bạn, mặc dù nội dung vẫn khả dụng trên mạng IPFS rộng hơn.

Tại sao CID mới của tôi lại đổi từ Qm... sang bafy...?

Các lần tải lên và ghim mới trả về CIDv1 hiện đại (bafk… cho nội dung nhỏ dạng một khối, bafy… cho các tệp và thư mục lớn hơn) theo hồ sơ IPIP-0499 unixfs-v1-2025: mã hóa CIDv1 base32, các khối 1 MiB, raw leaves. Điều này khớp với những gì các công cụ hiện đại (Helia, Kubo mới nhất, ipfs-car) tạo ra cho cùng nội dung, nên một tệp tải lên qua chúng tôi nhận cùng CID mà bất kỳ client hiện đại nào cũng sẽ tính toán cho cùng byte đó.

Các CID Qm… cũ từ các lần tải lên trước đó vẫn hoàn toàn có thể phân giải — gateway, POST /pin, GET /file, IPNS và mọi endpoint khác chấp nhận cả hai định dạng vô thời hạn. Không có gì bạn đã có sẽ ngừng hoạt động.

Làm thế nào để ghim nội dung nằm trên một node riêng tư / không thuộc DHT?

POST /pin chấp nhận multiaddresses[] tùy chọn (tối đa 5). Nếu được cung cấp, cụm của chúng tôi thực hiện ipfs swarm connect <multiaddr> cho từng gợi ý trước khi ghim chạy, nên nội dung trên các peer không quảng bá qua DHT công khai (node riêng tư, môi trường staging, máy VPN cục bộ) có thể truy cập được. Xem hướng dẫn Ghim từ một node IPFS riêng tư.

Tệp của tôi có ở trên IPFS nếu tôi hủy tài khoản không?

Chúng tôi bỏ ghim các tệp của bạn khỏi các nút của chúng tôi khi bạn hủy. Nếu các nút IPFS khác đã lưu nội dung của bạn vào bộ nhớ đệm, nó có thể vẫn truy cập được. Tuy nhiên, nếu không có ghim đang hoạt động, các tệp cuối cùng sẽ bị xóa bởi quá trình thu gom rác trên toàn mạng.

Xác thực & API

Làm thế nào để xác thực yêu cầu API?

Truyền khóa API của bạn qua tiêu đề X-Api-Key. Tạo khóa từ trang Khóa API trong bảng điều khiển của bạn.

Có giới hạn tốc độ API không?

Không. IPFS Ninja không áp đặt giới hạn tốc độ cho yêu cầu API. Bạn có thể thực hiện bao nhiêu yêu cầu tùy thích trên bất kỳ gói nào.

Khóa API có hết hạn không?

Không. Khóa API có hiệu lực cho đến khi bạn xóa chúng. Bạn có thể tạo nhiều khóa và thu hồi chúng riêng lẻ.

Sự khác biệt giữa khóa API và token gateway là gì?

Khóa API (bws_) có quyền truy cập đầy đủ -- tải lên, xóa, liệt kê tệp. Token gateway (gwt_) chỉ đọc và chỉ có thể truy cập tệp thông qua gateway chuyên dụng của bạn. Token gateway an toàn để nhúng vào ứng dụng frontend.

Gateway Chuyên dụng

Gateway chuyên dụng là gì?

Một gateway IPFS riêng tư tại tên miền phụ của bạn (ví dụ: abc123.gw.ipfs.ninja) chỉ phục vụ các tệp được ghim vào tài khoản của bạn. Không giống gateway công cộng, nó sẽ không phân giải CID từ người dùng khác.

Gói nào bao gồm gateway chuyên dụng?

Gateway chuyên dụng có sẵn trên tất cả các gói trả phí (Bodhi $5/tháng, Karma $19/tháng, Nirvana $59/tháng). Hạn mức băng thông hàng tháng của mỗi gói bao gồm lưu lượng từ cả gateway apex và gateway chuyên dụng. Xem "Có phí băng thông không?" bên dưới để biết hạn mức theo từng gói.

Tôi có thể hạn chế ai truy cập gateway của mình không?

Có. Bạn có thể bật chế độ yêu cầu token (yêu cầu token gwt_ cho mỗi yêu cầu) và/hoặc thiết lập danh sách trắng IP (tối đa 100 địa chỉ).

Tôi có thể hạn chế gateway theo nguồn gốc/miền không?

Có. Cấu hình allowedOrigins trong cài đặt gateway với danh sách các nguồn gốc HTTPS. Chỉ các yêu cầu trình duyệt từ những nguồn gốc đó mới được cho phép. Các yêu cầu không phải trình duyệt (không có tiêu đề Origin) đi qua mà không bị hạn chế. Danh sách trống cho phép tất cả nguồn gốc.

Token tải lên có chữ ký là gì?

Token tải lên có chữ ký là thông tin xác thực có thời hạn cho tải lên phía client. Bạn tạo chúng trên máy chủ bằng POST /upload/signed-url và chuyển cho trình duyệt hoặc ứng dụng di động. Client xác thực bằng Authorization: Signed <token> thay vì lộ khóa API. Mỗi token theo dõi việc sử dụng và tự động hết hạn. Xem tài liệu Token có chữ ký để biết chi tiết.

Tôi có thể tối ưu hóa hình ảnh được phục vụ từ IPFS không?

Có. Sử dụng GET /image/:cid với các tham số truy vấn như w, h, format và quality để thay đổi kích thước, chuyển đổi và nén hình ảnh trực tiếp. Phản hồi được lưu vào bộ nhớ đệm dựa trên CID định địa chỉ theo nội dung. Hoạt động trên tất cả các gói. Xem Tối ưu hóa hình ảnh.

Tôi có thể đính kèm siêu dữ liệu vào tệp không?

Có. Bao gồm một đối tượng metadata với tối đa 10 cặp khóa-giá trị khi tải lên qua POST /upload/new hoặc ghim qua POST /pin. Siêu dữ liệu được trả về trong danh sách tệp và endpoint chi tiết tệp. Xem tài liệu Tệp và Ghim.

Thanh toán & Gói đăng ký

Có gói miễn phí không?

Có. Gói Dharma miễn phí mãi mãi -- 1 GB dung lượng lưu trữ, yêu cầu API không giới hạn, không cần thẻ tín dụng.

Có phí băng thông không?

Không có phí băng thông theo mức sử dụng trên bất kỳ gói nào. Mỗi gói bao gồm một hạn mức băng thông gateway hàng tháng là giới hạn cứng — nội dung của bạn ngừng phục vụ trên cả gateway apex và gateway chuyên dụng khi đạt hạn mức, và tiếp tục vào ngày 1 tháng tiếp theo hoặc sau khi nâng cấp:

Gói	Băng thông hàng tháng
Dharma	2 GB
Bodhi	20 GB
Karma	100 GB
Nirvana	500 GB

Bạn sẽ nhận được email cảnh báo khi đạt 80% và 100% hạn mức của mình.

Dung lượng lưu trữ có đặt lại không?

Dung lượng lưu trữ không đặt lại. Gói của bạn bao gồm tổng dung lượng lưu trữ (Dharma 1 GB / Bodhi 10 GB / Karma 100 GB / Nirvana 1 TB). Để giải phóng dung lượng, hãy xóa các tệp bạn không còn cần. Nâng cấp gói sẽ tăng tổng dung lượng của bạn.

Tôi có thể hủy bất cứ lúc nào không?

Có. Hủy đăng ký thông qua cổng thanh toán -- không ràng buộc. Tài khoản của bạn trở về gói miễn phí và các tệp đã ghim vẫn có thể truy cập.

Điều gì xảy ra với tệp của tôi nếu tôi hạ cấp?

Tệp của bạn vẫn được ghim trên IPFS, nhưng bạn không thể tải lên thêm nếu việc sử dụng hiện tại vượt quá giới hạn lưu trữ của gói mới. Xóa tệp để quay lại dưới giới hạn.

Bảo mật

Dữ liệu của tôi có được mã hóa không?

Tất cả dữ liệu được mã hóa khi truyền qua TLS/HTTPS. Xác thực sử dụng token JWT (Cognito) và khóa API được lưu trữ an toàn. Nội dung tệp trên IPFS không được mã hóa ở trạng thái nghỉ -- IPFS là mạng công cộng theo thiết kế.

Có an toàn khi sử dụng khóa API trong mã phía máy chủ không?

Có. Khóa API được thiết kế cho sử dụng phía máy chủ. Không bao giờ để lộ chúng trong mã phía client. Để truy cập tệp phía client, sử dụng token gateway (gwt_) chỉ đọc.

Hỗ trợ

Làm thế nào để được trợ giúp?

Gửi email đến info@ipfs.ninja hoặc xem tài liệu Tham chiếu API.

Có SLA không?

Chúng tôi nỗ lực để đạt độ khả dụng cao nhưng hiện tại không cung cấp SLA chính thức. Dịch vụ được cung cấp trên cơ sở "nguyên trạng".