Deploy: слушать на 10.8.0.2:8420 (WG), security.md хэш пароля, AGENTS.md

AGENTS.md

@@ -0,0 +1,62 @@
+# AGENTS.md — инструкции для агентов (Hermes и др.), работающих с /opt/md2vk
+
+## О проекте
+
+md2vk — сервис публикации Markdown на стену VK через официальный VK API (wall.post + format_data).
+FastAPI + SQLAlchemy async + SQLite + Fernet. Документация — в `docs/`, начни с `docs/index.md` и `docs/access.md`.
+
+## Правила работы
+
+1. **Сначала читай доки проекта**: `docs/index.md`, `docs/access.md`, `docs/status.md`,
+   `docs/deploy.md` и прошлые сессии (`session_search`), потом действуй.
+2. **Не удаляй файлы и данные пользователя** без явного подтверждения (БД `data/md2vk.db`,
+   `secrets/`, пользователи). Перезапись/миграция БД — только по явной команде.
+3. **Секреты в git не коммитятся**: `secrets/token_encryption_key`,
+   `secrets/estorozhenko_api_key.txt`, `.env` — в .gitignore. Токены gitverse/gitea — в
+   `/opt/hermes/.hermes/secrets/git-tokens.env` (source его, не ищи по каталогам).
+4. **Прод-порт 8420** (не 8000 — занят docker-search-api на bigbox). Контейнер слушает 127.0.0.1:8420.
+5. **Изменения в прод-код** — через git: сначала commit/push в gitverse (истина), gitea подтянет pull mirror.
+6. **Caddy/fail2ban живут на vps02** (ssh-алиас `vps02`, sudo по ключу):
+   - Caddyfile: `/opt/caddy/Caddyfile`, reload: `docker exec caddy caddy reload --config /etc/caddy/Caddyfile`
+   - fail2ban: jail `md2vk`, ban после 5 попыток, unban: `sudo fail2ban-client -c /etc/fail2ban unban <ip>`
+   - Пароль basic auth — только bcrypt-хэш в Caddyfile; генерировать `docker exec caddy caddy hash-password`.
+7. **Рестарт docker на bigbox** — локально (`docker compose up -d`), не на vps02.
+8. **Наблюдаемость по умолчанию** (делать сразу, не спрашивать): лог авторизации +
+   метрики доступности/успешности/активной сессии. Лог: `/opt/md2vk/logs/access.{date}.log` (JSONL).
+9. **Хэштеги/теги — строчными буквами**; документация — с точными маппингами портов и доступов.
+10. **Не запускать ручные бэкапы** — делает крон (homelab-backup, 2:45).
+
+## Команды
+
+```bash
+cd /opt/md2vk
+make docker-up        # собрать+поднять (или: docker compose up -d --build)
+curl -s http://127.0.0.1:8420/api/v1/health              # {"status":"ok"}
+docker logs md2vk     # логи контейнера
+ls -t logs/           # аудит-лог (JSONL)
+```
+
+## Публикация через API (пример)
+
+```bash
+API_KEY=$(cat secrets/estorozhenko_api_key.txt)
+curl -s http://127.0.0.1:8420/api/v1/publish \
+  -H "Content-Type: application/json" \
+  -d "{\"api_key\":\"$API_KEY\",\"vk_account_id\":1,\"message_md\":\"**Привет** из md2vk\"}"
+```
+
+Сначала добавить VK-аккаунт: `POST /api/v1/accounts` c `access_token` (VK OAuth-токен, scope wall).
+
+## Git-схема
+
+- Истина: gitverse.ru (kpa39l/md2vk) — push через `https://kpa39l:<PAT>@gitverse.ru/kpa39l/md2vk.git`
+  (SSH-ключ ~/.ssh/gitverse также работает); PAT в `/opt/hermes/.hermes/secrets/git-tokens.env` ($GITVERSE_PAT)
+- Зеркало: gitea.nixg.ru (estorozhenko/md2vk) — pull mirror, обновляется автоматически (8h)
+- Ветки: main (default)
+
+## Ключевые лица/доступы
+
+- Владелец: estorozhenko (пользователь Hermes), kpa39l (gitverse-аккаунт, email kpa39l@yandex.ru)
+- vps02: 87.242.100.206 (estorozhenko, sudo по ключу), Caddy + fail2ban
+- bigbox: 10.8.0.2 (локальный хост), проект /opt/md2vk
+- DNS: nixg.ru (Jino), A-запись md2vk → 87.242.100.206