FAQ

Часто задаваемые вопросы об IPFS Ninja.

Общие вопросы

Что такое IPFS Ninja?

IPFS Ninja — это управляемый сервис закрепления IPFS. Вы загружаете любой файл через простой REST API или закрепляете существующие CID из сети IPFS. Каждый файл получает постоянный идентификатор содержимого (CID) и доступен через наш шлюз по адресу 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, так и на 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. Если вам нужен приватный доступ, используйте выделенный шлюз с режимом обязательного токена — это ограничивает доступ через ваш шлюз, хотя контент остаётся доступным в более широкой сети IPFS.

Почему мои новые CID изменились с Qm... на bafy...?

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

Устаревшие CID Qm… из более ранних загрузок остаются полностью разрешимыми — шлюз, 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-ключами и токенами шлюза?

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

Выделенные шлюзы

Что такое выделенный шлюз?

Приватный шлюз IPFS на вашем собственном поддомене (например, abc123.gw.ipfs.ninja), который обслуживает только файлы, закреплённые в вашем аккаунте. В отличие от публичного шлюза, он не разрешает CID других пользователей.

Какие планы включают выделенный шлюз?

Выделенные шлюзы доступны на всех платных планах (Bodhi $5/мес., Karma $19/мес., Nirvana $59/мес.). Ежемесячная квота пропускной способности каждого плана покрывает трафик как apex-, так и выделенного шлюза. См. «Есть ли плата за пропускную способность?» ниже для квот по каждому плану.

Могу ли я ограничить доступ к моему шлюзу?

Да. Вы можете включить режим обязательного токена (требует токен gwt_ при каждом запросе) и/или настроить белый список IP (до 100 адресов).

Могу ли я ограничить шлюз по источнику/домену?

Да. Настройте allowedOrigins в настройках шлюза со списком 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-запросы, кредитная карта не требуется.

Есть ли плата за пропускную способность?

Нет тарифицируемой платы за пропускную способность ни на одном из планов. Каждый план включает ежемесячную квоту пропускной способности шлюза, являющуюся жёстким лимитом — обслуживание вашего контента через apex- и выделенный шлюз останавливается по достижении квоты и возобновляется 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-ключи предназначены для серверного использования. Никогда не раскрывайте их в клиентском коде. Для клиентского доступа к файлам используйте токены шлюза (gwt_), которые доступны только для чтения.

Поддержка

Как получить помощь?

Напишите на info@ipfs.ninja или изучите документацию Справочника API.

Есть ли SLA?

Мы стремимся к высокой доступности, но в настоящее время не предлагаем формального SLA. Сервис предоставляется «как есть».