mirror of
https://github.com/getnora-io/nora.git
synced 2026-04-12 17:20:33 +00:00
docs: Russian documentation — admin guide, user guide, technical spec (Минцифры)
This commit is contained in:
301
docs-ru/admin-guide.md
Normal file
301
docs-ru/admin-guide.md
Normal file
@@ -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 загрузит его заново из внешнего реестра.
|
||||
Reference in New Issue
Block a user