VoIP Auto-Provisioning Server

Универсальный, независимый от конкретной АТС сервер автопровижининга для IP-телефонов: генерирует конфигурационные файлы по MAC-адресу устройства и раздаёт их по HTTP и TFTP, хранит шаблоны и ассеты (прошивки, логотипы, телефонные книги), управляется через веб-интерфейс.

• Бэкенд: Go (Echo, GORM), single-binary — фронтенд встроен через go:embed
• Фронтенд: Angular 22 (standalone, zoneless, signals, Material)
• БД: SQLite (pure-Go, WAL) / MariaDB / PostgreSQL
• Лицензия: MIT

Возможности

• Провижининг по HTTP: GET /provision/{mac} — конфигурация генерируется из шаблона и параметров устройства
• TFTP-сервер (RFC 1350, RRQ) для старых моделей телефонов, те же пути, что и HTTP
• ACL для TFTP: белый/чёрный списки по CIDR
• Иерархия устройств: дерево папок → устройства (MAC, шаблон, параметры)
• Параметры слияния: значения наследуются от корня дерева к устройству (ближе к устройству — выше приоритет); типы string / int64 / float64
• Шаблоны на диске с поддержкой include (абсолютные и относительные пути), защита от path traversal
• Ассеты: централизованное хранение и раздача прошивок, логотипов и т.п. (публично по /assets/{file})
• Журнал провижининга (кто, когда, какой файл, статус)
• JWT-авторизация (access 15 мин + refresh 7 дней), Web UI для управления
• Метрики Prometheus (/metrics)
• Логирование в JSON Lines (stdout или файл)

Быстрый старт

# 1. Сборка (фронтенд будет собран автоматически, если ещё не собран)
./deploy/build.sh

# либо только бэкенд с уже встроенным фронтендом:
go build -o voip-provisioning ./cmd/server

# 2. Каталоги для данных (локальная разработка)
mkdir -p data/templates data/assets

# 3. Запуск
./voip-provisioning --config config.yml

• Web UI: http://localhost:3000
• Учётные данные по умолчанию: admin / admin (создаётся при первом старте, смените через БД)
• TFTP по умолчанию выключен (tftp.enabled: false)

Режим разработки (горячая перезагрузка Angular)

./voip-provisioning --config config.yml     # бэкенд на :3000
cd internal/web && npx ng start             # фронтенд на :4200, прокси /api,/provision,/assets,/metrics → :3000

По умолчанию ng serve слушает только localhost. Чтобы открыть dev-сервер для других машин:

npx ng serve --host 0.0.0.0 --allowed-hosts=all

Удалённый доступ

Продакшен-сервер (single-binary) слушает 0.0.0.0:3000 по умолчанию, и веб-интерфейс в него встроен — достаточно открыть порт в файрволе и открыть http://<ip-сервера>:3000 (для TFTP дополнительно 69/udp). Порт 4200 нужен только при разработке фронтенда.

Рекомендации:

• TLS — через reverse-proxy (nginx/Caddy) перед сервером или VPN
• TFTP ACL (settings/tftp-acl) — белый список CIDR клиентов
• не выставлять /metrics наружу без необходимости

Конфигурация

Источники и приоритет (высокий → низкий): CLI-флаги → переменные окружения → файл конфигурации → значения по умолчанию.

Путь к файлу: --config <путь> (или --config=<путь>, либо переменная окружения CONFIG_FILE). Форматы: YAML / JSON.

Ключ (YAML)	Флаг CLI	Переменная окружения	По умолчанию	Описание
server.host	--host	SERVER_HOST	0.0.0.0	Адрес HTTP-слушателя
server.port	--port	SERVER_PORT	3000	Порт HTTP
server.provision_path	--provision-path	SERVER_PROVISIONPATH	/provision	Базовый путь провижининга
server.assets_path	--assets-path	SERVER_ASSETSPATH	/assets	Базовый путь ассетов
database.driver	--db-driver	DATABASE_DRIVER	sqlite	sqlite / mariadb / postgres
database.path	--db-path	DATABASE_PATH	/var/lib/voip-provisioning/db.sqlite	Путь к файлу БД (sqlite)
database.host	--db-host	DATABASE_HOST	127.0.0.1	Хост (mariadb/postgres)
database.port	--db-port	DATABASE_PORT	0 (3306 / 5432)	Порт (mariadb/postgres), 0 = по умолчанию драйвера
database.user	--db-user	DATABASE_USER	—	Пользователь (mariadb/postgres)
database.password	--db-password	DATABASE_PASSWORD	—	Пароль (mariadb/postgres); рекомендуется передавать переменной окружения
database.name	--db-name	DATABASE_NAME	voip_provisioning	Имя БД (mariadb/postgres)
templates.root	--templates-root	TEMPLATES_ROOT	/var/lib/voip-provisioning/templates	Корневой каталог шаблонов (должен существовать)
assets.root	--assets-root	ASSETS_ROOT	/var/lib/voip-provisioning/assets	Каталог ассетов
tftp.enabled	--tftp-enabled	TFTP_ENABLED	false	Включить TFTP-сервер
tftp.host	--tftp-host	TFTP_HOST	0.0.0.0	Адрес TFTP-слушателя
tftp.port	--tftp-port	TFTP_PORT	69	Порт TFTP (UDP)
jwt.secret	--jwt-secret	JWT_SECRET	— (обязательно)	Секрет подписи JWT (HS256)
jwt.access_ttl	--jwt-access-ttl	JWT_ACCESSTTL	15m	Время жизни access-токена
jwt.refresh_ttl	--jwt-refresh-ttl	JWT_REFRESHTTL	168h	Время жизни refresh-токена
logging.file	--log-file	LOGGING_FILE	"" (stdout)	Файл JSON-логов
logging.level	--log-level	LOGGING_LEVEL	info	debug / info / warn / error
metrics.enabled	--metrics-enabled	METRICS_ENABLED	true	Включить Prometheus-метрики
metrics.path	--metrics-path	METRICS_PATH	/metrics	Путь метрик

Образец для старта — config.yml.example (скопировать в config.yml, он в .gitignore); «боевой» шаблон для пакетов — config/default.yaml.

Провижининг

Телефон запрашивает GET /provision/{mac} (или тот же путь по TFTP RRQ). Сервер:

1. Находит устройство по MAC (регистронезависимо) в дереве устройств.
2. Подбирает имя файла по настраиваемым шаблонам (по умолчанию: {mac}.cfg, {mac}.xml, {mac}.txt, SEP{mac}.cnf.xml; список редактируется в Web UI / API).
3. Рендерит шаблон устройства со слитыми параметрами и отдаёт результат (HTTP 200) или 404.

Каждый запрос фиксируется в журнале провижининга (MAC, файл, статус, IP).

Web UI

• Dashboard — список/поиск устройств
• Devices — дерево папок и устройств, параметры
• Templates — редактор шаблонов с превью
• Assets — загрузка/удаление ассетов
• Logs — журнал провижининга
• Settings — паттерны имён файлов, TFTP ACL

API

Полное описание — docs/api.md. Кратко:

Метод и путь	Доступ	Назначение
POST /api/auth/login	публичный	Логин, выдача access + refresh токенов
POST /api/auth/refresh	публичный	Обновление access-токена
POST /api/auth/logout	JWT	Оточка refresh-токена
GET /api/auth/me	JWT	Текущий пользователь
GET /api/devices/tree	JWT	Дерево папок
GET/POST /api/devices/nodes, GET/PUT/DELETE /api/devices/nodes/:id	JWT	CRUD устройств
POST/PUT/DELETE /api/devices/folders[...]	JWT	CRUD папок
GET /api/devices/:mac/preview	JWT	Превью конфигурации устройства
POST /api/devices/import	JWT	Импорт устройств
GET /api/templates/tree, GET/PUT/DELETE /api/templates/*, POST /api/templates	JWT	Шаблоны
POST /api/templates/preview/*	JWT	Превью шаблона с параметрами
GET/POST /api/assets, DELETE /api/assets/:id	JWT	Ассеты
GET/DELETE /api/logs	JWT	Журнал провижининга
GET/PUT /api/settings[.../filename-patterns, /tftp-acl]	JWT	Настройки
GET /provision/{mac}	публичный	Конфигурация для телефона
GET /assets/{filename}	публичный	Файл ассета
GET /metrics	публичный	Метрики Prometheus

База данных

• SQLite (по умолчанию): pure-Go драйвер (без CGO), WAL-режим, busy_timeout, пул соединений (25 open / 10 idle, lifetime 1 ч)
• MariaDB / PostgreSQL: DSN собирается из отдельных параметров (host, port, user, password, name), пароль — через DATABASE_PASSWORD
• Миграции — автоматически при старте (AutoMigrate), сидирование пользователя admin

Тесты и качество кода

# Go: юнит- и интеграционные тесты (SQLite in-memory)
go test ./... -count=1

# golangci-lint (v2)
golangci-lint run ./...

# Angular: vitest (юнит + интеграция)
cd internal/web && npx ng test --watch=false

Деплой

Способ	Где
Docker / docker-compose	deploy/docker/
systemd-юнит	deploy/systemd/voip-provisioning.service
RPM / DEB	deploy/rpm/build.sh, deploy/deb/build.sh
Кросс-сборка (linux/darwin, amd64/arm)	./deploy/build.sh [version]

Структура проекта

cmd/server/            точка входа
config.yml.example     образец конфигурации (скопировать в config.yml)
config/default.yaml    конфигурация по умолчанию (для пакетов)
internal/
  auth/                JWT: токены, store, middleware
  config/              конфигурация (go-simple-args: CLI/env/YAML)
  database/            подключение, пулы, WAL, миграции, сиды
  http/                Echo-сервер, маршруты, SPA-fallback
    handler/           REST-обработчики (devices, templates, assets, ...)
    middleware/        JWT-аутентификация
  frontend/            go:embed собранного Angular
  logger/              JSON Lines логгер
  model/               GORM-модели
  provision/           логика генерации конфигурации
  repo/                репозитории (транзакции)
  template/            шаблонный движок с include
  tftp/                TFTP-сервер (RFC 1350 RRQ) + ACL
  web/                 Angular 22 (источник фронтенда)
deploy/                Docker, systemd, RPM/DEB, build.sh
docs/                  ТЗ, архитектура, API, ROADMAP

Документация

• docs/overview.md — продукт и требования
• docs/architecture.md — архитектура
• docs/api.md — API
• docs/ROADMAP.md — план развития

Лицензия

MIT