npm · mvn · docker · nuget · pypi · go · apt · yum/dnf"] LB["Load Balancer / Ingress"] SAVE["Save API service
stateless · pods 1..N"] AUTH["cs-auth (Auth / RBAC)
stateless · pods 1..N
общий RSA-ключ"] SCHED["Scheduler
save/backend/cmd/scheduler/main.go"] WORKER["Workers
save/backend/cmd/worker/main.go
cleanup, metadata jobs"] REDIS[("Queue (Redis)
job queue / pubsub")] DB[("Metadata DB
см. примечание ниже")] OBJ[("Object Storage
S3-совместимое / локальная ФС")] UI --> LB PM --> LB LB --> SAVE LB -- "/v2/token (Docker auth flow)" --> AUTH SAVE -- "авторизация действий · JWKS · события для аудита" --> AUTH SAVE --> DB SAVE --> OBJ AUTH --> DB %% Scheduler enqueues background jobs SCHED --> REDIS %% Workers consume jobs and operate on DB/Blob storage and emit audit events REDIS --> WORKER WORKER --> DB WORKER --> OBJ WORKER -- "audit events" --> AUTH %% Save can enqueue ad-hoc background jobs SAVE -- "поместить в очередь jobs" --> REDIS ``` :::note О схеме базы данных В развёртывании с **PostgreSQL** оба сервиса могут делить один экземпляр БД и одну схему; данные разделены префиксами имён таблиц. В развёртывании с **SQLite** у каждого сервиса свой отдельный файл базы. ::: ## Компоненты системы ### Save API service Основной backend-сервис, обрабатывающий входящие запросы к репозиториям и административному API. **Функции:** * Обработка HTTP/HTTPS запросов от пакетных менеджеров и веб-интерфейса. * Валидация токенов и интеграция с выделенным Auth/RBAC service. * Маршрутизация запросов к storage backend. * Интеграция с CodeScoring.OSA через OSA Proxy для сканирования артефактов при маршрутизации загрузок через прокси. * Применение политик безопасности и политик очистки. * Структурированное логирование и экспорт метрик в Prometheus. **Технические характеристики:** * Stateless-архитектура для горизонтального масштабирования. * Graceful shutdown при обновлении. * Health checks для Kubernetes. ### Auth/RBAC service Выделенный сервис аутентификации и авторизации, разворачиваемый отдельно от Save API service. **Функции:** * Аутентификация пользователей и сервисных аккаунтов. * Выпуск и обновление JWT-токенов (RSA-2048, alg=RS256). * Управление ролями и разрешениями (RBAC) на уровнях global / project / repository. * Управление API keys, robot accounts и project membership. * Аудит операций, связанных с доступом и общесистемными событиями. * Internal API для взаимодействия с Save API service. * OCI Distribution Spec token endpoint для Docker / Helm / oras-клиентов. **Технические характеристики:** * Отдельная кодовая база и отдельная точка входа. * Собственная схема в PostgreSQL при общем экземпляре БД, либо отдельный SQLite-файл. * Горизонтальное масштабирование независимо от Save API service. * **Обязательное условие масштабирования:** все реплики должны делить один и тот же RSA-ключ для подписи JWT. ### Storage Backend Подсистема хранения артефактов: * **Metadata Store** — PostgreSQL или SQLite для хранения метаданных. * **Blob Store** — объектное хранилище для артефактов: S3-совместимое или filesystem. Операции: сохранение и извлечение артефактов, управление версиями, генерация контрольных сумм. ### Background Workers Фоновые процессы для выполнения отложенных задач. Компоненты разделены на три основных роли: планировщик (scheduler), очередь заданий (Redis) и воркеры (workers). #### Scheduler * Отвечает за планирование периодических и отложенных задач (cron-подобные задания): очистка, массовые операции с метаданными, уведомления и т.д. * Реализован в `save/backend/cmd/scheduler/main.go`. * Помещает задания в очередь (Redis) в виде задач с описанием типа и полезной нагрузки; задания должны быть идемпотентными и иметь метаданные для повторов/аттрибуции. #### Queue (Redis) * Централизованная очередь задач (Redis-backed pub/sub или list-based queue). Обеспечивает надёжную доставку, видимость задач, механизмы повторов и возможность DLQ (dead-letter). * Рекомендуется конфигурация с включённой персистентностью и, при высокой нагрузке, кластеризацией Redis. * Save API service также может помещать ad-hoc задачи в очередь (например, по событию upload). #### Workers * Воркеры забирают задания из Redis и выполняют операции над Metadata DB и Object Storage (удаление артефактов, перерасчёт метаданных, репликация, и т.д.). * Реализованы в `save/backend/cmd/worker/main.go`. * Воркеры публикуют события аудита в `cs-auth` (через internal API) при необходимости. * Масштабируются горизонтально: несколько воркеров могут параллельно обрабатывать очередь; реализации должны учитывать контроль конкурентного доступа, тайм-ауты и ретраи. ### Web UI Веб-интерфейс для управления проектами, репозиториями, артефактами и настройками доступа. Общее описание возможностей модуля приведено на странице [Функциональные характеристики](/functionality.md#codescoring-save). ### Взаимодействие сервисов * Внешние клиенты (Web UI и пакетные менеджеры) обращаются только к Save API service через ingress; cs-auth напрямую снаружи кластера не доступен * Save API service делегирует аутентификацию, проверку ролей и выпуск токенов в Auth/RBAC service * Оба сервиса могут использовать отдельные или общий экземпляр PostgreSQL, но работают они в отдельных схемах/базах данных * Save API service напрямую работает с metadata store и object storage; cs-auth работает только с metadata store и не имеет доступа к object storage * Save обращается к cs-auth в нескольких случаях: * **Проксирование части административного API** — Save форвардит запросы, не обрабатывая их сам * **Проверка учётных данных**, отсутствующих в локальном кэше пода — (Basic Auth, API key, NuGet API key, NPM token, Docker token) * **Оповещение о событиях для аудита** - единый журнал событий для всех сервисов * Все internal-эндпоинты дополнительно защищены shared secret. * На горячем пути Save валидирует Bearer JWT **локально**, используя кэшированный публичный RSA-ключ JWKS без сетевого вызова в cs-auth. ## Модель данных ### Основные сущности #### Project (Проект) ```text - ID - Name - Description - Owner - Created/Updated timestamps ``` #### Repository (Репозиторий) ```text - ID - Project ID - Name - Type (proxy/hosted) - Format (maven, npm, docker, nuget, pypi, go, deb, rpm, raw) - Configuration - Storage Backend - Cleanup Policies - Created/Updated timestamps ``` #### Artifact (Артефакт) ```text - ID - Repository ID - Group/Namespace - Name - Version - Format-specific metadata - Size - Checksums (MD5, SHA1, SHA256) - Upload date - Last accessed ``` #### User (Пользователь) ```text - ID - Username - DisplayName - Email - PasswordHash (bcrypt) - IsActive - AuthSource (local / ldap / oidc) - LastLoginAt - Created/Updated timestamps ``` #### Role / Robot account (Роль или сервисный аккаунт) ```text - ID - Name - Description - Permissions (global / project / repository scopes) - IsAdmin - IsSystem - API keys (only for robot accounts) - Created/Updated timestamps ``` #### APIKey (API-ключ) ```text - ID - UserID (FK на user с IsService=true) - KeyPrefix (первые 12 hex-символов plaintext-ключа — индекс для O(1)-поиска) - KeyHash (bcrypt(plaintext)) - Description - ExpiresAt (NULL = бессрочный) - LastUsedAt - CreatedAt ``` Полный plaintext-ключ возвращается клиенту единожды при создании. #### Cleanup Policy (Политика очистки) ```text - ID - Name - Type (cleanup/security) - Rules - Repositories - Enabled - Created/Updated timestamps ``` ## Варианты установки CodeScoring.Save поддерживает несколько профилей установки. Требования, различия между профилями и порядок развертывания описаны в разделе [Варианты установки](/admin-guide/save/installation-options.md). ## Безопасность ### Аутентификация и авторизация * JWT tokens для API, выпускаемые Auth/RBAC service * Basic Auth / API keys для пакетных менеджеров и service accounts * Ролевая модель (RBAC) с тремя scope'ами (global / project / repository), управляемая выделенным Auth/RBAC service * Межсервисная валидация токенов через JWKS-эндпоинт Способы аутентификации со стороны клиента подробно описаны в разделе [Аутентификация](/user-guide/save/repositories.md#authentication). ### Шифрование данных Сами сервисы Save и cs-auth не выполняют шифрование на уровне приложения; используются возможности нижележащих компонентов: * **Encryption at rest** обеспечивается выбранным object storage (S3 server-side encryption, MinIO encryption-at-rest) и PostgreSQL (через TDE-расширения или volume-level шифрование). * **Encryption in transit** обеспечивается TLS на ingress / load balancer и в межсервисных соединениях. * **Пароли пользователей и API-ключи robot-аккаунтов** хранятся как bcrypt-хэши в cs-auth. ### Аудит * Полное логирование всех операций — единый журнал, в который пишут оба сервиса. * Экспорт в машинно-читаемый формат (JSON) и HTML. Максимум 10 000 записей за один экспорт. * Поддерживаемые фильтры списка/экспорта: `from`, `to`, `username`, `action`, `resource_type`, `q`, `user_id`. В web-UI доступен только поиск по имени пользователя, типу ресурса и действию. ## Производительность {#performance} ### Оптимизации * **Кэширование:** * In-process TTL-кэш `credential → PermissionSet` в каждом поде Save API service — устраняет round-trip в cs-auth при повторных запросах с теми же учётными данными * Локальная валидация Bearer JWT по публичному ключу JWKS — без сетевого вызова в cs-auth на горячем пути. JWKS обновляется в фоне периодически. * **Connection pooling:** * Пул соединений к БД * Переиспользование HTTP клиентов к upstream-репозиториям * **Параллельная обработка:** * Concurrent uploads / downloads через горутины. * Batch (bulk) operations API * **Streaming больших файлов:** * Артефакты передаются через `MultiWriter` без буферизации целиком в памяти. * Атомарная запись на диск через temp-file rename, чтобы избежать повреждения при конкурентной записи. ### Целевые показатели Для базовой инсталляции: * Latency (p95): < 100ms для cached requests * Throughput: 300+ requests/sec * Concurrent uploads: 100+ * Max artifact size: 5 GB ## Масштабирование ### Горизонтальное масштабирование * Save API service — stateless, масштабируется добавлением реплик. * Auth/RBAC service — stateless, масштабируется добавлением реплик. Обязательное условие: все реплики должны использовать один и тот же RSA-ключ для подписи JWT. * PostgreSQL — масштабируется вертикально, при необходимости используются read-реплики. * Объектное хранилище — масштабируется средствами провайдера: S3 или MinIO в кластере. ### Вертикальное масштабирование * Увеличение ресурсов подов. * Увеличение ресурсов PostgreSQL. * Расширение объектного хранилища. ## Мониторинг и наблюдаемость ### Метрики (Prometheus) Save экспортирует метрики в формате OpenTelemetry с Prometheus exporter'ом. **HTTP-метрики:** * `http_requests_total{method,path,status}` — счётчик HTTP-запросов. * `http_request_duration_seconds{method,path,status}` — гистограмма latency. * `http_requests_active` — gauge активных запросов. **Метрики операций:** * `storage_operations_total{operation,backend,success}` — операции с хранилищем. * `artifact_uploads_total{artifact_type,repository}` — загрузки артефактов. * `artifact_downloads_total{artifact_type,repository}` — скачивания артефактов. * `proxy_requests_total{artifact_type,repository,cache_hit,success}` — proxy-запросы. Cache hit rate вычисляется как `rate(proxy_requests_total{cache_hit="true"}[5m]) / rate(proxy_requests_total[5m])`. * `cleanup_operations_total{policy_type,repository,artifacts_deleted,success}` — операции очистки. ### Логирование * Структурированные логи в формате JSON (или text, по конфигурации). * Уровни: `debug`, `info`, `warn`, `error`. * Вывод: stdout, stderr или файл. * Совместимы с любым log-aggregator'ом (ELK, Loki, Vector), которые умеют JSON. ## Доступность и устойчивость CodeScoring.Save не реализует автоматическое переключение при отказе, восстановление на конкретный момент времени и встроенное резервное копирование самостоятельно. Эти возможности обеспечиваются стандартными средствами инфраструктуры, в которой развёрнут сервис: * **Несколько реплик Save и cs-auth** в Kubernetes за балансировщиком нагрузки обеспечивают доступность при отказе одного из подов. * **Репликация PostgreSQL** и **резервное копирование базы данных** настраиваются средствами PostgreSQL-оператора или managed-сервиса. * **Снапшоты и репликация объектного хранилища** выполняются средствами S3-совместимого хранилища. * **Многоузловой Kubernetes-кластер** обеспечивает устойчивость к отказу отдельного узла. Save не теряет данные при перезапуске, потому что всё состояние хранится во внешних компонентах: метаданные — в базе данных, артефакты — в объектном хранилище. Stateless-архитектура Save позволяет масштабировать сервис и пересоздавать поды без потери данных. --- url: /admin-guide/save/installation-requirements.md --- # Требования к установке CodeScoring.Save CodeScoring.Save поддерживает два варианта установки: SQLite-вариант в k3s и PostgreSQL-вариант в Kubernetes. Оба варианта устанавливаются через Helm-чарт `save`. ## Общие требования * Linux-based OS (Ubuntu 20.04+, CentOS 8+, RHEL 8+) * Kubernetes-совместимый кластер: k3s для SQLite-варианта, полноценный Kubernetes-кластер для PostgreSQL-варианта * Helm 3.x * Доступ к реестру контейнерных образов CodeScoring.Save ## Hosted-инсталляция **Минимальные требования:** * 2 ядра CPU * 4 GB RAM * 50 GB дискового пространства (рекомендуется SSD) **Рекомендуемые требования:** * 4 ядра CPU * 8 GB RAM * 100 GB дискового пространства (SSD) **Программное обеспечение:** * k3s v1.25+ * SQLite 3.x (включен в дистрибутив) ## PostgreSQL-инсталляция **Kubernetes-кластер:** * 3+ рабочих узла * 4 ядра CPU на узел * 8 GB RAM на узел * 50 GB дискового пространства на узел **PostgreSQL:** * 4 ядра CPU * 8 GB RAM * 100 GB storage (SSD рекомендуется) * PostgreSQL 14+ **Объектное хранилище:** * встроенный MinIO из зависимости Helm-чарта `minio` либо внешнее S3-совместимое хранилище: MinIO, AWS S3, Yandex Object Storage * 500 GB+ хранилища, зависит от объема артефактов --- url: /admin-guide/save/installation-options.md --- # Варианты установки CodeScoring.Save CodeScoring.Save поддерживает два варианта установки: SQLite-вариант в k3s и PostgreSQL-вариант в Kubernetes. Оба варианта устанавливаются через Helm-чарт `save`, но отличаются инфраструктурой и сценарием эксплуатации. Адрес Helm-репозитория и реестра контейнерных образов CodeScoring.Save предоставляет вендор. В примерах установки используются плейсхолдеры `
| Название события | Описание события | Значение trigger в запросе | Схема payload в запросе |
|---|---|---|---|
| SCA Policy has been triggered | Сработала политика при SCA-анализе | sca_policy_has_been_triggered |
``` "alert_id": 0, "stage": "dev|source|build|stage|test|prod|proxy", "level": "info|warning|critical", "policy_id": 0, "policy_name": 0, "dependency_id": 0, "dependency_purl": "purl", "matched_criteria": ["matched_criteria", ...], "project_id": 0 ``` |
| OSA Policy has been triggered | Сработала политика при OSA-анализе | osa_policy_has_been_triggered |
``` "alert_id": 0, "stage": "dev|source|build|stage|test|prod|proxy", "level": "info|warning|critical", "policy_id": 0, "policy_name": 0, "dependency_id": 0, "dependency_purl": "purl", "matched_criteria": ["matched_criteria", ...], "container_image_id": 0, "artifact_repository_id": 0 ``` |
| Project SCA analysis started | SCA-анализ проекта был запущен | project_sca_analysis_started |
``` "project_id": 0, "project_name": "project_name" ``` |
| Project SCA analysis finished | SCA-анализ проекта был завершён | project_sca_analysis_finished |
``` "project_id": 0, "project_name": "project_name", "vulnerabilities_count": 0, "dependencies_count": 0 ``` |
| Project SCA analysis cancelled | SCA-анализ проекта был отменён | project_sca_analysis_cancelled |
``` "project_id": 0, "project_name": "project_name" ``` |
| Project SCA analysis failed | SCA-анализ проекта был завершён с ошибкой | project_sca_analysis_failed |
``` "project_id": 0, "project_name": "project_name", "error": "error_description" ``` |
| Container Image SCA analysis started | SCA-анализ контейнерного образа был запущен | container_image_sca_analysis_started |
``` "container_image_id": 0, "container_image_name": "container_image_name" ``` |
| Container Image SCA analysis finished | SCA-анализ контейнерного образа был завершён | container_image_sca_analysis_finished |
``` "container_image_id": 0, "container_image_name": "container_image_name", "vulnerabilities_count": 0, "dependencies_count": 0 ``` |
| Container Image SCA analysis cancelled | SCA-анализ контейнерного образа был отменён | container_image_sca_analysis_cancelled |
``` "container_image_id": 0, "container_image_name": "container_image_name" ``` |
| Container Image SCA analysis failed | SCA-анализ контейнерного образа был завершён с ошибкой | container_image_sca_analysis_failed |
``` "container_image_id": 0, "container_image_name": "container_image_name", "error": "error_description" ``` |
| Clone analysis started | Анализ дубликатов проекта был запущен | clones_analysis_started |
``` "project_id": 0, "project_name": "project_name" ``` |
| Clone analysis finished | Анализ дубликатов проекта был завершён | clones_analysis_finished |
``` "project_id": 0, "project_name": "project_name" ``` |
| Clone analysis cancelled | Анализ дубликатов проекта был отменён | clones_analysis_cancelled |
``` "project_id": 0, "project_name": "project_name" ``` |
| Clone analysis failed | Анализ дубликатов проекта был завершён с ошибкой | clones_analysis_failed |
``` "project_id": 0, "project_name": "project_name", "error": "error_description" ``` |
| Authors analysis started | Анализ авторов проекта был запущен | authors_analysis_started |
``` "project_id": 0, "project_name": "project_name" ``` |
| Authors analysis finished | Анализ авторов проекта был завершён | authors_analysis_finished |
``` "project_id": 0, "project_name": "project_name" ``` |
| Authors analysis failed | Анализ авторов проекта был завершён с ошибкой | authors_analysis_failed |
``` "project_id": 0, "project_name": "project_name", "error": "error_description" ``` |
| Authors analysis cancelled | Анализ авторов проекта был отменён | authors_analysis_cancelled |
``` "project_id": 0, "project_name": "project_name" ``` |
| Cloning of repository started | Клонирование репозитория было запущено | cloning_of_repository_started |
``` "project_id": 0, "project_name": "project_name", "repo_url": "repo_url", "repo_ref_name": "repo_ref_name" ``` |
| Cloning of repository finished | Клонирование репозитория было завершено | cloning_of_repository_finished |
``` "project_id": 0, "project_name": "project_name", "repo_url": "repo_url", "repo_ref_name": "repo_ref_name" ``` |
| Cloning of repository failed | Клонирование репозитория было завершено с ошибкой | cloning_of_repository_failed |
``` "project_id": 0, "project_name": "project_name", "repo_url": "repo_url", "repo_ref_name": "repo_ref_name", "error": "error_description" ``` |
| Project Secrets analysis started | Начался анализ секретов проекта | project_secrets_analysis_started |
``` "project_id": 0, "project_name": "project_name" ``` |
| Project Secrets analysis finished | Завершился анализ секретов проекта | project_secrets_analysis_finished |
``` "project_id": 0, "project_name": "project_name" ``` |
| Project Secrets analysis cancelled | Анализ секретов проекта был отменен | project_secrets_analysis_cancelled |
``` "project_id": 0, "project_name": "project_name" ``` |
| Project Secrets analysis failed | Анализ секретов проекта был завершен с ошибкой | project_secrets_analysis_failed |
``` "project_id": 0, "project_name": "project_name" ``` |
| Secrets ML model user training run started | Началось обучение ML-модели для модуля Секретов | ml_model_user_secrets_training_run_started |
``` Пустой payload ``` |
| Secrets ML model user training run finished | Обучение ML-модели для модуля Секретов завершено | ml_model_user_secrets_training_run_finished |
``` Пустой payload ``` |
| Secrets ML model user training run cancelled | Обучение ML-модели для модуля Секретов отменено | ml_model_user_secrets_training_run_cancelled |
``` Пустой payload ``` |
| Secrets ML model user training run failed | Обучение ML-модели для модуля Секретов завершено с ошибкой | ml_model_user_secrets_training_run_failed |
``` Пустой payload ``` |
| Secrets ML model user accepted | ML-модель для модуля Секретов принята | ml_model_user_secrets_accepted |
``` Пустой payload ``` |
| Secrets ML model user purged | ML-модель для модуля Секретов очищена | ml_model_user_secrets_purged |
``` Пустой payload ``` |
{json.dumps(events, indent=2)}'
@app.post('/')
def handle_events():
received_events = request.json.get('events', [])
events.extend(received_events)
return 'OK'
```
:::
---
url: /user-guide/general/api.md
---
# Работа с API
CodeScoring имеет открытый API, который позволяет программно взаимодействовать с системой. Для описания команд API используется инструмент Swagger, доступный по ссылке **\[platform-url]/api/swagger**.
## Начало работы
Чтобы начать работу с CodeScoring API, необходим токен для аутентификации запросов. Получить токен можно в разделе `Профиль` по нажатию кнопки **Сгенерировать** в поле `API токен`.
Для аутентификации запросов вне Swagger необходимо прописать токен в header следующим образом:
`Authorization: Token