Описание проекта
Содержание
Комета
Личная 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; весь остальной код лежит уровнем выше.
Установка на хостинг
-
Скачайте
kometa-X.Y.Z.zipиз релизов и распакуйте в домашнюю папку аккаунта так, чтобыpublic_htmlиadmin_htmlоказались рядом сapp/. -
В панели хостинга:
-
document root основного домена →
…/public_html; -
создайте поддомен админки, document root →
…/admin_html; -
создайте базу MySQL и пользователя.
-
-
Откройте адрес админки. Установщик проверит сервер и попросит токен установки — он лежит в файле
storage/install-token(откройте через FTP или файловый менеджер). Так никто посторонний не успеет установить сайт раньше вас. -
После установки войдите и подключите второй фактор (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). Обложка — любая картинка из медиатеки.
Темы оформления
Тема включается в админке: «Темы» → предпросмотр → «Включить» (сайт пересоберётся сам).
Папка |
Тема |
Характер |
Шрифты |
|---|---|---|---|
|
Комета — стандартная |
нейтральная, узкая колонка |
системные |
|
Бумага |
тёплая, с засечками |
системные |
|
Меридиан |
деловая и справочная, синий акцент |
Golos Text |
|
Журнал |
для статей и блога, шапка по центру, буквица |
Literata + контрастная антиква для заголовков |
|
Графит |
техническая, всегда тёмная |
JetBrains Mono + Onest |
|
Аврора |
мягкая, текст на белом листе |
Manrope |
|
Сигнал |
швейцарская типографика: строгая сетка, крупный гротеск, один сигнальный цвет |
Inter Tight + JetBrains Mono |
|
Блокнот |
личный сайт: колонка слева с автором, меню и календарём |
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, оплата по факту
Сервис, модель и словарь терминов — в админке, «Настройки → Машинный перевод»; там же кнопка «Проверить ключ и пробный перевод». Перевести можно одну страницу (кнопка в редакторе) или несколько (галочки в списке страниц). Переводы сохраняются со статусом «машинный»: новые — черновиком.
Как переводится страница:
-
Сначала поля — заголовок, анонс, SEO-заголовок и описание, метки.
-
Затем текст фрагментами по границам блоков (абзацы, списки, таблицы). В каждый запрос модель получает контекст: заголовок и анонс страницы с их переводом и конец предыдущего фрагмента с переводом — так сохраняются термины, обращение и стиль.
-
Размер фрагмента подбирается сам: Комета продлевает
max_execution_time, если хостинг позволяет, читает фактический лимит и измеряет скорость сервиса на каждом фрагменте. При лимите 30 с фрагменты около 1500 символов, при 120 с — 5–8 тысяч (обычная статья уходит одним-двумя запросами). Если хостинг разрешает, поднимитеmax_execution_timeдо 120 с. -
Фрагмент, на который сервис не успел ответить дважды, делится пополам.
-
Если модель перегружена (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 с зависимостями и контрольной суммой и опубликует релиз.