Техническая инфраструктура
компании.

Документ помогает новому инженеру быстро сориентироваться в инфраструктуре компании и понять, как устроены наши проекты — без необходимости задавать каждый вопрос вживую.

После прочтения вы поймёте

• где живут проекты и сервисы;
• как обычно устроены окружения;
• какие инструменты и доступы используются;
• как запускать и сопровождать типовой проект;
• где искать логи, конфиги и точки диагностики.

Версия

1.0

Владелец

Команда разработки

Актуально на

16 июня 2026

Документ построен по двум уровням: сначала — общая инфраструктурная модель компании, затем — пример её применения на одном реальном проекте.

Принцип размещения

• Production backend проекта обычно живёт на выделенном под него сервере в Beget.
• Frontend того же проекта обычно размещается рядом — как frontend-hosting в Beget.
• Часть проектов и вспомогательных сервисов может быть размещена в FirstVDS.
• Production и staging окружения могут жить как в Beget, так и в FirstVDS.

Внешние платформы

• Lovable — среда для быстрых прототипов; прототипы нередко становятся основой production-приложений.
• Облачный n8n — единый инстанс на всю компанию, на нём работают automation/workflow-проекты.
• Облачные PostgreSQL в Beget — используются несколькими проектами.
• S3-совместимое хранилище в Beget — файлы и артефакты проектов.

Специальной промежуточной инфраструктуры (VPN, bastion, jump host) по умолчанию нет. Доступ к серверу настраивается напрямую по SSH.

Базовая модель доступа к backend-серверу

• Под backend-проект разворачивается отдельный сервер.
• На сервере выполняются базовые настройки безопасности.
• Стандартный SSH-порт закрывается, вместо него — кастомный случайный порт.
• Вход разрешён только по SSH-ключам, парольная авторизация отключена.
• Авторизация под root запрещена; root-доступ отключается для повседневной работы.
• Создаётся привилегированный пользователь с правами sudo.
• Создаётся отдельный непривилегированный пользователь, под которым запускается приложение.

Модель доступа для команды

• Для нового разработчика на сервере создаётся отдельный пользователь.
• Доступ выдаётся через персональный SSH-ключ.
• Совместная работа ведётся через персональные учётные записи, а не через общий аккаунт.

Как это выглядит на практике

• Вам отдельно сообщат, в каком репозитории лежит код проекта.
• В этом же сообщении придут параметры доступа к внутреннему git-серверу и пример команды для clone.
• SSH-ключ к git-серверу выдаётся адресно конкретному сотруднику.

# Подключение к внутреннему git-серверу
ssh -p <ssh_port> -i ~/.ssh/<key_path> <git_user>@<git_host_ip>

# Структура хранилища на сервере
~/git_store                      # корневой каталог git-хранилища
~/git_store/voice_ai.git         # проект

# Клонирование через локальный SSH-alias
git clone <git_user>@<git_alias>:git_store/voice_ai.git

Текущая базовая практика

• Конфигурация хранится в .env-файле проекта.
• .env обычно лежит в корне проекта.
• Единой централизованной системы управления секретами пока нет.
• Настройки привязаны к проекту, а не к корпоративной платформе конфигурации.

Как это происходит на практике

• .env-файл разработчик обычно заполняет сам.
• Если переменные или значения неочевидны — помогают другие разработчики команды.
• Перед запуском уточните, какой .env использовать: local, staging или production.

Текущая практика

• Автоматического CI в компании пока нет.
• Тесты запускаются локально или на тестовом сервере с тестовыми данными.
• После обкатки на тестовом сервере деплой в production выполняется вручную через git.
• Код на сервере обновляется через git pull.
• После обновления приложение перезапускается через docker compose.
• Production deploy выполняет ответственный разработчик.

# На сервере, под непривилегированным пользователем
cd /opt/projects/<project>
git pull
docker compose up -d --build
docker compose ps
docker compose logs -f --tail=200

• Логи по возможности выносятся в отдельные файлы.
• Для логов настраивается ротация.
• При необходимости логи смотрятся через docker compose logs.
• Единого централизованного сервиса мониторинга пока нет.

Откуда начинать диагностику

• Зайти на сервер проекта по SSH.
• Проверить статус контейнеров: docker compose ps.
• Посмотреть последние логи нужного сервиса: docker compose logs --tail=300 <service>.
• Проверить файловые логи в logs/ проекта.
• Если есть healthcheck — дёрнуть его руками.

Backend-стек

• Python как основной язык backend.
• uv — менеджер проекта и зависимостей.
• Makefile — алиасы команд и типовые операции.
• docker compose — запуск приложения.

Типовая структура на верхнем уровне

project/
├── <package>/              # основная кодовая база
├── docs/                   # проектная документация
├── logs/                   # логи приложения
├── ansible/                # инфраструктурные плейбуки (опционально)
├── nginx/                  # конфигурация прокси (опционально)
├── Makefile                # типовые команды
├── docker-compose.yml      # запуск сервисов
├── pyproject.toml          # зависимости (uv)
└── .env                    # конфигурация и секреты (НЕ коммитится)

Конкретные команды смотрите в README, docs и Makefile проекта — этот раздел описывает только общий принцип.

Типовой сценарий

• 01Склонировать проект из внутреннего git-хранилища или корпоративного GitHub.
• 02Создать и заполнить .env (запросить значения у команды, если неочевидно).
• 03Если проект контейнеризирован — поднять: docker compose up -d --build.
• 04Открыть README/Makefile и пройтись по smoke-командам проекта.

Подготовка сервера

• Под каждый проект сервер заранее готовится через Ansible.
• Стандартный SSH-порт меняется на случайный кастомный.
• Отключаются вход под root и парольная авторизация.
• Создаётся один привилегированный пользователь.
• Создаётся как минимум один непривилегированный пользователь для запуска проекта.
• При необходимости создаются дополнительные непривилегированные пользователи для разработчиков.

Размещение проекта на сервере

• Проекты обычно клонируются в /opt/projects.
• Доступ к этой директории настраивается через Ansible.
• Директория подготовлена для совместной работы нескольких непривилегированных пользователей.

ssh -p <port> <user>@<host>
cd /opt/projects/<project>
git pull
docker compose up -d --build
docker compose logs -f --tail=200 <service>

• Приложение действительно поднялось и не падает в перезапуск.
• Логи не содержат явных критических ошибок.
• Основной пользовательский сценарий проходит базовую проверку.
• Если в проекте есть healthcheck — он отвечает корректно.

Принцип простой: рутинные действия в своей зоне ответственности — самостоятельно. Решения, влияющие на production, доступы, общую инфраструктуру или работу других людей — по согласованию с командой.

voice_ai — внутреннее приложение компании для интеграции телефонии с голосовыми AI-агентами.

Прямая рабочая интеграция голосовых агентов ElevenLabs с сервисами уровня Twilio для нас недоступна, поэтому был реализован собственный контур на базе Asterisk. Проект связывает телефонный звонок клиента с голосовым AI-агентом через нашу маршрутизацию и серверную логику.

Серверная схема по зонам

server-r

Сервер в ru-зоне с Asterisk, подключён к SIP trunk Mango Office.

server-l

Сервер в eu-зоне с Asterisk, подключён к ElevenLabs и Retell. Здесь основная логика маршрутизации звонка между клиентом и AI-агентом.

• Зависимости ставятся через uv — в первую очередь для локальной разработки, отдельных сервисов и тестов.
• Основной runtime, особенно на сервере, идёт через docker compose.
• Перед первым контейнерным запуском нужна инициализация через Makefile.
• Часть поведения зависит от .env.
• Для проверки используются health и отдельные smoke-команды.

# Подготовка артефактов
make logs_init       # создать директории для логов
make sounds_init     # создать звуковой файл для Asterisk

# Поднимаем сервисы
docker compose up -d --build
docker compose ps

# Smoke-проверка
make health

• Asterisk работает в host network.
• Admin backend не должен писать в системные Asterisk-конфиги, кроме generated include.
• DID и SIP-маршрутизация чувствительны к корректным env-переменным.
• Есть внешние зависимости: Mango Office, ElevenLabs, Retell — следите за их статусом при разборе инцидентов.