Микропортал — инструкция

Сайт hommforever.ru — это статический микропортал на nginx, без backend и базы данных. Здесь — общее устройство, доступ к серверу, разбивка на блоки и как править каждый из них.

Содержание

Разделы
Технологии и хостинг
Доступ: SSH, sudo, права
Что лежит на сервере
Главная страница /
Разделы (блоки) портала
Nginx и SSL
Типичный процесс правки
Бэкапы и безопасность
Кэширование браузера
Администрирование (локальный MCP-сервер)

1. Разделы

Раздел	Кратко	Инструкция
Игры	HTML-игры из реестра `games.tsv`, открываются через iframe-обёртку.	/games/help.html
Демки	Самодостаточные HTML-демонстрации из реестра `demos.tsv`.	/demos/help.html
Файлы	Файлообменник: список файлов автоматически обновляется из серверного хранилища.	/files/help.html
Утилиты	Небольшие HTML-инструменты из реестра `utils.tsv`.	/utils/help.html

Помимо публичных разделов есть отдельный административный инструмент — локальный MCP-сервер для управления контентом. См. раздел 12. Администрирование.

2. Технологии и хостинг

Сервер: Yandex Cloud VM, IP 158.160.96.21.
ОС: Ubuntu (systemd, Bash, Python 3).
Веб-сервер: nginx 1.24, конфиг /etc/nginx/sites-enabled/hommforever.ru (или дефолтный конфиг сайта).
SSL: Let’s Encrypt через certbot, авто-обновление.
Корень сайта: /var/www/hommforever.ru/.
Домен: hommforever.ru, www.hommforever.ru → 301 на основной.
Никакого backend. Все страницы — статика. Где есть «генератор» (например, в /demos/) — он запускается вручную и пишет статический HTML.

3. Доступ: SSH, sudo, права

ssh hommforever@158.160.96.21

У пользователя hommforever есть sudo без пароля. Файлы сайта принадлежат root:root с правами 644 (директории 755) — поэтому правка через sudo:

sudo nano /var/www/hommforever.ru/index.html
sudo cp ... ; sudo mv ... ; sudo chown root:root ... ; sudo chmod 644 ...

Не используй --no-verify, chmod 777 и не ломай SSL-конфиги, размеченные как # managed by Certbot. Если что-то меняешь в nginx — обязательно sudo nginx -t перед sudo systemctl reload nginx.

4. Что лежит на сервере

/var/www/hommforever.ru/
├── index.html           ← главная страница портала (3 карточки)
├── assets/
│   └── icons/           ← общие иконки разделов (PNG)
├── games/              ← блок «Игры» (см. отдельную инструкцию)
│   └── index.html       ← блок «Игры»
├── demos/               ← блок «Демки» (см. отдельную инструкцию)
│   ├── demos.tsv        ← реестр демок
│   ├── build-index.py   ← генератор index.html
│   ├── rebuild.sh       ← запуск генератора
│   ├── view.html        ← iframe-обёртка
│   ├── help.html        ← инструкция по блоку
│   ├── README.md
│   ├── index.html       ← сгенерированный список
│   └── items/           ← сами HTML-демки
├── files/
│   ├── index.html       ← страница файлообменника
│   └── storage/         ← папка, из которой файлы автоматически попадают в список
├── utils/               ← блок «Утилиты» (см. отдельную инструкцию)
│   ├── utils.tsv        ← реестр утилит
│   ├── build-index.py   ← генератор index.html
│   ├── rebuild.sh       ← запуск генератора
│   ├── view.html        ← iframe-обёртка
│   ├── help.html        ← инструкция по блоку
│   ├── README.md
│   ├── index.html       ← сгенерированный список
│   └── items/           ← сами HTML-утилиты
├── apps/                ← резерв (placeholder)
├── files-games/         ← резерв (placeholder)
└── help/
    └── index.html       ← эта инструкция

5. Главная страница `/`

Файл: /var/www/hommforever.ru/index.html. Это самостоятельный HTML — стили inline, иконки из /assets/icons/. Содержит четыре карточки-ссылки: «Игры», «Демки», «Файлообменник», «Утилиты». Карточки целиком кликабельны (тег <a class="card">).

Чтобы поменять заголовок, описание или добавить пятый раздел — редактируй HTML напрямую. Никакого генератора у главной нет.

6. Разделы (блоки) портала

URL	Папка	Чем управляется
`/`	`/var/www/hommforever.ru/`	Ручной HTML.
`/demos/`	`demos/`	Реестр `demos.tsv` + генератор `build-index.py`. Подробная инструкция.
`/games/`	`games/`	Реестр `games.tsv` + генератор `build-index.py` по модели `/demos/`. Подробная инструкция.
`/files/`	`files/`	Файлообменник: статическая страница `/files/index.html` каждую секунду читает динамический `/files/index.json`; nginx проксирует JSON на Python-сервис `hommforever-files-api.service`, который сканирует `/var/www/hommforever.ru/files/storage/`. Подробная инструкция по «Файлам».
`/utils/`	`utils/`	Реестр `utils.tsv` + генератор `build-index.py` по модели `/demos/`. Подробная инструкция.
`/apps/`	`apps/`	Резерв, минимальный заглушечный `index.html`.
`/files-games/`	`files-games/`	Резерв, минимальный заглушечный `index.html`.
`/help/`	`help/`	Эта инструкция и справка по локальному MCP-серверу.

Каждый раздел — самодостаточный набор файлов в своей папке. Стили либо inline, либо в общем стиле «glassmorphism dark» (тёмный фон с радиальными градиентами + полупрозрачные панели + blur).

7. Файлообменник /files/

Раздел /files/ — публичная страница для скачивания файлов из серверной папки /var/www/hommforever.ru/files/storage/. HTML страницы находится в /var/www/hommforever.ru/files/index.html.

Архитектура и поток данных

Пользователь открывает https://hommforever.ru/files/.
JavaScript на странице запускает асинхронный polling: каждую 1 секунду делает fetch('/files/index.json', { cache: 'no-store' }).
/files/index.json — JSON-индекс списка файлов. Он генерируется локальным Python-сервисом на сервере.
nginx проксирует /files/index.json на локальный Python-сервис hommforever-files-api.service (/opt/hommforever-files-api/server.py), который сканирует папку /var/www/hommforever.ru/files/storage/ и публикует только разрешённые файлы. Подробности: инструкция по «Файлам».
Страница сравнивает сигнатуру списка: name, size, mtime/created, url и человекочитаемый размер. Если сигнатура не изменилась, таблица не перерисовывается; обновляется только статус проверки.
При первом успешном запросе список обязательно отрисовывается, даже если он пустой.

Что видно пользователю

Имя файла — кликабельная ссылка на скачивание или открытие.
Дата файла — берётся из created или mtime из JSON.
Размер файла — показывается как size_human, если поле есть, иначе как числовой size.
Статус автообновления — время последнего обновления списка или проверки без изменений.

Как добавить файл

Подключиться к серверу: ssh hommforever@158.160.96.21.
Скопировать файл в папку источника: /var/www/hommforever.ru/files/storage/. Например: cp report.pdf /var/www/hommforever.ru/files/storage/.
Убедиться, что файл читается веб-сервером. Обычно достаточно прав 644 для файла и 755 для директории.
В течение 1 секунды Python-сервис отдаст обновлённый /files/index.json, а открытая страница /files/ сама увидит изменение и перерисует список.

Как удалить файл

Удалить файл из /var/www/hommforever.ru/files/storage/, например: rm /var/www/hommforever.ru/files/storage/old-report.pdf.
В течение 1 секунды файл исчезнет из /files/index.json.
Открытая страница /files/ автоматически получит новый JSON и уберёт строку из таблицы без ручного обновления.

Фильтрация и безопасность

В публичный список не должны попадать скрытые и служебные элементы: имена, начинающиеся с точки, .DS_Store, временные/служебные файлы и потенциально исполняемые файлы. Исполняемые форматы лучше не размещать в файлообменнике; для публикации использовать обычные документы, архивы, изображения, текстовые файлы и другие безопасные статические файлы.

Тестовые файлы

Для проверки автообновления созданы два текстовых файла в /var/www/hommforever.ru/files/storage/: test-file-1.txt и test-file-2.txt. Они отображаются на /files/, присутствуют в /files/index.json и доступны для скачивания как обычные файлы.

8. Nginx и SSL

Nginx-конфиг сайта (упрощённо):

server {{
    server_name hommforever.ru www.hommforever.ru 158.160.96.21 _;
    root /var/www/hommforever.ru;
    index index.html;
    charset utf-8;
    location / {{ try_files $uri $uri/ =404; }}
    listen 443 ssl;
    # ssl_certificate ... managed by Certbot
}}

Любой подзапрос отдаётся напрямую из файловой системы; директории — через index.html.
HTTP редиректится на HTTPS (через certbot-блок).
Сертификаты обновляются автоматически (/etc/cron.d/certbot или systemd-таймер).
После правки конфига: sudo nginx -t && sudo systemctl reload nginx.

9. Типичный процесс правки

Подключиться: ssh hommforever@158.160.96.21 (или редактировать локально и scp на сервер).
Сохранить бэкап изменяемого файла:
```
sudo cp file.html file.html.bak.$(date +%Y%m%d%H%M%S)
```
Внести правки (sudo nano или scp с локальной машины).
Если правка в /demos/ — пересобрать: sudo /var/www/hommforever.ru/demos/rebuild.sh. Если правка в /games/ — пересобрать: sudo /var/www/hommforever.ru/games/rebuild.sh.
Открыть страницу в браузере с жёстким перезагрузом: Cmd/Ctrl+Shift+R.

10. Бэкапы и безопасность

Перед любой правкой — cp file file.bak.$(date ...). В репозитории это видно как *.bak.YYYYMMDDHHMMSS; периодически чисти их (ls *.bak.*, удалить устаревшие).
Не коммить и не выкладывай .env, ключи Certbot (/etc/letsencrypt/), приватные SSH-ключи.
Загруженные пользовательские файлы (если будут) — в отдельные папки с явным chown www-data:www-data; никогда не давай 755+ записи на корень сайта.

11. Кэширование браузера

Nginx по умолчанию отдаёт статику без агрессивных Cache-Control, но браузер всё равно может закэшировать HTML/JS. Если правка не видна:

Жёсткий перезагруз: Cmd+Shift+R (macOS) или Ctrl+Shift+R.
Если файл подгружается через iframe (как в /demos/view.html?demo=... или /games/view.html?game=...) — обновить именно эту вкладку, а не родителя.
Для критических ресурсов (картинки, иконки) удобно использовать query-string версию: /assets/icons/demos-transparent.png?v=4 — менять v при правке файла.

12. Администрирование (локальный MCP-сервер)

Для управления контентом разделов (демки, игры, утилиты, файлообменник) на сервере поднят локальный hommforever-site-mcp — административный MCP-сервер. Это не публичная часть сайта: он слушает только 127.0.0.1, не проксируется через nginx и используется при администрировании по SSH.

Подробная справка с командами, путями и списком tools — на отдельной странице: /help/mcp.html.

Исходник этой страницы: /var/www/hommforever.ru/help/index.html.