Перейти к содержанию

Developer Guide

Руководство для backend и frontend разработчиков ShivaVPN.

Получить доступы

Ресурс URL Как получить
GitLab https://git.karmann.tech Написать zardes — email для приглашения
Vaultwarden https://vault.shivavpn.io Зарегистрироваться → попросить zardes подтвердить
SSH к серверам — Передать публичный ключ zardes

После регистрации в Vaultwarden будет доступ к: - Databases (MySQL DEV/PROD) - Keycloak & Auth (client secrets, admin) - GitLab & CI/CD (project tokens)

Репозитории

# Backend (Java Spring Boot) — project #33
git clone git@git.karmann.tech:vpn/back.git backend-app

# VPN Config Service (Python FastAPI) — project #55
git clone git@git.karmann.tech:vpn/vpn-config-service.git

# Admin Frontend (Next.js) — project #39
git clone git@git.karmann.tech:vpn/group-frontend/admin-front.git

# Frontend основной сайт (React) — project ID уточнить
git clone git@git.karmann.tech:vpn/group-frontend/frontend.git

# Личный кабинет (Vue) — отдельный git
git clone git@git.karmann.tech:vpn/group-frontend/lk_front.git

Frontend репозитории — отдельные git

frontend/, lk_front/, payment-widget/ — не подмодули, у каждого свой .git, свой CI/CD, свой GitLab-проект. Личный кабинет: shiva-app.io/account → контейнер vpn-lk на 10.99.87.63.

Backend (Java Spring Boot)

Стек

  • Java 21, Spring Boot 3
  • MySQL 8.0 (PROD)
  • Redis — auth сессии
  • Keycloak — SSO (OAuth2 device auth)
  • CI/CD: GitLab → автоматический blue-green deploy при push в main

Сборка и запуск локально

cd backend-app/

# Собрать
./mvnw clean package -DskipTests

# Запустить с локальным профилем
./mvnw spring-boot:run -Dspring-boot.run.profiles=local

Для локального запуска нужен SSH tunnel к MySQL DEV:

ssh -L 3307:10.99.87.61:3306 -N root@212.70.189.60 -p 2255 -i ~/.ssh/id_ed25519_shivavpn &

В application-local.yml указать localhost:3307 как datasource.

Деплой

Push в main → GitLab CI автоматически: 1. Собирает Docker образ 2. Деплоит на неактивный слот (blue или green) 3. Переключает nginx upstream

# Проверить состояние деплоя
./scripts/ssh-internal.sh 10.99.87.249 "cat /opt/deploy/.deploy-state"

# Откат при проблемах
./scripts/ssh-internal.sh 10.99.87.249 "/opt/deploy/deploy-backend.sh --rollback"

Детали: Backend Deploy.

Ключевые компоненты

Класс Назначение
CountryServiceImpl.java Агрегация конфигов, хардкод табов (For Russia, Whitelist, Turbo)
ServerServiceImpl.java Создание/обновление VPN-клиентов
AuthServiceImpl.java Логин, JWT, async client creation
ConfigConverter.java Конвертация в VLESS URL
NodeSyncWorker.java 500ms poll очереди sync-задач
VpnSubscriptionController.java Публичные subscription endpoints

Подробнее: Архитектура бэкенда.

API

Эндпоинт Метод Auth Описание
/api/v2/countries GET Bearer JWT Список стран для iOS
/api/servers/{country}/config/xray GET Bearer JWT Конфиг для Desktop
/api/v2/subscription/vless/{account} GET нет Subscription URL
/api/admin/maintenance/accounts/{id}/add-days POST Bearer JWT Продление подписки
/actuator/health GET нет Health check

Базовый URL PROD: https://api.shivavpn.io

Аутентификация

Два метода одновременно (bridge mode): - Internal JWT: JwtUtils.java + Redis - Keycloak: OAuth2 device auth, realm shiva-users / shiva-devices

AuthTokenFilter.java определяет тип токена по заголовку и маршрутизирует.

VPN Config Service (Python FastAPI)

Стек

  • Python 3.11+, FastAPI, asyncio
  • PostgreSQL 16 (отдельный контейнер на порту 5434)
  • Redis (внутренний кэш)
  • SSH к VPN серверам через asyncssh
  • CI/CD: GitLab project #55, ручной deploy_prod

Локальный запуск

cd vpn-config-service/

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
# Заполнить значения (MySQL PROD данные, API ключи — из Vaultwarden)

# Запустить только API (без worker)
uvicorn app.main:app --reload --port 8000

# Или полный запуск
python worker.py

Деплой

# 1. Push в main
git push origin main

# 2. Дождаться CI: test → build
# 3. Вручную в GitLab UI: Pipelines → найти deploy_prod → Play

Никогда не деплоить через scp или volume mounts

Только через CI/CD pipeline. Иначе docker compose up возьмёт устаревший latest образ.

Подробнее: VPN Config Service.

Базы данных

MySQL PROD (основная БД)

  • Сервер: 10.99.87.62, контейнер vpn-db
  • База: vpn
  • Пользователь: vpn / пароль: Vaultwarden → Databases → MySQL PROD
# Подключение через tunnel для DBeaver
ssh -L 3308:10.99.87.62:3306 -N root@212.70.189.60 -p 2255 -i ~/.ssh/id_ed25519_shivavpn &

Ключевые таблицы MySQL

Таблица Содержимое
account Пользователи (16-значный номер, статус, дата истечения)
server VPN серверы (IP, страна, статус, transport_params)
vpn_user_server_config Маппинг аккаунт → конфиг на каждом сервере
vpn_user_server_account Статус клиента на каждом сервере
payment Платёжные транзакции
country Страны (код, название)

Маппинг аккаунт → VPN клиент: account.account (16 цифр) = clients[].id в XUI = VLESS user ID. Подробнее: Маппинг аккаунтов.

PostgreSQL VCS

  • Сервер: 10.99.87.249:5434, контейнер vpn-config-postgres
  • База: vpnconfig
  • Хранит: online сессии, трафик, статус серверов (оперативные данные)

Frontend

Основной сайт (React)

  • Repo: git.karmann.tech:vpn/group-frontend/frontend
  • Деплой: контейнер vpn-front на 10.99.87.63:80
  • URL: https://shiva-app.io

Личный кабинет (Vue)

  • Repo: git.karmann.tech:vpn/group-frontend/lk_front
  • Деплой: контейнер vpn-lk на 10.99.87.63:8082
  • URL: https://shiva-app.io/account

Admin Panel (Next.js)

  • Repo: GitLab project #39
  • Деплой: контейнер vpn-admin на 10.99.87.64:80
  • Логин: см. Vaultwarden → Infrastructure → Admin Panel

Keycloak

  • URL: http://10.99.87.249:8180 (только внутренний)
  • Admin: Vaultwarden → Keycloak & Auth
  • Realms: shiva-users (пользователи), shiva-devices (устройства)

Keycloak — legacy компонент

Планируется переход на чистый JWT без Keycloak. Сейчас работают оба метода параллельно.

Переводы (i18n)

Все строки бэкенда: backend-app/src/main/resources/messages.properties

При добавлении нового текста — добавлять в messages.properties и все языковые файлы.

Контакты

  • zardes — DevOps + Backend (техническая часть, инфраструктура)
  • Max — Product Owner (требования, приоритеты)

Вопросы по backend — писать zardes в Telegram.

Ссылки