nora/docs-ru/admin-guide.md

Руководство администратора 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. Автоматическая установка

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. Ручная установка

# Загрузка
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-образа

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

Создание пользователя:

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. Запуск и остановка

systemctl start nora       # Запуск
systemctl stop nora        # Остановка
systemctl restart nora     # Перезапуск
systemctl status nora      # Статус
journalctl -u nora -f      # Просмотр журнала

4.2. Проверка работоспособности

curl http://localhost:4000/health

Ответ при нормальной работе:

{
  "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. Создание резервной копии

nora backup --output /backup/nora-$(date +%Y%m%d).tar.gz

5.2. Восстановление

nora restore --input /backup/nora-20260316.tar.gz

5.3. Сборка мусора

nora gc --dry-run    # Просмотр (без удаления)
nora gc              # Удаление осиротевших блобов

---

6. Предварительное кэширование (nora mirror)

Команда nora mirror позволяет заранее загрузить зависимости через прокси-кэш NORA. Это обеспечивает доступность артефактов при работе в изолированных средах без доступа к сети Интернет.

6.1. Кэширование по lockfile

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. Кэширование по списку пакетов

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:

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. Устранение неполадок

Сервис не запускается

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 загрузит его заново из внешнего реестра.