Конфигурация

Gotcha полностью настраивается переменными окружения с префиксом GOTCHA_. Ни одного конфиг-файла, ни одной настройки через веб-интерфейс для системных параметров — только переменные окружения. Их авторитетный источник — файл cmd/gotcha/config.go в исходном коде; этот документ — читаемое описание того же самого, сгруппированное по смыслу. Шаблон со всеми переменными и комментариями лежит в .env.example в корне репозитория.

Конвенция именования переменных

Числовая переменная несёт единицу измерения прямо в имени: _SECONDS, _DAYS, _HOURS, _BYTES, _PER_SEC, _PER_MIN (например GOTCHA_ESCALATION_INTERVAL_SECONDS, GOTCHA_EXPORT_RETENTION_HOURS, GOTCHA_DIST_RATE_PER_MIN). Голое число без единицы в имени неоднозначно — шестьдесят чего именно, секунд или минут? Для сроков хранения (retention) в имени называется ещё и вид данных, который отсекается (GOTCHA_EVENT_RETENTION_DAYS, GOTCHA_LOG_RETENTION_DAYS, GOTCHA_DEPLOY_RETENTION_DAYS), а не общий RETENTION_DAYS на всё сразу. Префикс переменной называет подсистему, а не продукт целиком: GOTCHA_AGENT_* — только процесс агента на хосте (gotcha-agent), отдельный бинарь; GOTCHA_DIST_* — раздачу инстансом бинарей агента (не сам агент); GOTCHA_PROBE_* — выносную пробу (--mode=probe). Невалидное значение любой переменной — отказ старта процесса, а не тихий откат к дефолту: опечатка в конфигурации обязана быть замечена оператором сразу, а не спустя недели молчаливо неверного поведения.

Конвенцию единиц измерения проверяет тест internal/guards/env_example_test.go: подозрительна ЛЮБАЯ переменная, прочитанная в cmd/gotcha/config.go или internal/agent/config.go как голое число (intNum/num) без нужного суффикса в имени — гейт валит её, если она не перечислена явно в закрытом списке unitlessCounters того же теста (счётчики штук вроде лимитов, конкурентности и порта, у которых единицы измерения нет и быть не может). Добавление новой строки в этот список — заметная в код-ревью правка, а не тихий обход конвенции.

Отдельно от значения — само ИМЯ переменной тоже проверяется при старте. GOTCHA_*, которую не читает ни cmd/gotcha, ни internal/agent (реестр известных имён — internal/envcontract/known.go, объединение серверных и агентских переменных: агент штатно ставится на тот же хост, что и сервер, с общим .env), отказывает старту с подсказкой ближайшего известного имени (расстояние Левенштейна не больше двух) — опечатка вроде GOTCHA_HSTS_ENABLE (без D) больше не проходит молча с дефолтом. Исключение — префиксы GOTCHA_COMPOSE_* и GOTCHA_BUILD_*: их читает сам Docker Compose (подстановка ${...}) или Makefile (build-args образа), ни один Go-процесс их не читает, и в реестр известных имён они не входят.

Как задать переменные окружения в Docker Compose

Два равнозначных способа:

Способ 1 — файл .env рядом с docker-compose.yml (рекомендуется, самый простой). Docker Compose читает его автоматически:

# в папке gotcha/
nano .env

GOTCHA_SECRET_KEY=случайная-строка-из-openssl-rand
GOTCHA_BASE_URL=https://gotcha.example.com
GOTCHA_SMTP_HOST=smtp.yandex.ru
GOTCHA_SMTP_PORT=465
GOTCHA_SMTP_USER=noreply@example.com
GOTCHA_SMTP_PASSWORD=пароль-приложения
GOTCHA_SMTP_FROM=noreply@example.com

Применить изменения:

docker compose up -d

(команда пересоздаёт контейнер gotcha с новыми переменными; postgres/clickhouse не трогает, если их переменные не менялись).

Способ 2 — блок environment: прямо в docker-compose.yml. Если вы не хотите заводить .env, можно прописать переменные прямо в compose-файле, в секции сервиса gotcha:

services:
  gotcha:
    # ...
    environment:
      GOTCHA_PG_DSN: postgres://gotcha:gotcha@postgres:5432/gotcha?sslmode=disable
      GOTCHA_CH_DSN: clickhouse://gotcha:gotcha@clickhouse:9000/gotcha
      GOTCHA_BASE_URL: ${GOTCHA_BASE_URL:-http://localhost:59080}
      GOTCHA_SECRET_KEY: ${GOTCHA_SECRET_KEY:-insecure-dev-secret}
      GOTCHA_SMTP_HOST: smtp.yandex.ru

${VAR:-default} — это подстановка Docker Compose: «взять значение VAR из окружения/.env, а если не задано — использовать значение после :-». В штатном docker-compose.yml репозитория уже используется этот приём для GOTCHA_BASE_URL и GOTCHA_SECRET_KEY, так что для этих двух переменных обычно достаточно способа 1 (просто создать .env), ничего не редактируя в самом compose-файле.

После любого изменения переменных выполните docker compose up -d, чтобы применить их — Docker Compose сам обнаружит, что конфигурация контейнера изменилась, и пересоздаст его.

Core (основные)

Database (база данных)

Переменные только для compose (контейнеры баз)

Эти четыре — переменные подстановки Docker Compose, а не конфигурация процесса gotcha: приложение их не читает. Compose подставляет их в настройки контейнеров баз и в DSN выше.

Смена пароля базы на живой установке. POSTGRES_PASSWORD/CLICKHOUSE_PASSWORD действуют только при первичной инициализации тома — на живой установке смена одной переменной запирает приложение перед базой, которая ждёт старый пароль. Порядок важен:

1. Сменить пароль в самой базе:

   docker compose exec postgres psql -U gotcha -d gotcha -c "ALTER USER gotcha WITH PASSWORD 'новый-пароль'"
   docker compose exec clickhouse clickhouse-client --user gotcha --password 'старый-пароль' -q "ALTER USER gotcha IDENTIFIED BY 'новый-пароль'"
   

2. Задать GOTCHA_COMPOSE_PG_PASSWORD/GOTCHA_COMPOSE_CH_PASSWORD в .env.
3. docker compose up -d — контейнер приложения пересоздаётся с новым DSN.

Переменные только для Compose (контейнер приложения)

Переменные только для сборки (build-args Makefile)

Эти три — тоже переменные подстановки, но не Docker Compose, а Makefile: он передаёт их дальше в docker compose build как build-args образа (DOCKER_BUILD_ENV, см. Dockerfile). Ни один процесс gotcha их не читает; сборка make задаёт их сама (git describe/коммит/дата) — эти переменные нужны, только если вы собираете образ через docker compose build напрямую, в обход make.

Отталкиваться от симптома, а не от чисел. Docker даёт сети контейнеров MTU 1500, не глядя на аплинк хоста, а у VPS за туннелем (GRE, VXLAN, OpenVZ) он сплошь и рядом 1450. Само по себе расхождение встречается повсеместно, и большинство установок живут с ним, ничего не замечая.

Но безвредно оно только в одну сторону. Исходящие пакеты чинит своё же ядро: узкое звено — собственный интерфейс хоста, ядро сообщает об этом контейнеру, тот понижает MTU маршрута. Входящие зависят от удалённой стороны: она шлёт сегменты того размера, который контейнер объявил при установке соединения (MSS = MTU − 40, то есть 1460 вместо 1410), и уменьшит их, только если получит ICMP «fragmentation needed» от узла на пути. Дойдёт ли этот ICMP — не ваша сторона и не ваш контроль. Если его режут, отправитель продолжает слать по 1460 байт, и они пропадают.

Отсюда все признаки этой поломки:

• мелкие обмены идут, крупные пропадают: TCP устанавливается, приветствие SMTP 220 приходит, а TLS-хендшейк — первый крупный обмен — виснет по таймауту;
• разные адресаты ведут себя по-разному: до одного хоста TLS проходит, до другого нет, потому что ICMP режут не везде;
• может работать, а потом перестать: ядро держит выученный PMTU в кэше маршрута около десяти минут (net.ipv4.route.mtu_expires), и пока запись жива, всё в порядке — после протухания симптом возвращается сам;
• с хоста то же самое работает всегда: там интерфейс 1450, и MSS сразу объявляется 1410, никакого ICMP не требуется.

Последний пункт — главная ловушка при диагностике. Проверять надо изнутри контейнера, а не с хоста:

docker compose exec gotcha wget -q -O /dev/null https://api.github.com/ && echo ok || echo fail

Если отсюда TLS виснет, а с хоста openssl s_client -starttls smtp -connect <ваш-smtp>:587 проходит целиком — дело именно в MTU.

Этим же путём идёт всё исходящее — почта, вебхуки, OAuth и HTTP-проверки аптайма, — поэтому, когда это всё-таки случается, наблюдаемый сайт может числиться недоступным из-за MTU контейнера, который за ним наблюдает.

Проверка на хосте:

ip -o link show

Если у внешнего интерфейса (ens3, eth0) MTU меньше 1500, у docker0 — 1500, и при этом наблюдается описанный таймаут, задайте GOTCHA_COMPOSE_NET_MTU равным значению интерфейса и поднимите стек заново. Тогда контейнер объявляет MSS, который путь заведомо вывозит, и доставка перестаёт зависеть от чужого ICMP:

docker compose down && docker compose up -d

Именно down, а не один up -d: смена значения требует пересоздания сети, и если делать это под работающими контейнерами, встроенный DNS Docker остаётся с прежними записями — сервисы перестают находить друг друга по имени (lookup postgres on 127.0.0.11:53: server misbehaving), пока стек не поднимут целиком.

Если доставка не восстановилась — дело было не в MTU: верните значение обратно и разбирайтесь с достижимостью (Оповещения проводят по шагам).

Email / SMTP

Используется для писем-приглашений и email-канала алертов. Пока GOTCHA_SMTP_HOST пуст — отправка почты выключена целиком (в логах будет предупреждение GOTCHA_SMTP_HOST is not set, email alert channels are disabled), при этом остальная функциональность работает нормально.

Telegram

Исходящий прокси для Telegram задаётся стандартными переменными HTTPS_PROXY/HTTP_PROXY/NO_PROXY. На webhook-каналы, OAuth и проверки аптайма он не распространяется: они намеренно ходят к цели напрямую, потому что SSRF-фильтр решает по фактическому адресу соединения, а прокси унёс бы это решение за пределы инстанса. Диагностика Telegram — в разделе Оповещения.

Retention (хранение данных ClickHouse)

Сколько дней ClickHouse хранит данные каждого типа, прежде чем удалить старые записи. Меньше — меньше места на диске, больше — глубже история для расследований.

Изменение retention применяется на следующем старте приложения (значение используется, чтобы выставить TTL на таблицах ClickHouse) — задним числом уже удалённые данные не восстановятся.

Quotas & edition (квоты и редакция)

Авто-дефолт GOTCHA_MAX_WRITER_BUFFER_BYTES: если переменная не задана, потолок каждого буфера-писателя выводится из обнаруженного потолка кучи (того же 80%-от-GOTCHA_COMPOSE_MEM_LIMIT потолка, описанного выше в «Переменные только для Compose»), а не берётся flat-константой пакета (256 МиБ). Буферов-«единиц» шесть (событие, спаны-транзакций и спаны-детей у трейсинга — два независимых буфера одного писателя, метрики, профили, логи); авто-дефолт делит на них 60% потолка кучи, оставляя 40% на всё остальное (HTTP-приём, парсер JSON, клиент PostgreSQL, сам рантайм). На дефолтном docker-compose.yml (mem_limit: 1g, потолок кучи ≈ 819 МиБ) это даёт около 82 МиБ на буфер — вместо flat 256 МиБ, которые суммарно (1.5 ГиБ) превышали бы потолок кучи и на длительном простое ClickHouse могли привести к OOM ядра. Если потолок кучи вывести не из чего (bare-metal без cgroup и без GOMEMLIMIT) — поведение прежнее, flat 256 МиБ на буфер. Явно заданный GOTCHA_MAX_WRITER_BUFFER_BYTES всегда побеждает авто-дефолт — в том числе для стеснённых профилей (docker-compose.small.yml продолжает задавать 24 МиБ явно).

Когда обязательно менять квоты: значения 0 (безлимит) в oss-редакции — это сознательный выбор для приватного self-hosted инстанса, где DSN не утекает наружу. Если DSN проекта попадает в публично доступный код (например, во фронтенд-JS вашего сайта), кто угодно может слать на него события неограниченно — это и вектор злоупотребления, и риск исчерпать диск ClickHouse. В таком случае задайте реальные числа, например:

GOTCHA_DEFAULT_EVENT_QUOTA=100000
GOTCHA_DEFAULT_TRANSACTION_QUOTA=50000

(Это дефолт для новых организаций; квоту существующей организации можно изменить в её настройках в веб-интерфейсе.)

Privacy / scrubbing (приватность)

Серверная очистка персональных данных перед сохранением — включена по умолчанию.

Ограничители и оценщики

Потолки, защищающие инстанс от лавины, и период фоновых оценщиков. Ограничивают РАБОТУ, а не хранение — поэтому вынесены из «Хранения» и «Квот», где стояли раньше.

Наблюдаемость и логи

Детализация и формат логов самого инстанса.

Security (безопасность)

Флаг командной строки --migrate-only применяет схему и завершает процесс, не поднимая ни одного компонента: init-job для развёртываний с GOTCHA_AUTO_MIGRATE_ENABLED=false. См. Обновление.

Режимы процесса: что запускает каждый --mode=

Роль процесса задаётся флагом бинаря --mode= (не переменной окружения): all по умолчанию — так работает штатный docker-compose.yml; web, ingest и uptime — для раздельного развёртывания на несколько реплик; probe — выносная проба (см. ниже). Таблица показывает, какие компоненты поднимает каждый режим. Все четыре режима с базой держат HTTP-слушатель со служебными ручками (/healthz, /readyz, /version, /metrics, см. Мониторинг самого gotcha) и на старте выполняют бэкфилл секретов под текущий GOTCHA_SECRET_KEY.

Отсюда два следствия для раздельного развёртывания. Во-первых, web — не «только интерфейс»: он доставляет уведомления и подчищает базу наравне с остальными, поэтому запись notify outbox janitor в его логе — норма, а не признак перепутанного режима. Во-вторых, без реплики uptime или all оценщики не работают нигде — поднимите их явно через GOTCHA_EVALUATORS_ENABLED=true ровно на одной реплике (см. «Ограничители и оценщики»).

Uptime & probe (аптайм и выносные пробы)

Режим --mode=probe — это отдельный процесс, разворачиваемый в другом регионе/дата-центре: он не открывает ни PostgreSQL, ни ClickHouse, только ходит наружу к центральному инстансу по HTTP.

Agent distribution (раздача бинарей агента)

Выгрузки (export)

Подробности фичи и ограничений — в Выгрузках.

OAuth / SSO

Каждый провайдер входа включается независимо. Если включить провайдер, не задав его обязательные секреты — приложение откажется стартовать.

Пошаговая настройка каждого провайдера — в SSO.

Что дальше

• Установка — с чего начать на чистом сервере.
• Резервное копирование и восстановление.
• Обновление.
• SSO.