claude-apps-gateway-deploy.md +28 −26
6 6
7> Зарегистрируйте шлюз в вашем поставщике идентификации, создайте контейнер, разверните на Kubernetes или Cloud Run и управляйте им: проверки здоровья, ротация секретов, обновления и безопасность.7> Зарегистрируйте шлюз в вашем поставщике идентификации, создайте контейнер, разверните на Kubernetes или Cloud Run и управляйте им: проверки здоровья, ротация секретов, обновления и безопасность.
8 8
99На этой странице рассматривается операционная сторона запуска [шлюза Claude apps](/ru/claude-apps-gateway): регистрация клиента OAuth в вашем поставщике идентификации (IdP), развертывание шлюза как контейнера и его ежедневное управление. Для каждого параметра в файле `gateway.yaml`, который шлюз читает при загрузке, см. [Справочник по конфигурации](/ru/claude-apps-gateway-config).На этой странице рассматривается операционная сторона запуска [шлюза Claude apps](/docs/ru/claude-apps-gateway): регистрация клиента OAuth в вашем поставщике идентификации (IdP), развертывание шлюза как контейнера и его ежедневное управление. Для каждого параметра в файле `gateway.yaml`, который шлюз читает при загрузке, см. [Справочник по конфигурации](/docs/ru/claude-apps-gateway-config).
10 10
11Развертывание в производстве следует четырем этапам по порядку, и разделы ниже соответствуют им. Первые два — это места, где вы делаете выбор; вторые два — справочный материал, который следует консультировать после запуска.11Развертывание в производстве следует четырем этапам по порядку, и разделы ниже соответствуют им. Первые два — это места, где вы делаете выбор; вторые два — справочный материал, который следует консультировать после запуска.
12 12
31 31
32Работает любой OIDC-совместимый IdP: Okta, Microsoft Entra ID, Google Workspace, Keycloak, Dex, PingFederate и другие. IdP должен соответствовать трем требованиям:32Работает любой OIDC-совместимый IdP: Okta, Microsoft Entra ID, Google Workspace, Keycloak, Dex, PingFederate и другие. IdP должен соответствовать трем требованиям:
33 33
3434* Обслуживает `/.well-known/openid-configuration` по HTTPS в production; шлюз принимает [`http://` издателя](/ru/claude-apps-gateway-config#oidc), и издатель loopback дополнительно требует `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`* Обслуживает `/.well-known/openid-configuration` по HTTPS в production; шлюз принимает [`http://` издателя](/docs/ru/claude-apps-gateway-config#oidc), и издатель loopback дополнительно требует `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`
35* Поддерживает поток authorization-code. PKCE (Proof Key for Code Exchange) включен по умолчанию; отключите его с помощью `oidc.use_pkce: false` для IdP, которые его не поддерживают35* Поддерживает поток authorization-code. PKCE (Proof Key for Code Exchange) включен по умолчанию; отключите его с помощью `oidc.use_pkce: false` для IdP, которые его не поддерживают
36* Возвращает `email` и опционально `groups` в id\_token или обслуживает их из конечной точки userinfo с `oidc.userinfo_fallback: true`36* Возвращает `email` и опционально `groups` в id\_token или обслуживает их из конечной точки userinfo с `oidc.userinfo_fallback: true`
37 37
41 41
42* **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 не был попрошен выдать.42* **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 не был попрошен выдать.
43* **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`.43* **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`.
4444* **Google Workspace**: `issuer` = `https://accounts.google.com`. id\_token Google не содержит groups. Чтобы использовать основанные на группах `allowed_groups` или `managed.policies` с Google в качестве IdP, настройте [`oidc.google_groups`](/ru/claude-apps-gateway-config#oidc), которая ищет группы каждого пользователя через 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 }`.* **Google Workspace**: `issuer` = `https://accounts.google.com`. id\_token Google не содержит groups. Чтобы использовать основанные на группах `allowed_groups` или `managed.policies` с Google в качестве IdP, настройте [`oidc.google_groups`](/docs/ru/claude-apps-gateway-config#oidc), которая ищет группы каждого пользователя через 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 }`.
45 45
46Для поддержки с поставщиком удостоверений, не описанным выше, см. [Troubleshooting](#troubleshooting).46Для поддержки с поставщиком удостоверений, не описанным выше, см. [Troubleshooting](#troubleshooting).
47 47
48<Warning>48<Warning>
49 Refresh tokens позволяют шлюзу молча обновлять сеанс разработчика без отправки разработчика в браузер. Они также управляют deprovisioningом, потому что когда IdP отключает пользователя, следующее обновление не удается и сеанс заканчивается в течение `ttl_hours`. Шлюз запрашивает `offline_access` по умолчанию, чтобы получить refresh token. Если ваш IdP требует явного согласия для offline access, настройте клиент OAuth, чтобы это позволить.49 Refresh tokens позволяют шлюзу молча обновлять сеанс разработчика без отправки разработчика в браузер. Они также управляют deprovisioningом, потому что когда IdP отключает пользователя, следующее обновление не удается и сеанс заканчивается в течение `ttl_hours`. Шлюз запрашивает `offline_access` по умолчанию, чтобы получить refresh token. Если ваш IdP требует явного согласия для offline access, настройте клиент OAuth, чтобы это позволить.
50 50
5151 Если ваш IdP вообще не может выдавать refresh tokens, шлюз все еще работает, но нет молчаливого обновления, поэтому разработчики повторно запускают вход в браузер, когда их сеанс истекает. Чтобы это не происходило каждый час, поднимите [`session.ttl_hours`](/ru/claude-apps-gateway-config#session) на `8` или `12`. Компромисс — это задержка deprovisioningа, потому что без refresh tokens отключенный пользователь сохраняет доступ до истечения более длительного TTL. Если ваш IdP вообще не может выдавать refresh tokens, шлюз все еще работает, но нет молчаливого обновления, поэтому разработчики повторно запускают вход в браузер, когда их сеанс истекает. Чтобы это не происходило каждый час, поднимите [`session.ttl_hours`](/docs/ru/claude-apps-gateway-config#session) на `8` или `12`. Компромисс — это задержка deprovisioningа, потому что без refresh tokens отключенный пользователь сохраняет доступ до истечения более длительного TTL.
52</Warning>52</Warning>
53 53
54<h2 id="deployment">54<h2 id="deployment">
62Несколько решений формируют развертывание помимо того, где оно работает:62Несколько решений формируют развертывание помимо того, где оно работает:
63 63
64* **Стоимость**: нет отдельной лицензии или платы за место для шлюза; это часть бинарного файла `claude`. Вы платите за inference через ваше существующее облачное или обязательство Anthropic, плюс вычисления для контейнера и вашего сборщика телеметрии.64* **Стоимость**: нет отдельной лицензии или платы за место для шлюза; это часть бинарного файла `claude`. Вы платите за inference через ваше существующее облачное или обязательство Anthropic, плюс вычисления для контейнера и вашего сборщика телеметрии.
6565* **Обход**: шлюз не требует, чтобы единственный маршрут к модели проходил через него. Разработчик со своими собственными учетными данными все еще может вызвать поставщика напрямую, поэтому закрытие этого пути — это решение политики сети, например блокировка выхода на `api.anthropic.com` кроме как от шлюза. Блокировка этого выхода также нарушает [проверку безопасности домена WebFetch](/ru/data-usage#webfetch-domain-safety-check), которая вызывает `api.anthropic.com` с каждой машины разработчика; установите `skipWebFetchPreflight: true` в управляемой политике, чтобы отключить это.* **Обход**: шлюз не требует, чтобы единственный маршрут к модели проходил через него. Разработчик со своими собственными учетными данными все еще может вызвать поставщика напрямую, поэтому закрытие этого пути — это решение политики сети, например блокировка выхода на `api.anthropic.com` кроме как от шлюза. Блокировка этого выхода также нарушает [проверку безопасности домена WebFetch](/docs/ru/data-usage#webfetch-domain-safety-check), которая вызывает `api.anthropic.com` с каждой машины разработчика; установите `skipWebFetchPreflight: true` в управляемой политике, чтобы отключить это.
66* **Несколько шлюзов**: каждый шлюз — это отдельное развертывание со своей конфигурацией. CLI хранит отпечаток доверия и учетные данные для каждого имени хоста шлюза, поэтому разные команды могут подключаться к разным шлюзам без конфликтов. Чтобы обслуживать несколько издателей OIDC, запустите отдельные экземпляры.66* **Несколько шлюзов**: каждый шлюз — это отдельное развертывание со своей конфигурацией. CLI хранит отпечаток доверия и учетные данные для каждого имени хоста шлюза, поэтому разные команды могут подключаться к разным шлюзам без конфликтов. Чтобы обслуживать несколько издателей OIDC, запустите отдельные экземпляры.
67* **Бессерверная архитектура**: Cloud Run работает; установите `min-instances: 1`, чтобы избежать холодного обнаружения OIDC. Lambda и Cloud Functions не работают, потому что шлюз — это долгоживущий HTTP сервер.67* **Бессерверная архитектура**: Cloud Run работает; установите `min-instances: 1`, чтобы избежать холодного обнаружения OIDC. Lambda и Cloud Functions не работают, потому что шлюз — это долгоживущий HTTP сервер.
68 68
6969Каждая production топология здесь помещает прокси L7, такой как Ingress, фронтенд Cloud Run или ALB, перед простыми HTTP репликами. Установите [`listen.trusted_proxies`](/ru/claude-apps-gateway-config#listen) на диапазоны источников прокси, чтобы шлюз читал IP клиентов из `X-Forwarded-For`. Шлюз соблюдает заголовок только когда TCP peer доверен; [пример Google Cloud](/ru/claude-apps-gateway-on-gcp) имеет конкретные значения для каждой топологии. Без доверенных прокси каждый запрос выглядит как исходящий с IP прокси, что сворачивает ограничения скорости для каждого IP в один общий bucket и записывает IP прокси в события аудита.Каждая production топология здесь помещает прокси L7, такой как Ingress, фронтенд Cloud Run или ALB, перед простыми HTTP репликами. Установите [`listen.trusted_proxies`](/docs/ru/claude-apps-gateway-config#listen) на диапазоны источников прокси, чтобы шлюз читал IP клиентов из `X-Forwarded-For`. Шлюз соблюдает заголовок только когда TCP peer доверен; [пример Google Cloud](/docs/ru/claude-apps-gateway-on-gcp) имеет конкретные значения для каждой топологии. Без доверенных прокси каждый запрос выглядит как исходящий с IP прокси, что сворачивает ограничения скорости для каждого IP в один общий bucket и записывает IP прокси в события аудита.
70 70
71<h3 id="container-image">71<h3 id="container-image">
72 Образ контейнера72 Образ контейнера
74 74
75Создайте свой собственный образ вокруг нативного бинарного файла `claude` из стандартного выпуска Claude Code:75Создайте свой собственный образ вокруг нативного бинарного файла `claude` из стандартного выпуска Claude Code:
76 76
77771. Загрузите сборку Linux для архитектуры вашего образа из закрепленного выпуска; см. [Установка конкретной версии](/ru/setup#install-a-specific-version) для URL загрузки.1. Загрузите сборку Linux для архитектуры вашего образа из закрепленного выпуска; см. [Установка конкретной версии](/docs/ru/setup#install-a-specific-version) для URL загрузки.
78782. Проверьте его против подписанного GPG `manifest.json` выпуска, как описано в [Целостность бинарного файла и подпись кода](/ru/setup#binary-integrity-and-code-signing).2. Проверьте его против подписанного GPG `manifest.json` выпуска, как описано в [Целостность бинарного файла и подпись кода](/docs/ru/setup#binary-integrity-and-code-signing).
793. Скопируйте его в контекст сборки.793. Скопируйте его в контекст сборки.
80 80
81Зеркалируйте выпуск в ваш внутренний реестр, если ваши сборки не могут достичь хоста выпуска, и закрепите версию, которую запускает ваш флот.81Зеркалируйте выпуск в ваш внутренний реестр, если ваши сборки не могут достичь хоста выпуска, и закрепите версию, которую запускает ваш флот.
82 82
83Помимо бинарного файла, образу нужны:83Помимо бинарного файла, образу нужны:
84 84
8585* **Образ на основе glibc**: единственные динамические зависимости сборки glibc — это библиотеки glibc. Образы на основе Musl нуждаются в сборке `linux-x64-musl` или `linux-arm64-musl` плюс дополнительные пакеты; см. [Настройка Alpine Linux](/ru/setup#alpine-linux-and-musl-based-distributions).* **Образ на основе glibc**: единственные динамические зависимости сборки glibc — это библиотеки glibc. Образы на основе Musl нуждаются в сборке `linux-x64-musl` или `linux-arm64-musl` плюс дополнительные пакеты; см. [Настройка Alpine Linux](/docs/ru/setup#alpine-linux-and-musl-based-distributions).
86* **Записываемый каталог состояния**: шлюз работает как любой пользователь, но минимальные образы не имеют записываемого home. Установите `CLAUDE_CONFIG_DIR` на записываемый путь, такой как `/tmp/.claude`.86* **Записываемый каталог состояния**: шлюз работает как любой пользователь, но минимальные образы не имеют записываемого home. Установите `CLAUDE_CONFIG_DIR` на записываемый путь, такой как `/tmp/.claude`.
87* **Команда контейнера**: `claude gateway --config /etc/claude/gateway.yaml`, с файлом конфигурации, смонтированным только для чтения, и секретами, предоставленными как переменные окружения; шлюз слушает на `listen.port`, по умолчанию `8080`.87* **Команда контейнера**: `claude gateway --config /etc/claude/gateway.yaml`, с файлом конфигурации, смонтированным только для чтения, и секретами, предоставленными как переменные окружения; шлюз слушает на `listen.port`, по умолчанию `8080`.
88 88
99<Note>99<Note>
100 **Workload identity**100 **Workload identity**
101 101
102102 Предпочитайте workload identity платформы вместо статических ключей: IRSA на EKS для Bedrock и для Claude Platform на AWS, Workload Identity на GKE для Agent Platform и workload identity на AKS для Foundry. Установите `auth: {}` в блоке upstream или `use_azure_ad: true` для Foundry, и шлюз подхватывает идентификацию pod через цепь учетных данных по умолчанию этого поставщика. Для кросс-облачного сопряжения, такого как upstream Bedrock на GKE, установите явные учетные данные в блоке `auth` upstream вместо этого. [Справочник `upstreams`](/ru/claude-apps-gateway-config#upstreams) имеет детали настройки для каждой платформы. Предпочитайте workload identity платформы вместо статических ключей: IRSA на EKS для Bedrock и для Claude Platform на AWS, Workload Identity на GKE для Agent Platform и workload identity на AKS для Foundry. Установите `auth: {}` в блоке upstream или `use_azure_ad: true` для Foundry, и шлюз подхватывает идентификацию pod через цепь учетных данных по умолчанию этого поставщика. Для кросс-облачного сопряжения, такого как upstream Bedrock на GKE, установите явные учетные данные в блоке `auth` upstream вместо этого. [Справочник `upstreams`](/docs/ru/claude-apps-gateway-config#upstreams) имеет детали настройки для каждой платформы.
103</Note>103</Note>
104 104
105<h3 id="cloud-run">105<h3 id="cloud-run">
109Настройте сервис следующим образом:109Настройте сервис следующим образом:
110 110
111* Оставьте `listen.port` на его значении по умолчанию `8080`, которое соответствует `PORT` Cloud Run по умолчанию, или установите `port: ${PORT}`111* Оставьте `listen.port` на его значении по умолчанию `8080`, которое соответствует `PORT` Cloud Run по умолчанию, или установите `port: ${PORT}`
112112* Установите `public_url` на внешне доступное происхождение. Для production это обычно имя хоста внутреннего балансировщика нагрузки, потому что `/login` [отклоняет публичные адреса](/ru/claude-apps-gateway#prerequisites) и URL `*.run.app` разрешается на один, поэтому URL Cloud Run один работает только для `curl` или дымового теста браузера. Исключение — сеть, где `*.run.app` разрешается приватно через Private Service Connect и приватную зону Cloud DNS; в этой топологии URL Cloud Run — это действительный `public_url`. [Пример Google Cloud](/ru/claude-apps-gateway-on-gcp#deploy-the-gateway) охватывает оба.* Установите `public_url` на внешне доступное происхождение. Для production это обычно имя хоста внутреннего балансировщика нагрузки, потому что `/login` [отклоняет публичные адреса](/docs/ru/claude-apps-gateway#prerequisites) и URL `*.run.app` разрешается на один, поэтому URL Cloud Run один работает только для `curl` или дымового теста браузера. Исключение — сеть, где `*.run.app` разрешается приватно через Private Service Connect и приватную зону Cloud DNS; в этой топологии URL Cloud Run — это действительный `public_url`. [Пример Google Cloud](/docs/ru/claude-apps-gateway-on-gcp#deploy-the-gateway) охватывает оба.
113* Смонтируйте конфигурацию как том секрета113* Смонтируйте конфигурацию как том секрета
114* Установите `min-instances: 1`, чтобы избежать холодного обнаружения OIDC при первом запросе114* Установите `min-instances: 1`, чтобы избежать холодного обнаружения OIDC при первом запросе
115 115
116<Note>116<Note>
117117 Для полного примера на Google Cloud, охватывающего Cloud Run или GKE, Cloud SQL и Secret Manager, см. [Развертывание на Google Cloud](/ru/claude-apps-gateway-on-gcp). Для полного примера на Google Cloud, охватывающего Cloud Run или GKE, Cloud SQL и Secret Manager, см. [Развертывание на Google Cloud](/docs/ru/claude-apps-gateway-on-gcp).
118</Note>118</Note>
119 119
120<h3 id="push-the-gateway-url-to-developer-machines">120<h3 id="push-the-gateway-url-to-developer-machines">
121 Отправьте URL шлюза на машины разработчиков121 Отправьте URL шлюза на машины разработчиков
122</h3>122</h3>
123 123
124124Как только шлюз начнет обслуживать, отправьте `forceLoginMethod` и `forceLoginGatewayUrl` на каждую машину разработчика через управляемые параметры, через MDM или путем прямого написания файла `managed-settings.json` для каждой ОС. Без этого `/login` показывает стандартный выбор аккаунта без опции шлюза. См. [Управляемые параметры на стороне клиента](/ru/claude-apps-gateway-config#client-side-managed-settings) для путей файлов.Как только шлюз начнет обслуживать, отправьте `forceLoginMethod` и `forceLoginGatewayUrl` на каждую машину разработчика через управляемые параметры, через MDM или путем прямого написания файла `managed-settings.json` для каждой ОС. Без этого `/login` показывает стандартный выбор аккаунта без опции шлюза. См. [Управляемые параметры на стороне клиента](/docs/ru/claude-apps-gateway-config#client-side-managed-settings) для путей файлов.
125 125
126<h2 id="operations">126<h2 id="operations">
127 Операции127 Операции
160 160
161* **Существующие сеансы**: bearer tokens проверяются локально с помощью JWT secret, обновления сеанса не касаются хранилища, и процесс шлюза все еще может обслуживать inference161* **Существующие сеансы**: bearer tokens проверяются локально с помощью JWT secret, обновления сеанса не касаются хранилища, и процесс шлюза все еще может обслуживать inference
162* **Новые входы**: не удаются до восстановления Postgres, потому что поток устройства и его счетчики ограничения скорости живут в Postgres162* **Новые входы**: не удаются до восстановления Postgres, потому что поток устройства и его счетчики ограничения скорости живут в Postgres
163163* **[Применение ограничения расходов](/ru/claude-apps-gateway-spend-limits#postgres-availability)**: по умолчанию не удается открыто во время сбоя, поэтому inference все еще течет; переключите его на отказ закрыто, если вы предпочитаете блокировать, чем работать без учета* **[Применение ограничения расходов](/docs/ru/claude-apps-gateway-spend-limits#postgres-availability)**: по умолчанию не удается открыто во время сбоя, поэтому inference все еще течет; переключите его на отказ закрыто, если вы предпочитаете блокировать, чем работать без учета
164* **Готовность**: `/readyz` сообщает о неготовности во время сбоя, поэтому оркестраторы, которые управляют трафиком на готовность, удаляют каждую реплику из ротации сразу. В этой топологии весь трафик, включая inference, который шлюз все еще может обслуживать, не удается на балансировщике нагрузки до восстановления Postgres. Зонд живучести на `/healthz` продолжает проходить, поэтому реплики не перезапускаются. Укажите зонд готовности на `/healthz` вместо этого, если вы предпочитаете, чтобы вошедшие разработчики продолжали работать через сбой хранилища; стоимость в том, что новые входы не удаются против реплики, которая все еще сообщает о готовности.164* **Готовность**: `/readyz` сообщает о неготовности во время сбоя, поэтому оркестраторы, которые управляют трафиком на готовность, удаляют каждую реплику из ротации сразу. В этой топологии весь трафик, включая inference, который шлюз все еще может обслуживать, не удается на балансировщике нагрузки до восстановления Postgres. Зонд живучести на `/healthz` продолжает проходить, поэтому реплики не перезапускаются. Укажите зонд готовности на `/healthz` вместо этого, если вы предпочитаете, чтобы вошедшие разработчики продолжали работать через сбой хранилища; стоимость в том, что новые входы не удаются против реплики, которая все еще сообщает о готовности.
165 165
166Если ваш IdP выходит из строя, существующие сеансы работают до `ttl_hours`, а новые входы и обновления не удаются. Установите более длительный `ttl_hours`, если ваш IdP имеет частые окна обслуживания.166Если ваш IdP выходит из строя, существующие сеансы работают до `ttl_hours`, а новые входы и обновления не удаются. Установите более длительный `ttl_hours`, если ваш IdP имеет частые окна обслуживания.
191| `admin_audit` | Трассировка мутаций Admin API | `admin.audit_retention_days`, по умолчанию 365 |191| `admin_audit` | Трассировка мутаций Admin API | `admin.audit_retention_days`, по умолчанию 365 |
192| `principal_emails` | Последний просмотренный email каждого principal, отображаемое имя и группы IdP. Содержит PII. | `admin.identity_retention_days` с момента последней активности, по умолчанию 90 |192| `principal_emails` | Последний просмотренный email каждого principal, отображаемое имя и группы IdP. Содержит PII. | `admin.identity_retention_days` с момента последней активности, по умолчанию 90 |
193 193
194194Цикл на 30 секунд истекает строки `kv` прошедшие их TTL, и почасовая очистка применяет окна хранения на таблицы расходов, поэтому ничего не растет без ограничений. Без [ограничений расходов](/ru/claude-apps-gateway-spend-limits) настроенных, только `kv` записывается. Если ваша политика безопасности запрещает DDL из роли приложения, предварительно создайте эти таблицы и `_migrations` с ролью администратора и предоставьте роли приложения `SELECT, INSERT, UPDATE, DELETE` на каждой.Цикл на 30 секунд истекает строки `kv` прошедшие их TTL, и почасовая очистка применяет окна хранения на таблицы расходов, поэтому ничего не растет без ограничений. Без [ограничений расходов](/docs/ru/claude-apps-gateway-spend-limits) настроенных, только `kv` записывается. Если ваша политика безопасности запрещает DDL из роли приложения, предварительно создайте эти таблицы и `_migrations` с ролью администратора и предоставьте роли приложения `SELECT, INSERT, UPDATE, DELETE` на каждой.
195 195
196С ограничениями расходов в использовании, потерянная база данных означает потерю отслеживания расходов и лимитов, а не просто повторные входы разработчиков, поэтому запускайте регулярные резервные копии. Чтобы стереть одного ушедшего разработчика немедленно, а не ждать хранения, запустите `DELETE FROM principal_emails WHERE principal = '<sub>'` напрямую; это удаляет единственную таблицу, содержащую их email, имя и группы. Строки `spend` и `admin_audit` ссылаются только на псевдонимный OIDC `sub`.196С ограничениями расходов в использовании, потерянная база данных означает потерю отслеживания расходов и лимитов, а не просто повторные входы разработчиков, поэтому запускайте регулярные резервные копии. Чтобы стереть одного ушедшего разработчика немедленно, а не ждать хранения, запустите `DELETE FROM principal_emails WHERE principal = '<sub>'` напрямую; это удаляет единственную таблицу, содержащую их email, имя и группы. Строки `spend` и `admin_audit` ссылаются только на псевдонимный OIDC `sub`.
197 197
218| Данные | Путь | Отправлено Anthropic шлюзом |218| Данные | Путь | Отправлено Anthropic шлюзом |
219| ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------- |219| ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------- |
220| Inference (prompts, completions) | CLI → шлюз → ваш upstream | Только если API Anthropic — это настроенный upstream |220| Inference (prompts, completions) | CLI → шлюз → ваш upstream | Только если API Anthropic — это настроенный upstream |
221221| Телеметрия (метрики OTLP, плюс [опциональные логи и трассировки](/ru/claude-apps-gateway-config#telemetry)) | CLI → шлюз → ваш сборщик | Никогда || Телеметрия (метрики OTLP, плюс [опциональные логи и трассировки](/docs/ru/claude-apps-gateway-config#telemetry)) | CLI → шлюз → ваш сборщик | Никогда |
222| Идентификация (email, groups, sub) | IdP → шлюз → JWT → CLI; CLI штампует это на экспортах OTLP | Никогда |222| Идентификация (email, groups, sub) | IdP → шлюз → JWT → CLI; CLI штампует это на экспортах OTLP | Никогда |
223| Управляемые параметры | Ваш YAML шлюза → CLI | Никогда |223| Управляемые параметры | Ваш YAML шлюза → CLI | Никогда |
224| Журнал аудита | Stderr шлюза → ваш агрегатор | Никогда |224| Журнал аудита | Stderr шлюза → ваш агрегатор | Никогда |
237 237
238Две угрозы выходят за рамки, потому что это ваша инфраструктура для защиты:238Две угрозы выходят за рамки, потому что это ваша инфраструктура для защиты:
239 239
240240* **Скомпрометированный хост шлюза**: хост как содержит upstream учетные данные, так и распределяет [управляемые параметры](/ru/claude-apps-gateway-config#managed) каждому подключенному разработчику, поэтому контроль над конфигурацией шлюза сравним с контролем над вашим MDM. Диалог одобрения CLI для параметров, способных к shell, ограничивает молчаливые изменения, но не заменяет безопасность хоста.* **Скомпрометированный хост шлюза**: хост как содержит upstream учетные данные, так и распределяет [управляемые параметры](/docs/ru/claude-apps-gateway-config#managed) каждому подключенному разработчику, поэтому контроль над конфигурацией шлюза сравним с контролем над вашим MDM. Диалог одобрения CLI для параметров, способных к shell, ограничивает молчаливые изменения, но не заменяет безопасность хоста.
241* **Вредоносный поставщик OIDC**: поставщик подписывает id\_tokens, которым шлюз доверяет, поэтому он может утверждать любую идентификацию. Проверка и защита вашего IdP — это ваша ответственность.241* **Вредоносный поставщик OIDC**: поставщик подписывает id\_tokens, которым шлюз доверяет, поэтому он может утверждать любую идентификацию. Проверка и защита вашего IdP — это ваша ответственность.
242 242
243<h3 id="user-code-brute-force-resistance">243<h3 id="user-code-brute-force-resistance">
246 246
247`user_code`, который разработчик вводит на странице проверки `/device`, — это 8 символов, взятых из алфавита из 20 символов, что дает 20⁸ или около 2,56×10¹⁰ комбинаций, и он истекает через 10 минут.247`user_code`, который разработчик вводит на странице проверки `/device`, — это 8 символов, взятых из алфавита из 20 символов, что дает 20⁸ или около 2,56×10¹⁰ комбинаций, и он истекает через 10 минут.
248 248
249249Шлюз применяет ограничения скорости для каждого IP на конечных точках грантов устройства, настраиваемые через [`rate_limits`](/ru/claude-apps-gateway-config#http-tuning). Поднимите лимиты, если много разработчиков входят с одного общего корпоративного NAT адреса. Лимиты применяются только к потоку входа, а не к inference.Шлюз применяет ограничения скорости для каждого IP на конечных точках грантов устройства, настраиваемые через [`rate_limits`](/docs/ru/claude-apps-gateway-config#http-tuning). Поднимите лимиты, если много разработчиков входят с одного общего корпоративного NAT адреса. Лимиты применяются только к потоку входа, а не к inference.
250 250
251<h3 id="compliance-posture">251<h3 id="compliance-posture">
252 Позиция соответствия252 Позиция соответствия
255* **Резидентность данных**: собственная плоскость данных шлюза не отправляет ничего Anthropic, если только API Anthropic не является настроенным upstream; когда это так, ваше существующее соглашение об обработке данных применяется к пути inference. Телеметрия, аудит, идентификация и параметры идут только к назначениям, которые вы настраиваете.255* **Резидентность данных**: собственная плоскость данных шлюза не отправляет ничего Anthropic, если только API Anthropic не является настроенным upstream; когда это так, ваше существующее соглашение об обработке данных применяется к пути inference. Телеметрия, аудит, идентификация и параметры идут только к назначениям, которые вы настраиваете.
256* **Трафик хост-процесса**: хост-процесс — это CLI Claude Code, который может отправлять аналитику запуска и проверки обновлений Anthropic. Для развертываний со строгим выходом установите `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` в окружении контейнера шлюза.256* **Трафик хост-процесса**: хост-процесс — это CLI Claude Code, который может отправлять аналитику запуска и проверки обновлений Anthropic. Для развертываний со строгим выходом установите `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` в окружении контейнера шлюза.
257* **Аналитика клиента**: CLI отключает свою собственную аналитику использования при входе в шлюз, и отчеты об ошибках отключены по умолчанию на поверхностях API третьих сторон.257* **Аналитика клиента**: CLI отключает свою собственную аналитику использования при входе в шлюз, и отчеты об ошибках отключены по умолчанию на поверхностях API третьих сторон.
258258* **Машины клиентов**: CLI разработчиков все еще отправляют проверки имени хоста WebFetch и проверки версии Anthropic, если не установлены `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` и `skipWebFetchPreflight: true`. См. [использование данных](/ru/data-usage).* **Машины клиентов**: CLI разработчиков все еще отправляют проверки имени хоста WebFetch и проверки версии Anthropic, если не установлены `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` и `skipWebFetchPreflight: true`. См. [использование данных](/docs/ru/data-usage).
259* **Рейтинги опроса**: учетные данные шлюза отключают приемник рейтингов, привязанный к Anthropic, поэтому рейтинги не отправляются Anthropic.259* **Рейтинги опроса**: учетные данные шлюза отключают приемник рейтингов, привязанный к Anthropic, поэтому рейтинги не отправляются Anthropic.
260* **Обмен транскриптом**: выбор Yes на подсказке обмена транскриптом опроса записывает локальный файл в `~/.claude/feedback-bundles/` вместо загрузки Anthropic.260* **Обмен транскриптом**: выбор Yes на подсказке обмена транскриптом опроса записывает локальный файл в `~/.claude/feedback-bundles/` вместо загрузки Anthropic.
261* **Обновления клиента**: проверки обновлений отделены от трафика шлюза. Закрепите версии через вашу собственную дистрибуцию и установите `DISABLE_UPDATES`, если ноутбуки не должны получать выпуски. `DISABLE_AUTOUPDATER` останавливает только фоновые обновления, в то время как `claude update` все еще работает.261* **Обновления клиента**: проверки обновлений отделены от трафика шлюза. Закрепите версии через вашу собственную дистрибуцию и установите `DISABLE_UPDATES`, если ноутбуки не должны получать выпуски. `DISABLE_AUTOUPDATER` останавливает только фоновые обновления, в то время как `claude update` все еще работает.
262* **TLS**: обслуживайте `public_url` по HTTPS в production, либо из собственного слушателя шлюза через `listen.tls`, либо из TLS-завершающего ingress перед простыми HTTP репликами с установленным `listen.public_url`. Шлюз не отказывает простой HTTP. IdP должен обслуживать HTTPS в production, и Postgres поддерживает `?sslmode=require`. Установите `Strict-Transport-Security` на вашем ingress.262* **TLS**: обслуживайте `public_url` по HTTPS в production, либо из собственного слушателя шлюза через `listen.tls`, либо из TLS-завершающего ingress перед простыми HTTP репликами с установленным `listen.public_url`. Шлюз не отказывает простой HTTP. IdP должен обслуживать HTTPS в production, и Postgres поддерживает `?sslmode=require`. Установите `Strict-Transport-Security` на вашем ingress.
263263* **Раскрытие уязвимостей**: следуйте [Отчету о проблемах безопасности](/ru/security#reporting-security-issues)* **Раскрытие уязвимостей**: следуйте [Отчету о проблемах безопасности](/docs/ru/security#reporting-security-issues)
264 264
265<h2 id="troubleshooting">265<h2 id="troubleshooting">
266 Устранение неполадок266 Устранение неполадок
272* **Проблема входа**: разработчик запускает `claude --debug-file ./claude-debug.txt`, воспроизводит и отправляет этот файл плюс журнал аудита шлюза для того же окна272* **Проблема входа**: разработчик запускает `claude --debug-file ./claude-debug.txt`, воспроизводит и отправляет этот файл плюс журнал аудита шлюза для того же окна
273* **Проблема inference**: запрошенная модель, настроенные upstreams и журнал аудита шлюза для запроса, который записывает, какой upstream обслужил его и статус ответа273* **Проблема inference**: запрошенная модель, настроенные upstreams и журнал аудита шлюза для запроса, который записывает, какой upstream обслужил его и статус ответа
274 274
275stderr шлюза включает поток событий аудита, журнал аудита записывает идентификаторы разработчиков, а файл отладки записывает выходные данные hook и MCP сервера с машины разработчика. Проверьте и удалите эту информацию перед публикацией в общедоступную проблему.
276
275| Симптом | Причина | Исправление |277| Симптом | Причина | Исправление |
276| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |278| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
277279| `/login` разработчика показывает стандартный выбор аккаунта вместо экрана **Cloud gateway** | `forceLoginMethod` или `forceLoginGatewayUrl` не установлены в управляемых параметрах на этой машине | Разверните [файл управляемых параметров](/ru/claude-apps-gateway#set-the-gateway-url) на устройство; `/login` читает URL шлюза оттуда || `/login` разработчика показывает стандартный выбор аккаунта вместо экрана **Cloud gateway** | `forceLoginMethod` или `forceLoginGatewayUrl` не установлены в управляемых параметрах на этой машине | Разверните [файл управляемых параметров](/docs/ru/claude-apps-gateway#set-the-gateway-url) на устройство; `/login` читает URL шлюза оттуда |
278| Запуск показывает `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` | Установленная сборка Claude Code предшествует поддержке шлюза | Попросите разработчика обновить Claude Code до выпуска, который включает поддержку Cloud gateway |280| Запуск показывает `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` | Установленная сборка Claude Code предшествует поддержке шлюза | Попросите разработчика обновить Claude Code до выпуска, который включает поддержку Cloud gateway |
279281| CLI `/login`: `Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | Имя хоста шлюза разрешается на по крайней мере один публичный IP адрес. Claude Code проверяет каждый разрешенный адрес и требует, чтобы каждый был приватным. Частая причина — dual-stack имя, где одно семейство разрешается на публичный адрес, включая AWS внутренние dual-stack балансировщики нагрузки, которые возвращают публичные AAAA адреса. Публичные конечные точки шлюза, управляемые Anthropic, исключены из проверки, и `/login` принимает их через `https://`. До версии v2.1.206 `/login` отклонял их как любой другой публичный адрес | Попросите имя шлюза разрешаться только на приватные адреса на машинах разработчиков. Для dual-stack имени удалите публичный диапазон записи или обслуживайте отдельное внутреннее DNS имя. См. [предпосылку приватной сети](/ru/claude-apps-gateway#prerequisites). || CLI `/login`: `Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | Имя хоста шлюза разрешается на по крайней мере один публичный IP адрес. Claude Code проверяет каждый разрешенный адрес и требует, чтобы каждый был приватным. Частая причина — dual-stack имя, где одно семейство разрешается на публичный адрес, включая AWS внутренние dual-stack балансировщики нагрузки, которые возвращают публичные AAAA адреса. Публичные конечные точки шлюза, управляемые Anthropic, исключены из проверки, и `/login` принимает их через `https://`. До версии v2.1.206 `/login` отклонял их как любой другой публичный адрес | Попросите имя шлюза разрешаться только на приватные адреса на машинах разработчиков. Для dual-stack имени удалите публичный диапазон записи или обслуживайте отдельное внутреннее DNS имя. См. [предпосылку приватной сети](/docs/ru/claude-apps-gateway#prerequisites). |
280| CLI `/login`: `Gateway login requires a direct connection and does not support connecting through an HTTP proxy` | `HTTPS_PROXY` или `HTTP_PROXY` применяется к хосту шлюза и имя хоста прокси разрешается на публичный адрес. Прокси, чье имя хоста разрешается только на приватные адреса, разрешен и не вызывает эту ошибку | Добавьте хост шлюза в `NO_PROXY` на машине разработчика, чтобы соединение было прямым, или используйте прокси, чье имя хоста разрешается на приватные адреса |282| CLI `/login`: `Gateway login requires a direct connection and does not support connecting through an HTTP proxy` | `HTTPS_PROXY` или `HTTP_PROXY` применяется к хосту шлюза и имя хоста прокси разрешается на публичный адрес. Прокси, чье имя хоста разрешается только на приватные адреса, разрешен и не вызывает эту ошибку | Добавьте хост шлюза в `NO_PROXY` на машине разработчика, чтобы соединение было прямым, или используйте прокси, чье имя хоста разрешается на приватные адреса |
281| CLI `/login`: `Could not resolve gateway host <host>` | Машина не может разрешить внутреннее DNS имя шлюза, обычно потому что она не в корпоративной сети | Попросите разработчика подключиться к вашей сети или VPN, затем повторите попытку `/login` |283| CLI `/login`: `Could not resolve gateway host <host>` | Машина не может разрешить внутреннее DNS имя шлюза, обычно потому что она не в корпоративной сети | Попросите разработчика подключиться к вашей сети или VPN, затем повторите попытку `/login` |
282| Загрузка выходит с ошибкой валидации конфигурации, называющей `store.postgres_url` | Postgres не настроен; шлюз требует Postgres | Установите `store.postgres_url`. Для локальной разработки используйте одноразовый контейнер: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`. |284| Загрузка выходит с ошибкой валидации конфигурации, называющей `store.postgres_url` | Postgres не настроен; шлюз требует Postgres | Установите `store.postgres_url`. Для локальной разработки используйте одноразовый контейнер: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`. |
283285| Загрузка выходит: `requires the native binary` | Запуск под Node вместо нативного бинарного файла | Установите Claude Code с одним из [методов автономной установки](/ru/setup) || Загрузка выходит: `requires the native binary` | Запуск под Node вместо нативного бинарного файла | Установите Claude Code с одним из [методов автономной установки](/docs/ru/setup) |
284| Загрузка выходит с ошибкой обнаружения OIDC после `config.load` | `oidc.issuer` недоступен или цепь TLS не доверена | Проверьте, что издатель доступен из pod и обслуживает `/.well-known/openid-configuration`. Установите `ca_cert_pem` для приватной PKI. |286| Загрузка выходит с ошибкой обнаружения OIDC после `config.load` | `oidc.issuer` недоступен или цепь TLS не доверена | Проверьте, что издатель доступен из pod и обслуживает `/.well-known/openid-configuration`. Установите `ca_cert_pem` для приватной PKI. |
285| Загрузка выходит с ошибкой разрешения Postgres | Роль приложения не имеет `CREATE TABLE` | Предварительно создайте схему с ролью администратора и предоставьте DML роли приложения или временно предоставьте DDL для загрузок, которые применяют новые миграции |287| Загрузка выходит с ошибкой разрешения Postgres | Роль приложения не имеет `CREATE TABLE` | Предварительно создайте схему с ролью администратора и предоставьте DML роли приложения или временно предоставьте DDL для загрузок, которые применяют новые миграции |
286| `/oauth/callback` показывает "Sign-in could not be completed" | Домен email отклонен, валидация id\_token не удалась или `email_verified` явно `false`, что шлюз всегда отклоняет без переопределения | Проверьте `allowed_email_domains` и что IdP возвращает проверенное утверждение `email`. Для `email_verified: false` исправьте проверку на стороне IdP. Если ваш IdP выдает email под другим именем утверждения, установите `oidc.email_claim`. |288| `/oauth/callback` показывает "Sign-in could not be completed" | Домен email отклонен, валидация id\_token не удалась или `email_verified` явно `false`, что шлюз всегда отклоняет без переопределения | Проверьте `allowed_email_domains` и что IdP возвращает проверенное утверждение `email`. Для `email_verified: false` исправьте проверку на стороне IdP. Если ваш IdP выдает email под другим именем утверждения, установите `oidc.email_claim`. |
293| Вход завершается в IdP, но callback не удается, с ошибкой CSP в Chrome или "this sign-in link has expired" в Safari | IdP вернул код через `response_mode=form_post`, который автоматически отправляет его cross-origin через POST на `/oauth/callback`. Chrome блокирует это под строгой CSP; Safari позволяет отправку, но callback читает только строку запроса. | Убедитесь, что ваш IdP соблюдает `response_mode=query`, который шлюз явно запрашивает, чтобы callback был простым перенаправлением |295| Вход завершается в IdP, но callback не удается, с ошибкой CSP в Chrome или "this sign-in link has expired" в Safari | IdP вернул код через `response_mode=form_post`, который автоматически отправляет его cross-origin через POST на `/oauth/callback`. Chrome блокирует это под строгой CSP; Safari позволяет отправку, но callback читает только строку запроса. | Убедитесь, что ваш IdP соблюдает `response_mode=query`, который шлюз явно запрашивает, чтобы callback был простым перенаправлением |
294| Вход работает локально, но не удается за ALB | `public_url` не установлен, поэтому IdP получает внутреннее происхождение `http://` как `redirect_uri` | Установите `listen.public_url` на внешнее происхождение `https://` |296| Вход работает локально, но не удается за ALB | `public_url` не установлен, поэтому IdP получает внутреннее происхождение `http://` как `redirect_uri` | Установите `listen.public_url` на внешнее происхождение `https://` |
295| Разработчик видит подсказку доверия повторно | Сертификат TLS ротируется для каждой реплики или для каждого запроса | Используйте стабильный сертификат на ingress или завершите TLS один раз и запустите реплики по простому HTTP внутри |297| Разработчик видит подсказку доверия повторно | Сертификат TLS ротируется для каждой реплики или для каждого запроса | Используйте стабильный сертификат на ingress или завершите TLS один раз и запустите реплики по простому HTTP внутри |
296298| CLI `/login`: "Could not verify the gateway's TLS certificate" или `SELF_SIGNED_CERT_IN_CHAIN` | Цепь TLS шлюза подписана приватным CA, не в хранилище доверия хоста CLI | Claude Code читает хранилище доверия ОС по умолчанию на нативном бинарном файле и на Node 22.15 или позже; [`CLAUDE_CODE_CERT_STORE`](/ru/network-config#ca-certificate-store) управляет этим поведением. Если CA установлен в хранилище доверия ОС, убедитесь, что разработчики используют текущий runtime. В противном случае установите `NODE_EXTRA_CA_CERTS` на сертификат CA PEM перед запуском. Подсказка отпечатка первого подключения все еще применяется. || CLI `/login`: "Could not verify the gateway's TLS certificate" или `SELF_SIGNED_CERT_IN_CHAIN` | Цепь TLS шлюза подписана приватным CA, не в хранилище доверия хоста CLI | Claude Code читает хранилище доверия ОС по умолчанию на нативном бинарном файле и на Node 22.15 или позже; [`CLAUDE_CODE_CERT_STORE`](/docs/ru/network-config#ca-certificate-store) управляет этим поведением. Если CA установлен в хранилище доверия ОС, убедитесь, что разработчики используют текущий runtime. В противном случае установите `NODE_EXTRA_CA_CERTS` на сертификат CA PEM перед запуском. Подсказка отпечатка первого подключения все еще применяется. |
297 299
298<h2 id="related">300<h2 id="related">
299 Связанное301 Связанное
300</h2>302</h2>
301 303
302304* [Обзор шлюза Claude apps](/ru/claude-apps-gateway): быстрый старт и подключение разработчика* [Обзор шлюза Claude apps](/docs/ru/claude-apps-gateway): быстрый старт и подключение разработчика
303305* [Справочник по конфигурации](/ru/claude-apps-gateway-config): каждый параметр файла `gateway.yaml`* [Справочник по конфигурации](/docs/ru/claude-apps-gateway-config): каждый параметр файла `gateway.yaml`