Когда говорят «настроить API Key в Dify», речь может идти о совершенно разных вещах: о ключе провайдера, которым Dify вызывает модель, о ключе доступа, которым бизнес-система вызывает приложение Dify, или о Service API Key базы знаний. У них разные места создания, области прав и последствия утечки. Самое частое следствие путаницы: ключ провайдера попадает во фронтенд, вызывающей стороне выдаётся слишком широкий ключ приложения или при ротации меняют не тот объект, и весь продакшен получает 401.

Названия интерфейса и детали прав могут меняться от версии к версии — сверяйтесь с текущим интерфейсом и документацией вашего экземпляра.

Примечание: Dify — товарный знак его правообладателя LangGenius, Inc.; материал носит независимый технический характер и не означает подчинения или агентских отношений с командой Dify.

1. Сначала разделите три типа ключей

Разграничим их таблицей.

Тип ключа Назначение Где создать Область прав Кто управляет
Ключ провайдера моделей Dify вызывает upstream-модель Настройки → Провайдеры моделей → нужный провайдер Общий для всего рабочего пространства Owner, Admin
API Key приложения Внешняя система вызывает приложение Dify Приложение → Доступ к API Одно приложение, охватывает всех его конечных пользователей Editor и выше
Service Key базы знаний Внешняя система вызывает API базы знаний База знаний → Service API Можно ограничить конкретными базами знаний Editor и выше

Они не взаимозаменяемы: ключ провайдера не может вызывать интерфейс приложения, а ключ приложения не может заставить Dify обратиться к модели. Перед диагностикой определите, какой именно ключ у вас в руках.

2. Ключ провайдера моделей: уровень рабочего пространства, настройка администратора

Ключ провайдера — конфигурация уровня рабочего пространства; он добавляется в настройках провайдеров моделей и используется Dify для запросов к upstream. При добавлении платформа сначала проверяет ключ, после чего он доступен всему рабочему пространству. Управлять могут только Owner и Admin; Editor и Normal этих настроек не видят.

Несколько деталей, которые легко упустить:

  • У одного провайдера можно хранить несколько ключей — для разработки, продакшена или разных аккаунтов; так проще разбирать счёт и отключать отдельный ключ.
  • Ключи пользовательских моделей управляются отдельно. Удаление последнего ключа удаляет и пользовательскую модель; если удалить только модель, ключ сохранится, и при повторном добавлении его не нужно вводить заново.
  • В тарифах Professional и Team поддерживается балансировка нескольких ключей одной модели. Когда ключ достигает лимита, платформа примерно на минуту перестаёт его использовать.
  • Если Cloud предоставляет AI credits, ключ провайдера можно не настраивать; можно совмещать оба варианта и через Usage Priority выбирать приоритет. При использовании своего ключа расход идёт в счёт вашего аккаунта провайдера.

Рекомендуем называть ключи по схеме «назначение — среда — ответственный»: в консоли провайдера обычно виден расход по каждому ключу, и при аномалии проще найти источник.

3. API Key приложения: только на бэкенде

API Key приложения решает другую задачу: как внешняя система вызывает уже опубликованное приложение. Он не участвует в выборе модели и не подходит для вызова модельного интерфейса. Типичный порядок:

  1. Откройте нужное приложение и перейдите на страницу доступа к API.
  2. Создайте ключ и назовите его по схеме «вызывающая сторона — среда — дата».
  3. Скопируйте в серверные переменные окружения или менеджер секретов; не вставляйте во фронтенд, репозиторий или переписку.
  4. Сначала вызовите GET /info и проверьте, что ключ соответствует приложению.
  5. Затем вызывайте интерфейсы по типу приложения — у разных типов они различаются.
  6. После запуска зафиксируйте приложение, ответственного и дату создания ключа.
# Базовый адрес Dify Cloud; при self-hosting замените на адрес своего экземпляра
export DIFY_BASE_URL="https://api.dify.ai/v1"
export DIFY_APP_KEY="ваш-ключ-приложения"

curl "$DIFY_BASE_URL/info" \
  -H "Authorization: Bearer $DIFY_APP_KEY"

Ответ с именем приложения, режимом и описанием означает, что ключ действителен. Учтите два момента: один ключ приложения действует для всех конечных пользователей этого приложения, поэтому пользователей различают полем user в теле запроса, но user — только идентификатор, а не аутентификация; кроме того, API приложения следует вызывать с бэкенда — документация прямо не рекомендует размещать ключ во фронтенде или клиентском коде.

4. Service Key базы знаний: ограничивайте область, где возможно

У базы знаний есть отдельный Service API Key; вход находится на странице Service API базы знаний и не пересекается с ключом приложения. При создании можно ограничить, к каким базам знаний ключ имеет доступ; ключ с доступом ко всем базам может также вызывать интерфейс списка баз.

Принцип минимальных прав: создавайте отдельный ключ каждому потребителю и отмечайте только нужные базы знаний, а не обслуживайте всех одним полным ключом. Утечка ключа базы знаний означает возможное чтение или запись данных, а не только расход модельной квоты, — риск выше.

5. Где хранятся секреты: .env, SECRET_KEY и шифрование рабочего пространства

В самостоятельном развёртывании секреты делятся на два уровня, и многие меняют только первый.

Первый — docker/.env, скопированный из .env.example; конфигурация в корне перекрывает одноимённые значения в docker/envs/*.env. Самый недооценённый параметр — SECRET_KEY: он участвует в подписи cookie сессии и JWT, в HMAC-SHA256-подписи URL файлов и в AES-256-шифровании учётных данных сторонних OAuth. Примерное значение обязательно замените; сгенерировать можно через openssl rand -base64 42.

Смена SECRET_KEY завершает сессии всех пользователей, делает ранее выданные ссылки на файлы недействительными, а учётные данные OAuth, зашифрованные старым значением, восстановить нельзя. Это не обычная плановая ротация: перед изменением оцените последствия и сделайте резервную копию.

Второй уровень — шифрование учётных данных рабочего пространства. Ключи провайдеров моделей и учётные данные инструментов шифруются RSA-ключом каждого рабочего пространства; закрытый ключ хранится в бэкенде, указанном в STORAGE_TYPE. KEY_PROVIDER_TYPE по умолчанию равен local, но можно подключить Azure Key Vault с автоматической ротацией. Этот выбор нужно сделать до создания первого рабочего пространства: шифротексты двух способов несовместимы, и переключение на середине делает существующие учётные данные нерасшифровываемыми — их придётся вводить заново.

В новых версиях в конфигурации Agent также есть DIFY_AGENT_SERVER_SECRET_KEY и DIFY_AGENT_API_TOKEN; значения по умолчанию для разработки общедоступны, и перед запуском в продакшен их обязательно заменяют. .env не коммитьте в репозиторий и ужесточайте права на файл по документации; при резервном копировании включайте ключевые материалы, иначе после восстановления среды учётные данные могут перестать работать.

В Cloud учётные данные провайдеров размещает платформа, SECRET_KEY администрировать не нужно, но всё равно используйте отдельный аккаунт или проектный ключ и сохраняйте записи на стороне провайдера.

6. Ротация, минимальные права и роли команды

Ротация нужна не только при утечке. Её планируют при увольнении сотрудника, смене вызывающей стороны, подозрении на утечку, требовании провайдера и по регулярному графику. Полный порядок:

  1. Создайте у провайдера или в Dify новый ключ с теми же правами и сначала запустите его параллельно со старым.
  2. Запишите новый ключ в менеджер секретов или переменные окружения и опубликуйте конфигурацию.
  3. Некоторое время наблюдайте за долей ошибок, числом вызовов и счётом провайдера, убедитесь, что трафик переключён.
  4. Отключите старый ключ, а не просто удалите его из конфигурации.
  5. Зафиксируйте время ротации, исполнителя и область влияния, обновите документ передачи.

В распределении ролей рабочее пространство обычно устроено так: Owner обладает полным контролем и он один; Admin управляет участниками и провайдерами моделей; Editor создаёт, редактирует и удаляет приложения и базы знаний; Normal пользуется только опубликованными приложениями. Правила могут быть простыми: ключи провайдеров остаются у Owner и Admin; ключи приложений передаются ответственным за бэкенд; ключи баз знаний дробятся по потребителям и ограничиваются по области. Editor может менять приложение и обычно имеет доступ к его API Key, поэтому «может редактировать приложение» не равно «может управлять всеми модельными ключами компании».

7. Частые ошибки и диагностика

Сначала определите тип ключа, затем проверяйте сеть и права.

  • 401 Unauthorized: ключ с опечаткой, отозван, содержит лишние пробелы или перевод строки, либо ключ провайдера используется как ключ приложения. Проверьте через GET /info.
  • 403 или нехватка прав: недостаточно роли или ключ базы знаний не включает нужную базу.
  • 404 Not Found: неверный Base URL. В Cloud — https://api.dify.ai/v1; при self-hosting — свой домен с окончанием /v1, без полного пути интерфейса.
  • Интерфейс сообщает о недоступности модели: ключ провайдера истёк, недостаточно средств или upstream ограничивает запросы; повторно проверьте в настройках провайдера.
  • 404/403 на API базы знаний: перепутаны ключ приложения и Service Key, либо база не входит в область доступа ключа.
  • 429 Too Many Requests: сработал лимит. Снизьте параллелизм и повторите с экспоненциальной задержкой.
  • После смены SECRET_KEY все отключились: ожидаемое поведение, см. предыдущий раздел; сначала оцените последствия и не возвращайте старое значение вслепую.

Ещё одно частое заблуждение: Dify развёрнут в контейнере или облаке, а в настройках указан localhost или внутренний адрес. Dify не достучится до вашего локального сервиса, и правильный ключ не поможет. Если бизнес-система не подключается к самостоятельному Dify, проверьте DNS, файрвол, обратный прокси и сертификаты.

Частые вопросы

Можно ли менять местами ключ провайдера моделей и API Key приложения?

Нет. Первый нужен Dify для вызова upstream-модели, второй — внешней системе для вызова приложения Dify. Интерфейсы, права и объекты тарификации различаются.

Можно ли создать несколько API Key для одного приложения?

Обычно да. Частая практика — разделять по средам или вызывающим сторонам, чтобы отдельно отключать и отслеживать. Точный вход — в интерфейсе текущей версии.

Можно ли ограничить API Key приложения конкретной базой знаний или пользователем?

Ключ приложения действует на уровне приложения и не делится по базам знаний; поле user служит только для различения конечных пользователей и не является механизмом аутентификации. Если нужны права по базам знаний, используйте Service API Key с отмеченной областью.

Повлияет ли смена SECRET_KEY на ключи провайдеров моделей?

Ключи провайдеров и инструментов шифруются RSA-ключом рабочего пространства, а не напрямую SECRET_KEY; но после смены пользователи выйдут из системы, ссылки на файлы перестанут работать, а учётные данные OAuth восстановить не удастся. Перед изменением в продакшене прочитайте документацию развёртывания и сделайте резервную копию.

После обновления self-hosting ключи внезапно перестали работать — что проверить?

Сравните .env.example и текущий .env на новые переменные, убедитесь, что KEY_PROVIDER_TYPE и бэкенд хранилища не изменились; если способ шифрования менялся, старые учётные данные не расшифровать — их придётся ввести заново. Затем посмотрите коды ошибок в логах приложения.

Что дальше

Управление ключами Dify сводится к трём тезисам: сначала разделите типы, затем выдавайте по минимальным правам и, наконец, сделайте ротацию регулярным процессом. Если нужен единый OpenAI-совместимый вход и централизованное управление вызовами моделей, начните с регистрации в ZSQH AI Gateway; состав моделей и цены — на странице цены на модели.

Читайте также: