Продакшн-фиксы install/reconfigure: rollback, firewall lifecycle, preflight и runbook

docs/12-operations-and-troubleshooting.md

@@ -6,6 +6,17 @@
 
 ## Что должен помнить оператор
 
+### 0. Target prerequisites обязательны
+
+На target-хосте до запуска install должны быть доступны системные зависимости:
+
+```bash
+apt-get update
+apt-get install -y sudo ca-certificates curl iproute2 tar openssl nftables systemd
+```
+
+`sudo` обязателен: используется smoke-проверками прав от имени runtime-пользователей (`hysteria`, `hy2xs-admin`).
+
 ### 1. Builder и target — разные миры
 Если нужно изменить состав install package, это делается в локальном builder layer, а не на target server.
 
@@ -60,6 +71,13 @@ journalctl -u hysteria-server -n 100 --no-pager
 journalctl -u hy2xs-admin -n 100 --no-pager
 ```
 
+Проверка install-state marker:
+```bash
+cat /var/lib/hy2xs/install-state.json
+```
+
+Если `reconfigure` сообщает об отсутствии marker, нужно повторно выполнить чистый install и только потом применять runtime-изменения.
+
 ## Auth endpoint fail checklist
 
 ```bash
@@ -115,6 +133,12 @@ curl -sS \
 
 Редактировать нужно `/etc/hy2xs/hy2xs.env` и затем запускать `reconfigure --dry-run/--apply`.
 
+### Изменили bootstrap-поля, но пароль admin не сменился
+Это ожидаемо.
+
+`HY2XS_ADMIN_INITIAL_PASSWORD` и `HY2XS_ADMIN_CON_PASS` используются только как bootstrap-данные при первичной установке.
+Для ротации существующих credentials нужен отдельный flow на уровне account-management.
+
 ## Правила эксплуатации
 
 1. Не править сервер как будто на нём есть builder.

docs/13-production-runbook.md

@@ -0,0 +1,91 @@
+# HY2XS production runbook
+
+## 1. Supported target
+
+- clean Debian 12 amd64
+- single host install profile
+- IPv4-only runtime model
+
+## 2. Required prerequisites
+
+```bash
+apt-get update
+apt-get install -y sudo ca-certificates curl iproute2 tar openssl nftables systemd
+```
+
+`sudo` обязателен для permission smoke-checks от имени runtime-пользователей.
+
+## 3. Required open ports
+
+- UDP `${HY2XS_HYSTERIA_PORT}`
+- TCP `${HY2XS_UI_PORT}` (обычно localhost bind)
+- TCP `${HY2XS_SSH_PORT}`
+- TCP 80/443 для ACME (в зависимости от типа challenge)
+
+## 4. Clean host assumptions
+
+- нет legacy-конфликта по runtime-users (`hysteria`, `hy2xs-admin`)
+- нет конфликтующего не-HY2XS nftables entrypoint
+- install запускается от root
+
+## 5. Install command
+
+```bash
+./install.sh --non-interactive
+```
+
+## 6. Post-install verification
+
+```bash
+systemctl status hysteria-server
+systemctl status hy2xs-admin
+ss -H -lun | grep ':443'
+ss -H -ltn | grep ':8080'
+nft list ruleset
+cat /var/lib/hy2xs/install-state.json
+```
+
+## 7. Permission verification
+
+```bash
+ls -l /etc/hy2xs/hy2xs.env
+ls -l /etc/hysteria/config.yaml
+
+sudo -u hysteria test -r /etc/hysteria/config.yaml
+sudo -u hy2xs-admin test -r /etc/hysteria/config.yaml
+sudo -u hy2xs-admin test ! -w /etc/hysteria/config.yaml
+sudo -u hy2xs-admin test ! -r /etc/hy2xs/hy2xs.env
+```
+
+## 8. Firewall recovery
+
+Если `install`/`reconfigure` падают после firewall apply:
+
+- rollback guard не должен отменяться до успешного smoke;
+- для recovery использовать вывод оркестратора и перезапускать apply только после устранения root-cause.
+
+## 9. Reconfigure flow
+
+```bash
+hy2xs-orchestrator reconfigure --package-dir /usr/local/lib/hy2xs/package --config /etc/hy2xs/hy2xs.env --dry-run
+hy2xs-orchestrator reconfigure --package-dir /usr/local/lib/hy2xs/package --config /etc/hy2xs/hy2xs.env --apply
+```
+
+## 10. Admin bootstrap credentials
+
+- `HY2XS_ADMIN_INITIAL_PASSWORD` и `HY2XS_ADMIN_CON_PASS` — install-only bootstrap поля.
+- изменение значений в `/etc/hy2xs/hy2xs.env` после install не выполняет автоматическую ротацию существующих credentials.
+
+## 11. IPv4/IPv6 policy
+
+- HY2XS работает в IPv4-only режиме.
+- если IPv6 включён на хосте/провайдере — это вне baseline и должно быть отдельно управляемо оператором.
+
+## 12. Validation command
+
+```bash
+hy2xs-orchestrator doctor --package-dir /usr/local/lib/hy2xs/package --config /etc/hy2xs/hy2xs.env
+```
+
+Команда выполняет preflight + smoke как post-install/post-reboot validation.
+