Environment matrix и границы доступа

Паспорт документа

• Статус документа: working reference
• Актуально на: 2 апреля 2026 года
• Владелец: backend/platform-команда
• Пересмотр: при изменении env-модели, secret boundaries, сервисов или ownership-модели
• Область применения: production и local environment-схема для qadam-core, qadam-web и qadam-roadmap
• Связанные документы:
  • Runbook эксплуатации и деплоя
  • Ownership model
  • Текущее состояние

Цель документа

Этот документ фиксирует, где живут env-переменные, какие сервисы их используют и кто имеет право их менять. Это не список секретных значений. Источником истины здесь являются классы переменных, их владельцы и границы доступа.

1. Источники env по сервисам

2. Канонические production env-группы

Backend API (/etc/qadam/qadam.env)

API container runtime (/etc/qadam/qadam-api-runtime.env)

Product web (/etc/qadam/qadam.env)

Product web shadow/container runtime (/etc/qadam/qadam-web-runtime.env)

Дополнительные shell/runtime переменные этого контура задаются через deploy/env/web-runtime.env.example или через одноразовый shell-export:

Roadmap service (/etc/qadam/qadam-roadmap.env)

Gitea Actions runner (/opt/act_runner/qadam-core/.runner)

External runtime monitor (/etc/qadam/qadam-monitor.env)

Automated backup (/etc/qadam/qadam-backup.env)

3. Что не должно попадать в репозиторий

• production secrets;
• содержимое /etc/qadam/*.env;
• содержимое /opt/act_runner/qadam-core/.runner;
• пароли БД, JWT secrets, bot tokens, внешние integration keys;
• S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY и любые другие object storage credentials;
• ручные .env с боевыми значениями;
• Dockerfile, image layers, committed compose manifests и build args с боевыми секретами;
• данные из /var/lib/qadam-core и /var/lib/qadam-roadmap.

4. Границы изменения env

Backend/platform-команда меняет

• production env-файлы в /etc/qadam;
• systemd units;
• nginx конфигурацию;
• DATABASE_URL, REDIS_URL, JWT_SECRET, UPLOADS_DIR, OBJECT_STORAGE_DRIVER, S3_*, QADAM_PROJECT_ROOT;
• PUBLIC_WEB_BASE_URL, если backend начинает отдавать canonical/SEO URLs;
• TLS, домены и bind policy.
• qadam-monitor.service, qadam-monitor.timer и /etc/qadam/qadam-monitor.env.
• qadam-backup.service, qadam-backup.timer и /etc/qadam/qadam-backup.env.

Frontend-команда меняет

• локальные dev .env в qadam-web;
• frontend-only env для локальной разработки и preview-контуров;
• не меняет production secrets напрямую.

Совместное согласование требуется

• при изменении API_URL / NEXT_PUBLIC_API_URL;
• при изменении PUBLIC_WEB_BASE_URL или любой backend-generated canonical/SEO URL;
• при изменении auth-контуров или cookie-модели;
• при появлении нового обязательного env для web-flow;
• при изменении OpenAPI source/workflow;
• при смене режима OBJECT_STORAGE_DRIVER, bucket/public URL или политики доступа product media.

5. Принцип для docker и object storage secrets

• Production credentials не вшиваются в Dockerfile, image layers или в git-managed manifests.
• Для текущего mixed runtime secrets поставляются через /etc/qadam/*.env.
• Для действующего docker/image-based runtime API и для будущего image-based runtime остальных сервисов те же secrets должны поставляться через runtime env/secrets механизмы, а не через docker build.
• Dockerfile может содержать только несекретные build-time параметры.

6. Local development matrix

qadam-core

• файл: qadam-core/.env
• владелец локальной конфигурации: backend/platform-команда
• типовая связка:
  • PORT=5001
  • локальная PostgreSQL
  • локальный Redis
  • CORS_ORIGIN=http://localhost:3000

qadam-web

• файл: qadam-web/.env
• владелец локальной конфигурации: frontend-команда
• типовая связка:
  • NEXT_PUBLIC_API_URL=http://localhost:5001/api/v1
  • API_URL=http://localhost:5001/api/v1
  • OPENAPI_SCHEMA_URL=""
  • QADAM_PROJECT_ROOT="" или checkout qadam-core

7. Изменение env как change package

Любое изменение env-модели считается change package и должно включать:

1. обновление этого документа;
2. обновление deployment-runbook.md, если меняется production runtime;
3. обновление current-state.md, если поменялось фактическое состояние сервера;
4. обновление project/project-change-log.md;
5. если изменение затрагивает frontend — обновление frontend-change-log.md.

8. Минимальный контроль доступа

• Production env правится только с root-доступом на сервере.
• Репозитории qadam-core и qadam-web не считаются местом хранения production secrets.
• Любое новое обязательное secret-поле должно сопровождаться обновлением этого документа и runbook.