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

Пользователи плана Nirvana получают приватный шлюз IPFS на уникальном поддомене. Этот шлюз обслуживает только файлы, закреплённые в вашем аккаунте — он не разрешает CID других пользователей или публичной сети IPFS.

URL вашего шлюза

URL вашего шлюза показан на странице шлюза и возвращается конечной точкой /user/profile:

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

Режимы доступа

Режим	Поведение
Открытый (по умолчанию)	Любой, у кого есть URL вашего шлюза и CID, может получить доступ к вашим файлам. Токен не требуется.
Токен обязателен	Запросы должны включать токен шлюза через параметр ?token=gwt_... или заголовок X-Gateway-Token.

Лимиты

• 50 ГБ/мес. пропускной способности шлюза включено в план Nirvana
• При достижении лимита пропускной способности запросы к шлюзу возвращают 429 до следующего месяца
• Использование хранилища сбрасывается первого числа каждого месяца
• Обслуживаются только CID, закреплённые в вашем аккаунте — запросы других CID возвращают 403

Apex-шлюз

Общий apex-шлюз по адресу https://ipfs.ninja/ipfs/<CID> доступен во всех планах и не требует аутентификации, но обслуживает только CID, которые были загружены или закреплены пользователем IPFS Ninja. Запросы для любых других CID возвращают HTTP 410 Gone.

Для CID, который вам не принадлежит, можно либо (а) выполнить POST /pin, чтобы закрепить его за вашим аккаунтом, а затем использовать apex URL, либо (б) использовать сторонний шлюз, такой как https://ipfs.io/ipfs/<CID> или https://dweb.link/ipfs/<CID>.

Для встраивания на уровне продакшена (видео, NFT-просмотрщики, сайты) рекомендуемая модель — выделенный шлюз выше — он предлагает более высокие лимиты скорости, настраиваемые элементы управления доступом и выделенную пропускную способность.

Настройки шлюза

Настройте контроль доступа для вашего выделенного шлюза.

Обновить настройки

PUT /gateway-settings

Параметр	Тип	Обязательный	Описание
tokenRequired	boolean	Нет	Включить/отключить обязательный токен шлюза.
ipWhitelist	string[]	Нет	Массив разрешённых IP-адресов. Максимум 100. Пустой массив удаляет белый список.
allowedOrigins	string[]	Нет	Массив разрешённых источников для браузерных запросов. Максимум 100. Должен использовать формат HTTPS (например, https://myapp.com). Пустой массив разрешает все источники.

Примеры

# Включить режим обязательного токена
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}'

# Установить белый список 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"]}'

# Очистить белый список IP (разрешить все 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": []}'

# Ограничить определёнными источниками
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"]}'

# Удалить ограничения по источнику (разрешить все источники)
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": []}'

Ограничения по источнику

Когда allowedOrigins настроен, разрешаются только браузерные запросы от указанных источников. Шлюз проверяет заголовки Origin и Referer входящих запросов.

• Если список пуст (по умолчанию), разрешены все источники.
• Если источники указаны, запросы с заголовком Origin или Referer, не совпадающим ни с одной записью, отклоняются с ответом 403.
• Не-браузерные запросы без заголовка Origin (такие как серверные запросы или curl) проходят без ограничений.

Это полезно для встраивания контента шлюза в ваше веб-приложение с предотвращением хотлинкинга файлов другими сайтами.

Токены шлюза

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

Возможность	API-ключ (bws_)	Токен шлюза (gwt_)
Загрузка / удаление файлов	Да	Нет
Просмотр / получение метаданных файлов	Да	Нет
Чтение файлов через шлюз	Нет	Да
Безопасно для встраивания во фронтенд	Нет	Да

Создать токен шлюза

POST /gateway-tokens

Параметр	Тип	Обязательный	Описание
name	string	Нет	Метка для токена (например, "Frontend"). По умолчанию "Default".

Ответ 201 Created

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

WARNING

Полный токен возвращается только один раз при создании. Сохраните его в безопасном месте.

Список токенов шлюза

GET /gateway-tokens

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

Удалить токен шлюза

DELETE /gateway-tokens/:prefix

Параметр	Тип	Обязательный	Описание
prefix	string	Да	Префикс токена для удаления (например, "gwt_a1b2c3d4").

Использование токена шлюза

Когда ваш шлюз работает в режиме обязательного токена, передайте токен как параметр запроса или заголовок:

# Параметр запроса
curl "https://a1b2c3d4.gw.ipfs.ninja/ipfs/QmXk7VRz...?token=gwt_your_token"

# Или заголовок
curl https://a1b2c3d4.gw.ipfs.ninja/ipfs/QmXk7VRz... \
  -H "X-Gateway-Token: gwt_your_token"