FAQ

Често задавани въпроси за IPFS Ninja.

Общи

Какво е IPFS Ninja?

IPFS Ninja е управлявана услуга за закачане в IPFS. Качвате произволен файл чрез прост REST API или закачате съществуващи CID от IPFS мрежата. Всеки файл получава постоянен идентификатор на съдържанието (CID) и е достъпен чрез нашия gateway на ipfs.ninja/ipfs/<CID>.

Обслужва ли ipfs.ninja/ipfs/<CID> всеки CID в IPFS мрежата?

Не. Apex шлюзът обслужва само CID-ове, които са качени или закачени от потребител на IPFS Ninja. Заявките за непознати CID-ове връщат HTTP 410 Gone с указател към публични IPFS шлюзове (ipfs.io, dweb.link). За да обслужите CID на трета страна чрез нашия шлюз, първо изпълнете POST /pin към акаунта си — след закачването CID-ът става достъпен както на apex, така и на URL-а на вашия специализиран шлюз.

Каква е разликата между apex шлюза и специализирания шлюз?

Аспект	Apex ipfs.ninja/ipfs/<CID>	Специализиран <slug>.gw.ipfs.ninja/ipfs/<CID>
Обхват	Споделен между всички потребители	Само вашите CID-ове
Удостоверяване	Няма	Опционален токен / IP allowlist / origin allowlist
SLA	Best-effort	Пълно SLA
Препоръчва се за	Случайни връзки	Продукционно вграждане (NFT, видео, сайтове)
Ограничения на скоростта	Споделени по IP + по CID	По план, конфигурируеми

И двете обслужват идентично съдържание. За продукционен трафик използвайте специализирания шлюз.

Какви типове файлове се поддържат?

Всички типове файлове се поддържат. JSON обекти и масиви могат да се изпращат директно. Всички останали файлове (изображения, PDF, HTML, видео, аудио, двоични файлове) се изпращат като base64-кодирано съдържание.

Има ли ограничение на размера на файла?

Отделните качвания са ограничени от лимита за съхранение на вашия план. Няма ограничение на размера на отделен файл отвъд наличното ви съхранение.

Мога ли да закача съдържание, което вече съществува в IPFS?

Да. Използвайте POST /pin с произволен валиден CID. Нашият клъстер ще извлече съдържанието от IPFS мрежата и ще го закачи към вашия акаунт. Вижте документацията на Pinning API за подробности.

Колко време отнема закачането?

Зависи от размера на файла и колко IPFS възли имат съдържанието. Малки, добре разпределени файлове се закачат за секунди. Голямо или рядко закачано съдържание може да отнеме няколко минути. Крайната точка за закачане връща незабавно със статус pinning — проверявайте GET /pin/:cid за напредъка.

Какво се случва, ако CID не може да бъде намерен?

Статусът се променя на failed. Това означава, че CID е невалиден или съдържанието вече не е налично на нито един достъпен IPFS възел.

Публични ли са данните, качени в IPFS?

Да. Цялото съдържание, закачено в IPFS, е публично достъпно чрез неговия CID през произволен IPFS gateway. Ако се нуждаете от частен достъп, използвайте специализиран gateway с режим на задължителен токен — това ограничава достъпа чрез вашия gateway, въпреки че съдържанието остава достъпно в по-широката IPFS мрежа.

Защо новите ми CID се промениха от Qm... на bafy...?

Новите качвания и закачания връщат модерен CIDv1 (bafk… за малко съдържание в един блок, bafy… за по-големи файлове и директории) съгласно профила IPIP-0499 unixfs-v1-2025: base32 кодиране на CIDv1, части от 1 MiB, сурови листа. Това съответства на това, което произвежда съвременният инструментариум (Helia, последен Kubo, ipfs-car) за същото съдържание, така че файл, качен през нас, получава същия CID, който би изчислил всеки съвременен клиент за същите байтове.

По-старите CID-ове Qm… от предишни качвания остават напълно разрешими — gateway, POST /pin, GET /file, IPNS и всяка друга крайна точка приемат и двата формата за неопределено време. Нищо, което вече имате, не спира да работи.

Как закачам съдържание, което живее на частен/не-DHT възел?

POST /pin приема опционален multiaddresses[] (до 5). Ако е предоставен, нашият клъстер изпълнява ipfs swarm connect <multiaddr> за всяка подсказка преди да стартира закачането, така че съдържание на пиъри, които не се рекламират чрез публичния DHT (частни възли, staging среди, VPN-локални машини), е достъпно. Вижте ръководството Закачане от частен IPFS възел.

Ще останат ли файловете ми в IPFS, ако отменя акаунта си?

При отмяна откачаме файловете ви от нашите възли. Ако други IPFS възли са кеширали вашето съдържание, то може да остане достъпно. Без активно закачане обаче файловете в крайна сметка ще бъдат премахнати чрез събиране на боклук в цялата мрежа.

Удостоверяване и API

Как удостоверявам API заявки?

Предайте вашия API ключ чрез заглавието X-Api-Key. Генерирайте ключове от страницата API ключове в таблото за управление.

Има ли ограничения на скоростта на API?

Не. IPFS Ninja не налага ограничения на скоростта за API заявки. Можете да правите толкова заявки, колкото ви е необходимо, на всеки план.

Изтичат ли API ключовете?

Не. API ключовете са валидни, докато не ги изтриете. Можете да създавате множество ключове и да ги отменяте поединично.

Каква е разликата между API ключове и токени за gateway?

API ключовете (bws_) имат пълен достъп — качване, изтриване, списък на файлове. Токените за gateway (gwt_) са само за четене и могат да достъпват файлове само чрез вашия специализиран gateway. Токените за gateway е безопасно да се вграждат във frontend приложения.

Специализирани gateway-и

Какво е специализиран gateway?

Частен IPFS gateway на ваш собствен поддомейн (напр. abc123.gw.ipfs.ninja), който обслужва само файлове, закачени към вашия акаунт. За разлика от публичния gateway, той няма да разрешава CID от други потребители.

Кои планове включват специализиран gateway?

Специализираните gateway-и са налични във всички платени планове (Bodhi — $5/месец, Karma — $19/месец, Nirvana — $59/месец). Месечната квота за честотна лента на gateway на всеки план покрива трафика както от apex, така и от специализирания gateway. Вижте "Има ли такси за честотна лента?" по-долу за квотите на всеки план.

Мога ли да огранича кой достъпва моя gateway?

Да. Можете да активирате режим на задължителен токен (изисква gwt_ токен при всяка заявка) и/или да зададете бял списък с IP адреси (до 100 адреса).

Мога ли да огранича моя gateway по произход/домейн?

Да. Конфигурирайте allowedOrigins в настройките на gateway със списък от HTTPS произходи. Само заявки от браузъри от тези произходи ще бъдат разрешени. Заявки извън браузъра (без заглавие Origin) преминават без ограничение. Празен списък разрешава всички произходи.

Какво представляват подписаните токени за качване?

Подписаните токени за качване са удостоверения с ограничен срок за качване от страна на клиента. Генерирате ги на вашия сървър чрез POST /upload/signed-url и ги предавате на браузъри или мобилни приложения. Клиентът се удостоверява с Authorization: Signed <token> вместо да разкрива вашия API ключ. Всеки токен проследява използването и автоматично изтича. Вижте документацията за Подписани токени за подробности.

Мога ли да оптимизирам изображения, обслужвани от IPFS?

Да. Използвайте GET /image/:cid с параметри на заявката като w, h, format и quality за преоразмеряване, конвертиране и компресиране на изображения в движение. Отговорите се кешират на базата на CID, адресиран по съдържание. Работи на всички планове. Вижте Оптимизация на изображения.

Мога ли да прикача метаданни към файлове?

Да. Включете обект metadata с до 10 двойки ключ-стойност при качване чрез POST /upload/new или закачане чрез POST /pin. Метаданните се връщат в списъците с файлове и в крайната точка за детайли на файла. Вижте документацията за Файлове и Закачане.

Фактуриране и планове

Има ли безплатен план?

Да. Планът Dharma е безплатен завинаги — 1 GB съхранение, неограничени API заявки, без нужда от кредитна карта.

Има ли такси за честотна лента?

Няма такси за отчитана по обем честотна лента на никой план. Всеки план включва месечна квота за честотна лента на gateway, която е твърд лимит — съдържанието ви спира да се обслужва на apex и специализирания gateway, след като квотата бъде достигната, и се възобновява на 1-во число на следващия месец или след надграждане:

План	Месечна честотна лента
Dharma	2 GB
Bodhi	20 GB
Karma	100 GB
Nirvana	500 GB

Ще получите предупредителни имейли при 80% и 100% от квотата си.

Нулира ли се съхранението?

Съхранението не се нулира. Вашият план включва общ лимит за съхранение (Dharma 1 GB / Bodhi 10 GB / Karma 100 GB / Nirvana 1 TB). За освобождаване на място изтрийте файлове, от които вече не се нуждаете. Надграждането на плана увеличава общия ви лимит.

Мога ли да отменя по всяко време?

Да. Отменете абонамента си чрез портала за фактуриране — без обвързване. Акаунтът ви се връща към безплатното ниво, а съществуващите закачени файлове остават достъпни.

Какво се случва с файловете ми, ако понижа плана?

Файловете ви остават закачени в IPFS, но не можете да качвате повече, ако текущото ви използване надвишава лимита за съхранение на новия план. Изтрийте файлове, за да се върнете под лимита.

Сигурност

Криптирани ли са данните ми?

Всички данни са криптирани при пренос чрез TLS/HTTPS. Удостоверяването използва JWT токени (Cognito) и сигурно съхранени API ключове. Съдържанието на файловете в IPFS не е криптирано в покой — IPFS е публична мрежа по проект.

Безопасно ли е да използвам API ключове в моя сървърен код?

Да. API ключовете са проектирани за използване от страна на сървъра. Никога не ги излагайте в код от страна на клиента. За достъп до файлове от страна на клиента използвайте токени за gateway (gwt_), които са само за четене.

Поддръжка

Как мога да получа помощ?

Изпратете имейл на info@ipfs.ninja или прегледайте документацията Справка за API.

Има ли SLA?

Стремим се към висока наличност, но в момента не предлагаме формално SLA. Услугата се предоставя на база „такава, каквато е".