Запустить сервер 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
Шаг 1: Выберите адрес
Заголовок раздела «Шаг 1: Выберите адрес»Выберите 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 клиента, секрет клиента, закрытый ключ |
Клиент 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 возвращает код серверу, который сам завершает обмен.
Шаг 3: Соберите идентификаторы установки
Заголовок раздела «Шаг 3: Соберите идентификаторы установки»Connect отвечает только серверам из своего списка разрешённых. На каждом сервере направьте его на свой Connect, а затем прочитайте его идентификатор установки:
- Откройте Настройки → Сервер → Единый вход, откройте карточку Control Center Connect и выберите Использовать свой сервер Connect
- Введите свой URL и сохраните. Карточка покажет Идентификатор установки сервера
Из терминала на хосте сервера то же самое выглядит так:
cc_server connect enable --url https://connect.example.comcc_server connect statusstatus печатает идентификатор установки. Пока не выполнен шаг 5, он показывает
install_blocked, и это ожидаемо.
Идентификатор установки выводится для каждого адреса Connect отдельно, поэтому у одного и того же сервера для каждого Connect, с которым он общается, свой идентификатор. Он меняется только тогда, когда владелец сервера меняет ключ.
Шаг 4: Создайте ключ печати
Заголовок раздела «Шаг 4: Создайте ключ печати»Connect шифрует все учётные данные, которые возвращает, ключом печати. Создайте его и храните как файл с секретом:
docker run --rm ghcr.io/samuelalev/cc-connect:latest \ cc-connect-config seal-key > seal_keyschmod 600 seal_keysПотеря ключа печати выводит всех из системы: без него ни одну печать не открыть.
Шаг 5: Запустите контейнер
Заголовок раздела «Шаг 5: Запустите контейнер»Каждый выпуск публикует 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 внутри cc_server
Заголовок раздела «Смонтировать Connect внутри cc_server»Сервер может сам размещать Connect вместо отдельного контейнера. Смонтированный сервис — тот же самый, что запускает образ.
- Поместите переменные
CONNECT_*в файл.envсервера, как на шаге 5. Сервер отказывается запускаться, если какой-либо секрет Connect, включаяCONNECT_SENTRY_DSN, экспортирован в его окружении - Добавьте
CC_SERVER_CONNECT_HOST=on - Перезапустите сервер. Его журнал напечатает
embedded Connect at <url>
CC_SERVER_CONNECT_HOST=onCONNECT_ALLOWED_INSTALLS=<install id>CONNECT_SEAL_KEYS=<output of cc-connect-config seal-key>CONNECT_GITHUB_APP_ID=123456CONNECT_GITHUB_APP_SLUG=acme-control-centerCONNECT_GITHUB_CLIENT_ID=Iv23li0123456789abcdCONNECT_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 общие через хранилище состояния.
Сменить секрет провайдера
Заголовок раздела «Сменить секрет провайдера»Никто не выходит из системы:
- Создайте новый секрет у провайдера и сохраните старый
- Перенесите старое значение в
NAME_PREVIOUS, поместите новое вNAMEи увеличьтеCONNECT_<LANE>_SECRET_GENERATION. Смонтированные файлы подхватываются в течение 30 секунд - Дождитесь обновления входов, затем удалите старый секрет у провайдера и уберите
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, которые их создали.