diff --git a/docs/.vitepress/theme/components/diagramSources.ts b/docs/.vitepress/theme/components/diagramSources.ts index aba5bb3..dc9cfa7 100644 --- a/docs/.vitepress/theme/components/diagramSources.ts +++ b/docs/.vitepress/theme/components/diagramSources.ts @@ -66,6 +66,57 @@ export const diagramSources: Record = { Resolvers --> Prisma Prisma --> PrismaSchema Prisma --> Db`, + 'infrastructure-topology': `flowchart TB + subgraph Repo[Репозиторий fregat] + FrontendRepo[web-frontend] + BackendRepo[apollo-backend] + TgRepo[tg-bot] + MaxRepo[max-bot] + BonusRepo[bonus-bot] + WorkerRepo[hatchet-worker] + VaultRepo[vault] + end + + subgraph Dokploy[Dokploy] + FrontendSvc[web-frontend service] + BackendSvc[apollo-backend service] + TgSvc[tg-bot service] + MaxSvc[max-bot service] + BonusSvc[bonus-bot service] + WorkerSvc[hatchet-worker service] + VaultSvc[vault service] + end + + subgraph Infra[Инфраструктурный контур] + VaultData[Vault raft storage /vault/data] + BackendDb[(PostgreSQL for app)] + HatchetEngine[Hatchet engine] + HatchetPg[(PostgreSQL for Hatchet)] + OneC[1С] + Tailscale[Tailscale SSH / diagnostics] + end + + FrontendRepo --> FrontendSvc + BackendRepo --> BackendSvc + TgRepo --> TgSvc + MaxRepo --> MaxSvc + BonusRepo --> BonusSvc + WorkerRepo --> WorkerSvc + VaultRepo --> VaultSvc + + FrontendSvc --> BackendSvc + BackendSvc --> BackendDb + BackendSvc --> VaultSvc + TgSvc --> VaultSvc + MaxSvc --> VaultSvc + BonusSvc --> VaultSvc + WorkerSvc --> VaultSvc + VaultSvc --> VaultData + WorkerSvc --> HatchetEngine + HatchetEngine --> HatchetPg + BackendSvc -.exchange.-> OneC + FrontendSvc -.ops / debug.-> Tailscale + BackendSvc -.ops / debug.-> Tailscale`, 'database-model': `classDiagram direction LR diff --git a/docs/tz/technical-architecture.md b/docs/tz/technical-architecture.md index 8cf7fca..3eadb60 100644 --- a/docs/tz/technical-architecture.md +++ b/docs/tz/technical-architecture.md @@ -125,3 +125,150 @@ Сервисы программного продукта должны получать прикладные секреты из `Vault`. В конфигурации сервисов допускается хранение только bootstrap-параметров для подключения к Vault. Бизнес-секреты, ключи интеграций и иные чувствительные данные должны загружаться из Vault при старте приложения. + +## 6.12 Инфраструктура, деплой и эксплуатационный контур + +Текущая инфраструктурная схема проекта включает прикладные сервисы, сервис секретов, мессенджерные сервисы и вспомогательный worker-контур. + + + +Сервисы проекта и способ их развёртывания: + +| Сервис | Путь в репозитории | Роль | Deploy mode | Сервер | +| --- | --- | --- | --- | --- | +| web-frontend | `web-frontend` | клиентский и менеджерский веб-интерфейс | `dokploy_webhook` | `main` | +| apollo-backend | `apollo-backend` | GraphQL API и бизнес-логика | `dokploy_webhook` | `main` | +| hatchet-worker | `hatchet-worker` | фоновый worker-контур | `dokploy_webhook` | `main` | +| tg-bot | `tg-bot` | Telegram-контур | `dokploy_webhook` | `main` | +| max-bot | `max-bot` | MAX-контур | `dokploy_webhook` | `main` | +| bonus-bot | `bonus-bot` | бонусный сервис | `dokploy_webhook` | `main` | +| vault | `vault` | сервис секретов | `dokploy_webhook` | `main` | + +Серверная карта текущего проекта: + +- сервер `main` +- Tailscale user: `root` +- Tailscale host: `dsrptlab` + +Эксплуатационные операции доступа и диагностики выполняются через Tailscale SSH. + +## 6.13 Dokploy и цепочка развёртывания + +Для основных сервисов проекта используется режим `dokploy_webhook`. + +Это означает следующую последовательность: + +1. изменения фиксируются в Git-репозитории; +2. изменения публикуются в `main`; +3. Dokploy получает webhook-событие; +4. Dokploy выполняет сборку соответствующего сервиса; +5. сервис перезапускается с загрузкой секретов из Vault; +6. после старта выполняются bootstrap-действия, предусмотренные образом и entrypoint-командой. + +Текущие особенности прикладных сервисов: + +- `web-frontend` стартует через загрузку Vault env и запуск `.output/server/index.mjs` +- `apollo-backend` стартует через загрузку Vault env, `prisma migrate deploy` и запуск `src/server.js` +- bot-сервисы стартуют через общий паттерн загрузки Vault env и запуск `node src/server.js` + +## 6.14 Vault и хранение секретов + +Сервис `vault` развернут как отдельное приложение на базе образа `hashicorp/vault:1.21.3`. + +Текущие инфраструктурные правила работы Vault: + +- используется `raft` storage +- данные Vault сохраняются в `/vault/data` +- конфигурация сервиса хранится в `vault/config/vault.hcl` +- при старте выполняется проверка и, при необходимости, автоматический unseal из переменных окружения +- прикладные сервисы подключаются к Vault через bootstrap-переменные `VAULT_ADDR`, `VAULT_TOKEN`, `VAULT_KV_MOUNT`, `VAULT_SHARED_PATH`, `VAULT_PROJECT_PATH`, `VAULT_ENABLED` + +Прикладные сервисы используют общий shell-bootstrap `load-vault-env.sh`, который: + +- ожидает доступность Vault по health endpoint +- загружает shared secrets +- загружает project secrets +- экспортирует секреты в runtime environment процесса + +## 6.15 Структура сервисных каталогов + +Текущая сервисная структура репозитория: + +- `web-frontend` — Nuxt-приложение, GraphQL operations, VitePress-документация +- `apollo-backend` — Apollo Server, Prisma schema, миграции, импорт каталога +- `tg-bot` — Telegram-сервис +- `max-bot` — MAX-сервис +- `bonus-bot` — бонусный сервис +- `hatchet-worker` — worker-контур +- `vault` — Dockerfile, конфигурация и entrypoint Vault +- `hatchet` — docker-compose инфраструктурного контура Hatchet + +## 6.16 Контур фоновых процессов + +В проекте присутствует отдельный контур фонового исполнения задач: + +- `hatchet-worker` как прикладной worker +- `hatchet-engine` как движок исполнения +- `hatchet-dashboard` как интерфейс мониторинга +- отдельный `postgres` для Hatchet-контура + +Конфигурация этого контура находится в `hatchet/docker-compose.yml`. + +## 6.17 Зафиксированные runtime-версии и технологические зависимости + +### Базовые runtime и контейнерные образы + +| Компонент | Текущая версия | +| --- | --- | +| Node base image для web/backend/bots | `node:22-bookworm-slim` | +| Vault image | `hashicorp/vault:1.21.3` | +| Hatchet Postgres | `postgres:15.6` | +| Nuxt | `4.4.2` | +| Vue | `3.5.30` | +| Apollo Server | `5.5.0` | +| Prisma / Prisma Client | `7.6.0` | +| Mermaid | `11.14.0` | +| VitePress | `1.6.4` | + +### Основные зависимости фронтенда + +| Библиотека | Версия | Назначение | +| --- | --- | --- | +| `@nuxtjs/apollo` | `5.0.0-alpha.16` | GraphQL-клиентский слой | +| `@vue/apollo-composable` | `4.2.2` | composable API для GraphQL | +| `@apollo/client` | `3.14.1` | Apollo client runtime | +| `@nuxt/eslint` | `1.15.2` | linting Nuxt-проекта | +| `@nuxtjs/tailwindcss` | `6.14.0` | Tailwind integration | +| `daisyui` | `5.5.19` | UI primitives | +| `graphql` | `16.13.2` | GraphQL runtime | +| `@sentry/vue` | `10.46.0` | error tracking | +| `storybook` | `8.6.14` | UI component review | + +### Основные зависимости backend + +| Библиотека | Версия | Назначение | +| --- | --- | --- | +| `@apollo/server` | `5.5.0` | GraphQL server | +| `@as-integrations/express5` | `1.1.2` | Apollo + Express integration | +| `express` | `5.2.1` | HTTP server | +| `@prisma/client` | `7.6.0` | data access | +| `@prisma/adapter-pg` | `7.6.0` | Prisma adapter | +| `pg` | `8.20.0` | PostgreSQL driver | +| `graphql` | `16.13.2` | GraphQL runtime | +| `zod` | `4.3.6` | validation | +| `nodemailer` | `8.0.4` | email notifications | +| `dotenv` | `17.3.1` | env bootstrap in local/runtime layers | + +## 6.18 Технические конфигурационные файлы + +Ключевые технические файлы текущей реализации: + +- `deploy-map.toml` — карта сервисов, deploy mode и серверов +- `web-frontend/nuxt.config.ts` — конфигурация Nuxt и Apollo +- `web-frontend/codegen.ts` — конфигурация GraphQL codegen +- `apollo-backend/prisma.config.ts` — конфигурация Prisma +- `apollo-backend/prisma/schema.prisma` — модель данных +- `web-frontend/scripts/load-vault-env.sh` — Vault bootstrap frontend +- `apollo-backend/scripts/load-vault-env.sh` — Vault bootstrap backend +- `vault/config/vault.hcl` — конфигурация Vault +- `vault/entrypoint.sh` — startup/unseal логика Vault