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

Пользователи плана 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

TIP

Публичный шлюз по адресу ipfs.ninja/ipfs/ остаётся доступным на всех планах и обслуживает любой CID без аутентификации.

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

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

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

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"