Инструкция по развёртыванию EverShop из Git-репозитория на:
Репозиторий:
https://github.com/evershopcommerce/evershop
Используем следующую схему:
Internet
│
│ HTTPS :443
▼
┌──────────────┐
│ Nginx │
│ aaPanel │
└──────┬───────┘
│
│ 127.0.0.1:3000
▼
┌──────────────┐
│ EverShop │
│ Node.js │
│ systemd │
└──────┬───────┘
│
│ localhost:5432
▼
┌──────────────┐
│ PostgreSQL │
│ aaPanel │
└──────────────┘
PostgreSQL наружу не открываем.
Порт 3000 наружу также не открываем.
Nginx принимает HTTP/HTTPS и проксирует запросы на EverShop.
EverShop требует:
Для Debian 13 рекомендуется использовать Node.js 22 LTS.
Официальная документация подтверждает поддержку Node.js 20 и 22. PostgreSQL должен быть версии 13+.
Выполнить:
cat /etc/os-release
Проверить Node.js:
node --version
npm --version
Проверить PostgreSQL:
psql --version
Проверить Git:
git --version
Проверить Nginx:
nginx -v
Если Node.js отсутствует — установить 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
Не запускаем EverShop от root.
useradd --system \
--create-home \
--home-dir /opt/evershop \
--shell /bin/bash \
evershop
Проверка:
id evershop
mkdir -p /opt/evershop
chown -R evershop:evershop /opt/evershop
Переходим под пользователя 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
Это не установка:
npm install @evershop/evershop
Так устанавливается опубликованный пакет ядра.
В нашем случае используется сам репозиторий:
/opt/evershop/
├── packages/
│ └── evershop/
│ └── src/
├── extensions/
├── themes/
├── translations/
├── scripts/
├── tests/
├── package.json
├── package-lock.json
└── ...
Исходный код ядра находится в:
packages/evershop/src/
Это соответствует структуре текущего репозитория.
В корне проекта:
cd /opt/evershop
Установка:
npm ci
Если npm ci выдаёт ошибку из-за несовместимости lock-файла, использовать:
npm install
Но для production предпочтительнее:
npm ci
поскольку он устанавливает зависимости согласно package-lock.json.
PostgreSQL уже установлен через aaPanel.
Нужно создать отдельную БД и отдельного пользователя EverShop.
Сначала подключиться:
sudo -u postgres psql
Создать пользователя:
CREATE USER evershop WITH PASSWORD 'CHANGE_THIS_TO_STRONG_PASSWORD';
Создать базу:
CREATE DATABASE evershop OWNER evershop;
Выйти:
\q
psql \
-h 127.0.0.1 \
-U evershop \
-d evershop
Если запросил пароль и пустил в PostgreSQL — всё нормально.
Выйти:
\q
EverShop сам создаёт:
Не нужно самостоятельно создавать таблицы EverShop.
Официальная установка также предусматривает пустую PostgreSQL-базу, после чего evershop install создаёт схему и запускает миграции.
Проверяем текущий:
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 в существующем файле.
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.
Поскольку мы работаем с исходным репозиторием, важно сохранить workspace-конфигурацию.
Проверить:
node -e "console.log(require('./package.json').workspaces)"
В проекте должны использоваться workspace-директории репозитория.
Исходный репозиторий содержит packages/, а архитектура EverShop рассчитана на модульную разработку.
Есть два важных варианта конфигурации:
.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
Официальный установщик также создаёт необходимые директории, схему БД, миграции и администратора.
.envcat .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
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
Если сервер будет использоваться именно для разработки исходников 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 для разработки.
Если npm run setup ещё не запускался:
npm run setup
После завершения проверить наличие:
ls -la
В частности:
.env
media/
public/
Перед запуском:
npm run build
Build создаёт production bundles в:
.evershop/
Официальная документация требует выполнять build перед start.
Перед systemd обязательно проверить приложение вручную.
npm run start
Если всё нормально:
Server started at http://localhost:3000
Проверить с сервера:
curl -I http://127.0.0.1:3000
Остановить:
CTRL+C
Для разработки исходников:
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
Выходим из пользователя 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
Очень важно проверить:
which npm
Если:
/usr/bin/npm
то:
ExecStart=/usr/bin/npm run start
правильный.
Если путь другой:
which npm
использовать полученный путь.
Также:
which node
systemd-analyze verify /etc/systemd/system/evershop.service
Если ошибок нет:
systemctl daemon-reload
systemctl enable evershop
Запускаем:
systemctl start evershop
Проверяем:
systemctl status evershop
Должно быть:
Active: active (running)
Основной способ:
journalctl -u evershop -f
Последние 100 строк:
journalctl -u evershop -n 100
За текущую загрузку:
journalctl -u evershop -b
Только ошибки:
journalctl -u evershop -p err
Запуск:
systemctl start evershop
Остановка:
systemctl stop evershop
Перезапуск:
systemctl restart evershop
Статус:
systemctl status evershop
Автозапуск:
systemctl enable evershop
Отключение автозапуска:
systemctl disable evershop
PostgreSQL и Nginx уже установлены через aaPanel.
Не нужно вручную переустанавливать Nginx.
В aaPanel:
Website
↓
Add site
↓
Domain
Например:
shop.example.com
После создания сайта в aaPanel откройте конфигурацию Nginx.
В 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.
nginx -t
Если:
syntax is ok
test is successful
перезагрузить:
systemctl reload nginx
В aaPanel:
Website
↓
shop.example.com
↓
SSL
↓
Let's Encrypt
Получить сертификат.
После установки HTTPS схема будет:
https://shop.example.com
│
▼
Nginx
│
▼
127.0.0.1:3000
│
▼
EverShop
Порт 3000 не нужно открывать в firewall.
С сервера:
curl -I http://127.0.0.1:3000
Через домен:
curl -I https://shop.example.com
Открыть:
https://shop.example.com
Admin:
https://shop.example.com/admin
Для production достаточно:
22 SSH
80 HTTP
443 HTTPS
Не требуется открывать:
3000
5432
EverShop:
127.0.0.1:3000
PostgreSQL:
127.0.0.1:5432
ss -lntp | grep 5432
Желательно увидеть:
127.0.0.1:5432
или локальный Unix socket.
Проверить EverShop:
ss -lntp | grep 3000
Ожидается:
127.0.0.1:3000
После полного завершения настройки:
systemctl is-enabled evershop
Должно:
enabled
Проверить:
systemctl is-active evershop
Должно:
active
ВАЖНО:
Не делать:
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
Перед любым обновлением production:
sudo -u postgres pg_dump \
-Fc \
evershop \
> /root/evershop-$(date +%Y-%m-%d-%H%M%S).dump
Проверить:
ls -lh /root/evershop-*.dump
Это особенно важно потому, что EverShop применяет миграции базы автоматически при запуске. Официальная документация предупреждает, что миграции не являются обратимыми.
После обновления:
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
Типичный цикл:
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
Для production:
npm run build
systemctl restart evershop
Build обязателен.
EverShop компилирует исходный TypeScript/React код в production bundles.
Если вы непосредственно разрабатываете проект:
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 наружу.
Не рекомендуется без необходимости изменять:
packages/evershop/src/
Хотя это исходный код ядра и технически это возможно.
Предпочтительная архитектура EverShop:
EverShop Core
│
├── Extensions
│
└── Themes
Extensions находятся в:
extensions/
Themes:
themes/
EverShop специально предоставляет extension system для изменения и расширения функциональности без изменения core.
Изменение:
packages/evershop/src/
имеет смысл, если вы действительно хотите изменить:
Но для обычных функций магазина лучше:
extensions/
А для UI:
themes/
/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
Ниже минимальный сценарий для нового Debian 13.
curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt install -y nodejs git
useradd --system \
--create-home \
--home-dir /opt/evershop \
--shell /bin/bash \
evershop
mkdir -p /opt/evershop
chown -R evershop:evershop /opt/evershop
su - evershop -c '
cd /opt/evershop &&
git clone https://github.com/evershopcommerce/evershop.git . &&
git checkout dev
'
su - evershop -c '
cd /opt/evershop &&
npm ci
'
Создать вручную:
sudo -u postgres psql
CREATE USER evershop WITH PASSWORD 'CHANGE_THIS_PASSWORD';
CREATE DATABASE evershop OWNER evershop;
\q
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
И данные администратора.
npm run build
npm run start
Проверить:
curl -I http://127.0.0.1:3000
Остановить:
CTRL+C
После проверки приложения:
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
Создать удобный скрипт:
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
Для production рекомендую перед обновлением делать backup:
sudo -u postgres pg_dump \
-Fc \
evershop \
> /root/evershop-$(date +%Y-%m-%d-%H%M%S).dump
После этого:
/opt/evershop/deploy.sh
systemctl status evershop
journalctl -u evershop -n 200 --no-pager
ss -lntp | grep 3000
systemctl status postgresql
Подключение:
psql \
-h 127.0.0.1 \
-U evershop \
-d evershop
nginx -t
systemctl status nginx
Логи:
tail -f /www/server/nginx/logs/error.log
Путь может отличаться в зависимости от конфигурации aaPanel.
Запустить:
npm run build
Не скрывать ошибку.
Проверить:
node -v
npm -v
Проверить зависимости:
npm ls
Если зависимости повреждены:
rm -rf node_modules
npm ci
npm run build
Проверить:
node -p "require('./package.json').type"
Должно:
module
Если нет:
npm pkg set type=module
После этого:
npm run build
.evershop, .log, mediaПроверить:
ls -la
Исправить:
chown -R evershop:evershop /opt/evershop
Проверить .env:
cat /opt/evershop/.env
Проверить соединение:
psql \
-h 127.0.0.1 \
-U evershop \
-d evershop
Проверить PostgreSQL:
sudo -u postgres psql -c "\du"
Выполнить:
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
Не запускать 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
на рабочем сервере без понимания, какие локальные изменения существуют.
/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
Первоначальная установка:
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
↓
проверка
systemctl start evershop
systemctl stop evershop
systemctl restart evershop
systemctl status evershop
journalctl -u evershop -f
su - evershop
cd /opt/evershop
npm run dev
su - evershop
cd /opt/evershop
npm run build
su - evershop
cd /opt/evershop
git pull --ff-only origin dev
npm ci
npm run build
exit
systemctl restart evershop
sudo -u postgres pg_dump \
-Fc \
evershop \
> /root/evershop-$(date +%Y-%m-%d-%H%M%S).dump
curl -I http://127.0.0.1:3000
Для вашего случая я рекомендую:
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-процесс и автоматический запуск после перезагрузки сервера.