maeneko
602c0416ba
The product name, the channel word "Alpha" and the version were scattered across install.sh, the CLI banner, two spots in App.tsx and three package.json files, so a rename or a bump meant editing strings in code. They now live in one committed .env at the project root (BRAND, CHANNEL, VERSION), shipped inside the release archive and read at runtime: the CLI loads it after cli.env — so real env and machine settings still win — and injects the three values into awg-ui, which serves them from GET /ui/brand for the wordmark. awg-ui also parses the same file directly, so `npm run server` in dev shows what production shows. install.sh keeps its own VERSION and CHANNEL and says why: it prints the banner and builds the release URL before the archive holding .env has been downloaded. It writes BRAND into cli.env only when the operator passed one explicitly, so the file stays the single source otherwise. Version bumped to Beta 0.2.0 across .env, install.sh and the three package.json files.
127 lines
7.5 KiB
Markdown
127 lines
7.5 KiB
Markdown
# Forgetting
|
||
Панель управления и API для VPN на базе [AmneziaWG](https://github.com/amnezia-vpn/amneziawg-linux-kernel-module)
|
||
> [!WARNING]
|
||
> Данный проект предназначен только для использования в законных целях.
|
||
## Архитектура
|
||
|
||
Три компонента, устанавливаются в `/opt/awg-control/`:
|
||
|
||
| Компонент | Роль |
|
||
|---|---|
|
||
| **awg-ctrl** | Привилегированный REST-бэкенд. Управляет пирами через `awg`/`awg-quick`, ведёт SQLite-базу, генерирует `vpn://` ключи. Слушает только loopback. |
|
||
| **awg-ui** | Express + React. Веб-панель, аутентификация (JWT), интеграция с API MA7, прокси к awg-ctrl. Единственный сервис, доступный по сети. |
|
||
| **cli** | Менеджер процессов: `start`/`stop`/`restart`/`status`, смена логина/пароля панели, интерактивное TUI-меню. |
|
||
|
||
Внутренняя связь awg-ui → awg-ctrl подписывается асимметрично (Ed25519): приватный ключ только у awg-ui, awg-ctrl проверяет подпись публичным.
|
||
|
||
## Требования
|
||
- **ОС**: Ubuntu 24.04+ (Тесты проходили на Ubuntu 24.04.4 LTS)
|
||
- **Права**: root.
|
||
- **Ядро**: kvm (не OpenVZ/LXC/Docker/WSL — нужен загружаемый kernel-модуль AmneziaWG).
|
||
- **Заголовки ядра** под текущее ядро (для сборки DKMS-модуля).
|
||
- **Node.js 20.x** (ставится установщиком автоматически).
|
||
|
||
Совместимость установщик проверяет сам перед любыми изменениями.
|
||
|
||
## Установка
|
||
|
||
На сервере, от root:
|
||
|
||
```bash
|
||
bash <(curl -Ls https://git.ma7neko.ru/maeneko/forgetting/raw/branch/main/install.sh)
|
||
```
|
||
|
||
Установщик по умолчанию ставит сервер на AmneziaWG 3.1. Если модуль в ядре
|
||
старше 3.x или ядро старше 5.5, установка остановится с диагностикой — поставить
|
||
на 2.0 можно так:
|
||
|
||
```bash
|
||
AWG_GEN=auto bash <(curl -Ls https://git.ma7neko.ru/maeneko/forgetting/raw/branch/main/install.sh)
|
||
```
|
||
|
||
Перевести такой сервер на 3.1 позже можно кнопкой «Перейти на AWG 3.1» в панели —
|
||
переустановка не нужна, пользователи сохраняются, ключи перевыпускаются
|
||
автоматически.
|
||
|
||
### Свой источник и своё имя
|
||
|
||
В коде не зашиты ни репозиторий, ни бренд — всё задаётся окружением до запуска:
|
||
|
||
| Переменная | По умолчанию | Зачем |
|
||
|---|---|---|
|
||
| `REPO_BASE` | `https://git.ma7neko.ru/maeneko/forgetting` | основной источник архива релиза |
|
||
| `REPO_FALLBACK` | `https://github.com/maeneko/forgetting` | запасной, если в основном релиза ещё нет |
|
||
| `ARCHIVE_URL` | — | полный URL архива, перекрывает оба варианта |
|
||
| `BRAND` | из `.env` | имя продукта в баннерах, systemd-юните и панели |
|
||
|
||
Путь релиза у Gitea и GitHub одинаковый (`<repo>/releases/download/v<версия>/awgcontrol-<версия>.tar.gz`),
|
||
так что подходит любой из них. Если архив не найден в основном источнике,
|
||
установщик предупреждает и берёт его из запасного.
|
||
|
||
```bash
|
||
REPO_BASE=https://git.example.org/me/vpn BRAND="My VPN" \
|
||
bash <(curl -Ls https://git.example.org/me/vpn/raw/branch/main/install.sh)
|
||
```
|
||
|
||
Имя панели, канал и версия лежат в `.env` в корне проекта (едет в архиве
|
||
релиза, на сервере — `/opt/awg-control/.env`):
|
||
|
||
```env
|
||
BRAND=Forgetting
|
||
CHANNEL=Beta
|
||
VERSION=0.2.0
|
||
```
|
||
|
||
Оттуда их читают CLI (баннер меню) и панель (вордмарк, `GET /ui/brand`).
|
||
`BRAND=` при установке перекрывает значение из файла.
|
||
|
||
Сама панель и её API к домену не привязаны: работают по адресу того сервера,
|
||
куда установлены, внешних сервисов не требуют.
|
||
## Управление
|
||
|
||
```bash
|
||
awg-ctrl
|
||
```
|
||
|
||
Через systemd (автозапуск на загрузке):
|
||
|
||
```bash
|
||
systemctl start|stop|restart awg-control
|
||
```
|
||
|
||
## Интеграция с MA7
|
||
|
||
Этот сервер персональный — принадлежит одному абоненту MA7 (сервиса
|
||
VPN-подписки). Панель ничем не управляет в MA7 и не отдаёт наружу свой API:
|
||
вкладка «Профиль» только читает баланс своего владельца. Секрет MA7 живёт
|
||
только в `awg-ui` (`cli.env`) и в браузер не попадает — фронт ходит на свой
|
||
бэкенд, тот читает MA7.
|
||
|
||
Нужные переменные (задаются при установке или руками в `cli.env`):
|
||
|
||
| Переменная | Назначение |
|
||
|---|---|
|
||
| `MA7_API_BASE_URL` | адрес API MA7, например `https://amnesia.ma7neko.ru` |
|
||
| `MA7_JWT_SECRET` | секрет, которым панель сама подписывает `X-Bot-Token` (эндпоинта, выдающего токен, в MA7 нет) |
|
||
| `MA7_LOGIN` | логин владельца этого сервера в MA7 (`ma7_xxxxxx`) |
|
||
|
||
Вкладка «Профиль» просто показывает текущий баланс `MA7_LOGIN`. При установке
|
||
`MA7_LOGIN` заодно предлагается как логин панели (`UI_USER`) — сервер
|
||
персональный, и заказчик входит тем же именем, что знает по MA7; при желании
|
||
логин панели можно задать свой. Это разные переменные: `UI_USER` решает, кого
|
||
пускать в панель, `MA7_LOGIN` — чей баланс показывать.
|
||
|
||
`MA7_LOGIN` задаётся один раз при установке и **не редактируется из панели**: у панели
|
||
один общий пароль (`UI_USER`/`UI_PASS`) без отдельного клиентского входа, а
|
||
`MA7_JWT_SECRET` умеет искать в MA7 любого абонента — редактируемый в браузере
|
||
логин превратил бы личный баланс в инструмент подглядывания за чужими.
|
||
|
||
> [!WARNING]
|
||
> `MA7_JWT_SECRET` — мастер-ключ ко всему MA7: с ним можно читать данные любых
|
||
> пользователей MA7, не только этого сервера. Токены MA7 без срока действия,
|
||
> отзыва нет — «отобрать доступ» значит одновременно сменить `MA7_JWT_SECRET`
|
||
> во всех сервисах MA7 и здесь, в `cli.env`.
|
||
|
||
## Лицензия
|
||
[MIT](LICENSE) © 2026 Ivan Vasilev
|