LobeChat объединяет нескольких поставщиков моделей в одном интерфейсе — это удобно, но управление ключами часто остаётся без внимания: кто создал ключ, какие модели он может вызывать, хранится он в браузере или в базе данных, попадёт ли он в резервную копию, продолжит ли действовать после ухода сотрудника. Ниже — практический порядок действий: создание, настройка, хранение, ротация, командная политика и диагностика.

Примечание: LobeChat и LobeHub — продукты и товарные знаки их правообладателей; OpenAI — товарный знак OpenAI, Inc. Статья носит технический характер; автор не связан с указанными компаниями и не состоит с ними в партнёрских отношениях. Интерфейс, имена переменных и способ хранения зависят от версии — сверяйтесь с актуальной документацией. Модели и цены — на странице цены на модели.

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

«API-ключ LobeChat» часто означает три разные вещи:

  • Учётные данные аккаунта или платформы — для входа в LobeHub Cloud или корпоративную платформу; права определяет платформа.
  • Ключ поставщика моделей — выдаётся OpenAI, Anthropic, Google и другими и вставляется в поле соответствующего провайдера.
  • Ключ шлюза — выдаётся OpenAI-совместимым шлюзом; один ключ может вызывать модели нескольких компаний.

Статья посвящена третьему типу; она также применима к ключам других поставщиков, которые вы вводите в LobeChat. Ключ шлюза не используется для входа и не даёт доступа к закрытым интерфейсам вендоров. При настройке выбирайте OpenAI-совместимый вход или «пользовательского провайдера», а не вставляйте ключ в специальное поле конкретного вендора.

2. Создание ключа: сначала назначение и лимиты

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

  1. Откройте страницу регистрации ZSQH AI Gateway, зарегистрируйтесь и войдите в консоль.
  2. Перейдите на страницу API-ключей и создайте новый ключ.
  3. В названии укажите пользователя, окружение и назначение, например lobe-team-prod, а не test.
  4. Задайте лимит расходов и срок действия; если поддерживается ограничение по моделям, ограничьте список для проекта.
  5. Проверьте баланс аккаунта, чтобы не обнаружить проблему после настройки.
  6. Скопируйте ключ в менеджер паролей, не отправляйте его сначала в чат, документ или тикет.

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

export ZSQH_API_KEY="sk-ваш-ключ"

curl -sS "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"ваш-ID-модели","messages":[{"role":"user","content":"Ответь только OK"}]}'

Если в ответе есть поле choices, цепочка работает. При 401 сначала проверьте ключ; при 404 — путь /v1; при ошибке «модель не найдена» — идентификатор модели.

3. Серверные переменные окружения и пользовательская настройка

Ключи в LobeChat могут находиться на двух уровнях, и их роль совершенно разная. Вот соответствие:

Уровень Где настраивается Область действия Для чего подходит
Серверные переменные окружения Окружение развёртывания, lobehub.env, менеджер секретов Весь экземпляр Единый вход для команды, модель по умолчанию
Пользовательская настройка провайдера Интерфейс настроек после входа Один аккаунт Собственный ключ, временный тест
Ключ на стороне шлюза Консоль шлюза Учёт по ключу Лимиты, аудит, отзыв

Серверная переменная OPENAI_API_KEY — общий ключ: им могут пользоваться все, у кого есть доступ к экземпляру. Пользователь также может ввести свой ключ; в серверном режиме с базой данных пользовательские ключи шифруются и записываются в базу, а шифрование зависит от KEY_VAULTS_SECRET. Если эта переменная потеряна, сохранённые пользовательские ключи могут не расшифроваться, поэтому при развёртывании сразу делайте резервную копию.

Основные серверные переменные:

  • OPENAI_API_KEY — общий ключ шлюза.
  • OPENAI_PROXY_URL — переопределяет адрес OpenAI по умолчанию, указывает на совместимый шлюз.
  • OPENAI_MODEL_LIST — управляет списком моделей, но не даёт дополнительных прав.
  • KEY_VAULTS_SECRET — шифрует пользовательские ключи и адреса прокси в базе данных.
  • AUTH_SECRET — для сессий и аутентификации, генерируется отдельно.
  • DATABASE_URL — строка подключения PostgreSQL, обязательна для серверного режима.

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

4. Как настроить несколько моделей и провайдеров

Синтаксис OPENAI_MODEL_LIST: + добавляет, - скрывает, ID-модели=отображаемое имя<возможности> задаёт имя и возможности; элементы разделяются запятыми. Пример:

-all,+model-a=Ежедневные вопросы<128000:fc:vision>,+model-b=Анализ длинных текстов<200000:reasoning>

Первый элемент в угловых скобках — максимальный контекст, далее теги возможностей: распространены fc (вызов функций), vision (изображения), file (файлы), reasoning (рассуждения), search (веб-поиск). Теги должны соответствовать реальным возможностям модели: ошибка не проявится сразу, но приведёт к сбою в плагине или задаче с изображением.

Принцип нескольких провайдеров — «одна конфигурация на одну вышестоящую точку»:

  • Для одного шлюза создавайте одну запись провайдера и различайте назначение через список моделей.
  • Для разных шлюзов или окружений — отдельные записи с суффиксом окружения в названии.
  • Каждая запись использует свой ключ, чтобы отдельно задавать лимиты и отзывать доступ.
  • Не копируйте один ключ ради «богатого списка моделей» — учёт запутается.

Список моделей определяет только отображение; реальные права находятся на стороне шлюза. Чтобы ограничить модели для ключа, настройте это в консоли, а не полагайтесь на скрытие в интерфейсе.

5. Где хранятся ключи и откуда возможна утечка

По способу развёртывания:

  • Локальный или браузерный режим: настройки хранятся в локальном хранилище браузера и могут исчезнуть при смене устройства или очистке кэша. Не сохраняйте долгоживущие ключи на общем компьютере.
  • Серверный режим с базой данных: пользовательские ключи шифруются и записываются в PostgreSQL, шифрование зависит от KEY_VAULTS_SECRET. В резервной копии базы — шифротекст, но файл с секретом нужно хранить отдельно.
  • Файл переменных окружения: lobehub.env хранится открытым текстом; права — только на чтение сервисной учётной записью; файл не попадает в Git и не распространяется с образом.
  • S3 и резервные копии: в S3 хранятся файлы и материалы базы знаний, обычно без ключей; резервные копии базы и конфигурация развёртывания могут косвенно содержать чувствительные данные.

Учитывайте также скриншоты, тикеты и переписку. Многие утечки происходят не из-за взлома базы, а из-за ключа, вставленного не туда.

6. Ротация и отзыв

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

  1. Создайте новый ключ с теми же правами, добавив дату в название.
  2. Обновите lobehub.env или пользовательские настройки провайдеров, проверяя каждую запись.
  3. Перезапустите или пересоберите сервис и отправьте тестовый запрос.
  4. Убедитесь по журналу шлюза, что новый ключ используется, а старый не получает нового трафика.
  5. Некоторое время наблюдайте за ошибками и расходом, чтобы не осталось забытых скриптов или устройств.
  6. Отключите старый ключ и удалите его после периода хранения записей.

Не удаляйте старый ключ до настройки нового — возникнет окно недоступности. При подозрении на утечку сначала отключите ключ, затем проверьте аномальный расход и источники вызовов.

7. Командная политика: один человек — один ключ, окружения раздельно

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

Даже в небольшой команде стоит хранить запись «кто запросил, кто использует, когда истекает». Это ускоряет разбор инцидентов.

8. Диагностика

Симптом Частая причина Что делать
401 Unauthorized Неверный ключ, отключён или содержит пробел Скопируйте заново, проверьте принадлежность ключа текущему шлюзу
403 Forbidden Лимит исчерпан, недостаточно прав или ограничен список моделей Проверьте лимит и права на модели в консоли
404 Not Found Неверный путь API Оставьте только /v1
429 Too Many Requests Сработало ограничение скорости или лимит Проверьте расход и настройки параллелизма
model not found Неверный ID модели или модель не подключена Скопируйте точный идентификатор со страницы цен
Пользовательский ключ внезапно перестал работать KEY_VAULTS_SECRET изменён или отсутствует Восстановите прежний секрет и заново введите ключ
curl работает, интерфейс — нет Настройки не сохранены, кэш браузера или прокси Сохраните заново и проверьте прокси

При разборе сначала определите: «приложение не прочитало конфигурацию» или «шлюз отклонил запрос». В первом случае смотрите переменные, базу и логи; во втором — HTTP-код.

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

Ключ LobeChat хранится в браузере или на сервере?

Зависит от развёртывания. В браузерном или локальном режиме — в локальном хранилище; в серверном режиме с базой пользовательские ключи шифруются и записываются в PostgreSQL, а общий ключ из серверных переменных хранится в окружении открытым текстом.

Если на сервере задан OPENAI_API_KEY, нужно ли пользователю вводить свой?

Нет. Серверный ключ общий, пользователи экземпляра могут вызывать модели напрямую. Пользователь может добавить свой ключ для отдельного лимита или другого провайдера; приоритет зависит от версии.

Может ли один ключ вызывать несколько моделей?

Обычно да, если шлюз разрешает этому ключу такие модели. Список моделей управляет только отображением; реальные права и лимиты задаются в консоли шлюза.

Что произойдёт при изменении KEY_VAULTS_SECRET?

Зашифрованные пользовательские ключи и адреса прокси могут не расшифроваться — ключи внезапно перестанут работать. Перед изменением сделайте резервную копию и изучите инструкцию по миграции текущей версии; не меняйте секрет без необходимости.

Что делать в первую очередь при утечке ключа?

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

Итог

Настройка ключей LobeChat несложна; сложность — в долгом управлении: прослеживаемые названия, лимиты, защищённое хранение, границы резервных копий и возможность остановить утечку. Можно зарегистрироваться в ZSQH AI Gateway, создать отдельный ключ для клиента, а после успешного запуска ужесточить политику команды и регулярно сверять расходы на странице цены на модели.

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