From 8d7a34c134be7c87588843d196dcc1c81f56e3cd Mon Sep 17 00:00:00 2001 From: estorozhenko Date: Sat, 19 Sep 2026 05:50:32 +0000 Subject: [PATCH] =?UTF-8?q?Deploy:=20=D1=81=D0=BB=D1=83=D1=88=D0=B0=D1=82?= =?UTF-8?q?=D1=8C=20=D0=BD=D0=B0=2010.8.0.2:8420=20(WG),=20security.md=20?= =?UTF-8?q?=D1=85=D1=8D=D1=88=20=D0=BF=D0=B0=D1=80=D0=BE=D0=BB=D1=8F,=20AG?= =?UTF-8?q?ENTS.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++ docker-compose.yml | 4 ++- docs/security.md | 4 +-- 3 files changed, 67 insertions(+), 3 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..bba2862 --- /dev/null +++ b/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 ` + - Пароль 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:@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 \ No newline at end of file diff --git a/docker-compose.yml b/docker-compose.yml index 8d477bc..c170ae5 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -4,7 +4,9 @@ services: # Внутренний порт в контейнере — 8420; наружу слушает 127.0.0.1:8420 # (8000 на bigbox занят docker-search-api). Caddy на vps02 → 10.8.0.2:8420. ports: - - "127.0.0.1:8420:8420" + # Слушаем на WG-интерфейсе bigbox (10.8.0.2), т.к. Caddy на vps02 идёт по WireGuard. + # 127.0.0.1 не подходит — vps02 не видит loopback bigbox. Наружу (публичный IP) не слушаем. + - "10.8.0.2:8420:8420" volumes: - ./data:/data - ./logs:/logs diff --git a/docs/security.md b/docs/security.md index f319f4a..61eda59 100644 --- a/docs/security.md +++ b/docs/security.md @@ -6,8 +6,8 @@ - Весь https://md2vk.nixg.ru закрыт HTTP Basic Auth. - Пользователь: **estorozhenko**; пароль — у пользователя, в конфиге только bcrypt-хэш. -- Хэш в Caddyfile: `admin $2a$14$T5gAji7gmg1t3Ifxw0CJy.jat9vpFfOiJIE8j5bnHynEVH1q.QTPS` - (генерируется `docker exec caddy caddy hash-password --plaintext '<пароль>'`). +- Хэш в Caddyfile: `admin $2a$14$uzlQxJdcRZJ5gDpGG5B26OXnudIme1IYe7xh0WtDwFtbB6XiiDYTS` + (сгенерирован 2026-09-18 `docker exec caddy caddy hash-password --plaintext '<пароль>'`). - Без basic auth сервис наружу не отдаётся. ### 2. Внутренний — API-ключ (FastAPI)