Документация и UX установки: полный production-fix по fix32

2026-05-12 20:16:56 +05:00
parent 2ee50bfa8e
commit b3d274f89d
8 changed files with 266 additions and 6 deletions
@@ -135,6 +135,15 @@
 - [ ] После ручной установки config `awg2-harness validate-config` проходит.
 - [ ] Сервис стартует только после явного `systemctl enable --now awg2-harness.service`.

+## K2. Documentation / install UX
+
+- [ ] README не утверждает, что AmneziaVPN ожидает public key.
+- [ ] Документация явно разделяет private key для AmneziaVPN и public key для `authorized_keys`.
+- [ ] Есть пример заполнения AmneziaVPN fields: `Server IP address [:port]`, `SSH Username`, `Password or SSH private key`.
+- [ ] Описаны Windows пути `%USERPROFILE%\.ssh\amnezia_key` и `%USERPROFILE%\.ssh\amnezia_key.pub`.
+- [ ] Описан runtime config bootstrap из `/usr/share/doc/awg2-harness/repo/config.example.toml`.
+- [ ] Clean install подтверждает, что `/etc/awg2-harness/config.toml` не создаётся автоматически.
+
 ## L. Host firewall (ports/SSH safety)

 - [ ] `awg2-harness validate-config` падает, если отсутствует секция `[host_firewall]`.
@@ -2,6 +2,35 @@

 AWG2 Harness разрабатывался для self-hosted AmneziaWG/AWG 2.0 и совместимого legacy-сценария AmneziaWG/AWG 1.5. Конфиг живёт в `/etc/awg2-harness/config.toml`. Он общий для всего пакета и должен содержать только эксплуатационно значимые параметры.

+## Создание runtime config
+
+Пакет намеренно **не** создаёт `/etc/awg2-harness/config.toml` автоматически. Это снижает риск случайно применить firewall с неверным SSH-портом или неверным Amnezia-портом.
+
+После установки `.deb` создайте runtime config вручную:
+
+```bash
+install -d -m 0755 /etc/awg2-harness
+cp /usr/share/doc/awg2-harness/repo/config.example.toml /etc/awg2-harness/config.toml
+nano /etc/awg2-harness/config.toml
+```
+
+Перед первым `apply-firewall`/`apply-limits` оператор обязан сверить:
+
+- `host_firewall.ssh_port` — должен совпадать с реально слушающим `sshd` портом;
+- `host_firewall.amnezia_port` — должен совпадать с published Docker/Amnezia UDP port;
+- `amnezia.peer_ipv4_cidr` — должен совпадать с реальной peer-подсетью;
+- `anti_torrent.peer_ipv4_cidr` — обычно тот же CIDR.
+
+Discovery-команды:
+
+```bash
+docker port amnezia-awg2 2>/dev/null || docker port amnezia-awg
+
+C="$(docker ps --format '{{.Names}}' | grep -E '^(amnezia-awg2|amnezia-awg)$' | head -n1)"
+docker exec "$C" ip -4 addr
+docker exec "$C" wg show
+```
+
 ## Рекомендуемый `config.toml`

 ```toml
@@ -51,6 +51,27 @@ dpkg-deb -c dist/awg2-harness_0.1.6_amd64.deb | sort

 ### B1. SSH

+Сначала сгенерируйте отдельную пару ключей для Amnezia на Windows (RSA PEM):
+
+```cmd
+ssh-keygen -t rsa -b 4096 -m PEM -f %USERPROFILE%\.ssh\amnezia_key
+```
+
+Дальше разделяйте ключи строго:
+
+- на сервер в `/root/.ssh/authorized_keys` кладётся содержимое `%USERPROFILE%\.ssh\amnezia_key.pub`;
+- в AmneziaVPN в поле `Password or SSH private key` вставляется содержимое `%USERPROFILE%\.ssh\amnezia_key` (без `.pub`).
+
+`.pub` нельзя вставлять в поле private key в AmneziaVPN.
+
+Установка `.pub` на сервер:
+
+```bash
+install -d -m 0700 /root/.ssh
+nano /root/.ssh/authorized_keys
+chmod 0600 /root/.ssh/authorized_keys
+```
+
 Production-пример:

 ```bash
@@ -69,13 +90,37 @@ ss -ltnp | grep ':2323'

 Обязательно проверьте вход с нового терминала:

-```bash
-ssh -p 2323 root@<server-ip>
+```cmd
+ssh -i %USERPROFILE%\.ssh\amnezia_key -p 2323 root@<server-ip>
+```
+
+Проверить содержимое ключей в Windows:
+
+```cmd
+type %USERPROFILE%\.ssh\amnezia_key.pub
+type %USERPROFILE%\.ssh\amnezia_key
 ```

 ### B2. Amnezia

-Установите AmneziaWG/AWG через официальное приложение AmneziaVPN в режиме self-hosted server. Вводите в приложении тот SSH host/port/user/private key, который реально работает после B1.
+Установите AmneziaWG/AWG через официальное приложение AmneziaVPN в режиме self-hosted server.
+
+Заполнение полей в интерфейсе AmneziaVPN:
+
+```text
+Configure your server:
+
+Server IP address [:port]:
+<server-ip>:2323
+
+SSH Username:
+root
+
+Password or SSH private key:
+полное содержимое приватного ключа %USERPROFILE%\.ssh\amnezia_key
+```
+
+Важно: в это поле не вставляется `.pub`. Файл `.pub` нужен только для `/root/.ssh/authorized_keys` на сервере.

 Проверка после установки:

@@ -91,6 +136,10 @@ docker exec "$C" wg show

 ## C. Transfer artifacts

+Ниже два production-сценария установки.
+
+### C1. Вариант A: config передаётся вместе с `.deb`
+
 ```bash
 scp -P 2323 dist/awg2-harness_*_amd64.deb root@<server-ip>:/root/
 scp -P 2323 dist/SHA256SUMS root@<server-ip>:/root/
@@ -105,8 +154,17 @@ scp -P 2323 config.example.toml root@<server-ip>:/root/awg2-harness.config.toml
 - `[anti_torrent].peer_ipv4_cidr` обычно равен `[amnezia].peer_ipv4_cidr`;
 - `peer_limit` и `root_rate` отражают нужную traffic policy.

+### C2. Вариант B (основной): config создаётся на production после установки
+
+```bash
+scp -P 2323 dist/awg2-harness_*_amd64.deb root@<server-ip>:/root/
+scp -P 2323 dist/SHA256SUMS root@<server-ip>:/root/
+```
+
 ## D. Production install

+### D1. Вариант A
+
 ```bash
 cd /root
 sha256sum -c SHA256SUMS
@@ -116,6 +174,25 @@ install -m 0644 /root/awg2-harness.config.toml /etc/awg2-harness/config.toml
 systemctl daemon-reload
 ```

+### D2. Вариант B (основной)
+
+```bash
+cd /root
+sha256sum -c SHA256SUMS
+apt install ./awg2-harness_*_amd64.deb
+install -d -m 0755 /etc/awg2-harness
+cp /usr/share/doc/awg2-harness/repo/config.example.toml /etc/awg2-harness/config.toml
+nano /etc/awg2-harness/config.toml
+systemctl daemon-reload
+```
+
+Перед первым `apply-firewall` обязательно перепроверьте:
+
+- `[host_firewall].ssh_port` совпадает с реально слушающим `sshd` портом;
+- `[host_firewall].amnezia_port` совпадает с published Docker UDP port;
+- `[amnezia].peer_ipv4_cidr` совпадает с peer-подсетью;
+- `[anti_torrent].peer_ipv4_cidr` обычно тот же CIDR.
+
 ## E. Preflight before enable

 ```bash
@@ -0,0 +1,48 @@
+# Production example (reference)
+
+Этот пример фиксирует эталонный production-state после успешной установки и preflight. Значения обезличены и предназначены как reference для smoke-проверки.
+
+```text
+SSH:
+  host: <server-ip>
+  port: 2323
+  user: root
+
+Amnezia:
+  container: amnezia-awg2
+  interface: awg0
+  published UDP: 443
+  peer CIDR: 10.8.1.0/24
+
+Expected status:
+  service: active
+  traffic drift: no
+  host firewall drift: no
+  anti-torrent drift: no
+  swap drift: no
+```
+
+Проверка ключевых сигналов:
+
+```bash
+systemctl status awg2-harness.service --no-pager -l
+systemctl status awg2-reboot-scheduler.service --no-pager -l
+awg2-harness --config /etc/awg2-harness/config.toml status
+```
+
+Проверка Docker/Amnezia runtime:
+
+```bash
+docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
+C="$(docker ps --format '{{.Names}}' | grep -E '^(amnezia-awg2|amnezia-awg)$' | head -n1)"
+docker port "$C"
+docker exec "$C" wg show
+```
+
+Проверка, что runtime config создан вручную (ожидаемое поведение):
+
+```bash
+test -f /etc/awg2-harness/config.toml && echo "runtime config present"
+```
+
+Если файл отсутствует после `apt install`, это корректно: создайте его вручную из `/usr/share/doc/awg2-harness/repo/config.example.toml`.