mirror of
https://gitverse.ru/kpa39l/md2vk.git
synced 2026-09-29 09:55:04 +00:00
estorozhenko
62 lines
4.1 KiB
Markdown
62 lines
4.1 KiB
Markdown
# 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 |