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.

Правила работы

Сначала читай доки проекта: docs/index.md, docs/access.md, docs/status.md, docs/deploy.md и прошлые сессии (session_search), потом действуй.
Не удаляй файлы и данные пользователя без явного подтверждения (БД data/md2vk.db, secrets/, пользователи). Перезапись/миграция БД — только по явной команде.
Секреты в git не коммитятся: secrets/token_encryption_key, secrets/estorozhenko_api_key.txt, .env — в .gitignore. Токены gitverse/gitea — в /opt/hermes/.hermes/secrets/git-tokens.env (source его, не ищи по каталогам).
Прод-порт 8420 (не 8000 — занят docker-search-api на bigbox). Контейнер слушает 127.0.0.1:8420.
Изменения в прод-код — через git: сначала commit/push в gitverse (истина), gitea подтянет pull mirror.
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.
Рестарт docker на bigbox — локально (docker compose up -d), не на vps02.
Наблюдаемость по умолчанию (делать сразу, не спрашивать): лог авторизации + метрики доступности/успешности/активной сессии. Лог: /opt/md2vk/logs/access.{date}.log (JSONL).
Хэштеги/теги — строчными буквами; документация — с точными маппингами портов и доступов.
Не запускать ручные бэкапы — делает крон (homelab-backup, 2:45).

Команды

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 (пример)

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

4.1 KiB Raw Blame History Unescape Escape