Запустити сервер 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 має спільного бота застосунку. Він може читати, коментувати, ставити мітки й реагувати від імені бота в будь-якому з них. Рев’ю pull requests від імені бота дозволені лише для серверів, які ви перелічили в 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; POST без жодного з них відхиляється. Тож проксі має передавати обидва заголовки без змін, а CONNECT_PUBLIC_URL має бути адресою, яку справді використовують браузери людей. Якщо продовження на цій сторінці завжди показує “This link has expired”, а журнал показує 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і далі обов’язковий, зокрема для самого сервера, що розміщує Connect- Неправильно налаштоване монтування не дає серверу завантажитися, а не обслуговує відкритого брокера
- Демонстраційний сервер його ніколи не монтує
Зареєструйте переспрямування провайдерів на 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 |
Ідентифікатори встановлення, яким дозволено рев’ю pull requests від імені бота. Порожньо за замовчуванням; * відхиляється, і кожен 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, куди надсилаються рядки помилок: тип помилки, кадри стеку, маршрут і ідентифікатор запиту, ніколи повідомлення, тіло чи заголовок | |
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 зберігає виведені з обігу ідентифікатори назавжди, тож старий ключ і кожна печатка, створена для нього, перестають працювати, а команди 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, які їх створили.