# Удалённый каталог модулей

← [К разделу «Модули»](README.md)

AVE.cms может получать список модулей с сайта владельца системы. Сервер
каталога остаётся обычным статическим HTTPS-каталогом: ему не нужны PHP, база
данных или отдельный API.

## Подключение для владельца сайта

В чистом установщике выберите **Официальный канал AVE.cms**. URL каталога и
публичный ключ уже включены в сборку, поэтому копировать их с сайта или из
инструкции не требуется. Подключение не устанавливает модули автоматически:
оно только показывает доступные подписанные пакеты.

Если официальный источник был изменён, откройте **Модули → Каталог → Источник**
и нажмите **Восстановить**. Для другого издателя вставьте полученный от него
JSON-профиль при установке либо заполните URL и ключ вручную в этой панели.
Публичный ключ не является секретом.

## Подключение в панели

1. Откройте **Система → Модули → Управление**.
2. Нажмите **Источник**.
3. Включите удалённый каталог.
4. Укажите полный HTTPS URL файла `index.json`.
5. Вставьте публичный RSA-ключ издателя и сохраните настройки.

После проверки в блоке «Каталог модулей» появится отметка **Подпись
проверена**. Кнопка обновления повторно получает список, а кнопка установки
скачивает выбранный пакет и передаёт его штатному ZIP-установщику.

Публичный ключ не является секретом. Закрытый ключ в панель не загружается и на
web-сервер AVE.cms попадать не должен.

## Что проверяется

Перед выполнением кода система последовательно проверяет:

- HTTPS и публичный адрес источника;
- RSA-SHA256 подпись всего каталога;
- совместимость версии PHP и AVE.cms;
- размер и SHA-256 скачанного ZIP;
- одинаковый хост каталога и архива;
- официальный `AVE-MODULE.json` и SHA-256 каждого файла внутри пакета;
- безопасную структуру ZIP и ограничения распаковки.

Установка требует прав **Управление модулями** и **Установка кода модулей**.
Событие записывается в аудит.

## Публикация своего каталога

Команды выполняются в рабочей копии владельца, а не на production-сайте.
Закрытый ключ создаётся один раз:

```bash
php tools/generate-module-repository-key.php
```

Соберите ZIP нужных модулей обычным сборщиком, затем сформируйте каталог:

```bash
php tools/build-module-package.php modules/comments
php tools/build-module-repository.php
```

Готовая статическая папка находится в
`storage/releases/module-repository/`. Загрузите её содержимое на HTTPS-хост:
сначала `files/*.zip`, после проверки файлов — `index.json` последним,
например в `/updates/modules/`. URL для панели будет выглядеть так:

```text
https://example.org/updates/modules/index.json
```

Рядом автоматически создаётся
`storage/releases/module-repository-host.zip` с той же папкой, если удобнее
загрузить и распаковать один архив через панель хостинга.

Публичный ключ находится в `public-key.txt` внутри готовой папки. В настройку
вставляется содержимое файла, а не путь к нему. Закрытый ключ
остаётся в `storage/secrets/module-repository-private.pem` и не входит в
публикацию. Сохраните его в защищённой резервной копии: без него нельзя
выпустить следующее обновление того же доверенного каталога.

Чтобы передать потребителю оба источника одной вставкой, сформируйте профиль:

```bash
php tools/build-distribution-profile.php \
  --name="Мой канал AVE.cms" \
  --core-url=https://example.org/updates/core/index.json \
  --module-url=https://example.org/updates/modules/index.json \
  --output=storage/releases/my-repository-profile.json
```

Передайте созданный JSON, но никогда не передавайте закрытые PEM-ключи.

Для следующей публикации пересоберите изменённые ZIP, повторно запустите
`build-module-repository.php` и замените статические файлы на хосте. Генератор
выбирает последнюю семантическую версию каждого `code`. В имени опубликованного
ZIP есть часть SHA-256, поэтому разное содержимое одной версии получает разные
URL и не сталкивается со старым кешем хостинга/CDN. Не переименовывайте ZIP
вручную и не публикуйте новый `index.json` раньше указанных в нём файлов.

### Проверка файлов на хостинге

Сборщик кладёт рядом с `index.json` страницу `check.php`. После загрузки
репозитория откройте адрес папки или непосредственно:

```text
https://example.org/updates/modules/check.php
```

Страница сначала проверит цифровую подпись каталога, затем браузер по очереди
скачает каждый ZIP с обходом кеша и сравнит фактический размер и SHA-256 с
подписанными значениями. Так обнаруживается как недогруженный FTP-файл, так и
устаревшая копия CDN. Красную строку нужно повторно загрузить; `index.json`
заменяйте последним и только после полностью зелёной проверки. Закрытый ключ
странице не нужен и на хостинг не загружается.
Новая сборка репозитория содержит только ZIP, перечисленные в её подписанном
`index.json`. Поэтому в архив для хостинга не попадают устаревшие варианты одной
версии модуля. Если на хостинге или CDN старый `index.json` кешируется надолго,
его архивы можно временно сохранить отдельно на время жизни кеша. Новый
`index.json` всегда загружайте последним.

## Обновление установленного модуля

Если в каталоге опубликована более новая версия, одна операция заменяет папку
модуля целиком и сразу выполняет его новые миграции. Сверять старые файлы на
сервере не требуется: последняя подписанная версия пакета имеет приоритет.
Старые файлы временно сохраняются в staging до успешной проверки нового
`module.php`. Уже применённый ID миграции второй раз не запускается.

Патчи AVE.cms устанавливаются отдельной подсистемой обновлений. Модульный
установщик не имеет права заменять файлы ядра.