type: concept
title: "Архитектура компонентов платформы"
version: 1.0.0
date: 2026-04-02
status: approved

Архитектура компонентов платформы

1. ПРИНЦИП

Платформа строится из контейнеров. Хост-сервер предоставляет только:

OS · SSH · UFW · fail2ban · Docker Engine · WireGuard модуль · cron

Всё остальное — в контейнерах. Платформа работает на 1 сервере (старт) или N серверов (масштаб).

2. БЛОКИ ПЛАТФОРМЫ

┌─────────────────────────────────────────────────────────┐
│  МАТЬ  (BASE + CORE)          — управление, ядро        │
│        один сервер, центральный                         │
├─────────────────────────────────────────────────────────┤
│  ОТЕЦ  (CREATOR)              — архитектор-создатель    │
│        на Матери или отдельно                           │
├─────────────────────────────────────────────────────────┤
│  СЫН   (PROJECTOR)            — управление проектами    │
│        на Матери или на Дочке                           │
├─────────────────────────────────────────────────────────┤
│  ДОЧКА                        — дополнительный сервер   │
│        = Мать без CORE                                  │
│        может нести: СЫН, ИСПОЛНИТЕЛЬ или оба           │
└─────────────────────────────────────────────────────────┘

Дочка — это дополнительный сервер с BASE (portainer-agent + wireguard).
На неё ставится то что нужно:
- только СЫН (proj-claude) — если нужен отдельный Проектор
- только ИСПОЛНИТЕЛЬ (postgres + redis + nginx) — если нужен рантайм
- СЫН + ИСПОЛНИТЕЛЬ — чаще всего

Контекст передаётся только сверху вниз: Мать → Отец → Сын → Дочка.

3. КОМПОНЕНТЫ

МАТЬ

BASE — на каждом сервере, ставится первым:

Контейнер	Образ	Роль
base-portainer-agent	portainer/agent	→ Portainer Server по VPN
(WireGuard)	хост	VPN клиент или сервер

CORE — только на Матери, критичный:

Контейнер	Образ	Роль
core-postgres	postgres:16-alpine	БД для Gitea + Authelia
core-gitea	gitea/gitea	git, источник истины, OAuth
core-authelia	authelia/authelia	SSO forward-auth
core-nginx	nginx:alpine	вход :80/:443, SSL

OPS — управление платформой:

Контейнер	Образ	Роль
ops-portainer	portainer/portainer-ce	центральный UI контейнеров
ops-kuma	louislam/uptime-kuma	мониторинг
ops-vaultwarden	vaultwarden/server	секреты команды

MONITOR — алерты:

Контейнер	Образ	Роль
mon-telegram	python:alpine	бот → Telegram

BACKUP — резервирование:

Контейнер	Образ	Роль
backup-restic	restic/rest-server	принимает бэкапы по VPN

Scheduler (cron на хосте):

04:00  pg_dump → /var/backups/
04:30  restic backup → Beget S3
05:00  restic forget (ротация)
08:00  Gitea mirror → GitHub

ОТЕЦ (CREATOR)

Контейнер	Образ	Роль
creator-claude	claude-code	интерактивный терминал

Воркспейс (rw):
  architect/   — стандарты, концепции, паттерны
  library/     — компонентная библиотека
  system/      — агенты, планировщик
  infra/       — описание инфраструктуры

Прокси: HTTPS_PROXY=socks5://{eu-proxy}:1080
Auth:   volume creator-claude-auth:/root/.claude/

СЫН (PROJECTOR)

Контейнер	Образ	Роль
proj-claude	claude-code	интерактивный терминал

Воркспейс:
  projects/    — проекты клиентов (rw)
  architect/   — стандарты (ro)
  library/     — библиотека (ro)

Прокси: HTTPS_PROXY=socks5://{eu-proxy}:1080
Auth:   volume proj-claude-auth:/root/.claude/

Каждый Проектор изолирован: видит только свои проекты.

ДОЧКА (EXECUTOR)

Контейнер	Образ	Роль
exec-postgres	postgres:16-alpine	БД проектов
exec-redis	redis:7-alpine	кэш, очереди
exec-nginx	nginx:alpine	домены + SSL
project-*	кастомный	стеки проектов клиентов

Каждый проект:
  - своя БД в exec-postgres
  - свой конфиг домена в exec-nginx
  - свой стек контейнеров project-{name}

4. СЕТЬ

                    ИНТЕРНЕТ
                        │
         ┌──────────────┼──────────────┐
         ▼              ▼              ▼
      :80/:443       :80/:443       :1080 (SOCKS5)
         │              │              │
    ┌────┴────┐    ┌────┴────┐    ┌────┴────┐
    │  МАТЬ   │    │  ДОЧКА  │    │  EU     │
    │ 10.10.0.1│   │10.10.0.x│    │  PROXY  │
    │  VPN HUB│◄──►│VPN CLT  │    │         │
    └─────────┘    └─────────┘    └─────────┘

ЧЕРЕЗ VPN (закрыто снаружи):
  Portainer Agent  → Portainer Server  :9001
  Backup Agent     → Restic Server     :8000
  Uptime Kuma      → healthcheck       :*

НАПРЯМУЮ:
  Пользователи → Дочка :80/:443
  Claude Code  → EU Proxy :1080 → Anthropic API
  SSH          → все серверы :22

Docker-сети на каждом сервере:

proxy-net    — Nginx видит все сервисы (межстековая)
core-net     — внутренняя для CORE стека
ops-net      — внутренняя для OPS стека
exec-net     — внутренняя для EXECUTOR

5. ДОСТУП И РОЛИ

Роли в сети

Роль	Видит	Инструменты
Сисадмин	всё	SSH, Portainer, Gitea admin
Архитектор	architect/ library/ infra/ + вниз	Claude Code (creator)
Проектор	свои projects/	Claude Code (proj)

Каскад только сверху вниз: Сисадмин → Архитектор → Проектор.

SSO через Authelia

Браузер → Nginx → Authelia (проверка) → сервис

Сервис	Группа доступа
portainer.{domain}	sysadmin
git.{domain}	sysadmin, architect, projector
status.{domain}	sysadmin, architect
vault.{domain}	sysadmin, architect

6. GIT-РЕПОЗИТОРИИ

Репо	Содержимое	Кто пишет
`arch-core`	architect/ library/	Архитектор
`arch-infra`	infra/ system/	Архитектор + Сисадмин
`proj-shared`	шаблоны проектов	Архитектор
`project-{name}`	код конкретного проекта	Проектор

Gitea = единственный источник истины. GitHub = зеркало (страховка).

7. СЕКРЕТЫ

.env файлы на сервере (НЕ в git)
    │
    ▼
restic backup /opt/**/.env (зашифровано)
    │
    ▼
Beget S3 (ключ шифрования офлайн у Сисадмина)

.env.example (без значений) — в git как шаблон.

8. ЭТАПЫ МАСШТАБИРОВАНИЯ

Этап 0 — один сервер

1 VPS: МАТЬ + ОТЕЦ + СЫН + ДОЧКА
Риск: SPOF. Для старта / POC.

Этап 1 — два сервера (базовый)

Сервер А: МАТЬ + ОТЕЦ + СЫН + ДОЧКА #1
Сервер Б: ДОЧКА #2

Этап 2 — разделение ролей

Сервер А: МАТЬ + ОТЕЦ + СЫН
Сервер Б: ДОЧКА #1
Сервер В: ДОЧКА #2

Этап N — горизонтальный рост

+1 VPS = +1 ДОЧКА = +N проектов

9. ВОССТАНОВЛЕНИЕ

Что упало	Последствия	Время
exec-nginx	сайты 502	restart 30 сек
exec-postgres	сайты с БД down	restart 30 сек
core-postgres	нет деплоев, сайты живут	restore 30 мин
core-gitea	нет git push/pull	restore 30 мин
Вся МАТЬ	нет управления, сайты живут	новый VPS + restore 45 мин
Вся ДОЧКА	проекты down	новый VPS + restore 45-60 мин