Skip to main content
На этой странице рассматривается операционная сторона запуска шлюза Claude apps: регистрация клиента OAuth в вашем поставщике идентификации (IdP), развертывание шлюза как контейнера и его ежедневное управление. Для каждого параметра в файле gateway.yaml, который шлюз читает при загрузке, см. Справочник по конфигурации. Развертывание в производстве следует четырем этапам по порядку, и разделы ниже соответствуют им. Первые два — это места, где вы делаете выбор; вторые два — справочный материал, который следует консультировать после запуска.
  1. Настройка вашего поставщика идентификации: зарегистрируйте клиента OAuth и проверьте примечания для каждого IdP для Okta, Entra и Google
  2. Развертывание шлюза: создайте образ контейнера с закрепленной версией и запустите его на Kubernetes, Cloud Run или вашей собственной платформе. Этот раздел также охватывает решения по стоимости, обходу, нескольким шлюзам и бессерверным вычислениям
  3. Настройка операций: журналы, зонды здоровья, поведение при сбое, ротация секретов и обновления. Справочник для подключения мониторинга и runbooks
  4. Проверка позиции безопасности: какие данные куда передаются, модель угроз и ответы на вопросы соответствия. Справочник для проверки безопасности
Если вход или загрузка не удаются, перейдите прямо к Устранению неполадок, который организован по ошибкам, которые вы видите.
Развертывайте в вашей частной сети. Claude Code подключается только к шлюзу, адрес которого является приватным. Это защита безопасности, потому что доверенный шлюз может отправлять параметры, которые запускают команды на машинах разработчиков. Поместите шлюз за внутренним балансировщиком нагрузки или VPN и дайте ему имя хоста, которое разрешается только на приватные IP-адреса. Если ваша внутренняя сеть нумеруется из публичного пространства IPv4, которым владеет ваша организация, см. Разрешить шлюз на публичном адресном пространстве, которым вы владеете.

​
Настройка поставщика удостоверений

Зарегистрируйте конфиденциальное веб-приложение OAuth/OpenID Connect (OIDC) с одним URI перенаправления, https://<gateway>/oauth/callback, и назначьте его пользователям или группам, которые должны иметь доступ к шлюзу. Работает любой OIDC-совместимый IdP: Okta, Microsoft Entra ID, Google Workspace, Keycloak, Dex, PingFederate и другие. IdP должен соответствовать трем требованиям:
  • Обслуживает /.well-known/openid-configuration по HTTPS в production; шлюз принимает http:// издателя, и издатель loopback дополнительно требует CLAUDE_GATEWAY_ALLOW_LOOPBACK=1
  • Поддерживает поток authorization-code. PKCE (Proof Key for Code Exchange) включен по умолчанию; отключите его с помощью oidc.use_pkce: false для IdP, которые его не поддерживают
  • Возвращает email и опционально groups в id_token или обслуживает их из конечной точки userinfo с oidc.userinfo_fallback: true
Для приватной PKI установите oidc.ca_cert_pem. Несколько поставщиков обрабатывают утверждения email и group по-разному:
  • Okta: сервер авторизации организации в https://example.okta.com возвращает тонкий id_token, который опускает email и groups, поэтому установите oidc.userinfo_fallback: true всякий раз, когда вы используете его как issuer. Пользовательский сервер авторизации, такой как https://example.okta.com/oauth2/default, который включает email и опционально groups в id_token, выдает их напрямую и не требует fallback. Okta выдает groups только когда область groups запрашивается в oidc.scopes и фильтр утверждения groups приложения это позволяет; userinfo_fallback не может заполнить утверждение, которое IdP не был попрошен выдать.
  • Microsoft Entra ID: issuer = https://login.microsoftonline.com/<tenant-id>/v2.0. Entra выдает Object ID групп, а не имена, поэтому используйте GUID в managed.policies.match.groups или используйте App Roles для читаемых имен. Если ваш tenant выдает роли под roles вместо groups, установите oidc.groups_claim: roles.
  • Google Workspace: issuer = https://accounts.google.com. id_token Google не содержит groups. Чтобы использовать основанные на группах allowed_groups или managed.policies с Google в качестве IdP, настройте oidc.google_groups, которая ищет группы каждого пользователя через Admin SDK Directory API, используя сервисный аккаунт с делегированием на уровне домена. Без этого используйте oidc.allowed_email_domains для проверки членства и managed.policies.match.email_domain для назначения политики. Google также игнорирует стандартную область offline_access. Для refresh tokens установите oidc.scopes: [openid, profile, email] и oidc.extra_auth_params: { access_type: offline, prompt: consent }.
Refresh tokens позволяют шлюзу молча обновлять сеанс разработчика без отправки разработчика в браузер. Они также управляют deprovisioningом, потому что когда IdP отключает пользователя, следующее обновление не удается и сеанс заканчивается в течение ttl_hours. Шлюз запрашивает offline_access по умолчанию, чтобы получить refresh token. Если ваш IdP требует явного согласия для offline access, настройте клиент OAuth, чтобы это позволить.Если ваш IdP вообще не может выдавать refresh tokens, шлюз все еще работает, но нет молчаливого обновления, поэтому разработчики повторно запускают вход в браузер, когда их сеанс истекает. Чтобы это не происходило каждый час, поднимите session.ttl_hours на 8 или 12. Компромисс — это задержка deprovisioningа, потому что без refresh tokens отключенный пользователь сохраняет доступ до истечения более длительного TTL.

​
Развертывание

Шлюз — это один stateless бинарный файл Linux, который координирует работу через Postgres, поэтому развертывайте его так же, как вы развертываете любой другой stateless сервис в вашей среде. Держите его внутри вашей сети, где ваши разработчики и IdP могут достичь его по HTTPS, и относитесь к нему как к любому сервису, содержащему production учетные данные. Несколько решений формируют развертывание помимо того, где оно работает:
  • Стоимость: нет отдельной лицензии или платы за место. Шлюз является частью бинарного файла claude, поэтому вы платите за inference через ваше существующее обязательство, плюс вычисления, на которых он работает.
  • Обход: шлюз не требует, чтобы единственный маршрут к модели проходил через него. Разработчик со своими собственными учетными данными все еще может вызвать поставщика напрямую, поэтому закрытие этого пути — это решение политики сети, например блокировка выхода на api.anthropic.com кроме как от шлюза. Блокировка этого выхода также нарушает проверку безопасности домена WebFetch, которая вызывает api.anthropic.com с каждой машины разработчика. Установите skipWebFetchPreflight: true в управляемой политике, чтобы отключить это.
  • Несколько шлюзов: каждый — это отдельное развертывание со своей конфигурацией, и CLI хранит доверие и учетные данные для каждого имени хоста шлюза, поэтому команды могут использовать разные шлюзы без конфликтов. Чтобы обслуживать несколько издателей OIDC, запустите отдельные экземпляры.
  • Бессерверная архитектура: Cloud Run работает, если вы установите min-instances: 1, чтобы избежать холодного обнаружения OIDC. Lambda и Cloud Functions не работают, потому что шлюз — это долгоживущий HTTP сервер.
Каждая production топология здесь помещает прокси L7, такой как Ingress, фронтенд Cloud Run или ALB, перед простыми HTTP репликами. Установите listen.trusted_proxies на диапазоны источников прокси, чтобы шлюз читал IP клиентов из X-Forwarded-For. Шлюз соблюдает заголовок только когда TCP peer доверен. Пример Google Cloud и пример AWS содержат конкретные значения для каждой топологии. Без доверенных прокси каждый запрос выглядит как исходящий с IP прокси, что сворачивает ограничения скорости для каждого IP в один общий bucket и записывает IP прокси в события аудита. Не перенаправляйте запросы на конечные точки авторизации устройства и токена шлюза, например с переписыванием HTTP-в-HTTPS или канонизацией хоста на ingress. Claude Code не следует перенаправлениям на эти запросы, поэтому правило ingress, которое их перенаправляет, нарушает вход и обновление токена. Дайте прокси любой timeout неактивности, превышающий интервал keepalive шлюза, который зависит от upstream:
  • На каждом upstream кроме provider: anthropic, шлюз записывает SSE ping один раз, когда поток был молчалив около 15 секунд.
  • На provider: anthropic, шлюз пропускает ответ без изменений, включая собственные ping’и API Anthropic.
Значение по умолчанию, такое как 60 секунд ALB, достаточно, чтобы держать тихий поток открытым. Пример AWS поднимает его до часа в любом случае, и его строка troubleshooting охватывает шлюзы старше v2.1.229, которые не отправляли ничего во время тихих периодов на upstream’ах, которые теперь получают ping’и.

​
Образ контейнера

Создайте свой собственный образ вокруг нативного бинарного файла claude из стандартного выпуска Claude Code:
  1. Загрузите сборку Linux для архитектуры вашего образа из закрепленного выпуска; см. Установка конкретной версии для URL загрузки.
  2. Проверьте его против подписанного GPG manifest.json выпуска, как описано в Целостность бинарного файла и подпись кода.
  3. Скопируйте его в контекст сборки.
Зеркалируйте выпуск в ваш внутренний реестр, если ваши сборки не могут достичь хоста выпуска, и закрепите версию, которую запускает ваш флот. Помимо бинарного файла, образу нужны:
  • Образ на основе glibc: единственные динамические зависимости сборки glibc — это библиотеки glibc. Образы на основе Musl нуждаются в сборке linux-x64-musl или linux-arm64-musl плюс дополнительные пакеты; см. Настройка Alpine Linux.
  • Записываемый каталог состояния: шлюз работает как любой пользователь, но минимальные образы не имеют записываемого home. Установите CLAUDE_CONFIG_DIR на записываемый путь, такой как /tmp/.claude.
  • Команда контейнера: claude gateway --config /etc/claude/gateway.yaml, с файлом конфигурации, смонтированным только для чтения, и секретами, предоставленными как переменные окружения; шлюз слушает на listen.port, по умолчанию 8080.

​
Kubernetes

Запустите шлюз как Deployment, как любой stateless сервис:
  • Смонтируйте конфигурацию из ConfigMap и секреты из Secret; ссылайтесь на секреты в YAML через ${file:/path/to/secret} или как переменные окружения
  • Завершите TLS на Ingress и установите listen.public_url на имя хоста Ingress
  • Укажите зонд готовности на GET /readyz и зонд живучести на GET /healthz
Для полного примера на AWS, охватывающего ECS Fargate или EKS, Amazon RDS и AWS Secrets Manager, см. Развертывание на AWS. Предпочитайте workload identity платформы вместо статических ключей; справочник upstreams содержит детали настройки для каждой платформы. Для кросс-облачного сопряжения, такого как upstream Bedrock на GKE, установите явные учетные данные в блоке auth upstream вместо этого.

​
Cloud Run

Настройте сервис следующим образом:
  • Оставьте listen.port на его значении по умолчанию 8080, которое соответствует PORT Cloud Run по умолчанию, или установите port: ${PORT}
  • Установите public_url на внешне доступное происхождение. Для production это обычно имя хоста внутреннего балансировщика нагрузки, потому что /login отклоняет публичные адреса и URL *.run.app разрешается на один, поэтому URL Cloud Run один работает только для curl или дымового теста браузера. Исключение — сеть, где *.run.app разрешается приватно через Private Service Connect и приватную зону Cloud DNS; в этой топологии URL Cloud Run — это действительный public_url. Пример Google Cloud охватывает оба.
  • Смонтируйте конфигурацию как том секрета
  • Установите min-instances: 1, чтобы избежать холодного обнаружения OIDC при первом запросе
Для полного примера на Google Cloud, охватывающего Cloud Run или GKE, Cloud SQL и Secret Manager, см. Развертывание на Google Cloud.

​
Отправьте URL шлюза на машины разработчиков

Как только шлюз начнет обслуживать, отправьте forceLoginMethod, forceLoginGatewayUrl и parentSettingsBehavior: "merge" на каждую машину разработчика через управляемые параметры, через MDM или путем прямого написания файла managed-settings.json для каждой ОС. Без этого /login показывает стандартный выбор аккаунта без опции шлюза. Как только вы развернете ключи, Claude Code перестанет использовать оставшийся API ключ или вход claude.ai на машине, поэтому спланируйте отправку вместе с вашими инструкциями по входу. Политика администратора требует вход через Cloud шлюз описывает сообщения, которые видят разработчики. См. где каждый механизм хранит политику для путей файлов и Управляемые параметры на стороне клиента для эквивалента Claude Desktop bootstrapUrl.

​
Крупные развертывания

Вход ограничен по скорости для каждого IP адреса клиента, и значения по умолчанию подходят для небольшой команды. Каждый адрес получает 30 начал входа и 10 отправок кода каждые 10 минут. Развертывание для тысяч разработчиков может достичь этих ограничений в первое утро по одной из двух причин:
  • Шлюз не может видеть за вашим балансировщиком нагрузки. Без listen.trusted_proxies, каждый разработчик выглядит как исходящий с адреса балансировщика нагрузки и делит один лимит. Установите это в первую очередь. Шлюз логирует предупреждение в первый раз, когда он игнорирует заголовок X-Forwarded-For.
  • Много разработчиков делят несколько NAT или VPN адресов выхода. Они делят лимиты этих адресов даже когда trusted_proxies правильно установлен. Поднимите rate_limits, чтобы соответствовать.
Чтобы определить размер max, разделите разработчиков на адреса выхода, которые они делят. Оцените, сколько из них входят в один период window_seconds, который по умолчанию составляет 10 минут. Затем удвойте это, чтобы охватить повторные попытки и разработчиков, которые входят как в Claude Code, так и в Claude Desktop. Например, 10 000 разработчиков за 4 адресами выхода входят равномерно в течение часа. Это 2 500 разработчиков на адрес и около 420 из них в каждые 10 минут, которые вы удваиваете и округляете до 1 000. Пример ниже устанавливает оба лимита на 1 000:
device_verify — это то, что останавливает кого-то от угадывания кода входа другого разработчика, поэтому поднимайте его только настолько, насколько нужна ваша оценка. Даже при этих лимитах код состоит из 8 символов из 20-символного алфавита и истекает через 10 минут, поэтому угадывание остается непрактичным; см. Устойчивость к перебору кода пользователя. Когда ваш IdP выдает refresh токены, Claude Code молча обновляет сеансы, поэтому вы можете вернуть лимит после развертывания. Без refresh токенов разработчики входят снова каждые session.ttl_hours. Определите размер обоих лимитов и для этой стабильной скорости и оставьте их повышенными. Когда лимит достигнут, Claude Code v2.1.274 или позже показывает The gateway is limiting sign-in attempts right now. Шлюз на v2.1.274 или позже показывает Too many attempts came from your network address на странице проверки, с параметрами для проверки. Он также записывает строку логирования sign-in refused, которая называет параметр для изменения.

​
Операции

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

​
Логи

Шлюз записывает два потока в stderr, оба удобные для JSON:
  • События аудита: одна строка JSON на каждое событие, связанное с безопасностью. Направьте stderr в ваш агрегатор логов. Излучаемые события включают config.load, session.mint, session.refresh, device.authorize, device.verify, device.callback, auth.denied, access.denied, access.public_client, inference, managed.serve, desktop_bootstrap.serve, desktop_bootstrap.denied, spend.blocked, admin.denied, admin.limit.upsert и admin.limit.delete. Поля варьируются в зависимости от события:
    • Успешные события mint и refresh содержат sub, email, client_ip и результат
    • auth.denied и access.denied содержат причину и IP клиента, плюс путь запроса для auth.denied, так как в момент этих отказов не существует идентификации пользователя. Две причины access.denied изменяют то, что несёт событие:
      • xff_unparseable: событие также содержит запись X-Forwarded-For, которую не удалось прочитать
      • client_ip_unknown: событие не содержит IP клиента, потому что соединение не имело адреса узла, пока был установлен список access_control
    • access.public_client содержит IP клиента первого запроса за процесс, поступившего с публичного адреса, пока access_control.allow_cidrs пуст. Шлюз обслуживает запрос как обычно; событие сигнализирует, что шлюз может быть доступен из публичного интернета. Смотрите справку access_control для информации о том, что считается публичным и для рекомендуемого списка разрешений.
    • inference записывает, какой вышестоящий сервер обслужил запрос и статус ответа
    • desktop_bootstrap.denied записывает отклонённую выборку Claude Desktop bootstrap с причиной (not_configured, policy_not_opted_in или no_policy_matched) и идентификацией пользователя
    • admin.denied записывает отклонённую попытку аутентификации admin-API с IP клиента, методом, путём и причиной, без представленного ключевого материала: invalid_key когда был представлен x-api-key, но он не совпал ни с одним настроенным ключом, bearer_rejected когда был представлен только заголовок Authorization и он не проверился как сеанс шлюза в admin.admin_groups, или no_credentials когда ни один заголовок не был представлен
  • Операционные логи: удобочитаемые строки с префиксом [gateway] для загрузки, предупреждений и ошибок вышестоящих серверов. Переменная окружения CLAUDE_GATEWAY_LOG_LEVEL управляет подробностью и принимает debug, info, warn или error, с info по умолчанию. На уровне debug каждый вход и обновление также логируют имена, а не значения, утверждений в id_token, плюс имена утверждений userinfo когда userinfo_fallback предоставил какие-либо, так что вы можете диагностировать параметры email_claim и groups_claim без логирования PII. Это не влияет на события аудита, которые всегда излучаются.

​
Здоровье

Шлюз обслуживает GET /healthz как зонд живучести и GET /readyz как зонд готовности. /readyz проверяет доступность хранилища. Если вы установили store.readiness_grace_seconds, /readyz продолжает сообщать о готовности до этого количества секунд после того, как хранилище перестаёт отвечать. Оба конечных пункта освобождены от access_control.allow_cidrs, поэтому зонды продолжают работать на заблокированном слушателе. Документ обнаружения OAuth в /.well-known/oauth-authorization-server также возвращает 200 только после успешной загрузки конфигурации, обнаружения OIDC, построения вышестоящего клиента и миграции Postgres, поэтому он также служит сквозной проверкой загрузки.

​
Одновременные вышестоящие запросы

По умолчанию каждая реплика шлюза отправляет не более 256 запросов вышестоящему серверу одновременно. Потоковый ответ учитывается в пределе до завершения потока. Запрос, который прибывает, пока реплика находится на пределе, ждёт внутри шлюза свободного слота. Разработчик видит ответ, который медленно начинается или кажется зависшим. На вышестоящем сервере provider: anthropic запрос, который ждёт дольше, чем timeouts.upstream_ttfb_ms, отказывается от этого вышестоящего сервера и не выполняется с 502, когда позже никакой вышестоящий сервер его не обслуживает. Строка лога при запуске, которая содержит upstream requests:, показывает действующий предел. Пока реплика имеет больше открытых запросов, чем предел, она также логирует предупреждение, которое содержит client requests are open, не более одного раза в минуту. Чтобы обслуживать больше запросов одновременно, у вас есть два варианта:
  • Добавьте реплики.
  • Повысьте предел на каждой реплике. Установите переменную окружения BUN_CONFIG_MAX_HTTP_REQUESTS на контейнере шлюза на целое число от 1 до 65535, затем перезагрузите контейнер.
Реплика заполняет свой предел при частоте запросов примерно равной пределу, делённому на среднее количество секунд, в течение которых запрос остаётся открытым. Например, если запросы остаются открытыми в среднем 10 секунд, реплика с пределом по умолчанию 256 заполняет его примерно при 26 запросах в секунду. Если вы автомасштабируетесь по CPU, реплика на пределе ставит запросы в очередь без запуска масштабирования, поэтому установите целевое значение ниже уровня CPU, который ваши реплики показывают, когда они логируют предупреждение client requests are open.
Каждый открытый запрос удерживает память в процессе шлюза, пока он потоковает и пока ждёт слота. Если вы держите предел на 256, память на перегруженной реплике всё ещё растёт, потому что ожидающие запросы сохраняют свои тела запросов. Размер памяти контейнера для количества запросов, открытых в пиковый момент, и следите за памятью, когда вы меняете предел. Реплика, которая исчерпывает память, убивается и отбрасывает каждый поток, который она удерживает.

​
Поведение при сбое

Если Postgres выходит из строя, сам шлюз продолжает обслуживать вошедших разработчиков, а новые входы не удаются. Действительно ли разработчики продолжают работать, зависит от того, как ваш оркестратор обрабатывает готовность:
  • Существующие сеансы: токены-носители проверяются локально с помощью секрета JWT, обновления сеансов не касаются хранилища, и процесс шлюза всё ещё может обслуживать вывод
  • Новые входы: не удаются до восстановления Postgres, потому что поток устройства и его счётчики ограничения скорости находятся в Postgres
  • Применение лимита расходов: по умолчанию не выполняется во время сбоя, поэтому вывод всё ещё течёт; переключитесь на отказ в закрытом состоянии, если вы предпочитаете блокировать, чем работать без учёта
  • Готовность: по умолчанию /readyz сообщает о неготовности, как только Postgres недоступен, поэтому каждая реплика не выполняет свою проверку готовности одновременно. Где трафик достигает только реплик, которые проходят проверку, весь трафик, включая вывод, который шлюз всё ещё может обслуживать, не выполняется до восстановления Postgres. Зонд живучести на /healthz продолжает проходить на протяжении всего времени.
Если ваш IdP выходит из строя, существующие сеансы работают до ttl_hours и новые входы не удаются. Обновление сеанса получает ответ повторить попытку и успешно выполняется после восстановления IdP. Установите более длительный ttl_hours, если ваш IdP имеет частые окна обслуживания.

​
Период благодати готовности

Чтобы сохранить вошедших разработчиков работающими через короткий сбой Postgres, такой как отказоустойчивость базы данных, установите store.readiness_grace_seconds на более длительное время, чем требуется отказоустойчивость, например 300. При включённых лимитах расходов и поведении отказа по умолчанию, запросы через реплику, которая остаётся готовой, не учитываются до восстановления Postgres, поэтому держите значение как можно ниже, чтобы оно охватывало вашу отказоустойчивость. Если вы установили enforcement.fail_closed_on_error: true, шлюз отказывает вывод вошедших разработчиков с сообщением 429 spend limit unavailable до восстановления Postgres, даже пока реплики всё ещё проходят свою проверку готовности. Параметр требует Claude Code v2.1.282 или позже на сервере шлюза. Более ранний шлюз отказывается запускаться, когда находит ключ, поэтому обновите каждую реплику перед добавлением. Обновления охватывают откат. Если вы направите зонд готовности на /healthz вместо этого, реплики также продолжают проходить его через сбой, но /healthz никогда не сообщает о неготовности, поэтому реплика, чьё соединение Postgres не восстанавливается, продолжает проходить тоже.

​
Ротация секрета JWT

Ротируйте секрет подписи поэтапно, чтобы существующие сеансы оставались действительными:
  1. Сгенерируйте новый секрет. Добавьте его в начало массива session.jwt_secret.
  2. Разверните развёртывание. Новые токены подписываются новым секретом; старые токены всё ещё проверяются.
  3. После ttl_hours плюс запас, удалите старый секрет и разверните снова.
Ротация также является единственным способом вынудить сеансы выйти до их истечения: токены-носители проверяются локально против секрета JWT, поэтому нет отзыва для каждого сеанса. Замена секрета полностью, без сохранения старого в массиве, делает недействительным каждый выдающийся сеанс сразу. Для индивидуального отключения отмените подготовку пользователя в вашем IdP; их сеанс заканчивается в течение ttl_hours.

​
Postgres

Шлюз содержит пять таблиц данных плюс таблицу _migrations, все созданные его миграциями при загрузке: Цикл в 30 секунд истекает строки kv после их TTL, и почасовая очистка применяет окна удержания на таблицы расходов, поэтому ничего не растёт без ограничений. Без лимитов расходов настроенных, только kv записывается. Шлюз применяет свои собственные миграции схемы при загрузке и при каждом обновлении, поэтому его роль базы данных нуждается в правах на создание и изменение таблиц. Направьте его на базу данных или схему, выделенную для шлюза, чтобы сохранить это разрешение узким. При использовании лимитов расходов потерянная база данных означает потерю отслеживания расходов и лимитов, а не только повторные входы разработчиков, поэтому выполняйте регулярные резервные копии. Чтобы стереть одного ушедшего разработчика немедленно, а не ждать удержания, запустите DELETE FROM principal_emails WHERE principal = '<sub>' напрямую; это удаляет единственную таблицу, содержащую их адрес электронной почты, имя и группы. Строки spend и admin_audit ссылаются только на псевдонимный OIDC sub.

​
Обновления

Реплики не имеют состояния, поэтому перезагрузка при развёртывании не теряет состояние шлюза. Шлюз запускает миграции схемы при загрузке, что означает, что развёртывание нового двоичного файла самостоятельно мигрирует базу данных. Одновременные реплики сериализуются на консультативной блокировке Postgres, поэтому только одна применяет каждую миграцию. Когда ваш оркестратор останавливает реплику с SIGTERM, как при развёртывании при перезагрузке или масштабировании, шлюз прекращает принимать новые соединения и позволяет запросам и потокам, уже находящимся в полёте, завершиться перед выходом. Он ждёт до 25 секунд, называемых окном дренажа, затем закрывает всё, что всё ещё открыто. SIGINT, такой как Ctrl+C в терминале, запускает тот же дренаж, и второй сигнал во время дренажа закрывает открытые запросы и выходит сразу. Дренаж требует шлюза v2.1.274 или позже. Длительные генерации могут потоковать в течение минут. На Kubernetes и Amazon ECS поднимите оба этих параметра вместе, чтобы дать этим потокам больше времени:
  • Окно дренажа: установите переменную окружения CLAUDE_GATEWAY_DRAIN_TIMEOUT_MS на контейнере шлюза на положительное целое число миллисекунд, такое как 120000. Шлюз игнорирует значение в любой другой форме, такой как 120s, и сохраняет значение по умолчанию 25 секунд
  • Период благодати вашего оркестратора: terminationGracePeriodSeconds на Kubernetes или stopTimeout на Amazon ECS
Период благодати по умолчанию составляет 30 секунд на обеих платформах. Держите его по крайней мере на 5 секунд дольше, чем окно дренажа, или оркестратор убьёт шлюз до завершения дренажа. На Kubernetes добавьте продолжительность любого хука preStop также, потому что период благодати начинает отсчёт перед запуском хука, а не когда шлюз получает SIGTERM. Ваша платформа также может ограничить, как долго может работать дренаж:
  • Amazon ECS на Fargate: stopTimeout позволяет максимум 120 секунд
  • Cloud Run: останавливает экземпляр через 10 секунд после SIGTERM, поэтому открытые потоки получают максимум 10 секунд там, независимо от того, какое окно дренажа
Когда окно дренажа заканчивается с открытыми запросами, шлюз логирует предупреждение, которое содержит drain window over after, подсчитывает запросы, которые он отрезал, и называет оба параметра для повышения. Миграции являются добавочными, поэтому откат к предыдущему двоичному файлу, который знает меньше миграций, безопасен; он игнорирует дополнительные строки. Откат также переподтверждает YAML против схемы более старого двоичного файла, поэтому конфигурация, которая приняла ключ, введённый более новым выпуском, не выполняется при загрузке на более старом. Удалите новый ключ перед откатом. Поскольку вы закрепляете версию шлюза в своём собственном образе, исправления в новых выпусках Claude Code, включая исправления безопасности, достигают вашего развёртывания только когда вы обновляете закрепление и переразворачиваете. Включите шлюз в тот же цикл исправления, который вы используете для других сервисов, которые содержат учётные данные производства.

​
Безопасность

Этот раздел отвечает на вопросы, которые задает проверка безопасности: какие данные проходят через шлюз и куда они идут, какие атаки защищает дизайн и какие ответы принадлежат в опроснике соответствия.

​
Поток данных

​
Краткое резюме модели угроз

Шлюз находится внутри периметра вашей сети, но отдельные ноутбуки разработчиков не рассматриваются как доверенные. Дизайн учитывает это тремя способами:
  • Разработчики держат краткосрочные JWT вместо сырых ключей upstream. Ветвь CLI-к-шлюзу использует грант устройства RFC 8628, и обмен авторизацией шлюза с IdP запускает PKCE в конфигурации по умолчанию, поэтому перехваченный код авторизации IdP бесполезен.
  • Страница проверки устройства применяет same-origin POST и ограничение скорости для каждого IP согласно RFC 8628 §5.1. См. Сопротивление brute-force пользовательского кода.
  • Исходящие запросы шлюза к вашему IdP, вашим сборщикам OTLP и provider: anthropic upstreams проходят через защиту от подделки запроса на стороне сервера (SSRF), которая разрешает DNS, блокирует link-local и адреса облачных метаданных плюс loopback по умолчанию и закрепляет соединение на разрешенный IP, поэтому управляемые оператором URL не могут быть перенаправлены на конечные точки облачных метаданных. Диапазоны приватных RFC 1918 намеренно разрешены, потому что IdP и сборщики OTLP обычно живут на приватных IP. Для других поставщиков шлюз отказывает в base_url, который называет один из этих адресов или имя хоста метаданных при загрузке конфигурации, и SDK поставщика затем подключается без проверки DNS. Если вы включите только прокси выход, эта проверка адреса переходит к вашему forward proxy: шлюз передает ему имена хостов и список разрешений прокси должен отказать этим назначениям. Установите CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 в окружении шлюза только когда что-то, что шлюз должен достичь, легитимно живет на loopback, такое как локальная разработка IdP или сборщик OTLP sidecar на localhost. Переменная ослабляет блокировку loopback для каждого настроенного оператором URL и также пропускает предупреждение при загрузке, которое проверяет, может ли pod достичь конечной точки облачных метаданных, поэтому предпочитайте давать сборщику его собственный внутренний адрес.
Если вы добавляете свои собственные элементы управления выходом, шлюз должен достичь сервера метаданных всякий раз, когда он использует учетные данные метаданных экземпляра, такие как workload identity. Две угрозы выходят за рамки, потому что это ваша инфраструктура для защиты:
  • Скомпрометированный хост шлюза: хост как содержит upstream учетные данные, так и распределяет управляемые параметры каждому подключенному разработчику, поэтому контроль над конфигурацией шлюза сравним с контролем над вашим MDM. Диалог одобрения CLI для параметров, способных к shell, ограничивает молчаливые изменения, но не заменяет безопасность хоста.
  • Вредоносный поставщик OIDC: поставщик подписывает id_tokens, которым шлюз доверяет, поэтому он может утверждать любую идентификацию. Проверка и защита вашего IdP — это ваша ответственность.

​
Сопротивление brute-force пользовательского кода

user_code, который разработчик вводит на странице проверки /device, — это 8 символов, взятых из алфавита из 20 символов, что дает 20⁸ или около 2,56×10¹⁰ комбинаций, и он истекает через 10 минут. Шлюз применяет ограничения скорости для каждого IP на конечных точках грантов устройства, настраиваемые через rate_limits. Поднимите лимиты, если много разработчиков входят с одного общего корпоративного NAT адреса. Крупные развертывания показывает, как их размер. Лимиты применяются только к потоку входа, а не к inference.

​
Позиция соответствия

  • Резидентность данных: собственная плоскость данных шлюза не отправляет ничего Anthropic, если только API Anthropic не является настроенным upstream; когда это так, ваше существующее соглашение об обработке данных применяется к пути inference. Телеметрия, аудит, идентификация и параметры идут только к назначениям, которые вы настраиваете.
  • Трафик хост-процесса: хост-процесс — это Claude Code CLI. claude gateway работает под теми же правилами третьих сторон, что и развертывания Amazon Bedrock и Google Cloud’s Agent Platform, и не отправляет ничего Anthropic. До v2.1.227 хост-процесс отправлял телеметрию запуска, такую как версия продукта и платформа, которую установка CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 в окружении контейнера отключала. Эти выпуски также отправляли один запрос HEAD при загрузке, без тела или учетных данных, на /api/hello на https://api.anthropic.com, или на ANTHROPIC_BASE_URL когда окружение установило его, если только окружение также не установило переменную прокси, такую как HTTPS_PROXY или сертификат клиента mTLS. Они игнорировали ответ, поэтому блокировка этого запроса на брандмауэре выхода не влияла на шлюз.
  • Аналитика клиента: CLI отключает свою собственную аналитику использования и отчеты об ошибках при входе в шлюз. До первого входа CLI все еще отправляет события запуска Anthropic, включая на машинах, чьи управляемые параметры принуждают вход в шлюз. Чтобы отключить и их, доставьте DISABLE_TELEMETRY в тех же управляемых параметрах на стороне клиента, которые принуждают вход в шлюз.
  • Отчеты об ошибках: CLI отключает отчеты об ошибках всякий раз, когда его запросы модели идут на любую конечную точку, отличную от первоклассного API Anthropic, такую как Amazon Bedrock или пользовательский ANTHROPIC_BASE_URL.
  • Машины клиентов: CLI разработчиков все еще отправляют проверки имени хоста WebFetch и проверки версии Anthropic, если не установлены CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 и skipWebFetchPreflight: true. См. использование данных.
  • Рейтинги опроса: при входе в шлюз CLI отключает загрузку рейтингов, привязанную к Anthropic, вместе с потоками аналитики, поэтому он не отправляет рейтинги Anthropic.
  • Обмен транскриптом: выбор Yes на подсказке обмена транскриптом опроса записывает локальный файл в ~/.claude/feedback-bundles/ вместо загрузки Anthropic.
  • Обновления клиента: проверки обновлений отделены от трафика шлюза. Закрепите версии через вашу собственную дистрибуцию и установите DISABLE_UPDATES, если ноутбуки не должны получать выпуски. DISABLE_AUTOUPDATER останавливает только фоновые обновления, в то время как claude update все еще работает.
  • TLS: обслуживайте public_url по HTTPS в production, либо из собственного слушателя шлюза через listen.tls, либо из TLS-завершающего ingress перед простыми HTTP репликами, с установленным listen.public_url в обоих случаях. Шлюз не отказывает простой HTTP. IdP должен обслуживать HTTPS в production, и Postgres поддерживает ?sslmode=require. Установите Strict-Transport-Security на вашем ingress.
  • Раскрытие уязвимостей: следуйте Отчету о проблемах безопасности

​
Устранение неполадок

Для вопросов и обратной связи используйте поддержку Claude Code или откройте issue в репозитории Claude Code на GitHub. При сообщении о проблеме включите:
  • Проблема шлюза: stderr шлюза для соответствующего окна, ваш gateway.yaml с редактированными секретами, версию шлюза, показанную на целевой странице в / и в заголовке ответа x-cc-gateway-version на /managed/settings, и что недавно изменилось
  • Проблема входа: разработчик запускает claude --debug-file ./claude-debug.txt, воспроизводит и отправляет этот файл плюс журнал аудита шлюза для того же окна
  • Проблема inference: запрошенная модель, настроенные upstreams и журнал аудита шлюза для запроса, который записывает, какой upstream обслужил его и статус ответа
stderr шлюза включает поток событий аудита, журнал аудита записывает идентификаторы разработчиков, а файл отладки записывает выходные данные hook и MCP сервера с машины разработчика. Проверьте и удалите эту информацию перед публикацией в общедоступную проблему. Сообщение Cloud gateway sign-in was not completed называет имя хоста шлюза. Когда Claude Code имеет оба отпечатка, сообщение также показывает первые 16 символов каждого. Если Claude Code сообщает couldn't load your organization's managed settings после входа в шлюз, Claude Code называет причину, перезагружается на месте и возобновляет разговор. Если Claude Code не может перезагрузиться, например в фоновом сеансе, Claude Code завершает сеанс и сохраняет вход.