Развертывание и эксплуатация шлюза Claude apps

На этой странице рассматривается операционная сторона запуска шлюза Claude apps: регистрация клиента OAuth в вашем поставщике идентификации (IdP), развертывание шлюза как контейнера и его ежедневное управление. Для каждого параметра в файле gateway.yaml, который шлюз читает при загрузке, см. Справочник по конфигурации. Развертывание в производстве следует четырем этапам по порядку, и разделы ниже соответствуют им. Первые два — это места, где вы делаете выбор; вторые два — справочный материал, который следует консультировать после запуска.

1. Настройка вашего поставщика идентификации: зарегистрируйте клиента OAuth и проверьте примечания для каждого IdP для Okta, Entra и Google
2. Развертывание шлюза: создайте образ контейнера с закрепленной версией и запустите его на Kubernetes, Cloud Run или вашей собственной платформе. Этот раздел также охватывает решения по стоимости, обходу, нескольким шлюзам и бессерверным вычислениям
3. Настройка операций: журналы, зонды здоровья, поведение при сбое, ротация секретов и обновления. Справочник для подключения мониторинга и runbooks
4. Проверка позиции безопасности: какие данные куда передаются, модель угроз и ответы на вопросы соответствия. Справочник для проверки безопасности

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

​

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

Зарегистрируйте конфиденциальное веб-приложение 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 }.

Для поддержки с поставщиком удостоверений, не описанным выше, см. Troubleshooting.

​

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

Шлюз — это один бинарный файл Linux. Он масштабируется горизонтально, потому что реплики не имеют состояния, а Postgres — это общий уровень координации. Запустите его так же, как вы запускаете stateless сервисы в вашей среде. Остальная часть этого раздела указывает, что нужно образу, с краткими примечаниями для Kubernetes и Cloud Run. Шлюз предназначен для запуска внутри вашей сети, потому что он содержит ваши upstream учетные данные и действует как единственная точка выхода для inference. Он может работать везде, где ваши разработчики и ваш IdP могут достичь по HTTPS; рассматривайте его как любой другой сервис, содержащий production учетные данные. Несколько решений формируют развертывание помимо того, где оно работает:

• Стоимость: нет отдельной лицензии или платы за место для шлюза; это часть бинарного файла claude. Вы платите за inference через ваше существующее облачное или обязательство Anthropic, плюс вычисления для контейнера и вашего сборщика телеметрии.
• Обход: шлюз не требует, чтобы единственный маршрут к модели проходил через него. Разработчик со своими собственными учетными данными все еще может вызвать поставщика напрямую, поэтому закрытие этого пути — это решение политики сети, например блокировка выхода на 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 имеет конкретные значения для каждой топологии. Без доверенных прокси каждый запрос выглядит как исходящий с IP прокси, что сворачивает ограничения скорости для каждого IP в один общий bucket и записывает IP прокси в события аудита.

​

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

Создайте свой собственный образ вокруг нативного бинарного файла 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

​

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 при первом запросе

​

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

Как только шлюз начнет обслуживать, отправьте forceLoginMethod и forceLoginGatewayUrl на каждую машину разработчика через управляемые параметры, через MDM или путем прямого написания файла managed-settings.json для каждой ОС. Без этого /login показывает стандартный выбор аккаунта без опции шлюза. См. Управляемые параметры на стороне клиента для путей файлов.

​

Операции

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

​

Логи

Шлюз записывает два потока в stderr, оба JSON-дружественные:

• События аудита: однострочный JSON для каждого события, связанного с безопасностью. Направьте stderr в ваш агрегатор логов. Выдаваемые события включают config.load, session.mint, session.refresh, device.authorize, device.verify, auth.denied, access.denied, inference, managed.serve, spend.blocked и admin.denied. Поля варьируются по событиям:
  • Успешные события mint и refresh содержат sub, email, client_ip и результат
  • События отказа содержат причину, путь и IP клиента, так как идентификация не существует при отказе
  • inference записывает, какой upstream обслужил запрос и статус ответа
  • admin.denied записывает отклоненную попытку аутентификации admin-API с причиной (invalid_key или no_credentials), IP клиента, методом и путем, без представленного материала ключа
• Операционные логи: читаемые для человека строки с префиксом [gateway] для загрузки, предупреждений и ошибок upstream. Переменная окружения CLAUDE_GATEWAY_LOG_LEVEL управляет многословностью и принимает info, warn или error, с info по умолчанию. Это не влияет на события аудита, которые всегда выдаются.

​

Здоровье

Шлюз обслуживает GET /healthz как зонд живучести и GET /readyz как зонд готовности; /readyz проверяет доступность хранилища. Оба исключены из access_control.allow_cidrs, поэтому зонды продолжают работать на заблокированном слушателе. Документ обнаружения OAuth в /.well-known/oauth-authorization-server также возвращает 200 только после загрузки конфигурации, обнаружения OIDC, построения клиента upstream и миграции Postgres, поэтому он также служит проверкой загрузки end-to-end. Работающий шлюз также обслуживает описание путей и форм запросов, которые он принимает, в <public_url>/protocol, соответствующих версии, которую вы запускаете. Содержимое не стабильно между выпусками.

​

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

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

• Существующие сеансы: bearer tokens проверяются локально с помощью JWT secret, обновления сеанса не касаются хранилища, и процесс шлюза все еще может обслуживать inference
• Новые входы: не удаются до восстановления Postgres, потому что поток устройства и его счетчики ограничения скорости живут в Postgres
• Применение ограничения расходов: по умолчанию не удается открыто во время сбоя, поэтому inference все еще течет; переключите его на отказ закрыто, если вы предпочитаете блокировать, чем работать без учета
• Готовность: /readyz сообщает о неготовности во время сбоя, поэтому оркестраторы, которые управляют трафиком на готовность, удаляют каждую реплику из ротации сразу. В этой топологии весь трафик, включая inference, который шлюз все еще может обслуживать, не удается на балансировщике нагрузки до восстановления Postgres. Зонд живучести на /healthz продолжает проходить, поэтому реплики не перезапускаются. Укажите зонд готовности на /healthz вместо этого, если вы предпочитаете, чтобы вошедшие разработчики продолжали работать через сбой хранилища; стоимость в том, что новые входы не удаются против реплики, которая все еще сообщает о готовности.

Если ваш IdP выходит из строя, существующие сеансы работают до ttl_hours, а новые входы и обновления не удаются. Установите более длительный ttl_hours, если ваш IdP имеет частые окна обслуживания.

​

Ротация JWT secret

Ротируйте подписывающий secret в три этапа, чтобы существующие сеансы оставались действительными:

1. Создайте новый secret. Добавьте его в начало массива session.jwt_secret.
2. Разверните развертывание. Новые tokens подписываются новым secret; старые tokens все еще проверяются.
3. После ttl_hours плюс запас, удалите старый secret и разверните снова.

Ротация также является единственным способом вынудить сеансы выйти до истечения: bearer tokens проверяются локально против JWT secret, поэтому нет отзыва для каждого сеанса. Замена secret полностью, без сохранения старого в массиве, делает недействительным каждый выдающийся сеанс сразу. Для индивидуального offboarding deprovision пользователя в вашем IdP; их сеанс заканчивается в течение ttl_hours.

​

Postgres

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

​

Обновления

Реплики не имеют состояния, поэтому rolling restart безопасен в любое время. Шлюз запускает миграции схемы при загрузке, что означает, что развертывание нового бинарного файла автоматически мигрирует базу данных. Если роль базы данных не может запускать DDL, предварительно создайте схему, включая таблицу _migrations, инициализированную текущей версией; в противном случае загрузка не удается при попытке CREATE TABLE. Миграции добавляются только, поэтому откат к предыдущему бинарному файлу, который знает меньше миграций, безопасен; он игнорирует дополнительные строки. Откат также переподтверждает YAML против схемы более старого бинарного файла, поэтому конфигурация, которая приняла ключ, введенный более новым выпуском, не удается при загрузке на более старом. Удалите новый ключ перед откатом. Потому что вы закрепляете версию шлюза в своем собственном образе, исправления в новых выпусках Claude Code, включая исправления безопасности, достигают вашего развертывания только когда вы обновляете закрепление и переразворачиваете. Включите шлюз в тот же цикл патчей, который вы используете для других сервисов, содержащих production учетные данные.

​

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

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

​

Поток данных

​

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

Шлюз находится внутри периметра вашей сети, но отдельные ноутбуки разработчиков не рассматриваются как доверенные. Дизайн учитывает это тремя способами:

• Разработчики держат краткосрочные JWT вместо сырых ключей upstream. Ветвь CLI-к-шлюзу использует грант устройства RFC 8628, и обмен авторизацией шлюза с IdP запускает PKCE в конфигурации по умолчанию, поэтому перехваченный код авторизации IdP бесполезен.
• Страница проверки устройства применяет same-origin POST и ограничение скорости для каждого IP согласно RFC 8628 §5.1. См. Сопротивление brute-force пользовательского кода.
• Исходящие запросы проходят через защиту от подделки запроса на стороне сервера (SSRF), которая разрешает DNS, блокирует link-local и адреса облачных метаданных плюс loopback по умолчанию и закрепляет соединение на разрешенный IP, поэтому управляемые оператором URL, такие как IdP и назначения OTLP, не могут быть перенаправлены на конечные точки облачных метаданных. Диапазоны приватных RFC 1918 намеренно разрешены, потому что IdP и сборщики OTLP обычно живут на приватных IP. Для локальной разработки против loopback IdP или сборщика установите CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 в окружении шлюза; оставьте его неустановленным в production.

Если вы добавляете свои собственные элементы управления выходом, шлюз должен достичь сервера метаданных всякий раз, когда он использует учетные данные метаданных экземпляра, такие как 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. Телеметрия, аудит, идентификация и параметры идут только к назначениям, которые вы настраиваете.
• Трафик хост-процесса: хост-процесс — это CLI Claude Code, который может отправлять аналитику запуска и проверки обновлений Anthropic. Для развертываний со строгим выходом установите CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 в окружении контейнера шлюза.
• Аналитика клиента: CLI отключает свою собственную аналитику использования при входе в шлюз, и отчеты об ошибках отключены по умолчанию на поверхностях API третьих сторон.
• Машины клиентов: CLI разработчиков все еще отправляют проверки имени хоста WebFetch и проверки версии Anthropic, если не установлены CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 и skipWebFetchPreflight: true. См. использование данных.
• Рейтинги опроса: учетные данные шлюза отключают приемник рейтингов, привязанный к 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 обслужил его и статус ответа

​

Связанное

• Обзор шлюза Claude apps: быстрый старт и подключение разработчика
• Справочник по конфигурации: каждый параметр файла gateway.yaml