diff --git a/docs-ru/README.md b/docs-ru/README.md new file mode 100644 index 0000000..97be4c6 --- /dev/null +++ b/docs-ru/README.md @@ -0,0 +1,13 @@ +# Документация NORA для Росреестра + +## Структура + +- `ТУ.md` — Технические условия +- `Руководство.md` — Руководство пользователя +- `Руководство_администратора.md` — Руководство администратора +- `SBOM.md` — Перечень компонентов (Software Bill of Materials) + +## Статус + +Подготовка документации для включения в Единый реестр российских программ +для электронных вычислительных машин и баз данных (Минцифры РФ). diff --git a/docs-ru/admin-guide.md b/docs-ru/admin-guide.md new file mode 100644 index 0000000..0c83be8 --- /dev/null +++ b/docs-ru/admin-guide.md @@ -0,0 +1,301 @@ +# Руководство администратора NORA + +**Версия:** 1.0 +**Дата:** 2026-03-16 +**Правообладатель:** ООО «ТАИАРС» (торговая марка АРТАИС) + +--- + +## 1. Общие сведения + +NORA — многопротокольный реестр артефактов, предназначенный для хранения, кэширования и распространения программных компонентов. Программа обеспечивает централизованное управление зависимостями при разработке и сборке программного обеспечения. + +### 1.1. Назначение + +- Хранение и раздача артефактов по протоколам Docker (OCI), npm, Maven, PyPI, Cargo, Helm OCI и Raw. +- Проксирование и кэширование внешних репозиториев для ускорения сборок и обеспечения доступности при отсутствии соединения с сетью Интернет. +- Контроль целостности артефактов посредством верификации SHA-256. +- Аудит и протоколирование всех операций. + +### 1.2. Системные требования + +| Параметр | Минимальные | Рекомендуемые | +|----------|-------------|---------------| +| ОС | Linux (amd64, arm64) | Ubuntu 22.04+, RHEL 8+ | +| ЦПУ | 1 ядро | 2+ ядра | +| ОЗУ | 256 МБ | 1+ ГБ | +| Диск | 1 ГБ | 50+ ГБ (зависит от объёма хранимых артефактов) | +| Сеть | TCP-порт (по умолчанию 4000) | — | + +### 1.3. Зависимости + +Программа поставляется как единый статически слинкованный исполняемый файл. Внешние зависимости отсутствуют. Перечень библиотек, включённых в состав программы, приведён в файле `nora.cdx.json` (формат CycloneDX). + +--- + +## 2. Установка + +### 2.1. Автоматическая установка + +```bash +curl -fsSL https://getnora.io/install.sh | bash +``` + +Скрипт выполняет следующие действия: + +1. Определяет архитектуру процессора (amd64 или arm64). +2. Загружает исполняемый файл с GitHub Releases. +3. Создаёт системного пользователя `nora`. +4. Создаёт каталоги: `/etc/nora/`, `/var/lib/nora/`, `/var/log/nora/`. +5. Устанавливает файл конфигурации `/etc/nora/nora.env`. +6. Устанавливает и активирует systemd-сервис. + +### 2.2. Ручная установка + +```bash +# Загрузка +wget https://github.com/getnora-io/nora/releases/download/v1.0.0/nora-linux-x86_64 +chmod +x nora-linux-x86_64 +mv nora-linux-x86_64 /usr/local/bin/nora + +# Создание пользователя +useradd --system --shell /usr/sbin/nologin --home-dir /var/lib/nora --create-home nora + +# Создание каталогов +mkdir -p /etc/nora /var/lib/nora /var/log/nora +chown nora:nora /var/lib/nora /var/log/nora + +# Установка systemd-сервиса +cp dist/nora.service /etc/systemd/system/ +systemctl daemon-reload +systemctl enable nora +``` + +### 2.3. Установка из Docker-образа + +```bash +docker run -d \ + --name nora \ + -p 4000:4000 \ + -v nora-data:/data \ + ghcr.io/getnora-io/nora:latest +``` + +--- + +## 3. Конфигурация + +Конфигурация задаётся через переменные окружения, файл `config.toml` или их комбинацию. Приоритет: переменные окружения > config.toml > значения по умолчанию. + +### 3.1. Основные параметры + +| Переменная | Описание | По умолчанию | +|-----------|----------|--------------| +| `NORA_HOST` | Адрес привязки | `127.0.0.1` | +| `NORA_PORT` | Порт | `4000` | +| `NORA_PUBLIC_URL` | Внешний URL (для генерации ссылок) | — | +| `NORA_STORAGE_PATH` | Путь к каталогу хранилища | `data/storage` | +| `NORA_STORAGE_MODE` | Тип хранилища: `local` или `s3` | `local` | +| `NORA_BODY_LIMIT_MB` | Максимальный размер тела запроса (МБ) | `2048` | + +### 3.2. Аутентификация + +| Переменная | Описание | По умолчанию | +|-----------|----------|--------------| +| `NORA_AUTH_ENABLED` | Включить аутентификацию | `false` | +| `NORA_AUTH_HTPASSWD_FILE` | Путь к файлу htpasswd | `users.htpasswd` | + +Создание пользователя: + +```bash +htpasswd -Bc /etc/nora/users.htpasswd admin +``` + +Роли: `admin` (полный доступ), `write` (чтение и запись), `read` (только чтение, по умолчанию). + +### 3.3. Проксирование внешних репозиториев + +| Переменная | Описание | По умолчанию | +|-----------|----------|--------------| +| `NORA_NPM_PROXY` | URL npm-реестра | `https://registry.npmjs.org` | +| `NORA_NPM_PROXY_AUTH` | Учётные данные (`user:pass`) | — | +| `NORA_NPM_METADATA_TTL` | TTL кэша метаданных (секунды) | `300` | +| `NORA_PYPI_PROXY` | URL PyPI-реестра | `https://pypi.org/simple/` | +| `NORA_MAVEN_PROXIES` | Список Maven-репозиториев через запятую | `https://repo1.maven.org/maven2` | +| `NORA_DOCKER_UPSTREAMS` | Docker-реестры, формат: `url\|auth,url2` | `https://registry-1.docker.io` | + +### 3.4. Ограничение частоты запросов + +| Переменная | Описание | По умолчанию | +|-----------|----------|--------------| +| `NORA_RATE_LIMIT_ENABLED` | Включить ограничение | `true` | +| `NORA_RATE_LIMIT_GENERAL_RPS` | Запросов в секунду (общие) | `100` | +| `NORA_RATE_LIMIT_AUTH_RPS` | Запросов в секунду (аутентификация) | `1` | +| `NORA_RATE_LIMIT_UPLOAD_RPS` | Запросов в секунду (загрузка) | `200` | + +--- + +## 4. Управление сервисом + +### 4.1. Запуск и остановка + +```bash +systemctl start nora # Запуск +systemctl stop nora # Остановка +systemctl restart nora # Перезапуск +systemctl status nora # Статус +journalctl -u nora -f # Просмотр журнала +``` + +### 4.2. Проверка работоспособности + +```bash +curl http://localhost:4000/health +``` + +Ответ при нормальной работе: +```json +{ + "status": "healthy", + "version": "1.0.0", + "storage": { "backend": "local", "reachable": true }, + "registries": { "docker": "ok", "npm": "ok", "maven": "ok", "cargo": "ok", "pypi": "ok" } +} +``` + +### 4.3. Метрики (Prometheus) + +``` +GET /metrics +``` + +Экспортируются: количество запросов, латентность, загрузки и выгрузки по протоколам. + +--- + +## 5. Резервное копирование и восстановление + +### 5.1. Создание резервной копии + +```bash +nora backup --output /backup/nora-$(date +%Y%m%d).tar.gz +``` + +### 5.2. Восстановление + +```bash +nora restore --input /backup/nora-20260316.tar.gz +``` + +### 5.3. Сборка мусора + +```bash +nora gc --dry-run # Просмотр (без удаления) +nora gc # Удаление осиротевших блобов +``` + +--- + +## 6. Предварительное кэширование (nora mirror) + +Команда `nora mirror` позволяет заранее загрузить зависимости через прокси-кэш NORA. Это обеспечивает доступность артефактов при работе в изолированных средах без доступа к сети Интернет. + +### 6.1. Кэширование по lockfile + +```bash +nora mirror npm --lockfile package-lock.json --registry http://localhost:4000 +nora mirror pip --lockfile requirements.txt --registry http://localhost:4000 +nora mirror cargo --lockfile Cargo.lock --registry http://localhost:4000 +``` + +### 6.2. Кэширование по списку пакетов + +```bash +nora mirror npm --packages lodash,express --registry http://localhost:4000 +nora mirror npm --packages lodash --all-versions --registry http://localhost:4000 +``` + +### 6.3. Параметры + +| Флаг | Описание | По умолчанию | +|------|----------|--------------| +| `--registry` | URL экземпляра NORA | `http://localhost:4000` | +| `--concurrency` | Количество параллельных загрузок | `8` | +| `--all-versions` | Загрузить все версии (только с `--packages`) | — | + +--- + +## 7. Миграция хранилища + +Перенос артефактов между локальным хранилищем и S3: + +```bash +nora migrate --from local --to s3 --dry-run # Просмотр +nora migrate --from local --to s3 # Выполнение +``` + +--- + +## 8. Безопасность + +### 8.1. Контроль целостности + +При проксировании npm-пакетов NORA вычисляет и сохраняет контрольную сумму SHA-256 для каждого тарбола. При повторной выдаче из кэша контрольная сумма проверяется. В случае расхождения запрос отклоняется, а в журнал записывается предупреждение уровня SECURITY. + +### 8.2. Защита от подмены пакетов + +- Валидация имён файлов при публикации (защита от обхода каталогов). +- Проверка соответствия имени пакета в URL и теле запроса. +- Иммутабельность версий: повторная публикация той же версии запрещена. + +### 8.3. Аудит + +Все операции (загрузка, выгрузка, обращения к кэшу, ошибки) фиксируются в файле `audit.jsonl` в каталоге хранилища. Формат — JSON Lines, одна запись на строку. + +### 8.4. Усиление systemd + +Файл сервиса содержит параметры безопасности: + +- `NoNewPrivileges=true` — запрет повышения привилегий. +- `ProtectSystem=strict` — файловая система только для чтения, кроме указанных каталогов. +- `ProtectHome=true` — запрет доступа к домашним каталогам. +- `PrivateTmp=true` — изолированный каталог временных файлов. + +--- + +## 9. Точки подключения (endpoints) + +| Протокол | Endpoint | Описание | +|----------|----------|----------| +| Docker / OCI | `/v2/` | Docker Registry V2 API | +| npm | `/npm/` | npm-реестр (прокси + публикация) | +| Maven | `/maven2/` | Maven-репозиторий | +| PyPI | `/simple/` | Python Simple API (PEP 503) | +| Cargo | `/cargo/` | Cargo-реестр | +| Helm | `/v2/` (OCI) | Helm-чарты через OCI-протокол | +| Raw | `/raw/` | Произвольные файлы | +| Мониторинг | `/health`, `/ready`, `/metrics` | Проверка и метрики | +| Интерфейс | `/ui/` | Веб-интерфейс управления | +| Документация API | `/api-docs` | OpenAPI (Swagger UI) | + +--- + +## 10. Устранение неполадок + +### Сервис не запускается + +```bash +journalctl -u nora --no-pager -n 50 +``` + +Частые причины: занят порт, недоступен каталог хранилища, ошибка в конфигурации. + +### Прокси-кэш не работает + +1. Проверьте доступность внешнего реестра: `curl https://registry.npmjs.org/lodash`. +2. Убедитесь, что переменная `NORA_NPM_PROXY` задана корректно. +3. При использовании приватного реестра укажите `NORA_NPM_PROXY_AUTH`. + +### Ошибка целостности (Integrity check failed) + +Контрольная сумма кэшированного тарбола не совпадает с сохранённой. Возможные причины: повреждение файловой системы или несанкционированное изменение файла. Удалите повреждённый файл из каталога хранилища — NORA загрузит его заново из внешнего реестра. diff --git a/docs-ru/technical-spec.md b/docs-ru/technical-spec.md new file mode 100644 index 0000000..6bcbc7d --- /dev/null +++ b/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 diff --git a/docs-ru/user-guide.md b/docs-ru/user-guide.md new file mode 100644 index 0000000..f844557 --- /dev/null +++ b/docs-ru/user-guide.md @@ -0,0 +1,221 @@ +# Руководство пользователя NORA + +**Версия:** 1.0 +**Дата:** 2026-03-16 +**Правообладатель:** ООО «ТАИАРС» (торговая марка АРТАИС) + +--- + +## 1. Общие сведения + +NORA — реестр артефактов для команд разработки. Программа обеспечивает хранение и кэширование библиотек, Docker-образов и иных программных компонентов, используемых при сборке приложений. + +Данное руководство предназначено для разработчиков, которые используют NORA в качестве источника зависимостей. + +--- + +## 2. Настройка рабочего окружения + +### 2.1. npm / Node.js + +Укажите NORA в качестве реестра: + +```bash +npm config set registry http://nora.example.com:4000/npm +``` + +Или создайте файл `.npmrc` в корне проекта: + +``` +registry=http://nora.example.com:4000/npm +``` + +После этого все команды `npm install` будут загружать пакеты через NORA. При первом обращении NORA загрузит пакет из внешнего реестра (npmjs.org) и сохранит его в кэш. Последующие обращения обслуживаются из кэша. + +### 2.2. Docker + +```bash +docker login nora.example.com:4000 +docker pull nora.example.com:4000/library/nginx:latest +docker push nora.example.com:4000/myteam/myapp:1.0.0 +``` + +### 2.3. Maven + +Добавьте репозиторий в `settings.xml`: + +```xml + + + nora + central + http://nora.example.com:4000/maven2 + + +``` + +### 2.4. Python / pip + +```bash +pip install --index-url http://nora.example.com:4000/simple flask +``` + +Или в `pip.conf`: + +```ini +[global] +index-url = http://nora.example.com:4000/simple +``` + +### 2.5. Cargo / Rust + +Настройка в `~/.cargo/config.toml`: + +```toml +[registries.nora] +index = "sparse+http://nora.example.com:4000/cargo/" + +[source.crates-io] +replace-with = "nora" +``` + +### 2.6. Helm + +Helm использует OCI-протокол через Docker Registry API: + +```bash +helm push mychart-0.1.0.tgz oci://nora.example.com:4000/helm +helm pull oci://nora.example.com:4000/helm/mychart --version 0.1.0 +``` + +--- + +## 3. Публикация пакетов + +### 3.1. npm + +```bash +npm publish --registry http://nora.example.com:4000/npm +``` + +Требования: +- Файл `package.json` с полями `name` и `version`. +- Каждая версия публикуется однократно. Повторная публикация той же версии запрещена. + +### 3.2. Docker + +```bash +docker tag myapp:latest nora.example.com:4000/myteam/myapp:1.0.0 +docker push nora.example.com:4000/myteam/myapp:1.0.0 +``` + +### 3.3. Maven + +```bash +mvn deploy -DaltDeploymentRepository=nora::default::http://nora.example.com:4000/maven2 +``` + +### 3.4. Raw (произвольные файлы) + +```bash +# Загрузка +curl -X PUT --data-binary @release.tar.gz http://nora.example.com:4000/raw/builds/release-1.0.tar.gz + +# Скачивание +curl -O http://nora.example.com:4000/raw/builds/release-1.0.tar.gz +``` + +--- + +## 4. Работа в изолированной среде + +Если сборочный сервер не имеет доступа к сети Интернет, используйте предварительное кэширование. + +### 4.1. Кэширование зависимостей проекта + +На машине с доступом к Интернету и NORA выполните: + +```bash +nora mirror npm --lockfile package-lock.json --registry http://nora.example.com:4000 +``` + +После этого все зависимости из lockfile будут доступны через NORA, даже если связь с внешними реестрами отсутствует. + +### 4.2. Кэширование всех версий пакета + +```bash +nora mirror npm --packages lodash,express --all-versions --registry http://nora.example.com:4000 +``` + +Эта команда загрузит все опубликованные версии указанных пакетов. + +--- + +## 5. Веб-интерфейс + +NORA предоставляет веб-интерфейс для просмотра содержимого реестра: + +``` +http://nora.example.com:4000/ui/ +``` + +Доступные функции: +- Просмотр списка артефактов по протоколам. +- Количество версий и размер каждого пакета. +- Журнал последних операций. +- Метрики загрузок. + +--- + +## 6. Документация API + +Интерактивная документация API доступна по адресу: + +``` +http://nora.example.com:4000/api-docs +``` + +Формат: OpenAPI 3.0 (Swagger UI). + +--- + +## 7. Аутентификация + +Если администратор включил аутентификацию, для операций записи требуется токен. + +### 7.1. Получение токена + +```bash +curl -u admin:password http://nora.example.com:4000/auth/token +``` + +### 7.2. Использование токена + +```bash +# npm +npm config set //nora.example.com:4000/npm/:_authToken TOKEN + +# Docker +docker login nora.example.com:4000 + +# curl +curl -H "Authorization: Bearer TOKEN" http://nora.example.com:4000/npm/my-package +``` + +Операции чтения по умолчанию не требуют аутентификации (роль `read` назначается автоматически). + +--- + +## 8. Часто задаваемые вопросы + +**В: Что произойдёт, если внешний реестр (npmjs.org) станет недоступен?** +О: NORA продолжит обслуживать запросы из кэша. Пакеты, которые ранее не запрашивались, будут недоступны до восстановления связи. Для предотвращения такой ситуации используйте `nora mirror`. + +**В: Можно ли публиковать приватные пакеты?** +О: Да. Пакеты, опубликованные через `npm publish` или `docker push`, сохраняются в локальном хранилище NORA и доступны всем пользователям данного экземпляра. + +**В: Как обновить кэш метаданных?** +О: Кэш метаданных npm обновляется автоматически по истечении TTL (по умолчанию 5 минут). Для немедленного обновления удалите файл `metadata.json` из каталога хранилища. + +**В: Поддерживаются ли scoped-пакеты npm (@scope/package)?** +О: Да, полностью. Например: `npm install @babel/core --registry http://nora.example.com:4000/npm`.