Webvane — одно приложение (Java) и база PostgreSQL. Сайт компании, панель, приём событий и записи сессий — в одном процессе.
Требования
- Linux-сервер с Docker и Docker Compose (или Java 17 и PostgreSQL 13+ без Docker);
- 2 ядра и 4 ГБ памяти — до миллиона визитов в месяц; записи сессий занимают диск — режим и срок хранения настраиваются (Записи сессий);
- домен для панели и HTTPS (nginx или другой прокси перед приложением).
Запуск
В папке code/backend (там docker-compose.yml: приложение собирается из исходников, база — PostgreSQL 16):
docker compose up -d --build
Сайт компании — /, панель — /panel, документация — /docs, приём событий — /collect, счётчик — /t.js.
Первый администратор создаётся при первом старте, если администраторов ещё нет: WEBVANE_ADMIN_EMAIL и
WEBVANE_ADMIN_PASSWORD (по умолчанию admin@webvane.local / webvane). Потом смена переменной пароль не меняет.
Вход — /panel/auth/login, «Вход в панель»: «Логин», «Пароль» → «Войти»; после входа открывается экран Сайты.
Ошибки входа:
| Что видите | Что делать |
|---|---|
| «Введите логин и пароль.» | заполните оба поля |
| «Неверный логин или пароль.» | проверьте раскладку и пароль из WEBVANE_ADMIN_PASSWORD |
| «Слишком много попыток, подождите несколько минут.» | после 5 неверных попыток за 15 минут вход закрыт на 15 минут |
| «Пользователь заблокирован.» | учётка заблокирована — обратитесь к владельцу сервера |
«Выйти» — справа в шапке панели, рядом с почтой.
Настройки
| Переменная | Что |
|---|---|
WEBVANE_PORT | порт приложения, по умолчанию 8080 |
WEBVANE_DB_HOST, WEBVANE_DB_NAME, WEBVANE_DB_USER, WEBVANE_DB_PASSWORD | база PostgreSQL (без Docker по умолчанию localhost:5432, webvane, postgres / admin) |
WEBVANE_PUBLIC_URL | внешний адрес сервера (https://stat.компания.ru) — для кода установки и ссылок; не задан — адрес, на котором открыта панель |
WEBVANE_TRUST_PROXY | true за nginx: адрес посетителя из X-Forwarded-For |
WEBVANE_TELEGRAM_TOKEN | бот для оповещений (Настройки сайта → оповещения) |
WEBVANE_MASTER_KEY | ключ шифрования токенов кабинетов и ключей сервисов в базе — 32 байта в base64 (openssl rand -base64 32); не задан — хранятся открыто. Смена ключа: v1:<старый>,v2:<новый> — при перезапуске значения перейдут на новый. Потеряли ключ — токены вводят заново (Подключения) |
WEBVANE_YANDEX_CLIENT_ID, WEBVANE_YANDEX_CLIENT_SECRET | вход через Яндекс: Директ и Метрика (Подключения) |
WEBVANE_GOOGLE_CLIENT_ID, WEBVANE_GOOGLE_CLIENT_SECRET, WEBVANE_GOOGLE_DEVELOPER_TOKEN | вход через Google: Google Ads |
WEBVANE_AI_URL, WEBVANE_AI_KEY, WEBVANE_AI_MODEL, WEBVANE_AI_IMAGE_MODEL | модель сервера для мастера подключений и генератора креативов; для креативов удобнее подключить Claude ключом в панели (Креативы → подключить модель) |
Прокси и HTTPS
Перед приложением ставят nginx с сертификатом и пробрасывают весь трафик на порт приложения (8080) вместе с
заголовками Host и X-Forwarded-For. Включите WEBVANE_TRUST_PROXY=true (иначе адресом всех посетителей будет
адрес nginx) и задайте WEBVANE_PUBLIC_URL — иначе код установки возьмёт адрес, на котором открыта панель, и при
входе в панель по localhost в коде окажется внутренний адрес.
Хранилище файлов
Все файлы Webvane — картинки креативов (/mk-creatives), записи сессий (идущие визиты — /recordings-buffer,
оставленные — /recordings) и база IP (/geoip/geoip.mmdb) — пишутся и читаются только через хранилище файлов;
своих папок, путей и переменных окружения для них у Webvane нет. Его папка задана в базе: таблица
cmn_serviceproperty, свойство rootPath сервиса IOFileStore. У Webvane это /opt/wv/filemanager (ставится при установке и при обновлении
с версии, где был путь по умолчанию модуля файлов или путь …/data/files, который записывали версии до 0.2, например
/app/data/files в Docker); путь, заданный вручную в другое место, не меняется. Если в старой папке уже есть файлы —
перенесите её содержимое в /opt/wv/filemanager (в Docker — в том ./data/files), иначе старые картинки и записи
не откроются. Текущий путь виден в «Настройках записи» → «Место на диске». В Docker папка — том ./data/files
(см. docker-compose.yml).
Своя папка — SQL и перезапуск Webvane:
update cmn_serviceproperty set val = '/srv/webvane/files'
where class_name = 'IOFileStore' and name = 'rootPath';
Папка должна существовать или создаваться, и у пользователя, от которого запущен Webvane, должно быть право записи в неё
(sudo mkdir -p /opt/wv/filemanager && sudo chown <пользователь> /opt/wv/filemanager). Если базу перенесли с другой
машины, проверьте путь: C:/… от Windows на Linux не работает — файлы не сохранятся.
Страна и город
Страну и город визита Webvane определяет по IP сам, на вашем сервере: нужна локальная база в формате MaxMind DB
(.mmdb). Подойдёт бесплатная DB-IP Lite City (db-ip.com, лицензия CC BY 4.0, без регистрации) или
GeoLite2-City (MaxMind, бесплатно после регистрации). Скачайте файл и положите его в хранилище файлов как
/geoip/geoip.mmdb — в папку geoip корня хранилища (/opt/wv/filemanager/geoip/geoip.mmdb, в Docker —
./data/files/geoip/geoip.mmdb), затем перезапустите приложение — при первом визите в логе будет строка
geoip: /geoip/geoip.mmdb (DBIP-City-Lite). Базу стоит обновлять раз в месяц.
IP посетителя в базу аналитики не пишется: по нему находится страна и город, дальше хранится только хэш с солью дня. Без файла поля «Страна» и «Город» пустые, в «Аудитории» — «Не определено».
Обновление
Новая версия — новые исходники и пересборка: docker compose up -d --build. Новые таблицы и колонки приложение
добавляет само при старте. Данные не теряются.
Резервные копии
База — обычным pg_dump (в Docker: docker compose exec db pg_dump -U webvane webvane > webvane.sql); файлы
(картинки, записи сессий, база IP) — папка хранилища файлов (в Docker — том ./data/files; файлы самой базы лежат в ./data/postgres).
Восстановление — psql или pg_restore и копия папки на новом сервере.