Описание проекта

Содержание
  1. Требования
  2. Структура
  3. Установка на хостинг
  4. Обновление
  5. Картинки и видео
  6. Темы оформления
  7. Машинный перевод: Gemini или Claude
  8. Полезные команды
  9. Разработка
  10. Релиз

Комета

Личная CMS со статической генерацией: контент хранится в MySQL, а сайт отдаётся готовыми HTML-файлами прямо веб-сервером. PHP работает только в админке (отдельный поддомен), на 404 / редиректах и при ленивой генерации отсутствующих страниц.

Полное техническое задание — в проекте «CMS» на claude.ai.

Статус: 0.4 — этап 2 и доработки медиа: папки, фильтры и поиск в медиатеке, видео MP4/WebM, картинки в тексте разного размера с обтеканием, галереи и просмотр по клику, адреса файлов без даты, копирование страниц, раздел «Блог» в админке. Дальше — этап 3: Cloudflare, IndexNow, отложенная публикация, аналитика, SEO-аудит, бэкапы.

Требования

  • PHP 8.4+ (рекомендуется 8.5): pdo_mysql, mbstring, dom, curl, fileinfo, zip, gd с поддержкой JPEG (желательно ещё WebP и AVIF); желательно intl, OPcache

  • MySQL 8 / MariaDB 10.6+

  • Apache 2.4 с mod_rewrite или nginx

  • Два адреса: сайт (example.com) и поддомен админки (admin.example.com)

Структура

app/            код CMS (src/ — классы, views/ — шаблоны админки)
admin_html/     document root поддомена админки
public_html/    document root сайта: index.php + .htaccess, остальное генерирует CMS
bin/kometa      командная строка
migrations/     миграции базы
config/         config.php (создаёт установщик, в git не попадает)
storage/        кеш, журналы, сессии, медиа, прошлые версии (в git не попадает)
docs/           пример конфигурации nginx
docker/         локальная среда разработки
build/          сборка архива релиза

Наружу смотрят только public_html и admin_html; весь остальной код лежит уровнем выше.

Установка на хостинг

  1. Скачайте kometa-X.Y.Z.zip из релизов и распакуйте в домашнюю папку аккаунта так, чтобы public_html и admin_html оказались рядом с app/.

  2. В панели хостинга:

    • document root основного домена → …/public_html;

    • создайте поддомен админки, document root → …/admin_html;

    • создайте базу MySQL и пользователя.

  3. Откройте адрес админки. Установщик проверит сервер и попросит токен установки — он лежит в файле storage/install-token (откройте через FTP или файловый менеджер). Так никто посторонний не успеет установить сайт раньше вас.

  4. После установки войдите и подключите второй фактор (Google Authenticator, Aegis, 2FAS и т.п.). Сохраните резервные коды.

Для nginx смотрите docs/nginx.conf.

Обновление

На сервере с SSH:

php bin/kometa update            # до последнего релиза
php bin/kometa update v0.2.0     # до конкретной версии
php bin/kometa rollback          # вернуть предыдущую
php bin/kometa releases          # сохранённые версии

Без SSH — в админке: ссылка с номером версии в шапке → «Обновить» (страница /system/update, там же откат). Или залить архив вручную и выполнить php bin/kometa update --file=kometa-X.Y.Z.zip.

Обновление подменяет только код (app/, vendor/, bin/, migrations/, admin_html/, public_html/index.php и т.п.). Конфигурация, storage/ и сгенерированные страницы не трогаются. Предыдущая версия сохраняется в storage/releases/ (последние 3). Миграции базы только «вперёд»: откат возвращает код, но не схему.

Для приватного репозитория укажите в config/config.php → update.token fine-grained токен GitHub с правом Contents: Read-only.

После обновления сайт автоматически пересобирается по новым шаблонам (страницы, у которых HTML не изменился, не перезаписываются).

Картинки и видео

  • Файлы хранятся по адресам вида /media/fa/foto-fa4046-960.webp: fa — начало хеша содержимого, дата загрузки по адресу не видна. Старые адреса с датой (до 0.4) отвечают 301 на новые.

  • На сайт уходят уменьшенные копии ширин из theme.json → image_sizes (по умолчанию 480, 960, 1440, 1920) в AVIF / WebP / JPEG; браузер сам выбирает нужную по srcset и sizes. Оригинал хранится не больше 2560 px по длинной стороне.

  • Размер картинки в тексте — в панели над картинкой в редакторе: во всю ширину текста, большая (540 px), средняя (360 px), маленькая (240 px); обтекание слева / справа / по центру; «Увеличивать по клику» открывает просмотрщик. Несколько картинок рядом — блок «Галерея».

  • Видео MP4 / WebM загружается в медиатеку как есть (без перекодирования), размер ограничен настройками PHP хостинга (upload_max_filesize, post_max_size). Обложка — любая картинка из медиатеки.

Темы оформления

Тема включается в админке: «Темы» → предпросмотр → «Включить» (сайт пересоберётся сам).

Папка

Тема

Характер

Шрифты

default

Комета — стандартная

нейтральная, узкая колонка

системные

paper

Бумага

тёплая, с засечками

системные

meridian

Меридиан

деловая и справочная, синий акцент

Golos Text

journal

Журнал

для статей и блога, шапка по центру, буквица

Literata + контрастная антиква для заголовков

graphite

Графит

техническая, всегда тёмная

JetBrains Mono + Onest

aurora

Аврора

мягкая, текст на белом листе

Manrope

signal

Сигнал

швейцарская типографика: строгая сетка, крупный гротеск, один сигнальный цвет

Inter Tight + JetBrains Mono

bloknot

Блокнот

личный сайт: колонка слева с автором, меню и календарём

Spectral + JetBrains Mono

Все темы, кроме «Графита», следуют светлой или тёмной схеме системы. Шрифты лежат в самой теме (assets/fonts/*.woff2, лицензия OFL), поэтому одинаково выглядят у всех посетителей и не зависят от чужих серверов; в каждом файле латиница и кириллица (русский, украинский, белорусский).

Своя тема со шрифтом: в CSS пути пишутся как в обычном файле из assets/css/ — src: url("../fonts/x.woff2"), движок сам подставит адрес в public_html/assets/<тема>/ с хешем содержимого. Шрифты основного текста стоит перечислить в theme.json → "preload_fonts": ["fonts/x.woff2"], тогда они начнут загружаться раньше.

Машинный перевод: Gemini или Claude

В config/config.php добавьте ключ нужного сервиса:

'gemini' => ['key' => 'AIza…'],      // бесплатно: aistudio.google.com → Get API key
'claude' => ['key' => 'sk-ant-…'],   // platform.claude.com → API Keys, оплата по факту

Сервис, модель и словарь терминов — в админке, «Настройки → Машинный перевод»; там же кнопка «Проверить ключ и пробный перевод». Перевести можно одну страницу (кнопка в редакторе) или несколько (галочки в списке страниц). Переводы сохраняются со статусом «машинный»: новые — черновиком.

Как переводится страница:

  1. Сначала поля — заголовок, анонс, SEO-заголовок и описание, метки.

  2. Затем текст фрагментами по границам блоков (абзацы, списки, таблицы). В каждый запрос модель получает контекст: заголовок и анонс страницы с их переводом и конец предыдущего фрагмента с переводом — так сохраняются термины, обращение и стиль.

  3. Размер фрагмента подбирается сам: Комета продлевает max_execution_time, если хостинг позволяет, читает фактический лимит и измеряет скорость сервиса на каждом фрагменте. При лимите 30 с фрагменты около 1500 символов, при 120 с — 5–8 тысяч (обычная статья уходит одним-двумя запросами). Если хостинг разрешает, поднимите max_execution_time до 120 с.

  4. Фрагмент, на который сервис не успел ответить дважды, делится пополам.

  5. Если модель перегружена (Gemini 503 «high demand» — у новых Flash это бывает часами), запрос сразу уходит в запасные модели из настроек (по умолчанию gemini-flash-lite-latest, gemini-2.5-flash, gemini-2.5-flash-lite). Если заняты все — пауза растёт: 10, 20, 40 с… до 5 минут.

Без ограничения по времени и с максимальными фрагментами переводит консоль:

php bin/kometa translate --missing --langs=en,uk     # всё непереведённое и устаревшее
php bin/kometa translate --pages=12,15 --langs=en    # выбранные страницы
php bin/kometa translate --job=7                     # продолжить задачу, начатую в админке

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

php bin/kometa check                                  # проверить сервер, базу, миграции
php bin/kometa migrate                                # применить миграции
php bin/kometa user:create --email=… --name=…         # ещё один администратор
php bin/kometa user:password [email protected]          # сменить пароль
php bin/kometa user:reset-2fa [email protected]         # потеряли телефон и коды
php bin/kometa cache:clear                            # очистить кеш шаблонов
php bin/kometa build                                  # пересобрать весь сайт

Разработка

docker compose up -d
docker compose exec php composer install

Сайт — http://localhost:8080, админка — http://localhost:8081. В установщике: сервер базы db, база/пользователь/пароль kometa.

Редактор (TipTap + CodeMirror) собирается в admin_html/assets/editor/; собранные файлы лежат в репозитории, Node.js нужен только для изменения редактора:

cd editor && npm ci && npm run build

Проверки (их же запускает GitHub Actions):

composer lint
composer stan
KOMETA_TEST_DB_HOST=127.0.0.1 KOMETA_TEST_DB_PORT=3307 KOMETA_TEST_DB_NAME=kometa \
KOMETA_TEST_DB_USER=root KOMETA_TEST_DB_PASS=root composer test

Релиз

echo "0.2.0" > VERSION
git commit -am "Версия 0.2.0"
git tag v0.2.0
git push && git push --tags

GitHub Actions соберёт kometa-0.2.0.zip с зависимостями и контрольной суммой и опубликует релиз.