115 lines
5.3 KiB
Markdown
115 lines
5.3 KiB
Markdown
# Transport Packaging Scripts
|
||
|
||
Эти скрипты реализуют MVP для `manual + pinned` доставки transport-бинарей
|
||
в режиме `runtime_mode=exec`.
|
||
|
||
## Файлы
|
||
|
||
- `manifest.example.json` — шаблон pinned-манифеста (заполнить реальными версиями/URL/checksum).
|
||
- `manifest.production.json` — pinned production-манифест с зафиксированными версиями и checksum.
|
||
- `source_policy.example.json` — шаблон trusted-source/signature policy.
|
||
- `source_policy.production.json` — production policy с trusted URL-prefix и режимами подписи.
|
||
- `update.sh` — ручной update (скачивание, checksum verify, атомарный switch symlink, history).
|
||
- `auto_update.sh` — opt-in обёртка над `update.sh` (interval gate + lock + jitter).
|
||
- `rollback.sh` — откат на предыдущую версию из history.
|
||
- `systemd/transport-packaging-auto-update.{service,timer}` — шаблоны для systemd расписания.
|
||
|
||
## Быстрый старт
|
||
|
||
1. Выберите манифест:
|
||
- production: `scripts/transport-packaging/manifest.production.json`;
|
||
- кастомный: скопируйте `manifest.example.json` и заполните значения.
|
||
|
||
2. Для кастомного манифеста заполните:
|
||
- `enabled=true` для нужных компонентов;
|
||
- `version`, `url`, `sha256` для каждой target-платформы.
|
||
|
||
3. Выполните update:
|
||
|
||
```bash
|
||
./scripts/transport-packaging/update.sh \
|
||
--manifest /path/to/manifest.json \
|
||
--source-policy ./scripts/transport-packaging/source_policy.production.json \
|
||
--component singbox,dnstt \
|
||
--target linux-amd64
|
||
```
|
||
|
||
4. При проблеме откатите:
|
||
|
||
```bash
|
||
./scripts/transport-packaging/rollback.sh \
|
||
--bin-root /opt/selective-vpn/bin \
|
||
--component singbox,dnstt
|
||
```
|
||
|
||
## Поведение update.sh
|
||
|
||
- Поддерживает `packaging_profile=system|bundled` в API-контракте.
|
||
- Для `bundled` активный бинарь переключается symlink в `bin_root`.
|
||
- История обновлений: `BIN_ROOT/.packaging/<component>.history`.
|
||
- Fail-fast валидация checksum (`sha256sum`) обязательна.
|
||
- Trusted source policy:
|
||
- `--source-policy` ограничивает допустимые URL (`https`, host/prefix allowlist).
|
||
- для `manifest.production.json` policy подхватывается автоматически из `source_policy.production.json`.
|
||
- Signature policy:
|
||
- настраивается через `policy.signature.default_mode` и `components.<name>.signature_mode` (`off|optional|required`);
|
||
- поддержан `signature.type=openssl-sha256` (detached signature);
|
||
- для `required` нужны поля `signature.url` + `signature.public_key_path` (и опционально `signature.sha256`).
|
||
- Staged rollout / canary:
|
||
- `target.rollout.stage`: `stable|canary` (default `stable`);
|
||
- `target.rollout.percent`: `0..100` (default `100`);
|
||
- runtime-флаги: `--rollout-stage`, `--cohort-id`, `--force-rollout`, `--canary`.
|
||
|
||
## Auto-update opt-in
|
||
|
||
- По умолчанию выключен (`--enabled false`).
|
||
- Скрипт `auto_update.sh`:
|
||
- запускает `update.sh` только при `enabled=true`;
|
||
- защищён lock'ом (`flock`) от параллельных запусков;
|
||
- поддерживает интервал запуска (`--min-interval-sec`) и jitter (`--jitter-sec`);
|
||
- хранит state в `.../.packaging/auto-update` (`last_run_epoch`, `last_success_epoch`, `last_error`).
|
||
|
||
Пример ручного запуска:
|
||
|
||
```bash
|
||
./scripts/transport-packaging/auto_update.sh \
|
||
--enabled true \
|
||
--manifest ./scripts/transport-packaging/manifest.production.json \
|
||
--source-policy ./scripts/transport-packaging/source_policy.production.json \
|
||
--component singbox,phoenix \
|
||
--min-interval-sec 21600 \
|
||
--jitter-sec 300
|
||
```
|
||
|
||
Шаблон systemd:
|
||
|
||
1. Скопировать `systemd/transport-packaging-auto-update.service` и `.timer` в `/etc/systemd/system/`.
|
||
2. Скопировать `systemd/transport-packaging-auto-update.env.example` в `/etc/selective-vpn/transport-packaging-auto-update.env`.
|
||
3. Включить timer:
|
||
|
||
```bash
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable --now transport-packaging-auto-update.timer
|
||
```
|
||
|
||
## Примеры rollout
|
||
|
||
```bash
|
||
# Установить только stable targets
|
||
./scripts/transport-packaging/update.sh \
|
||
--manifest ./scripts/transport-packaging/manifest.production.json \
|
||
--rollout-stage stable
|
||
|
||
# Установить только canary targets для конкретного cohort
|
||
./scripts/transport-packaging/update.sh \
|
||
--manifest /path/to/manifest-with-canary.json \
|
||
--rollout-stage canary \
|
||
--cohort-id 5
|
||
```
|
||
|
||
## Ограничения MVP
|
||
|
||
- Обновление запускается вручную (без авто-таймера).
|
||
- Нет фонового scheduler/каналов обновления.
|
||
- В `manifest.production.json` компонент `dnstt` выключен по умолчанию (`enabled=false`), т.к. текущий источник prebuilt-бинарей не является официальным release upstream.
|