FAQ

Często zadawane pytania dotyczące IPFS Ninja.

Ogólne

Czym jest IPFS Ninja?

IPFS Ninja to zarządzana usługa przypinania IPFS. Przesyłasz dowolny plik przez proste API REST lub przypinasz istniejące CID z sieci IPFS. Każdy plik otrzymuje stały identyfikator treści (CID) i jest dostępny przez naszą bramkę pod ipfs.ninja/ipfs/<CID>.

Czy ipfs.ninja/ipfs/<CID> obsługuje dowolny CID w sieci IPFS?

Nie. Bramka apex obsługuje tylko CID-y, które zostały przesłane lub przypięte przez użytkownika IPFS Ninja. Żądania dotyczące nieznanych CID-ów zwracają HTTP 410 Gone ze wskaźnikiem do publicznych bramek IPFS (ipfs.io, dweb.link). Aby udostępniać CID osoby trzeciej przez naszą bramkę, najpierw wykonaj POST /pin na swoje konto — po przypięciu CID jest dostępny zarówno pod adresem apex, jak i Twojej dedykowanej bramki.

Jaka jest różnica między bramką apex a bramką dedykowaną?

Aspekt	Apex ipfs.ninja/ipfs/<CID>	Dedykowana <slug>.gw.ipfs.ninja/ipfs/<CID>
Zakres	Współdzielona przez wszystkich użytkowników	Tylko Twoje CID-y
Uwierzytelnianie	Brak	Opcjonalny token / lista IP / lista źródeł
SLA	Best-effort	Pełne SLA
Zalecane do	Linków okazjonalnych	Osadzania produkcyjnego (NFT, wideo, strony)
Limity szybkości	Współdzielone per IP + per CID	Per plan, konfigurowalne

Obie obsługują identyczną zawartość. Do ruchu produkcyjnego użyj bramki dedykowanej.

Jakie typy plików są obsługiwane?

Wszystkie typy plików są obsługiwane. Obiekty i tablice JSON można wysyłać bezpośrednio. Wszystkie inne pliki (obrazy, PDF, HTML, wideo, audio, binarne) są wysyłane jako treść zakodowana w base64.

Czy jest limit rozmiaru pliku?

Poszczególne przesyłania są ograniczone limitem przechowywania twojego planu. Nie ma limitu rozmiaru na plik poza dostępną przestrzenią.

Czy mogę przypiąć treść już istniejącą na IPFS?

Tak. Użyj POST /pin z dowolnym prawidłowym CID. Nasz klaster pobierze treść z sieci IPFS i przypnie ją do twojego konta. Zobacz dokumentację API Przypinania po szczegóły.

Ile trwa przypinanie?

Zależy od rozmiaru pliku i liczby węzłów IPFS posiadających treść. Małe, dobrze rozproszone pliki są przypinane w sekundach. Duża lub rzadko przypinana treść może zająć kilka minut. Endpoint przypinania zwraca natychmiast ze statusem pinning — odpytuj GET /pin/:cid, aby sprawdzić postęp.

Co się stanie, jeśli CID nie zostanie znaleziony?

Status zmienia się na failed. Oznacza to, że CID jest nieprawidłowy lub treść nie jest już dostępna na żadnym osiągalnym węźle IPFS.

Czy dane przesłane do IPFS są publiczne?

Tak. Cała treść przypięta na IPFS jest publicznie dostępna przez jej CID z dowolnej bramki IPFS. Jeśli potrzebujesz prywatnego dostępu, użyj dedykowanej bramki z trybem wymaganego tokenu — ogranicza to dostęp przez twoją bramkę, choć treść pozostaje dostępna w szerszej sieci IPFS.

Dlaczego moje nowe CID-y zmieniły się z Qm... na bafy...?

Nowe przesłania i przypięcia zwracają nowoczesne CIDv1 (bafk… dla małej, jednoblokowej treści, bafy… dla większych plików i katalogów) zgodnie z profilem IPIP-0499 unixfs-v1-2025: kodowanie base32 CIDv1, fragmenty 1 MiB, surowe liście (raw leaves). Odpowiada to temu, co produkują nowoczesne narzędzia (Helia, najnowsze Kubo, ipfs-car) dla tej samej treści, więc plik przesłany przez nas otrzymuje ten sam CID, jaki obliczyłby dowolny nowoczesny klient dla tych samych bajtów.

Starsze CID-y Qm… z wcześniejszych przesłań pozostają w pełni rozwiązywalne — bramka, POST /pin, GET /file, IPNS i każdy inny endpoint akceptują oba formaty bezterminowo. Nic z tego, co już masz, nie przestaje działać.

Jak przypiąć treść znajdującą się na prywatnym / nie-DHT węźle?

POST /pin akceptuje opcjonalne multiaddresses[] (do 5). Jeśli je podasz, nasz klaster wykonuje ipfs swarm connect <multiaddr> dla każdej wskazówki przed uruchomieniem przypięcia, dzięki czemu treść na peerach nieogłaszających się przez publiczne DHT (prywatne węzły, środowiska stagingowe, maszyny lokalne w VPN) jest osiągalna. Zobacz przewodnik Przypinanie z prywatnego węzła IPFS.

Czy moje pliki pozostaną na IPFS, jeśli anuluję konto?

Odpinamy twoje pliki z naszych węzłów po anulowaniu. Jeśli inne węzły IPFS mają w pamięci podręcznej twoją treść, może nadal być dostępna. Jednak bez aktywnego przypinania pliki zostaną ostatecznie usunięte przez zbieranie śmieci w sieci.

Autentykacja i API

Jak uwierzytelnić żądania API?

Przekaż klucz API przez nagłówek X-Api-Key. Wygeneruj klucze ze strony Klucze API w panelu.

Czy są limity szybkości API?

Nie. IPFS Ninja nie narzuca limitów szybkości na żądania API. Możesz wykonywać dowolną liczbę żądań na każdym planie.

Czy klucze API wygasają?

Nie. Klucze API są ważne do momentu ich usunięcia. Możesz tworzyć wiele kluczy i odwoływać je pojedynczo.

Jaka jest różnica między kluczami API a tokenami bramki?

Klucze API (bws_) mają pełny dostęp — przesyłanie, usuwanie, wyświetlanie plików. Tokeny bramki (gwt_) są tylko do odczytu i mogą uzyskiwać dostęp do plików tylko przez dedykowaną bramkę. Tokeny bramki są bezpieczne do osadzania w aplikacjach frontendowych.

Dedykowane bramki

Czym jest dedykowana bramka?

Prywatna bramka IPFS na twojej subdomenie (np. abc123.gw.ipfs.ninja), która obsługuje tylko pliki przypięte do twojego konta. W przeciwieństwie do publicznej bramki, nie będzie rozwiązywać CID innych użytkowników.

Które plany obejmują dedykowaną bramkę?

Dedykowane bramki są dostępne we wszystkich płatnych planach (Bodhi 5 USD/miesiąc, Karma 19 USD/miesiąc, Nirvana 59 USD/miesiąc). Miesięczny limit przepustowości każdego planu obejmuje ruch zarówno z bramki apex, jak i bramki dedykowanej. Zobacz „Czy są opłaty za przepustowość?” poniżej po limity dla poszczególnych planów.

Czy mogę ograniczyć, kto ma dostęp do mojej bramki?

Tak. Możesz włączyć tryb wymaganego tokenu (wymaga tokenu gwt_ przy każdym żądaniu) i/lub ustawić białą listę IP (do 100 adresów).

Czy mogę ograniczyć bramkę według pochodzenia/domeny?

Tak. Skonfiguruj allowedOrigins w ustawieniach bramki z listą źródeł HTTPS. Tylko żądania przeglądarki z tych źródeł będą dozwolone. Żądania spoza przeglądarki (bez nagłówka Origin) przechodzą bez ograniczeń. Pusta lista zezwala na wszystkie źródła.

Czym są podpisane tokeny przesyłania?

Podpisane tokeny przesyłania to poświadczenia z ograniczonym czasem do przesyłania po stronie klienta. Generujesz je na serwerze za pomocą POST /upload/signed-url i przekazujesz przeglądarkom lub aplikacjom mobilnym. Klient uwierzytelnia się za pomocą Authorization: Signed <token> zamiast ujawniać klucz API. Każdy token śledzi użycie i automatycznie wygasa. Zobacz dokumentację Podpisanych tokenów po szczegóły.

Czy mogę optymalizować obrazy serwowane z IPFS?

Tak. Użyj GET /image/:cid z parametrami zapytania jak w, h, format i quality, aby zmieniać rozmiar, konwertować i kompresować obrazy w locie. Odpowiedzi są buforowane na podstawie CID z adresowaniem treści. Działa na wszystkich planach. Zobacz Optymalizacja obrazów.

Czy mogę dołączać metadane do plików?

Tak. Dołącz obiekt metadata z maksymalnie 10 parami klucz-wartość podczas przesyłania przez POST /upload/new lub przypinania przez POST /pin. Metadane są zwracane w listach plików i endpoincie szczegółów pliku. Zobacz dokumentację Pliki i Przypinanie.

Płatności i plany

Czy jest darmowy plan?

Tak. Plan Dharma jest darmowy na zawsze — 1 GB pamięci, nieograniczone żądania API, bez karty kredytowej.

Czy są opłaty za przepustowość?

Brak opłat za mierzoną przepustowość na żadnym planie. Każdy plan zawiera miesięczny limit przepustowości bramki, który jest twardym limitem — Twoja treść przestaje być serwowana przez bramkę apex i bramkę dedykowaną po osiągnięciu limitu i wraca 1. dnia następnego miesiąca lub po ulepszeniu planu:

Plan	Miesięczna przepustowość
Dharma	2 GB
Bodhi	20 GB
Karma	100 GB
Nirvana	500 GB

Otrzymasz e-maile ostrzegawcze przy 80% i 100% limitu.

Czy pamięć się resetuje?

Pamięć się nie resetuje. Twój plan zawiera łączny limit przechowywania (Dharma 1 GB / Bodhi 10 GB / Karma 100 GB / Nirvana 1 TB). Aby zwolnić miejsce, usuń pliki, których już nie potrzebujesz. Ulepszenie planu zwiększa łączny limit.

Czy mogę anulować w dowolnym momencie?

Tak. Anuluj subskrypcję przez portal płatności — bez zobowiązań. Twoje konto wraca do darmowego poziomu, a istniejące przypięte pliki pozostają dostępne.

Co się stanie z moimi plikami po obniżeniu planu?

Twoje pliki pozostają przypięte na IPFS, ale nie możesz przesyłać więcej, jeśli obecne użycie przekracza limit przechowywania nowego planu. Usuń pliki, aby zmieścić się w limicie.

Bezpieczeństwo

Czy moje dane są szyfrowane?

Wszystkie dane są szyfrowane podczas transmisji przez TLS/HTTPS. Autentykacja wykorzystuje tokeny JWT (Cognito) i bezpiecznie przechowywane klucze API. Treść plików na IPFS nie jest szyfrowana w spoczynku — IPFS jest publiczną siecią z założenia.

Czy bezpiecznie jest używać kluczy API w kodzie serwerowym?

Tak. Klucze API są przeznaczone do użytku po stronie serwera. Nigdy nie ujawniaj ich w kodzie po stronie klienta. Dla dostępu do plików po stronie klienta używaj tokenów bramki (gwt_), które są tylko do odczytu.

Wsparcie

Jak mogę uzyskać pomoc?

Napisz na info@ipfs.ninja lub sprawdź dokumentację API.

Czy jest SLA?

Dążymy do wysokiej dostępności, ale obecnie nie oferujemy formalnego SLA. Usługa jest świadczona w stanie „takim, jaki jest".