Устанавливаете сайт — начните с INSTALL.md: одна команда
sudo bash install.sh делает всё, что описано ниже. Этот файл — для тех, кто
хочет понять, что и зачем она делает, или поставить сайт вручную.
В каталоге — шаблоны для Ubuntu, nginx и systemd. В них example.ru — домен
сайта: установка подставляет настоящий сама, при ручной установке его заменяют
командой sed (ниже).
Что делает установка
Последовательность (то же делает server/site_install.py):
Проверить готовую сборку в
dist/. В архиве она уже есть. Если вы меняете исходники, соберите сайт на своём компьютере перед отправкой на сервер.Установить команду выкладки и выложить сборку:
install -m 755 server/site_release.py /usr/local/sbin/cms-youwebsite-release, затемsudo cms-youwebsite-release dist --no-service(при первой выкладке службы ещё нет). Команда кладёт сборку в/var/www/cms-youwebsite/current/.Разместить сервер в
/opt/cms-youwebsite/.Создать защищённое хранилище
/var/lib/cms-youwebsite/.Скопировать
service.env.exampleв/etc/cms-youwebsite/service.env. Обязательных заготовок в нём нет: почту сайта задают в окнах установки (она хранится в/var/lib/cms-youwebsite/mail.jsonи главнее строкSMTP_*), секрет входа служба создаёт сама. СтрокиSMTP_*заполняют только при установке без окон. Если в файле остались значенияREPLACE_WITH_…, служба перечислит их в журнале (journalctl -u <служба>), а с заготовкой или короткимADMIN_SESSION_SECRETне запустится вовсе.Файл пользователей
/var/lib/cms-youwebsite/editors.jsonсоздаёт служба в окнах установки или команда из пункта 7 (владелецwww-data, права600). Файл лежит в каталоге данных, потому что админ добавляет и удаляет пользователей прямо в консоли и служба его записывает. В резервные копии он не попадает. Пароли хранятся только в виде PBKDF2-хеша (образец файла —editors.example.json).Установить команды управления пользователями и окон установки:
install -m 755 server/manage_editors.py /usr/local/sbin/cms-youwebsite-users,install -m 755 server/site_setup.py /usr/local/sbin/cms-youwebsite-setup. Владельца сайта (суперадмина) и почту проще задать в окнах установки:sudo cms-youwebsite-setupвыдаёт одноразовую ссылку на сутки, дальше всё в браузере (подробно — INSTALL.md, шаг 3). Вариант в терминале —sudo cms-youwebsite-users: первый пользователь — суперадмин (команда сама предлагает это, если суперадмина ещё нет). Дальше пользователей приглашает админ в консоли («Пользователи»): человек получает письмо и сам задаёт пароль. Команда на сервере нужна для восстановления доступа: пункт 9 назначает суперадмина, если прежний недоступен (уволился, потерял почту). Команда и консоль работают с одним файлом и не мешают друг другу. Входы отключённого или изменённого пользователя завершаются сразу, перезапускать службу не нужно.Роли: автор пишет новые публикации и правит только свои; редактор — все публикации, проверяет авторов; админ — ещё код страниц, настройки, журнал, копии и пользователи (кроме админов); суперадмин — один, назначает админов, включает проверку публикаций авторов и может передать свои права другому админу (с подтверждением обеих сторон кодами на почту).
У каждого редактора есть постоянный идентификатор (
id), не зависящий от логина и почты. У материалов сервер сам отмечает, кто их создал и кто последним изменил; эти отметки видны в консоли. При удалении редактора материалы остаются на сайте, а сам он остаётся в файле в спискеdeleted_editors: в отметках и в журнале он показан как «(удалён)». Если позже зарегистрировать человека с тем же логином или почтой, это будет новая учётная запись, и чужие отметки или записи журнала к нему не перейдут.Подпись для читателей («Пресс-служба», «Иван Петров») задаётся в форме публикации свободным текстом и с учётными записями не связана.
Установить unit-файлы systemd (службу сайта и таймер ночных копий
cms-youwebsite-backup.timer), конфигурацию Nginx и проверить их перед запуском.
Резервные копии, восстановление и переезд на новый сервер — в BACKUP.md.
Передача сайта клиенту
Роли защищают консоль, но не сервер: у кого есть доступ к серверу (SSH, root), у того есть доступ ко всем данным и к файлу пользователей. Поэтому после запуска:
- Суперадмином должен быть представитель клиента, а не разработчик. Если сайт запускали вы, передайте права в консоли («Пользователи» → «Передать права суперадмина») и удалите свою учётную запись.
- Доступ к серверу и к панели хостинга оформите на клиента: смена паролей, новый владелец ключей SSH.
- Удалите свои ключи из
~/.ssh/authorized_keysна сервере и из панели хостинга, если работа по поддержке не предусмотрена договором. - Покажите клиенту «Шапку и меню» и «Подвал» в консоли: свой логотип, свои контакты; подпись «Сайт на CMS YouWebsite» со знаком он вправе убрать сам (галочка в «Подвале»).
- Передайте клиенту файл настроек (
/etc/cms-youwebsite/service.env) и команды на сервере: сменить почту сайта —sudo cms-youwebsite-setup --mail, восстановить доступ —sudo cms-youwebsite-users, пункт 9.
Nginx и сертификат HTTPS
Файлы из deploy/nginx/ раскладываются так:
| Файл в репозитории | Куда на сервере |
|---|---|
limits.conf |
/etc/nginx/conf.d/cms-youwebsite-limits.conf |
security-headers.conf |
/etc/nginx/snippets/cms-youwebsite-security-headers.conf |
tls.conf |
/etc/nginx/snippets/cms-youwebsite-tls.conf |
acme-challenge.conf |
/etc/nginx/snippets/cms-youwebsite-acme-challenge.conf |
site.conf |
/etc/nginx/sites-available/cms-youwebsite.conf (+ ссылка в sites-enabled) |
first-certificate.conf |
только на время выпуска первого сертификата |
Сертификат Let's Encrypt выпускается и продлевается в режиме --webroot:
certbot кладёт проверочный файл в /var/www/letsencrypt, а nginx отдаёт его по
адресу /.well-known/acme-challenge/… и по HTTP, и по HTTPS. Плагин certbot для
nginx не нужен и конфигурацию не меняет.
Первый сертификат. Основной site.conf не запустится, пока файлов
сертификата ещё нет, поэтому сначала включается временный файл:
sudo mkdir -p /var/www/letsencrypt
sudo cp deploy/nginx/first-certificate.conf /etc/nginx/sites-enabled/cms-youwebsite-first.conf
sudo nginx -t && sudo systemctl reload nginx
sudo certbot certonly --webroot -w /var/www/letsencrypt \
-d example.ru -d www.example.ru \
--deploy-hook "systemctl reload nginx"
sudo rm /etc/nginx/sites-enabled/cms-youwebsite-first.conf
sudo ln -s /etc/nginx/sites-available/cms-youwebsite.conf /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
Продление выполняет таймер certbot (systemctl list-timers certbot.timer)
сам, по тем же настройкам; после продления nginx перечитывает сертификат
(--deploy-hook). Проверить, что продление пройдёт, можно в любой момент:
sudo certbot renew --dry-run
Если сертификат раньше выпускался через certbot --nginx, переведите его на
webroot один раз той же командой certbot certonly --webroot …, что и выше.
Кэш в браузере
| Что | Правило в site.conf |
Почему |
|---|---|---|
| Страницы сайта и публикаций | no-cache |
Браузер каждый раз спрашивает, не изменилась ли страница (ответ 304 почти ничего не стоит). После выкладки новой версии старые страницы не ссылаются на удалённые файлы. |
/build/ — скрипты и стили сборки |
год, immutable |
В имени отпечаток содержимого: новая версия — новое имя файла. |
Картинки, значки, шрифты из public/ |
сутки | Имя не меняется: заменённый логотип посетители увидят не позже чем через день. |
| Фото и документы публикаций | сутки | См. «Отдача файлов и корзина». |
Папку /build/ задаёт assetsDir в vite.config.ts. Не кладите в public/
папку с таким именем.
Поддомены и HSTS
Сайт отдаёт заголовок HSTS с includeSubDomains (security-headers.conf):
браузер, побывавший на сайте, год открывает домен и все его поддомены
только по HTTPS и не даёт обойти ошибку сертификата. CMS рассчитана на
отдельный сайт: наши новые сайты на поддоменах разворачиваются заново и сразу
получают сертификат. Риск — чужие сервисы клиента на поддоменах без HTTPS.
Проверка. Перед запуском (сборка с indexable: true напоминает об этом) и
после подключения клиентом любого нового сервиса:
python3 server/check_subdomains.py # домен из site.json
python3 server/check_subdomains.py --extra intranet,video
Команда находит распространённые поддомены (mail, 1c, crm, old, test и
др.), а также запись «*», и проверяет на каждом HTTPS так же, как браузер:
сертификат, срок, имя. Поддомены с необычными именами добавьте через --extra
(полный список — в DNS у регистратора). Код выхода 1, если проблемы есть.
Если нашёлся поддомен без рабочего HTTPS — по порядку, от лучшего:
- Поставить на поддомен сертификат. На нашем сервере —
certbot certonly --webrootдля этого имени, как в разделе выше. На хостинге или у подрядчика — включить бесплатный Let's Encrypt в панели (его дают почти все хостинги). Для почты хостинга часто проще пользоваться адресом самого хостинга (mail.хостинг.ru), а записьmail.домен-клиентаубрать. - Если сертификат поставить нельзя — убрать
includeSubDomainsизsecurity-headers.confи перезагрузить nginx. Это не ослабляет защиту сайта:- сам сайт и
wwwпо-прежнему только по HTTPS (у каждого свой заголовок); - cookie входа в консоль называется
__Host-…: такой cookie браузер не даёт выставить или подменить ни одному поддомену, даже без HTTPS; - у посетителей, которые уже получили правило с поддоменами, оно снимется при их следующем заходе на сайт: браузер обновляет правило при каждом визите.
- сам сайт и
- Чего не делать: не отключать HSTS целиком и не ставить
max-age=0— это открывает сам сайт для подмены при первом заходе по HTTP; не размещать консоль и API на поддомене без HTTPS.
Клиент видит напоминание в консоли («Настройки» → «Подключаете сервис на адресе вида „что-то.ваш-домен“?»): прежде чем подключать что-то на поддомене, он должен сообщить администратору.
Фото и метаданные
При загрузке фото (JPG, PNG, WebP) служба удаляет из файла метаданные: EXIF с GPS-координатами, моделью камеры и датой съёмки, миниатюры, XMP, IPTC, сведения о происхождении (C2PA), комментарии и всё, что дописано после изображения. Фото не пережимается: качество и пиксели те же. Из EXIF остаётся только пометка поворота, иначе фото с телефона легли бы на бок. Редактор видит в консоли, какие сведения были удалены.
Фото, загруженные до этой версии, очищаются командой. Сначала пробный запуск — он только покажет, что найдено:
sudo -u www-data python3 /opt/cms-youwebsite/strip_metadata.py
sudo -u www-data python3 /opt/cms-youwebsite/strip_metadata.py --apply
Имена и адреса файлов не меняются; в журнале сайта появится запись «очистка метаданных у загруженных фото».
Отдача файлов и корзина
Фото и документы nginx отдаёт сам, прямо из
/var/lib/cms-youwebsite/uploads/ (правило location ~ "^/api/content/media/…"
в nginx/site.conf). Так PDF открываются и листаются частями, а служба сайта не
тратит время на большие файлы. Отдаются только имена вида <uuid>.<расширение>,
всё остальное отвечает 404. Служба создаёт файлы с правами 600 от www-data,
поэтому рабочие процессы nginx тоже должны работать от www-data (в Ubuntu так по
умолчанию). Браузер хранит файл не дольше суток без перепроверки.
Когда публикацию удаляют, из неё убирают фото или PDF, а документ заменяют или
удаляют, файлы, на которые больше ничего не ссылается, переносятся в
uploads/.trash/<дата>/ и сразу перестают открываться по ссылке. Через
CONTENT_TRASH_DAYS дней (по умолчанию 30) папка дня удаляется окончательно. До
этого файл можно вернуть, переложив его обратно в uploads/.
Файлы, на которые никогда не ссылалась ни одна публикация (фото загрузили, но публикацию не сохранили), находит команда. Сначала пробный запуск — он только покажет список и содержимое корзины:
sudo -u www-data python3 /opt/cms-youwebsite/cleanup_uploads.py
sudo -u www-data python3 /opt/cms-youwebsite/cleanup_uploads.py --apply
С --apply найденные файлы уходят в корзину (не удаляются сразу), а просроченные
дни корзины удаляются. Файлы моложе суток команда не трогает.
Страницы публикаций
Служба пишет готовые страницы в /var/lib/cms-youwebsite/public/
(SITE_PAGES_DIR), а шаблон берёт из собранного сайта
/var/www/cms-youwebsite/current/news/index.html (SITE_TEMPLATE_DIR).
Nginx отдаёт оттуда /news/ и /sitemap.xml. Каталог с кодом сайта службе
только для чтения.
Выкладка новой версии сайта
Новую версию сайта выкладывайте одной командой, а не копированием файлов:
sudo cms-youwebsite-release dist
Обновление целиком (программа и сайт из нового архива) делает
sudo bash install.sh — он вызывает эту же команду. Отдельно она нужна
разработчику, который выкладывает только новую сборку сайта.
Готовая сборка из архива сделана с адресом-заготовкой https://example.ru.
Настоящие адрес, название и разрешение индексации лежат на сервере в
/etc/cms-youwebsite/site.json (их записывает установка): команда подставляет
их в копию сборки — в canonical, заголовки страниц, метатег robots,
robots.txt и site.json — и выкладывает уже её. Сборку со своим адресом
(src/content/site.ts) команда выкладывает как есть.
Команда:
- проверяет, что сборка целая. Если чего-то не хватает, сайт не трогает и пишет, чего именно;
- копирует новую версию: сначала стили и скрипты, страницы — последними;
- просит службу пересобрать страницы (
systemctl reload). Если вsite.jsonсменились адрес или название сайта, служба перезапускается: их она читает только при запуске. Входы редакторов сохраняются в обоих случаях (если сменился адрес — войти нужно по новому адресу); - ждёт, пока страницы соберутся, и пишет «Готово» или причину ошибки;
- хранит стили и скрипты (
/build/) трёх последних версий, остальные удаляет.
Зачем так. Служба пишет свои страницы в public/: публикации, страницы с
правками кода, а если админ менял «Шапку и меню» или «Подвал» — все страницы и 404.html.
В них ссылки на стили той версии, по которой они собраны. Если просто
скопировать новую сборку и удалить старые стили, эти страницы откроются без
оформления, пока служба их не пересоберёт. Команда делает всё по порядку и
сама: перезапускать службу вручную не нужно.
Пути команда берёт из /etc/cms-youwebsite/service.env (SITE_TEMPLATE_DIR,
SITE_PAGES_DIR, CMS_YOUWEBSITE_SERVICE, по умолчанию cms-youwebsite). История
выкладок — /var/www/cms-youwebsite/releases.json.
Если обновился и сервер (/opt/cms-youwebsite/), после копирования его
файлов перезапустите службу: sudo systemctl restart cms-youwebsite. При запуске
она тоже пересобирает все страницы. Если страницы собрать не удалось, материалы всё равно
сохраняются, редактор видит предупреждение, а причина пишется в журнал службы
(journalctl -u <служба>).
Подробный порядок зависит от выбранного хостинга и домена. Рабочие секреты в этот каталог не добавляются.
Установка вручную, по командам
То же, что делает sudo bash install.sh, по шагам. Команды проверены на
настоящем сервере (Ubuntu 26.04, 1 ядро, 1 ГБ памяти).
1. Установить nginx (на сервере)
Все команды — на сервере, от root, в папке распакованного архива:
cd /root/cms-youwebsite-2.0.0
apt-get update && apt-get install -y nginx certbot
2. Выложить сайт
install -d /etc/cms-youwebsite
printf '{"url": "https://ВАШ-ДОМЕН", "name": "Название сайта", "indexable": false}\n' > /etc/cms-youwebsite/site.json
install -m 755 server/site_release.py /usr/local/sbin/cms-youwebsite-release
cms-youwebsite-release dist --no-service
Сайт лежит в /var/www/cms-youwebsite/current/. Адрес и название из
/etc/cms-youwebsite/site.json команда подставляет в готовую сборку сама; если
вы собрали сайт со своим адресом в src/content/site.ts, файл не нужен.
3. Установить службу сайта
mkdir -p /opt/cms-youwebsite
cp server/*.py /opt/cms-youwebsite/
rm -f /opt/cms-youwebsite/test_*.py
install -d -m 700 -o www-data -g www-data /var/lib/cms-youwebsite
install -m 755 server/manage_editors.py /usr/local/sbin/cms-youwebsite-users
install -m 755 server/site_setup.py /usr/local/sbin/cms-youwebsite-setup
install -m 640 -o root -g www-data deploy/service.env.example /etc/cms-youwebsite/service.env
/etc/cms-youwebsite/service.env — настройки службы. Править его не нужно: почту
зададите в окнах установки, секрет входа служба создаст сама.
/var/lib/cms-youwebsite/ — данные сайта: тексты, фото, пользователи,
копии. Доступ — только у службы (www-data).
Стартовые публикации. Служба сама их не берёт: без этого шага сайт
запустится пустым. Если в server/seed/ лежат материалы, которые должны
появиться на сайте (публикации клиента или демонстрационные записи), перенесите
их — только при первой установке, пока каталог данных пуст, иначе команда
затрёт рабочие публикации:
test ! -e /var/lib/cms-youwebsite/content.json && \
install -m 600 -o www-data -g www-data server/seed/content.json /var/lib/cms-youwebsite/content.json && \
cp -R server/seed/uploads /var/lib/cms-youwebsite/uploads && \
chown -R www-data:www-data /var/lib/cms-youwebsite/uploads
Если сайт должен начаться без публикаций, пропустите этот шаг.
4. Сертификат HTTPS и nginx
cp deploy/nginx/limits.conf /etc/nginx/conf.d/cms-youwebsite-limits.conf
cp deploy/nginx/security-headers.conf /etc/nginx/snippets/cms-youwebsite-security-headers.conf
cp deploy/nginx/tls.conf /etc/nginx/snippets/cms-youwebsite-tls.conf
cp deploy/nginx/acme-challenge.conf /etc/nginx/snippets/cms-youwebsite-acme-challenge.conf
sed 's/example\.ru/ВАШ-ДОМЕН/g' deploy/nginx/site.conf > /etc/nginx/sites-available/cms-youwebsite.conf
sed 's/example\.ru/ВАШ-ДОМЕН/g' deploy/nginx/first-certificate.conf > /etc/nginx/sites-enabled/cms-youwebsite-first.conf
rm -f /etc/nginx/sites-enabled/default
mkdir -p /var/www/letsencrypt
nginx -t && systemctl reload nginx
Вместо ВАШ-ДОМЕН — ваш домен без https://, например my-school.ru.
Перед выпуском убедитесь, что оба имени уже указывают на сервер (иначе Let's Encrypt откажет, а после нескольких отказов временно заблокирует домен):
dig +short A ВАШ-ДОМЕН; dig +short A www.ВАШ-ДОМЕН # оба — IP сервера
Выпустите сертификат и включите сайт:
certbot certonly --webroot -w /var/www/letsencrypt -d ВАШ-ДОМЕН -d www.ВАШ-ДОМЕН \
--deploy-hook "systemctl reload nginx"
rm /etc/nginx/sites-enabled/cms-youwebsite-first.conf
ln -s /etc/nginx/sites-available/cms-youwebsite.conf /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
При первом запуске certbot спросит почту и согласие с условиями Let's Encrypt.
Если команду запускают без терминала (скриптом), добавьте
--non-interactive --agree-tos и --email АДРЕС или
--register-unsafely-without-email — писем об окончании срока Let's Encrypt
всё равно больше не рассылает.
Сертификат продлевается сам (таймер certbot). Проверьте продление:
certbot renew --dry-run # «all simulated renewals succeeded»
5. Запустить службу и ночные копии
cp deploy/cms-youwebsite.service deploy/cms-youwebsite-backup.service deploy/cms-youwebsite-backup.timer /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now cms-youwebsite.service cms-youwebsite-backup.timer
journalctl -u cms-youwebsite -n 20 --no-pager
В журнале должно быть «Страницы собраны…» и «listening on http://127.0.0.1:8791». Пока владельца нет, в журнале одна подсказка — «Владельца сайта ещё нет. Выполните на сервере sudo cms-youwebsite-setup…»: это следующий шаг.
Дальше — окна установки: cms-youwebsite-setup (INSTALL.md, шаг 3).
Своя сборка из исходников
На компьютере разработчика с Node.js 20+ выполните:
npm ci
npm run check && npm run test:api && npm run build
Отправьте папку на сервер вместе с dist/, исключив node_modules, и запустите
из неё sudo bash install.sh. Адрес и название из исходников-заготовки
установка подставит сама. Устройство исходников описано в
CUSTOMIZATION.md.
Установщик без вопросов и настройка без браузера
sudo bash install.sh --domain my-site.ru --name "Название сайта" --www --demo --yes
--yes подтверждает согласие с условиями Let's Encrypt. По необходимости
укажите --no-www, --no-demo или --email АДРЕС.
Чтобы настроить почту без браузера, выполните sudo cms-youwebsite-setup --mail
или заполните SMTP_HOST, SMTP_PORT, SMTP_SECURITY, SMTP_USERNAME,
SMTP_PASSWORD, SMTP_FROM_EMAIL в /etc/cms-youwebsite/service.env, убрав у
них начальный #. CONTACT_EMAIL задаёт адрес для обращений посетителей.
Если оставить его пустым, используется SMTP_FROM_EMAIL. После правки файла
выполните sudo systemctl restart cms-youwebsite. Настройки в mail.json
имеют приоритет над файлом окружения.
Когда почта настроена, выполните sudo cms-youwebsite-users и создайте
владельца. Нужны логин, почта для кодов входа и пароль от 12 символов.