docs: Russian documentation — admin guide, user guide, technical spec (Минцифры)

docs-ru/technical-spec.md

@@ -0,0 +1,165 @@
+# Технические условия
+
+## Программа «NORA — Реестр артефактов»
+
+**Версия документа:** 1.0
+**Дата:** 2026-03-16
+**Правообладатель:** ООО «ТАИАРС» (торговая марка АРТАИС)
+
+---
+
+## 1. Наименование и обозначение
+
+**Полное наименование:** NORA — многопротокольный реестр артефактов.
+
+**Краткое наименование:** NORA.
+
+**Обозначение:** nora-registry.
+
+---
+
+## 2. Назначение
+
+Программа предназначена для хранения, кэширования и распространения программных компонентов (артефактов), используемых при разработке, сборке и развёртывании программного обеспечения.
+
+### 2.1. Область применения
+
+- Организация внутренних репозиториев программных компонентов.
+- Проксирование и кэширование общедоступных репозиториев (npmjs.org, PyPI, Maven Central, Docker Hub, crates.io).
+- Обеспечение доступности зависимостей в изолированных средах без доступа к сети Интернет (air-gapped).
+- Контроль целостности и безопасности цепочки поставки программного обеспечения.
+
+### 2.2. Класс программного обеспечения
+
+Инструментальное программное обеспечение для разработки и DevOps.
+
+Код ОКПД2: 62.01 — Разработка компьютерного программного обеспечения.
+
+---
+
+## 3. Функциональные характеристики
+
+### 3.1. Поддерживаемые протоколы
+
+| Протокол | Стандарт | Назначение |
+|----------|----------|------------|
+| Docker / OCI | OCI Distribution Spec v1.0 | Контейнерные образы, Helm-чарты |
+| npm | npm Registry API | Библиотеки JavaScript / TypeScript |
+| Maven | Maven Repository Layout | Библиотеки Java / Kotlin |
+| PyPI | PEP 503 (Simple API) | Библиотеки Python |
+| Cargo | Cargo Registry Protocol | Библиотеки Rust |
+| Raw | HTTP PUT/GET | Произвольные файлы |
+
+### 3.2. Режимы работы
+
+1. **Хранилище (hosted):** приём и хранение артефактов, опубликованных пользователями.
+2. **Прокси-кэш (proxy):** прозрачное проксирование запросов к внешним репозиториям с локальным кэшированием.
+3. **Комбинированный:** одновременная работа в режимах хранилища и прокси-кэша (поиск сначала в локальном хранилище, затем во внешнем репозитории).
+
+### 3.3. Управление доступом
+
+- Аутентификация на основе htpasswd (bcrypt).
+- Ролевая модель: `read` (чтение), `write` (чтение и запись), `admin` (полный доступ).
+- Токены доступа с ограниченным сроком действия.
+
+### 3.4. Безопасность
+
+- Контроль целостности кэшированных артефактов (SHA-256).
+- Защита от обхода каталогов (path traversal) при публикации.
+- Проверка соответствия имени пакета в URL и теле запроса.
+- Иммутабельность опубликованных версий.
+- Аудит всех операций в формате JSON Lines.
+- Поддержка TLS при размещении за обратным прокси-сервером.
+
+### 3.5. Эксплуатация
+
+- Предварительное кэширование зависимостей (`nora mirror`) по файлам фиксации версий (lockfile).
+- Сборка мусора (`nora gc`) — удаление осиротевших блобов.
+- Резервное копирование и восстановление (`nora backup`, `nora restore`).
+- Миграция между локальным хранилищем и S3-совместимым объектным хранилищем.
+- Мониторинг: эндпоинты `/health`, `/ready`, `/metrics` (формат Prometheus).
+- Веб-интерфейс для просмотра содержимого реестра.
+- Документация API в формате OpenAPI 3.0.
+
+---
+
+## 4. Технические характеристики
+
+### 4.1. Среда исполнения
+
+| Параметр | Значение |
+|----------|----------|
+| Язык реализации | Rust |
+| Формат поставки | Единый исполняемый файл (статическая линковка) |
+| Поддерживаемые ОС | Linux (ядро 4.15+) |
+| Архитектуры | x86_64 (amd64), aarch64 (arm64) |
+| Контейнеризация | Docker-образ на базе `scratch` |
+| Системная интеграция | systemd (файл сервиса в комплекте) |
+
+### 4.2. Хранение данных
+
+| Параметр | Значение |
+|----------|----------|
+| Локальное хранилище | Файловая система (ext4, XFS, ZFS) |
+| Объектное хранилище | S3-совместимое API (MinIO, Yandex Object Storage, Selectel S3) |
+| Структура | Иерархическая: `{protocol}/{package}/{artifact}` |
+| Аудит | Append-only JSONL файл |
+
+### 4.3. Конфигурация
+
+| Источник | Приоритет |
+|----------|-----------|
+| Переменные окружения (`NORA_*`) | Высший |
+| Файл `config.toml` | Средний |
+| Значения по умолчанию | Низший |
+
+### 4.4. Производительность
+
+| Параметр | Значение |
+|----------|----------|
+| Время запуска | < 100 мс |
+| Обслуживание из кэша | < 2 мс (метаданные), < 10 мс (артефакты до 1 МБ) |
+| Параллельная обработка | Асинхронный ввод-вывод (tokio runtime) |
+| Ограничение частоты | Настраиваемое (по умолчанию 100 запросов/сек) |
+
+---
+
+## 5. Лицензирование
+
+| Компонент | Лицензия |
+|-----------|----------|
+| NORA (core) | MIT License |
+| NORA Enterprise | Проприетарная |
+
+Полный перечень лицензий включённых библиотек приведён в файле SBOM (формат CycloneDX).
+
+---
+
+## 6. Комплектность
+
+| Компонент | Описание |
+|-----------|----------|
+| `nora` | Исполняемый файл |
+| `nora.service` | Файл systemd-сервиса |
+| `nora.env.example` | Шаблон конфигурации |
+| `install.sh` | Скрипт установки |
+| `nora.cdx.json` | SBOM в формате CycloneDX |
+| Руководство администратора | Настоящий комплект документации |
+| Руководство пользователя | Настоящий комплект документации |
+| Технические условия | Настоящий документ |
+
+---
+
+## 7. Контактная информация
+
+**Правообладатель:** ООО «ТАИАРС»
+
+**Торговая марка:** АРТАИС
+
+**Сайт продукта:** https://getnora.io
+
+**Документация:** https://getnora.dev
+
+**Исходный код:** https://github.com/getnora-io/nora
+
+**Поддержка:** https://t.me/getnora