fork: инструменты сборки и локальные дополнения (швы, синхронизация с автором)

2026-10-12 15:16:32 +03:00
parent 47cdfd34a5
commit 45b8d1c783
5 changed files with 485 additions and 0 deletions
@@ -0,0 +1,85 @@
+# Форк 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_KIT/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.