md2vk/README.md

md2vk

Сервис публикации Markdown на стене VK через официальный VK API (wall.post + format_data).

┌─────────────┐     ┌─────────────┐     ┌──────────────┐
│  Hermes     │────▶│  md2vk      │────▶│  VK API      │
│  Agent      │     │  :8420      │     │  wall.post   │
│  (skill)    │◀────│  FastAPI    │     │  vk.com      │
└─────────────┘     └─────────────┘     └──────────────┘

Прод: https://md2vk.nixg.ru (basic auth — см. docs/security.md; Swagger /docs).

Документация

Вся документация — в docs/:

• docs/index.md — указатель, обзор
• docs/access.md — реквизиты и доступы (vps02, Caddy, gitverse, gitea, DNS, VK API)
• docs/architecture.md — архитектура, порты, схема
• docs/vk-api.md — порядок взаимодействия с VK API (OAuth, wall.post, лонгриды)
• docs/security.md — безопасность (basic auth, fail2ban, Fernet, API-ключ)
• docs/deploy.md — деплой (docker, Caddy, fail2ban)
• docs/status.md — статус/история

Инструкции для агентов (Hermes и др.): AGENTS.md.

Возможности

• Публикация Markdown на стене VK с сохранением форматирования
• Конвертация Markdown → VK format_data (JSON) без публикации
• Управление VK-аккаунтами — несколько страниц через один сервис
• Отложенные посты — запись scheduled (планировщик — открытая задача)
• Архив публикаций с фильтрацией по статусу
• Аудит-лог запросов API (JSONL, ротация по дням)

API

Метод	Путь	Описание
GET	/api/v1/health	Проверка работоспособности
GET	/api/v1/accounts	Список VK-аккаунтов
POST	/api/v1/accounts	Добавить VK-аккаунт
DELETE	/api/v1/accounts/{id}	Удалить VK-аккаунт
POST	/api/v1/publish	Опубликовать пост на стене
POST	/api/v1/convert	Конвертировать Markdown (без публикации)
POST	/api/v1/publications	Архив публикаций

Swagger UI: http://127.0.0.1:8420/docs (прод — за basic auth).

Быстрый старт

cd /opt/md2vk
make docker-up        # docker compose up -d --build
curl -s http://127.0.0.1:8420/api/v1/health   # {"status":"ok"}

Детали деплоя и проверки — docs/deploy.md.

Технологии

Python 3.12+, FastAPI, SQLAlchemy 2.0 (async), SQLite (aiosqlite), httpx, cryptography (Fernet), Docker, Caddy, fail2ban.