Запуск через Compose
Из корня репозитория, с работающим Docker Engine:
cp .env.example .env
docker compose config --quiet
docker compose build
# Необязательно: подготовить город из локальной OSM-выгрузки.
docker compose run --rm --no-deps app node --import tsx tools/demo.ts
docker compose up -d --wait
Открыть http://localhost:3000/?play. Можно создать город через интерфейс.
Города и сохранения находятся в отдельных постоянных томах cities и saves.
Пересборка и docker compose down сохраняют тома. down -v удаляет их.
Существующий каталог города нельзя перезаписывать, пока на него ссылаются комнаты.
Приложение работает от пользователя node, с лимитами памяти, CPU,
процессов и ротацией логов. Значения .env.example рассчитаны на старт с
1000 жителями; миллион жителей и пять комнат требуют замера и настройки.
Порт по умолчанию доступен локально. Для внешнего доступа измените
CITYGEN_HOST_IP или используйте HTTPS reverse proxy с WebSocket.
Встроенный лимит создания видит IP TCP-соединения, поэтому за прокси он
общий для всех посетителей; недоверенные X-Forwarded-For не используются.
Остановка посылает SIGTERM; сервер завершает комнаты и ждёт запись снимков (до 120 секунд). Перед обновлением:
docker compose stop
# Сделать резервную копию ОБОИХ томов средствами Docker-хоста.
docker compose build
docker compose up -d --wait
Проверка: docker compose ps, docker compose logs --tail=100 app,
curl --fail http://localhost:3000/health. Миграция комнат v1→v2 выполняется
при открытии комнаты; неизвестная версия остаётся на диске с ошибкой.
Квота CITYGEN_SAVE_QUOTA_BYTES включает все снимки и временный новый файл
до ротации: оставьте запас минимум на один полный снимок. При переполнении
запись отклоняется, прежние снимки сохраняются. Квота относится к снимкам;
объём городов ограничивайте средствами Docker-хоста.
Администрирование
Задать CITYGEN_ADMIN_TOKEN случайной строкой минимум из 32 символов в .env
и пересоздать контейнер. Пустое значение отключает API. .env игнорируется Git
и не попадает в build context. /?admin показывает комнаты, использование
диска и ошибки несовместимых снимков, позволяет сохранить активную комнату.
Ответ приходит после записи. Токен остаётся только в памяти страницы.
API: GET /api/admin, POST /api/admin/rooms/{id}/checkpoint,
заголовок Authorization: Bearer <token>. Привилегии оператора не выдаются
игрокам и создателям комнат. Удаление миров/городов через API не предусмотрено.
Мониторинг
docker compose --profile monitoring up -d --wait
Prometheus на http://localhost:9090 опрашивает /metrics каждые 5 секунд,
хранит до 7 дней / 1 ГБ. alerts.yml содержит правила недоступности,
тиков дольше 50 мс и ошибок сохранения. Предупреждения видны в Prometheus;
внешние уведомления требуют отдельного Alertmanager. Зафиксирована
версия 3.15.1.
Метрики: комнаты/игроки, сущности, последний/максимальный тик, байты рассылки, ошибки и последний успешный тик сохранения. Ошибки снимков, медленные тики, запуск/остановка пишутся JSON-строками в stderr.
Без Engine можно проверить docker compose --profile monitoring config --quiet.
Полный smoke-test контейнера после запуска: /health, вход двух клиентов,
команда «Обед», остановка/запуск и проверка восстановленного состояния.