# Форк 3X-UI KIT (hacker07)

Это личный форк [3X-UI KIT](https://github.com/itsnotkubrick/3X-UI_KIT): наш код живёт рядом с
кодом автора и не ломается, когда автор обновляет свой. Здесь описано, как это устроено и что
делать после каждого обновления автора.

## Что где лежит

| Что | Где | Правит |
|---|---|---|
| Наши доработки (команды, хуки) | `scripts/kit-local.sh` | только мы |
| Описание «швов» в коде автора | `tools/fork_apply.py` | только мы |
| Синхронизация с автором и проверки | `tools/fork-sync.sh` | только мы |
| Файлы автора (`scripts/kit.sh`, `scripts/3x-ui.sh`, …) | как есть | только автор |

Ключевая идея: **в файлах автора мы правим только «швы»** — несколько констант и одну строку
подключения. Всё, что мы дописываем по существу, лежит в нашем файле, которого автор не знает.
Швы описаны в одном месте (`tools/fork_apply.py`) и накатываются только на чистое дерево автора;
если автор изменил нужную строку — инструмент останавливается и говорит об этом, а не делает
полу-патч.

## Ветки

- `upstream` — точная копия ветки автора (`main`), только вперёд.
- `dev` — наша сборка: `upstream` + швы + наш файл. Из неё делаются релизы.
- релизы — теги `v<номера>`; номер = `<версия автора>.<наш уровень>` (например, автор 1.2 → наш
  первый релиз 1.2.1, следующий наш — 1.2.2, после релиза автора 1.3 — 1.3.1).

Номер обязан строго расти: на серверах `kit update` не принимает откат назад.

## Обновление автора (по шагам)

```bash
cd H:/My_Proj/Fork_3X-UI_KIT
bash tools/fork-sync.sh            # подтянуть автора, перенести наши правки, прогнать проверки
#  при конфликте — разобрать его вручную, инструмент сам ничего не публикует

bash tools/release.sh ~/.ssh/3x-ui-kit-fork/release_key   # SHA256SUMS + подпись нашим ключом
git add -A && git commit -m "Релиз v$(cat VERSION): швы форка + подпись"
git tag v$(cat VERSION)
git push origin dev v$(cat VERSION) upstream
```

## Установка и обновление из этого репозитория

```bash
# установка на чистый сервер (вместо команды автора с GitHub)
bash <(curl -fsSL https://git.rukavishnikoff.ru/hacker07/3X-UI_autoVPS/raw/branch/main/scripts/3x-ui.sh)

# обновление уже стоящего сервера (тянет наш релиз и проверяет нашу подпись)
kit update --force && kit check
```

Внутри `kit` источником файлов служит `KIT_RAW`/`kit_ref_raw()` — они указывают на этот
репозиторий, а подпись релиза проверяется ключом из `KIT_SIGNERS` (только ключ форка).

## Подпись релизов

- Открытая часть ключа — `tools/fork-signer.pub` и в `KIT_SIGNERS` (в `scripts/kit.sh`).
- Закрытая часть — только на рабочей станции владельца (`~/.ssh/3x-ui-kit-fork/release_key`),
  с паролем; в репозиторий, CI и на серверы не попадает. Кто получит ключ — получит root на всех
  серверах, которые обновляются из этого репозитория.
- Смена ключа: подпиши новый релиз старым ключом, иначе серверы его не примут.

## Наши команды

```bash
kit local help      # справка по дополнениям форка
kit local version   # версия, источник обновлений, дата сборки нашего файла
kit local channel   # откуда берутся обновления и чем проверяется подпись
kit local seams     # какие швы форка сейчас в установленном /usr/local/bin/kit
```

## Грабли, о которых стоит помнить

1. **Ночное автообновление** (`kit-update.timer`, 03:00) перезаписывает `/usr/local/bin/kit`
   подписанным релизом из настроенного репозитория. Поэтому канал обновления и швы — один шаг:
   сервер должен смотреть в этот репозиторий, иначе наши правки исчезнут ночью.
2. **Переводы строк.** Релиз подписывается по контрольным суммам файлов в рабочей копии, а сервер
   сверяет их с файлами из Gitea. При `core.autocrlf=true` суммы не сойдутся (CRLF против LF):
   в этом клоне должно быть `git config core.autocrlf false`.
3. **Наш файл обязан быть в списке релиза** (`tools/release.sh`, `FILES=(…)`) и в списке загрузки
   `fetch_release()` — иначе при обновлении `kit.sh` приедет новый, а `kit-local.sh` останется старым.
4. **Панель 3X-UI ставится с GitHub** по закреплённой версии и SHA256 — это шаг автора, форк его не
   трогает. Для установки с нуля серверу нужен доступ к GitHub.