Перейти к содержимому

Запустить сервер Connect

Control Center Connect выполняет входы в провайдеры (GitHub, Google Calendar, Linear, Slack) для серверов, которые не зарегистрировали собственных приложений. Это руководство показывает, как запустить собственный Connect, чтобы приложения провайдеров, их секреты и список серверов, которым разрешено ими пользоваться, оставались у вас.

Что Connect может и чего не может видеть, описано в справке по Connect. Прочитайте её сначала, если решаете, запускать ли свой.

  • Публичный адрес HTTPS для Connect, например https://connect.example.com, за прокси, терминирующим TLS. Обычный http принимается только на loopback
  • Docker или cc_server, который можно перезапустить с дополнительными переменными окружения
  • Право регистрировать приложения у каждого провайдера, которого вы хотите обслуживать
  • Серверы, которые будут им пользоваться, и их владельцы под рукой: у каждого сервера есть идентификатор установки, который вы добавляете в список разрешённых Connect

Выберите URL сейчас и больше его не меняйте. CONNECT_PUBLIC_URL входит во всё, что делает Connect: к нему привязаны подписи запросов, запечатанные учётные данные, URL перенаправления провайдеров и идентификатор установки каждого сервера. Изменить его позже — значит заново зарегистрировать перенаправления и заставить каждого человека войти снова.

Шаг 2: Зарегистрируйте приложения провайдеров

Заголовок раздела «Шаг 2: Зарегистрируйте приложения провайдеров»

Регистрируйте только тех провайдеров, которых хотите обслуживать. Провайдер с неполным набором переменных исключается из конфигурации Connect, и серверы видят его недоступным. Ниже <base> — это ваш CONNECT_PUBLIC_URL.

Провайдер Что зарегистрировать Что сохранить
Приложение GitHub Callback URL <base>/oauth/github/callback. Setup URL <base>/oauth/github/setup с включённым Redirect on update. Оставьте Request user authorization (OAuth) during installation выключенным: если он включён, GitHub игнорирует setup URL. Оставьте Expire user authorization tokens включённым Id приложения, slug, id клиента, секрет клиента, закрытый ключ
Google Клиент OAuth типа Web application с URI перенаправления <base>/oauth/google/callback и включённый Google Calendar API Id клиента, секрет клиента
Linear Приложение OAuth с URL обратного вызова <base>/oauth/linear/callback и <base>/oauth/linear_app/callback Только id клиента
Slack Redirect URLs <base>/oauth/slack_oidc/callback и <base>/oauth/slack/callback. Event Subscriptions по адресу <base>/v1/hooks/slack/events (app_mention, message.*, assistant_thread_*, app_uninstalled, tokens_revoked). Slash-команды по адресу <base>/v1/hooks/slack/commands. Ротация токенов включена Id приложения, id клиента, секрет клиента, секрет подписи

Дайте GitHub App следующие разрешения на репозиторий: Metadata — чтение, Contents — чтение и запись, Pull requests — чтение и запись, Issues — чтение и запись, Checks, Actions и Commit statuses — чтение. Для запросов ревью от команд добавьте разрешение организации Members на чтение. Вебхуки можно оставить выключенными: серверы опрашивают.

Connect нужен закрытый ключ GitHub App (Generate a private key в настройках App). Он подписывает запросы App, которые находят установку, покрывающую репозиторий (или, если у репозитория её нет, установку владельца), и выпускает токен установки для одного репозитория — каждый раз только после того, как вход запрашивающего человека подтвердил доступ к этому репозиторию.

Каждый сервер на вашем Connect делит бота App. Он может читать, комментировать, ставить метки и реагировать от имени бота для любого из них. Ревью пул-реквестов от имени бота разрешено только серверам, перечисленным в CONNECT_GITHUB_REVIEW_BOT_INSTALLS (их идентификаторы установки через запятую); каждый другой сервер публикует ревью токеном самого ревьюера. Push никогда не выполняется от имени бота. Чтобы позволить своему серверу ревьюить от имени бота, добавьте его идентификатор установки туда и перезапустите. Храните файл ключа как секрет, как ключ печати. Linear не нужен секрет: Connect возвращает код серверу, который сам завершает обмен.

Connect отвечает только серверам из своего списка разрешённых. На каждом сервере направьте его на свой Connect, а затем прочитайте его идентификатор установки:

  1. Откройте Настройки → Сервер → Единый вход, откройте карточку Control Center Connect и выберите Использовать свой сервер Connect
  2. Введите свой URL и сохраните. Карточка покажет Идентификатор установки сервера

Из терминала на хосте сервера то же самое выглядит так:

Окно терминала
cc_server connect enable --url https://connect.example.com
cc_server connect status

status печатает идентификатор установки. Пока не выполнен шаг 5, он показывает install_blocked, и это ожидаемо.

Идентификатор установки выводится для каждого адреса Connect отдельно, поэтому у одного и того же сервера для каждого Connect, с которым он общается, свой идентификатор. Он меняется только тогда, когда владелец сервера меняет ключ.

Connect шифрует все учётные данные, которые возвращает, ключом печати. Создайте его и храните как файл с секретом:

Окно терминала
docker run --rm ghcr.io/samuelalev/cc-connect:latest \
cc-connect-config seal-key > seal_keys
chmod 600 seal_keys

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

Каждый выпуск публикует ghcr.io/samuelalev/cc-connect с подтверждением происхождения сборки. В продакшене закрепляйте тег версии.

Окно терминала
docker run -d --name cc-connect -p 8790:8790 \
-e CONNECT_PUBLIC_URL=https://connect.example.com \
-e CONNECT_ALLOWED_INSTALLS=<install id>,<install id> \
-e CONNECT_SEAL_KEYS_FILE=/run/secrets/seal_keys \
-v "$PWD/seal_keys:/run/secrets/seal_keys:ro" \
-e CONNECT_GITHUB_APP_ID=123456 \
-e CONNECT_GITHUB_APP_SLUG=acme-control-center \
-e CONNECT_GITHUB_CLIENT_ID=Iv23li0123456789abcd \
-e CONNECT_GITHUB_CLIENT_SECRET_FILE=/run/secrets/github \
-v "$PWD/github_secret:/run/secrets/github:ro" \
-e CONNECT_GITHUB_APP_PRIVATE_KEY_FILE=/run/secrets/github_key \
-v "$PWD/github_app_key.pem:/run/secrets/github_key:ro" \
-v cc-connect-data:/data \
ghcr.io/samuelalev/cc-connect:latest

Направьте обратный прокси на порт 8790 и задайте CONNECT_TRUST_PROXY равным числу прокси перед Connect, чтобы лимит на адрес видел адрес каждого клиента. Образ работает от непривилегированного пользователя, хранит своё состояние в томе /data и имеет встроенную проверку работоспособности (cc-connect --healthcheck, которая опрашивает /healthz: процесс отвечает). /readyz дополнительно проверяет, что его хранилища состояния и привязок отвечают и что Redis, если он используется, работает с maxmemory-policy noeviction; укажите на него проверку готовности оркестратора.

Страница согласия на вход отвечает POST-формой, которую Connect принимает только со своей страницы: Sec-Fetch-Site, если он передан, должен быть same-origin, а Origin, если он передан, должен совпадать с источником CONNECT_PUBLIC_URL; запрос без обоих заголовков отклоняется. Поэтому прокси должен пропускать оба заголовка без изменений, а CONNECT_PUBLIC_URL должен быть тем адресом, который реально открывают браузеры людей. Если продолжение на этой странице всегда показывает «Срок действия этой ссылки истёк», а в журнале есть oauth.done_refused с причиной origin или no_origin, один из этих двух параметров выключен.

Connect отказывается запускаться (код выхода 78), если его конфигурация открыта, небезопасна или не доделана, и печатает, какая переменная неверна. Его останавливают отсутствующий список разрешённых, адрес http не на loopback, некорректный ключ печати или одновременно заданные NAME и NAME_FILE.

Проверка: на каждом сервере карточка Connect показывает Работает, а Где выполняется каждый вход называет Connect для каждого зарегистрированного вами провайдера. cc_server connect status печатает Health: ok и те же каналы.

Сервер может сам размещать Connect вместо отдельного контейнера. Смонтированный сервис — тот же самый, что запускает образ.

  1. Поместите переменные CONNECT_* в файл .env сервера, как на шаге 5. Сервер отказывается запускаться, если какой-либо секрет Connect, включая CONNECT_SENTRY_DSN, экспортирован в его окружении
  2. Добавьте CC_SERVER_CONNECT_HOST=on
  3. Перезапустите сервер. Его журнал напечатает embedded Connect at <url>
Окно терминала
CC_SERVER_CONNECT_HOST=on
CONNECT_ALLOWED_INSTALLS=<install id>
CONNECT_SEAL_KEYS=<output of cc-connect-config seal-key>
CONNECT_GITHUB_APP_ID=123456
CONNECT_GITHUB_APP_SLUG=acme-control-center
CONNECT_GITHUB_CLIENT_ID=Iv23li0123456789abcd
CONNECT_GITHUB_CLIENT_SECRET=<secret>
CONNECT_GITHUB_APP_PRIVATE_KEY_FILE=/etc/cc/github_app_key.pem

После этого Connect обслуживается по адресу <server>/connect:

  • CONNECT_PUBLIC_URL по умолчанию — источник публичного URL сервера плюс /connect. За прокси задайте его явно. Его путь должен быть ровно /connect, и он должен быть HTTPS, если это не loopback
  • До смонтированного сервиса доходят только переменные CONNECT_*, поэтому он никогда не заимствует собственные приложения провайдеров сервера
  • CONNECT_ALLOWED_INSTALLS по-прежнему обязателен, в том числе для самого размещающего сервера
  • Неправильно настроенное монтирование не даёт серверу загрузиться, а не обслуживает открытого брокера
  • Демонстрационный сервер его никогда не монтирует

Зарегистрируйте перенаправления провайдеров на https://<server>/connect, затем направьте серверы (включая размещающий) на этот URL, как на шаге 3.

Каждая настройка — это переменная окружения. Любой секрет можно вместо этого брать из смонтированного файла: задайте NAME_FILE вместо NAME. Connect перечитывает файл не чаще чем раз в 30 секунд и сохраняет последнее корректное значение. Секреты с пометкой двойной во время смены также принимают NAME_PREVIOUS (или NAME_PREVIOUS_FILE).

Переменная По умолчанию Значение
CONNECT_PUBLIC_URL обязательна Канонический публичный URL. HTTPS или http только на loopback. Путь означает монтирование. Без query и фрагмента
CONNECT_ALLOWED_INSTALLS обязательна Идентификаторы установки через запятую. * принимается только вместе с CONNECT_SIGNED_CONFIG_FILE
CONNECT_DENY_INSTALLS Идентификаторы установки, которым отказывают, даже если они разрешены
CONNECT_GITHUB_ALLOWED_OWNERS Числовые id владельцев GitHub. Если задано, токены репозиториев выпускаются только для принадлежащих им репозиториев. Не ограничивает, кто входит: человек, которому разрешено пользоваться этим Connect, всё равно получает собственный токен пользователя App. Чтобы обслуживать только одну организацию, держите App приватным для неё
CONNECT_GITHUB_REVIEW_BOT_INSTALLS Идентификаторы установки, которым разрешено, чтобы бот App ревьюил пул-реквесты. По умолчанию пусто; * отклоняется, и каждый id также должен быть разрешён
CONNECT_HOST, CONNECT_PORT 0.0.0.0, 8790 Адрес привязки и порт
CONNECT_TRUST_PROXY 0 Доверенные переходы прокси в X-Forwarded-For (от 0 до 8). Используется только для лимитов на адрес, подсказки сети на странице входа и записанного в журнал адреса. За прокси 0 считает каждого клиента прокси, и журнал сообщает об этом один раз
Переменная По умолчанию Значение
CONNECT_GITHUB_APP_ID, CONNECT_GITHUB_APP_SLUG, CONNECT_GITHUB_CLIENT_ID GitHub App
CONNECT_GITHUB_CLIENT_SECRET Секрет, двойной
CONNECT_GITHUB_APP_PRIVATE_KEY Секрет. Закрытый ключ App (PEM)
CONNECT_GOOGLE_CLIENT_ID, CONNECT_GOOGLE_CLIENT_SECRET Клиент Google. Секрет двойной
CONNECT_LINEAR_CLIENT_ID Приложение Linear. Без секрета
CONNECT_SLACK_APP_ID, CONNECT_SLACK_CLIENT_ID Приложение Slack
CONNECT_SLACK_CLIENT_SECRET, CONNECT_SLACK_SIGNING_SECRET Секреты, двойные
CONNECT_KLIPY_APP_KEY Ключ поиска GIF Klipy. Секрет, двойной
CONNECT_KLIPY_MODE proxy proxy оставляет ключ в Connect; key передаёт его серверам
CONNECT_<LANE>_SECRET_GENERATION 1 GitHub, Google и Slack: поколение, записываемое в новые печати
CONNECT_<LANE>_MIN_SEAL_GENERATION 1 GitHub, Google и Slack: для более старых печатей нужно войти снова
CONNECT_<LANE>_ACCEPTS_NEW true Любой канал: false останавливает новые входы, а существующие продолжают обновляться
Переменная По умолчанию Значение
CONNECT_SEAL_BACKEND local local или gcp-kms
CONNECT_SEAL_KEYS Секрет, обязателен для local. Записи kid:key через запятую, самая новая первой; старые записи по-прежнему расшифровывают
CONNECT_KMS_KEY projects/…/locations/…/keyRings/…/cryptoKeys/…, обязателен для gcp-kms
CONNECT_STATE memory memory для одного экземпляра, redis для нескольких. Полное хранилище в памяти отказывает в новых входах и запросах, а не забывает живую запись
CONNECT_REDIS_URL Секрет. redis:// или rediss://. Redis 6.2 или новее с maxmemory-policy noeviction, обе вещи проверяются при запуске
CONNECT_REDIS_CA_FILE Пакет CA для rediss://
CONNECT_BINDINGS file Где хранятся привязки команд Slack: file или firestore
CONNECT_DATA_DIR data (/data в образе) Содержит bindings.json. Блокируется одним Connect: второй на том же каталоге не запускается
CONNECT_FIRESTORE_PROJECT, CONNECT_FIRESTORE_DATABASE база данных (default) Для CONNECT_BINDINGS=firestore. Connect не запускается, если Firestore не отвечает
Переменная По умолчанию Значение
CONNECT_SIGNED_CONFIG_FILE Конфигурация, подписанная офлайн, отдаётся как есть. Используется размещённым Connect от Control Center
CONNECT_CONFIG_PUBLIC_KEYS Ключи, по которым должна проверяться подписанная конфигурация
CONNECT_CONFIG_EPOCH 1 Эпоха конфигурации, которую генерирует самостоятельно размещённый Connect
CONNECT_LOG_HMAC_KEY случайный для каждого процесса Секрет. Задайте его, чтобы метки, заменяющие идентификаторы установки, оставались стабильными между перезапусками и экземплярами
CONNECT_SENTRY_DSN Секрет. https-DSN Sentry, куда сообщаются строки ошибок: тип ошибки, кадры стека, маршрут и id запроса, никогда не сообщение, тело или заголовок
CONNECT_SENTRY_ENVIRONMENT self-hosted Окружение Sentry
CONNECT_VERSION, CONNECT_IMAGE_DIGEST Сообщаются через /v1/version
CONNECT_RATE_INSTALL_PER_MINUTE 600 Запросов на установку
CONNECT_RATE_IP_PER_MINUTE 300 Запросов на адрес (адрес IPv6 считается по /64)
CONNECT_RATE_GLOBAL_PER_SECOND 500 Запросов на весь экземпляр
CONNECT_RATE_SLACK_HOOK_IP_PER_MINUTE 600 Доставок событий и команд Slack на адрес, учитываются отдельно от других запросов
CONNECT_RATE_SLACK_HOOK_GLOBAL_PER_SECOND 100 Доставок событий и команд Slack на весь экземпляр
CONNECT_RATE_SLACK_TEAM_PER_MINUTE 600 Событий Slack на команду
CONNECT_RATE_KLIPY_PER_MINUTE 120 Поисков GIF на установку
CONNECT_RATE_KLIPY_IP_PER_MINUTE 240 Поисков GIF на адрес, по всем серверам
CONNECT_RATE_LOGINS_IP_PER_10_MINUTES 60 Начатых входов на адрес
CONNECT_RATE_GITHUB_TOKENS_ACCOUNT_PER_HOUR 30 Выпущенных токенов GitHub на один аккаунт GitHub на одном сервере (входы, обновления, токены репозиториев)
CONNECT_RATE_GITHUB_TOKENS_ACCOUNT_CEILING_PER_HOUR 4 × значение выше (120) То же для аккаунта GitHub на всех серверах
CONNECT_RATE_GITHUB_TOKENS_IP_PER_HOUR 600 Выпущенных токенов GitHub на адрес
CONNECT_RATE_GITHUB_EXCHANGE_CEILING_PER_HOUR 500 Новых входов GitHub для всего приложения
CONNECT_RATE_GITHUB_APP_MINTS_INSTALL_PER_HOUR 120 Токенов бота на сервер
CONNECT_RATE_GITHUB_APP_MINTS_ACCOUNT_PER_HOUR 240 Токенов бота на запрашивающий аккаунт GitHub, по всем серверам
CONNECT_RATE_GITHUB_APP_CEILING_PER_HOUR 3000 Токенов бота для всего приложения
CONNECT_RATE_GITHUB_TOKEN_CEILING_PER_HOUR 1500 Обновления и токены репозиториев для всего приложения. У новых входов свой лимит выше
CONNECT_GITHUB_TOKEN_CAP_WARN 10 Живых токенов репозиториев, которые может держать один аккаунт GitHub, прежде чем Connect запишет предупреждение
CONNECT_RATE_RETIRE_IP_PER_HOUR 10 Идентификаторов установки, выведенных из обращения, на адрес (на /48 для IPv6)

Вызов сверх лимита получает ответ rate_limited. Серверы повторяют позже и никогда не выводят из-за этого никого из системы.

Для большинства организаций достаточно одного экземпляра с CONNECT_STATE=memory. Нескольким экземплярам за одним адресом нужны CONNECT_STATE=redis и CONNECT_BINDINGS=firestore, чтобы вход, начатый на одном экземпляре, мог завершиться на другом, и чтобы каждый экземпляр видел одни и те же привязки Slack и выведенные из обращения идентификаторы установки. Общий CONNECT_DATA_DIR не работает: первый Connect блокирует его. Лимиты запросов на установку, на адрес и на экземпляр действуют на каждом экземпляре; лимиты на входы, токены GitHub, токены бота, поиски GIF на адрес, выведение из обращения и команды Slack общие через хранилище состояния.

Никто не выходит из системы:

  1. Создайте новый секрет у провайдера и сохраните старый
  2. Перенесите старое значение в NAME_PREVIOUS, поместите новое в NAME и увеличьте CONNECT_<LANE>_SECRET_GENERATION. Смонтированные файлы подхватываются в течение 30 секунд
  3. Дождитесь обновления входов, затем удалите старый секрет у провайдера и уберите NAME_PREVIOUS

Чтобы сменить ключ печати, поставьте новую запись cc-connect-config seal-key первой в CONNECT_SEAL_KEYS и сохраните старую, пока её печати не обновятся.

Серверы запоминают id приложения и клиента, которые ваш Connect объявил, когда они впервые им воспользовались. Если вы замените приложение, карточка Connect на каждом сервере покажет Приложения Connect изменились, и входы через Connect приостановятся, пока владелец сервера не нажмёт Доверять новым приложениям. Предупредите владельцев серверов перед переключением, чтобы они знали, что это запрос от вас.

Добавьте его идентификатор установки в CONNECT_DENY_INSTALLS и перезапустите. Его владелец увидит «Connect заблокировал идентификатор установки этого сервера. Свяжитесь с оператором вашего сервера Connect.», и все входы через Connect на нём остановятся.

Сервер также выводит из обращения собственный старый идентификатор установки, когда его владелец меняет ключ. Он доказывает, что идентификатор его собственный, одной печатью учётных данных, которую этот Connect создал для него, поэтому вывести идентификатор может только сервер, который хотя бы раз провёл вход через Connect. Connect хранит выведенные из обращения идентификаторы навсегда, так что старый ключ и все печати, сделанные для него, перестают работать, а привязанные к старому идентификатору рабочие пространства Slack освобождаются. Токены, уже выданные, истекают сами: в течение 8 часов для токенов человека и 1 часа для токенов бота. Connect хранит не более 100 000 выведенных из обращения идентификаторов; сверх этого смена ключа отклоняется, и журнал сообщает об этом на уровне error.

Сервер сообщает, что Connect его заблокировал

Заголовок раздела «Сервер сообщает, что Connect его заблокировал»

Его идентификатора установки нет в CONNECT_ALLOWED_INSTALLS, он есть в CONNECT_DENY_INSTALLS или был выведен из обращения при смене ключа. Идентификатор меняется, когда владелец сервера меняет ключ; попросите новый.

Все входы к одному провайдеру завершаются ошибкой

Заголовок раздела «Все входы к одному провайдеру завершаются ошибкой»

Одной из его переменных может не хватать, поэтому Connect исключил канал. Проверьте журнал запуска и таблицы выше. GitHub нужны все пять значений: id приложения, slug, id клиента, секрет клиента и закрытый ключ; Google нужны и id клиента, и секрет.

Входы завершаются ошибкой несовпадения перенаправления

Заголовок раздела «Входы завершаются ошибкой несовпадения перенаправления»

Перенаправление, зарегистрированное у провайдера, не совпадает в точности с CONNECT_PUBLIC_URL. Сравните схему, хост, порт и путь /connect для смонтированного Connect.

Ключ печати изменился или потерян, сервер сменил свой ключ или данные сервера восстановили на другой машине. Запечатанные учётные данные открываются только для той установки и того Connect, которые их создали.