> For the complete documentation index, see [llms.txt](https://docs.ipcheck.ing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipcheck.ing/developer/ru/getting-started/deploy-with-nodejs.md).

# Развертывание с Node.js

Запуск из исходного кода — правильный выбор, когда вы хотите настроить сборку — изменить оформление, добавить инструмент или задать любые `VITE_*` переменные, чего предсобранный образ Docker сделать не может.

## Предварительные требования

| Требование     | Примечания                                                                                                                           |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Node.js 24** | Официальный образ Docker основан на `node:24-alpine`. Более старые основные версии не тестировались.                                 |
| **pnpm**       | В репозитории версия pnpm зафиксирована в `package.json` (`packageManager`). Используйте Corepack, чтобы получить именно эту версию. |
| **git**        | Для клонирования и получения обновлений.                                                                                             |

{% tabs %}
{% tab title="Corepack (рекомендуется)" %}
Corepack поставляется вместе с Node.js и автоматически подготавливает зафиксированную версию pnpm:

```bash
corepack enable
```

Никакой глобальной установки, никакого расхождения версий.
{% endtab %}

{% tab title="npm" %}

```bash
npm install -g pnpm
```

Работает везде, но вы сами отвечаете за то, чтобы pnpm оставался близок к зафиксированной версии.
{% endtab %}
{% endtabs %}

## Установка и сборка

{% stepper %}
{% step %}

#### Клонирование

```bash
git clone https://github.com/jason5ng32/MyIP.git
cd MyIP
```

{% endstep %}

{% step %}

#### Настройте окружение

```bash
cp .env.example .env
```

Откройте `.env` и заполните как минимум учетные данные MaxMind:

{% code title=".env" %}

```bash
BACKEND_PORT="11966"
FRONTEND_PORT="18966"
MAXMIND_ACCOUNT_ID="your-account-id"
MAXMIND_LICENSE_KEY="your-license-key"
MAXMIND_AUTO_UPDATE="true"
ALLOWED_DOMAINS="myip.example.com"
```

{% endcode %}

Все остальные переменные необязательны — см. [Переменные окружения](/developer/ru/reference/environment-variables.md).

{% hint style="warning" %}
Задайте свои `VITE_*` переменные **до** когда вы собираете проект. Vite читает их во время сборки и встраивает в бандл; чтобы изменить их позже, потребуется еще один `pnpm run build`.
{% endhint %}
{% endstep %}

{% step %}

#### Установите зависимости

```bash
pnpm install
```

{% endstep %}

{% step %}

#### Соберите фронтенд

```bash
pnpm run build
```

Это создает `dist/`, статический бандл, который обслуживает фронтенд-сервер.
{% endstep %}

{% step %}

#### Запуск

```bash
pnpm start
```

Откройте <http://localhost:18966>.
{% endstep %}
{% endstepper %}

## Два процесса

`pnpm start` запускает обе части приложения в одном терминале (через `concurrently`):

| Процесс  | Скрипт               | Порт по умолчанию         | Роль                                                                                                                     |
| -------- | -------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Frontend | `frontend-server.js` | `18966` (`FRONTEND_PORT`) | Обслуживает `dist/` с настроенными заголовками кэша, обрабатывает fallback для истории SPA и проксирует `/api` к бэкенду |
| Бэкенд   | `backend-server.js`  | `11966` (`BACKEND_PORT`)  | API на Express, а также обновляторы наборов данных MaxMind и CAIDA                                                       |

Пользователи обращаются только к порту фронтенда. Бэкенд не нужно делать доступным извне хоста — фронтенд проксирует `/api` к `http://localhost:<BACKEND_PORT>` запросы к нему.

Их также можно запускать по отдельности:

```bash
pnpm run start-frontend
pnpm run start-backend
```

{% hint style="info" %}
`start-backend` запускает Node с `--import ./sentry-instrument.js`. Этот флаг должен быть указан до загрузки Express, чтобы подключилась ESM-инструментация Sentry. Без `SENTRY_DSN_BACKEND` него это ничего не делает, поэтому его безопасно оставлять в каждом развертывании.
{% endhint %}

## Запуск под pm2

`pnpm start` завершается вместе с вашей оболочкой. Для реального развертывания используйте конфиг pm2, который идет вместе с репозиторием — в нем уже указаны правильные флаги Node.

{% stepper %}
{% step %}

#### Установите pm2

```bash
npm install -g pm2
```

{% endstep %}

{% step %}

#### Запустите оба приложения

```bash
pm2 start ecosystem.config.cjs
```

Это регистрирует два процесса: `myip-backend` и `myip-frontend`.
{% endstep %}

{% step %}

#### Пережить перезагрузки

```bash
pm2 save
pm2 startup
```

Затем выполните команду, которую выведет pm2.
{% endstep %}
{% endstepper %}

Полезные команды:

```bash
pm2 status
pm2 logs myip-backend
pm2 restart ecosystem.config.cjs
pm2 stop myip-frontend
```

{% hint style="info" %}
Обновлятор MaxMind берет файловую блокировку перед загрузкой, поэтому запуск бэкенда в нескольких экземплярах pm2 не приведет к двум одновременным загрузкам или наполовину записанной базе данных.
{% endhint %}

## Обновление

```bash
git pull
pnpm install
pnpm run build
pm2 restart ecosystem.config.cjs
```

Не пропускайте `pnpm run build` — запущенное приложение обслуживает то, что находится в `dist/`, а не ваш обновленный исходный код.

## Где хранятся данные

Наборы данных загружаются в рабочее дерево и исключены из git:

* `common/maxmind-db/` — `GeoLite2-City.mmdb`, `GeoLite2-ASN.mmdb`, а также состояние обновлятора и файлы блокировки
* `common/as-org-db/`, `common/as-rel-db/` — наборы данных CAIDA, используемые для названий организаций ASN и графа связности ASN

Они переживают `git pull`, поэтому при обновлении ничего не скачивается заново.

## Следующие шаги

* [Настройка MaxMind](/developer/ru/getting-started/maxmind-setup.md) — включая ручной `.mmdb` вариант, который работает только на этом пути развертывания
* [Обратный прокси и домены](/developer/ru/getting-started/reverse-proxy-and-domains.md) — TLS и `ALLOWED_DOMAINS`
* [Среда разработки](/developer/ru/development/dev-environment.md) — `pnpm dev` с горячей перезагрузкой, если вы планируете вносить изменения в код
* [Переменные окружения](/developer/ru/reference/environment-variables.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ipcheck.ing/developer/ru/getting-started/deploy-with-nodejs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.