EverShop — Production Deployment из исходного кода

Инструкция по развёртыванию EverShop из Git-репозитория на:

Репозиторий:

https://github.com/evershopcommerce/evershop


1. Архитектура

Используем следующую схему:

                    Internet
                       │
                       │ HTTPS :443
                       ▼
                ┌──────────────┐
                │    Nginx     │
                │   aaPanel    │
                └──────┬───────┘
                       │
                       │ 127.0.0.1:3000
                       ▼
                ┌──────────────┐
                │   EverShop   │
                │   Node.js    │
                │   systemd   │
                └──────┬───────┘
                       │
                       │ localhost:5432
                       ▼
                ┌──────────────┐
                │ PostgreSQL   │
                │   aaPanel    │
                └──────────────┘

PostgreSQL наружу не открываем.

Порт 3000 наружу также не открываем.

Nginx принимает HTTP/HTTPS и проксирует запросы на EverShop.


2. Требования

EverShop требует:

Для Debian 13 рекомендуется использовать Node.js 22 LTS.

Официальная документация подтверждает поддержку Node.js 20 и 22. PostgreSQL должен быть версии 13+.


3. Проверяем сервер

Выполнить:

cat /etc/os-release

Проверить Node.js:

node --version
npm --version

Проверить PostgreSQL:

psql --version

Проверить Git:

git --version

Проверить Nginx:

nginx -v

Если Node.js отсутствует — установить Node.js 22.


4. Установка Node.js 22

curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt install -y nodejs

Проверка:

node -v
npm -v

Ожидается примерно:

v22.x.x
10.x.x

5. Создаём системного пользователя

Не запускаем EverShop от root.

useradd --system \
  --create-home \
  --home-dir /opt/evershop \
  --shell /bin/bash \
  evershop

Проверка:

id evershop

6. Создаём директорию проекта

mkdir -p /opt/evershop
chown -R evershop:evershop /opt/evershop

7. Клонируем исходный код

Переходим под пользователя EverShop:

su - evershop

Переходим в директорию:

cd /opt/evershop

Клонируем репозиторий:

git clone https://github.com/evershopcommerce/evershop.git .

Проверяем:

git status

Проверяем ветку:

git branch

В текущем репозитории основная рабочая ветка, отображаемая GitHub, — dev.

Если нужно работать именно с ней:

git checkout dev

Проверить:

git branch --show-current

Должно быть:

dev

8. ВАЖНО: работаем именно с исходниками

Это не установка:

npm install @evershop/evershop

Так устанавливается опубликованный пакет ядра.

В нашем случае используется сам репозиторий:

/opt/evershop/
├── packages/
│   └── evershop/
│       └── src/
├── extensions/
├── themes/
├── translations/
├── scripts/
├── tests/
├── package.json
├── package-lock.json
└── ...

Исходный код ядра находится в:

packages/evershop/src/

Это соответствует структуре текущего репозитория.


9. Установка зависимостей

В корне проекта:

cd /opt/evershop

Установка:

npm ci

Если npm ci выдаёт ошибку из-за несовместимости lock-файла, использовать:

npm install

Но для production предпочтительнее:

npm ci

поскольку он устанавливает зависимости согласно package-lock.json.


10. PostgreSQL

PostgreSQL уже установлен через aaPanel.

Нужно создать отдельную БД и отдельного пользователя EverShop.

Сначала подключиться:

sudo -u postgres psql

Создать пользователя:

CREATE USER evershop WITH PASSWORD 'CHANGE_THIS_TO_STRONG_PASSWORD';

Создать базу:

CREATE DATABASE evershop OWNER evershop;

Выйти:

\q

11. Проверяем подключение к PostgreSQL

psql \
  -h 127.0.0.1 \
  -U evershop \
  -d evershop

Если запросил пароль и пустил в PostgreSQL — всё нормально.

Выйти:

\q

12. ВАЖНО: база должна быть пустой

EverShop сам создаёт:

Не нужно самостоятельно создавать таблицы EverShop.

Официальная установка также предусматривает пустую PostgreSQL-базу, после чего evershop install создаёт схему и запускает миграции.


13. Создаём package scripts

Проверяем текущий:

cat package.json

У EverShop используются команды:

dev
start
start:debug
build
setup
seed
user:create

Официальная документация также указывает theme-команды для разработки тем.

Не удаляйте существующие scripts из package.json.

Если нужных команд нет, добавьте:

{
  "scripts": {
    "dev": "evershop dev",
    "start": "evershop start",
    "start:debug": "evershop start --debug",
    "build": "evershop build",
    "setup": "evershop install",
    "seed": "evershop seed",
    "user:create": "evershop user:create",
    "user:changePassword": "evershop user:changePassword",
    "theme:create": "evershop theme:create",
    "theme:active": "evershop theme:active",
    "theme:twizz": "evershop theme:twizz",
    "theme:status": "evershop theme:status",
    "theme:uninstall": "evershop theme:uninstall",
    "theme:export-content": "evershop theme:export-content"
  }
}

Не заменяйте полностью существующий package.json этим фрагментом.

Нужно добавить/сохранить scripts в существующем файле.


14. Проверяем ESM

EverShop использует ES Modules.

В package.json должно быть:

"type": "module"

Проверка:

grep '"type"' package.json

Если отсутствует:

npm pkg set type=module

Проверка:

node -p "require('./package.json').type"

Ожидается:

module

Это особенно важно с современными версиями npm. Официальная документация отдельно предупреждает, что неправильный type приводит к ошибкам import/export во время build.


15. Workspace

Поскольку мы работаем с исходным репозиторием, важно сохранить workspace-конфигурацию.

Проверить:

node -e "console.log(require('./package.json').workspaces)"

В проекте должны использоваться workspace-директории репозитория.

Исходный репозиторий содержит packages/, а архитектура EverShop рассчитана на модульную разработку.


16. Конфигурация базы данных

Есть два важных варианта конфигурации:

.env
config/

Для первоначальной установки проще использовать официальный setup wizard.

Запустить:

npm run setup

EverShop попросит:

Database host
Database port
Database name
Database user
Database password

Admin name
Admin email
Admin password

Для нашей конфигурации:

Database host:
127.0.0.1

Database port:
5432

Database name:
evershop

Database user:
evershop

Database password:
YOUR_PASSWORD

После установки будет создан:

.env

Официальный установщик также создаёт необходимые директории, схему БД, миграции и администратора.


17. Проверяем .env

cat .env

Должно быть примерно:

DB_HOST="127.0.0.1"
DB_PORT="5432"
DB_NAME="evershop"
DB_USER="evershop"
DB_PASSWORD="YOUR_PASSWORD"
DB_SSLMODE="disable"

Не добавляйте .env в Git.

Проверить:

git status --short

Если .env почему-либо показывается как untracked:

echo ".env" >> .gitignore

18. Права на директории

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

public/
.evershop/
.log/
media/

Это требование указано в официальной инструкции.

Создать:

mkdir -p public
mkdir -p .evershop
mkdir -p .log
mkdir -p media

Установить владельца:

chown -R evershop:evershop /opt/evershop

Проверить:

ls -ld \
  /opt/evershop/public \
  /opt/evershop/.evershop \
  /opt/evershop/.log \
  /opt/evershop/media

19. Development-зависимости

Если сервер будет использоваться именно для разработки исходников EverShop, установить дополнительные зависимости:

npm install --save-dev \
  @types/node \
  typescript \
  @parcel/watcher \
  @types/config \
  @types/express \
  @types/pg \
  @types/react \
  execa

Для текущей версии EverShop @types/react должен разрешаться в версии 19.x. При необходимости:

npm install --save-dev @types/react@19 @types/react-dom@19

Проверка:

npm ls @types/react

Официальная документация отдельно отмечает требование React 19 typings для разработки.


20. Первоначальная установка БД

Если npm run setup ещё не запускался:

npm run setup

После завершения проверить наличие:

ls -la

В частности:

.env
media/
public/

21. Первый production build

Перед запуском:

npm run build

Build создаёт production bundles в:

.evershop/

Официальная документация требует выполнять build перед start.


22. Первый запуск вручную

Перед systemd обязательно проверить приложение вручную.

npm run start

Если всё нормально:

Server started at http://localhost:3000

Проверить с сервера:

curl -I http://127.0.0.1:3000

Остановить:

CTRL+C

23. Development режим

Для разработки исходников:

npm run dev

Development mode включает hot reload.

Это удобно, когда работа идёт непосредственно на сервере.

Официальная документация указывает:

npm run dev

как основной development-запуск с hot reload.

Не использовать npm run dev для production systemd-сервиса.

Production:

npm run build
npm run start

24. Создаём systemd service

Выходим из пользователя evershop:

exit

Создаём:

nano /etc/systemd/system/evershop.service

Содержимое:

[Unit]
Description=EverShop E-commerce Platform
Documentation=https://evershop.io/docs
After=network-online.target postgresql.service
Wants=network-online.target

[Service]
Type=simple

User=evershop
Group=evershop

WorkingDirectory=/opt/evershop

Environment=NODE_ENV=production
Environment=PORT=3000

ExecStart=/usr/bin/npm run start

Restart=always
RestartSec=5

TimeoutStopSec=30
KillSignal=SIGINT

NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target

25. Проверяем путь npm

Очень важно проверить:

which npm

Если:

/usr/bin/npm

то:

ExecStart=/usr/bin/npm run start

правильный.

Если путь другой:

which npm

использовать полученный путь.

Также:

which node

26. Проверяем systemd configuration

systemd-analyze verify /etc/systemd/system/evershop.service

Если ошибок нет:

systemctl daemon-reload

27. Включаем EverShop

systemctl enable evershop

Запускаем:

systemctl start evershop

Проверяем:

systemctl status evershop

Должно быть:

Active: active (running)

28. Логи EverShop

Основной способ:

journalctl -u evershop -f

Последние 100 строк:

journalctl -u evershop -n 100

За текущую загрузку:

journalctl -u evershop -b

Только ошибки:

journalctl -u evershop -p err

29. Управление сервисом

Запуск:

systemctl start evershop

Остановка:

systemctl stop evershop

Перезапуск:

systemctl restart evershop

Статус:

systemctl status evershop

Автозапуск:

systemctl enable evershop

Отключение автозапуска:

systemctl disable evershop

30. Nginx через aaPanel

PostgreSQL и Nginx уже установлены через aaPanel.

Не нужно вручную переустанавливать Nginx.

В aaPanel:

Website
  ↓
Add site
  ↓
Domain

Например:

shop.example.com

После создания сайта в aaPanel откройте конфигурацию Nginx.


31. Nginx reverse proxy

В server block сайта добавить:

location / {
    proxy_pass http://127.0.0.1:3000;

    proxy_http_version 1.1;

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;

    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    proxy_cache_bypass $http_upgrade;
}

Для загрузки больших файлов:

client_max_body_size 50M;

Итоговый блок:

server {
    listen 80;
    server_name shop.example.com;

    client_max_body_size 50M;

    location / {
        proxy_pass http://127.0.0.1:3000;

        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;

        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_cache_bypass $http_upgrade;
    }
}

EverShop официально предполагает работу через reverse proxy для production.


32. Проверяем Nginx

nginx -t

Если:

syntax is ok
test is successful

перезагрузить:

systemctl reload nginx

33. HTTPS

В aaPanel:

Website
  ↓
shop.example.com
  ↓
SSL
  ↓
Let's Encrypt

Получить сертификат.

После установки HTTPS схема будет:

https://shop.example.com
        │
        ▼
      Nginx
        │
        ▼
127.0.0.1:3000
        │
        ▼
    EverShop

Порт 3000 не нужно открывать в firewall.


34. Проверяем приложение

С сервера:

curl -I http://127.0.0.1:3000

Через домен:

curl -I https://shop.example.com

Открыть:

https://shop.example.com

Admin:

https://shop.example.com/admin

35. Firewall

Для production достаточно:

22    SSH
80    HTTP
443   HTTPS

Не требуется открывать:

3000
5432

EverShop:

127.0.0.1:3000

PostgreSQL:

127.0.0.1:5432

36. Проверяем, что PostgreSQL не торчит наружу

ss -lntp | grep 5432

Желательно увидеть:

127.0.0.1:5432

или локальный Unix socket.

Проверить EverShop:

ss -lntp | grep 3000

Ожидается:

127.0.0.1:3000

37. Проверяем systemd после reboot

После полного завершения настройки:

systemctl is-enabled evershop

Должно:

enabled

Проверить:

systemctl is-active evershop

Должно:

active

38. Обновление исходников

ВАЖНО:

Не делать:

npm install @evershop/evershop@latest

Мы работаем с Git-репозиторием.

Обновление исходников:

su - evershop
cd /opt/evershop

Проверяем текущую ветку:

git branch --show-current

Получаем изменения:

git fetch origin

Если используется dev:

git checkout dev
git pull --ff-only origin dev

39. Перед обновлением — backup PostgreSQL

Перед любым обновлением production:

sudo -u postgres pg_dump \
  -Fc \
  evershop \
  > /root/evershop-$(date +%Y-%m-%d-%H%M%S).dump

Проверить:

ls -lh /root/evershop-*.dump

Это особенно важно потому, что EverShop применяет миграции базы автоматически при запуске. Официальная документация предупреждает, что миграции не являются обратимыми.


40. Обновление зависимостей после git pull

После обновления:

cd /opt/evershop
npm ci

Затем:

npm run build

После успешного build:

sudo systemctl restart evershop

Проверить:

sudo systemctl status evershop

Логи:

sudo journalctl -u evershop -n 100 --no-pager

41. Полный production deploy после изменения исходников

Типичный цикл:

su - evershop
cd /opt/evershop

git status
git pull --ff-only origin dev

npm ci

npm run build

exit

systemctl restart evershop

systemctl status evershop

Проверка:

curl -I http://127.0.0.1:3000

42. Если изменили только TypeScript/React

Для production:

npm run build
systemctl restart evershop

Build обязателен.

EverShop компилирует исходный TypeScript/React код в production bundles.


43. Development workflow

Если вы непосредственно разрабатываете проект:

su - evershop
cd /opt/evershop
npm run dev

Development сервер:

http://127.0.0.1:3000

Для разработки лучше использовать SSH tunnel:

На локальном компьютере:

ssh -L 3000:127.0.0.1:3000 root@SERVER_IP

После этого локально открыть:

http://localhost:3000

Это позволяет не открывать порт 3000 наружу.


44. Важный момент по архитектуре кастомизации

Не рекомендуется без необходимости изменять:

packages/evershop/src/

Хотя это исходный код ядра и технически это возможно.

Предпочтительная архитектура EverShop:

EverShop Core
     │
     ├── Extensions
     │
     └── Themes

Extensions находятся в:

extensions/

Themes:

themes/

EverShop специально предоставляет extension system для изменения и расширения функциональности без изменения core.


45. Когда изменять packages/evershop/src

Изменение:

packages/evershop/src/

имеет смысл, если вы действительно хотите изменить:

Но для обычных функций магазина лучше:

extensions/

А для UI:

themes/

46. Рекомендуемая структура вашей работы

/opt/evershop/

├── packages/
│   └── evershop/
│       └── src/
│
├── extensions/
│   ├── extension-one/
│   └── extension-two/
│
├── themes/
│   └── custom-theme/
│
├── translations/
│
├── public/
│
├── media/
│
├── .evershop/
│
├── .log/
│
├── .env
│
├── package.json
├── package-lock.json
└── tsconfig.json

47. Быстрая установка — всё одной последовательностью

Ниже минимальный сценарий для нового Debian 13.

47.1 Node.js

curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt install -y nodejs git

47.2 Пользователь

useradd --system \
  --create-home \
  --home-dir /opt/evershop \
  --shell /bin/bash \
  evershop

47.3 Директория

mkdir -p /opt/evershop
chown -R evershop:evershop /opt/evershop

47.4 Clone

su - evershop -c '
cd /opt/evershop &&
git clone https://github.com/evershopcommerce/evershop.git . &&
git checkout dev
'

47.5 Dependencies

su - evershop -c '
cd /opt/evershop &&
npm ci
'

47.6 PostgreSQL

Создать вручную:

sudo -u postgres psql
CREATE USER evershop WITH PASSWORD 'CHANGE_THIS_PASSWORD';
CREATE DATABASE evershop OWNER evershop;
\q

47.7 Setup

su - evershop
cd /opt/evershop

npm run setup

Ввести:

DB_HOST: 127.0.0.1
DB_PORT: 5432
DB_NAME: evershop
DB_USER: evershop
DB_PASSWORD: CHANGE_THIS_PASSWORD

И данные администратора.


47.8 Build

npm run build

47.9 Проверка

npm run start

Проверить:

curl -I http://127.0.0.1:3000

Остановить:

CTRL+C

48. Создание systemd одной командой

После проверки приложения:

exit

Создать service:

cat > /etc/systemd/system/evershop.service <<'EOF'
[Unit]
Description=EverShop E-commerce Platform
Documentation=https://evershop.io/docs
After=network-online.target postgresql.service
Wants=network-online.target

[Service]
Type=simple

User=evershop
Group=evershop

WorkingDirectory=/opt/evershop

Environment=NODE_ENV=production
Environment=PORT=3000

ExecStart=/usr/bin/npm run start

Restart=always
RestartSec=5

TimeoutStopSec=30
KillSignal=SIGINT

NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target
EOF

Затем:

systemd-analyze verify /etc/systemd/system/evershop.service &&
systemctl daemon-reload &&
systemctl enable evershop &&
systemctl start evershop

Проверка:

systemctl status evershop

49. Быстрый deploy после изменения кода

Создать удобный скрипт:

nano /opt/evershop/deploy.sh
#!/bin/bash

set -e

cd /opt/evershop

echo "==> Updating source..."

git pull --ff-only origin dev

echo "==> Installing dependencies..."

npm ci

echo "==> Building EverShop..."

npm run build

echo "==> Restarting service..."

systemctl restart evershop

echo "==> Checking service..."

systemctl --no-pager --full status evershop

echo "==> Deploy completed."

Права:

chmod +x /opt/evershop/deploy.sh

Но поскольку скрипт должен перезапускать systemd, его удобнее запускать от root.

Запуск:

/opt/evershop/deploy.sh

50. Более безопасный deploy

Для production рекомендую перед обновлением делать backup:

sudo -u postgres pg_dump \
  -Fc \
  evershop \
  > /root/evershop-$(date +%Y-%m-%d-%H%M%S).dump

После этого:

/opt/evershop/deploy.sh

51. Диагностика

EverShop не запускается

systemctl status evershop
journalctl -u evershop -n 200 --no-pager

Проверить порт

ss -lntp | grep 3000

Проверить PostgreSQL

systemctl status postgresql

Подключение:

psql \
  -h 127.0.0.1 \
  -U evershop \
  -d evershop

Проверить Nginx

nginx -t
systemctl status nginx

Логи:

tail -f /www/server/nginx/logs/error.log

Путь может отличаться в зависимости от конфигурации aaPanel.


52. Build падает

Запустить:

npm run build

Не скрывать ошибку.

Проверить:

node -v
npm -v

Проверить зависимости:

npm ls

Если зависимости повреждены:

rm -rf node_modules
npm ci
npm run build

53. Ошибка import/export

Проверить:

node -p "require('./package.json').type"

Должно:

module

Если нет:

npm pkg set type=module

После этого:

npm run build

54. Ошибка доступа к .evershop, .log, media

Проверить:

ls -la

Исправить:

chown -R evershop:evershop /opt/evershop

55. Ошибка PostgreSQL

Проверить .env:

cat /opt/evershop/.env

Проверить соединение:

psql \
  -h 127.0.0.1 \
  -U evershop \
  -d evershop

Проверить PostgreSQL:

sudo -u postgres psql -c "\du"

56. Проверка всего стека

Выполнить:

systemctl is-active postgresql
systemctl is-active evershop
systemctl is-active nginx

Проверить:

ss -lntp | grep -E ':(80|443|3000|5432)'

Ожидаемая схема:

Nginx       → 80/443
EverShop    → 127.0.0.1:3000
PostgreSQL  → 127.0.0.1:5432

57. Что НЕ нужно делать

Не запускать production от root:

npm run start

от root.

Не открывать наружу:

3000
5432

Не использовать:

npm install @evershop/evershop

если цель — изменять ядро самого репозитория.

Не использовать:

npm run seed

на production.

Seed предназначен для development/testing.

Не делать обновление production без backup PostgreSQL.

Не выполнять:

git reset --hard

на рабочем сервере без понимания, какие локальные изменения существуют.


58. Итоговая схема файлов

/opt/evershop
│
├── packages/
│   └── evershop/
│       └── src/              ← CORE SOURCE CODE
│
├── extensions/               ← CUSTOM EXTENSIONS
│
├── themes/                   ← CUSTOM THEMES
│
├── translations/
│
├── public/                   ← GENERATED/PUBLIC FILES
├── media/                    ← USER UPLOADS
│
├── .evershop/                ← BUILD
├── .log/
│
├── .env                      ← DATABASE/ENV CONFIG
│
├── package.json
├── package-lock.json
│
└── deploy.sh

59. Итоговый production flow

Первоначальная установка:

Debian 13
   ↓
Node.js 22
   ↓
Git
   ↓
Clone EverShop
   ↓
npm ci
   ↓
PostgreSQL database
   ↓
npm run setup
   ↓
npm run build
   ↓
systemd
   ↓
127.0.0.1:3000
   ↓
Nginx aaPanel
   ↓
HTTPS
   ↓
Internet

Рабочий цикл разработки:

Изменение исходников
        ↓
   npm run build
        ↓
systemctl restart evershop
        ↓
      тест

Обновление Git:

git pull
   ↓
npm ci
   ↓
npm run build
   ↓
systemctl restart evershop

Перед обновлением production:

PostgreSQL backup
        ↓
      git pull
        ↓
      npm ci
        ↓
    npm run build
        ↓
systemctl restart evershop
        ↓
      проверка

60. Главные команды

Запуск

systemctl start evershop

Остановка

systemctl stop evershop

Перезапуск

systemctl restart evershop

Статус

systemctl status evershop

Логи

journalctl -u evershop -f

Development

su - evershop
cd /opt/evershop
npm run dev

Production build

su - evershop
cd /opt/evershop
npm run build

Git update

su - evershop
cd /opt/evershop
git pull --ff-only origin dev
npm ci
npm run build
exit
systemctl restart evershop

PostgreSQL backup

sudo -u postgres pg_dump \
  -Fc \
  evershop \
  > /root/evershop-$(date +%Y-%m-%d-%H%M%S).dump

Проверка EverShop

curl -I http://127.0.0.1:3000

61. Рекомендуемый вариант конкретно для этого сервера

Для вашего случая я рекомендую:

Debian 13
│
├── aaPanel
│   ├── Nginx
│   └── PostgreSQL
│
├── /opt/evershop
│   └── Git repository
│
├── Node.js 22
│
├── systemd
│   └── evershop.service
│
└── Nginx reverse proxy
    └── HTTPS

Docker здесь не нужен.

Главное преимущество такого варианта для вас — сервер содержит настоящий Git checkout EverShop, поэтому можно непосредственно работать с:

packages/evershop/src/
extensions/
themes/

и после изменений выполнять обычный:

npm run build
systemctl restart evershop

При этом systemd обеспечивает постоянный production-процесс и автоматический запуск после перезагрузки сервера.