Инфраструктура и деплой¶

Обзор¶

Plechiki развёрнут на домашнем сервере (Intel NUC) с использованием легковесного Kubernetes-дистрибутива k3s. Все сервисы контейнеризированы, образы хранятся в приватном реестре Harbor. CI/CD реализован через GitHub Actions.

Kubernetes-кластер¶

Параметр	Значение
Дистрибутив	k3s v1.32.3
Узел	Intel NUC (`nuc`), control-plane
Container Runtime	containerd
Ingress Controller	Traefik
Cert Manager	cert-manager (Let's Encrypt)
Namespace	`plechiki`
StorageClass	local-path

Ресурсы кластера¶

Deployments¶

Deployment	Образ	Порт	Описание
`frontend`	`plechiki-frontend:latest`	80	React SPA (nginx)
`backend`	`plechiki-backend:latest`	8080	Kotlin Spring Boot API
`ml`	`plechiki-ml:latest`	8000	Python FastAPI ML-сервис
`minio`	`minio:latest`	9000/9001	S3-совместимое хранилище

StatefulSets¶

StatefulSet	Образ	Порт	Хранилище
`postgres`	`postgres:15-alpine`	5432	5Gi PVC (`data-postgres-0`)

Persistent Volumes¶

PVC	Размер	Назначение
`data-postgres-0`	5Gi	Данные PostgreSQL
`minio-pvc`	5Gi	Объектное хранилище (фото)
`ml-models-pvc`	2Gi	Веса ML-моделей

Ingress (Traefik + TLS)¶

Все домены защищены TLS-сертификатами Let's Encrypt через cert-manager (ClusterIssuer: letsencrypt-prod).

Домен	Сервис	Порт
`plechiki.ru.dmitriy.space`	frontend	80
`api.plechiki.ru.dmitriy.space`	backend	80→8080
`ml.plechiki.ru.dmitriy.space`	ml	8000
`minio.plechiki.ru.dmitriy.space`	minio	9001
`minio-api.plechiki.ru.dmitriy.space`	minio	9000

Secrets¶

Secret	Содержимое
`postgres-secret`	POSTGRES_USER, POSTGRES_PASSWORD
`minio-credentials`	root-user, root-password
`backend-secret`	Конфигурация бэкенда (DB URL, MinIO, ML URL)

Docker Compose (локальная разработка)¶

Для локальной разработки используется Docker Compose с аналогичным набором сервисов:

Сервис	Порт	Назначение
`frontend`	5173	Vite dev server
`backend`	8080	Spring Boot
`ml`	8000	FastAPI
`spec`	8081	Swagger UI (OpenAPI)

Переменные окружения задаются через .env файл. Подключение к удалённому PostgreSQL и MinIO (в кластере k3s) осуществляется через NodePort и публичные домены.

CI/CD Pipeline¶

flowchart LR
    A[git push main] --> B[GitHub Actions]

    B --> C1[Build Frontend]
    B --> C2[Build Backend]
    B --> C3[Build ML]
    B --> C4[Build Spec]

    C1 --> D1[Docker Image]
    C2 --> D2[Docker Image]
    C3 --> D3[Docker Image]
    C4 --> D4[Docker Image]

    D1 --> E[Harbor Registry]
    D2 --> E
    D3 --> E
    D4 --> E

    E --> F[Deploy Job]
    F --> G1[kubectl apply manifests]
    G1 --> G2[Set image digests]
    G2 --> G3[Rollout restart]
    G3 --> H[k3s Cluster]

Диаграмма

Этапы pipeline¶

Триггер: push в ветку main (или ручной запуск через workflow_dispatch)
Сборка (параллельно для каждого сервиса):
Docker buildx build
Push в Harbor (harbor.ru.dmitriy.space/library/<name>:latest)
Деплой (после завершения всех сборок):
Извлечение kubeconfig из GitHub Secret (base64)
kubectl apply манифестов в порядке зависимостей
Установка новых image digests для каждого deployment
kubectl rollout restart для обновления подов

Порядок применения манифестов¶

1. traefik-config.yaml          (конфигурация Ingress Controller)
2. namespace.yaml               (namespace plechiki)
3. postgres-secret + configmap  (секреты и init.sql)
4. postgres statefulset + svc   (база данных)
5. minio-secret + deployment    (хранилище)
6. backend-secret               (секреты бэкенда)
7. ml deployment + service      (ML-сервис)
8. backend deployment + service (API)
9. frontend deployment + service(SPA)
10. ingress resources            (маршрутизация)

ML Base Image¶

ML-сервис использует двухстадийную сборку Docker: - Base image (plechiki-ml-base): PyTorch + тяжёлые зависимости. Пересобирается вручную через workflow_dispatch при обновлении зависимостей. - App image (plechiki-ml): base + FastAPI + код приложения + модели. Собирается автоматически при push.

TLS и домены¶

Cert Manager: автоматическое получение и обновление TLS-сертификатов от Let's Encrypt
ClusterIssuer: letsencrypt-prod (ACME HTTP-01 challenge через Traefik)
Wildcard: не используется; каждый домен получает отдельный сертификат
Traefik: настроен с увеличенными таймаутами (3600s) для поддержки загрузки больших Docker-образов в Harbor

Схема сети¶

Интернет
    │
    ▼
Traefik (LoadBalancer 192.168.1.2:80/443)
    │
    ├── plechiki.ru.dmitriy.space      → frontend:80
    ├── api.plechiki.ru.dmitriy.space   → backend:8080
    ├── ml.plechiki.ru.dmitriy.space    → ml:8000
    ├── minio.plechiki.ru.dmitriy.space → minio:9001
    └── minio-api.plechiki.ru.dmitriy.space → minio:9000

Внутри кластера (ClusterIP):
    backend → postgres:5432 (headless)
    backend → ml:8000
    backend → minio:9000 (S3 API)

Внешний доступ к БД:
    postgres-nodeport:31433 → postgres:5432