diff --git a/AGENTS.md b/AGENTS.md index 6190d1a..639f5a2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,23 +1,220 @@ -# 🤖 Agent Guide — buryan-hub Infrastructure +# AGENTS.md -**Точка входа для любого AI-агента.** Обновлено: 2026-09-25 +Руководство для AI-агентов, работающих с инфраструктурой buryan-hub. -## 🏗️ Архитектура -- **Proxmox VE (PVE):** 192.168.1.10, 29 LXC контейнеров -- **VPS (публичный):** 193.233.210.184 (nginx, Let's Encrypt) -- **Домены:** *.buryans.ru (n8n, vault, finance, music, ...) +**Last updated:** 2026-09-25 +**Maintainer:** Роман +**Repo:** `git.buryans.ru/root/buryan-infra` -## 🔌 Подключение +--- - ssh root@192.168.1.10 # PVE - pct exec -- # внутри CT - ssh root@193.233.210.184 # VPS +## 🏗 Архитектура + +Инфраструктура живёт на **Proxmox VE** (pve, `192.168.1.10`). +Сервисы раскиданы по LXC-контейнерам (CT) и VM. + +### Ключевые узлы + +| Узел | IP | Роль | +|---|---|---| +| **pve** | `192.168.1.10` | Proxmox хост | +| **vps** | `193.233.210.184` / Headscale `100.64.0.2` | Внешний сервер (nginx, edge) | +| **CT 151** | `192.168.1.151` | PostgreSQL 17 (общая БД) | +| **CT 155** | `192.168.1.155` | Matrix Synapse + Element + Coturn + LiveKit | +| **CT 140** | `192.168.1.140` | Gitea | +| **CT 134** | `192.168.1.134` | Prometheus / monitoring | +| **CT 114** | — | Authentik (SSO) | +| **CT 108** | — | n8n (автоматизация) | +| **CT 109** | — | Vaultwarden | + +### Сеть / VPN + +- **Headscale** (`headscale.buryans.ru`) — self-hosted Tailscale control plane. +- Tailnet: **`buryan-hub`** (`100.64.0.x`). +- **DNS:** `100.100.100.100` (Headscale DNS). + +--- + +## 🔐 SSO / Authentik + +Все сервисы используют **единый SSO** через Authentik (`authentik.buryans.ru`). + +| Сервис | Application slug | Тип | +|---|---|---| +| Matrix | `matrix` | OIDC | +| Gitea | `gitea` | OIDC | +| Grafana | `grafana` | OIDC | +| ... | ... | ... | + +**При добавлении нового сервиса:** +1. Authentik → Applications → Create with Provider. +2. Provider type: OAuth2/OpenID. +3. Redirect URI: `/oauth2/callback` (или как требует сервис). +4. Client type: Confidential. +5. Signing key: **RSA** (не ECC). +6. Сохранить Client ID + Secret в Vaultwarden. + +--- + +## 💬 Matrix (matrix.buryans.ru) + +**Стек:** +- Synapse (CT 155, `:8008`), Docker `matrixdotorg/synapse:latest` +- PostgreSQL 17 (CT 151, `matrix_db`) +- Element Web (`element.buryans.ru`, CT 155, `:8088`) +- Coturn (CT 155, `:3478`, `:5349`) +- LiveKit (CT 155, `:7880`, host network) +- nginx (vps, `:443` + `:8448`) + +**OIDC:** Authentik, issuer `https://authentik.buryans.ru/application/o/matrix/`. +**Federation:** выключена (`federate: false`). + +### Полезные команды + + # Статус + pct exec 155 -- docker ps + pct exec 155 -- docker logs --tail 50 -f matrix-synapse + + # БД + pct exec 151 -- sudo -u postgres psql -P pager=off -d matrix_db -c "\dt" | head -20 + + # Юзеры + pct exec 151 -- sudo -u postgres psql -P pager=off -d matrix_db -tAc "SELECT name, admin FROM users;" + + # Бэкап вручную + /root/matrix-backups/backup-matrix.sh + + # Offsite вручную + /opt/buryan-hub/scripts/offsite-backup.sh + + # Restic + export RESTIC_REPOSITORY="sftp:root@100.64.0.2:/backup/restic-repo" + export RESTIC_PASSWORD_FILE="/root/.restic-password" + restic snapshots --tag pve-matrix-backups + + # TURN endpoint (что Synapse отдаёт клиенту) + curl -sS -H "Authorization: Bearer " \ + https://matrix.buryans.ru/_matrix/client/v3/voip/turnServer | jq + + # TURN-креды (что Coturn реально принимает) + pct exec 155 -- docker exec matrix-coturn turnutils_uclient \ + -y -u "" -w "" -p 3478 -v 192.168.1.155 + # Ожидаем: allocate/refresh success. channel bind 403 = норма (артефакт утилиты) + +### Файлы и секреты + +| Что | Путь | На каком хосте | +|---|---|---| +| `homeserver.yaml` | `/opt/matrix/data/homeserver.yaml` | CT 155 | +| Signing key | `/opt/matrix/data/matrix.buryans.ru.signing.key` | CT 155 | +| Turnserver config | `/opt/matrix/config_gen/turnserver.conf` | CT 155 | +| Postgres пароль | `/root/.matrix-pg-pass` | pve | +| Restic пароль | `/root/.restic-password` | pve | +| Signing key backup | `/root/matrix-signing.key.backup` | pve | +| Локальные бэкапы | `/root/matrix-backups/` | pve | +| `deploy-matrix-v2.sh` | `~/buryan-infra/deploy-matrix-v2.sh` | pve | +| `backup-matrix.sh` | `/root/matrix-backups/backup-matrix.sh` | pve | +| `offsite-backup.sh` | `/opt/buryan-hub/scripts/offsite-backup.sh` | pve | +| `restore-test.sh` | `/opt/buryan-hub/scripts/restore-test.sh` | pve | +| Runbook Matrix | `docs/matrix-sprint-runbook.md` | репо | +| Backlog Matrix | `docs/backlog-matrix.md` | репо | + +### Бэкапы + +| Задача | Скрипт | Cron | Что бэкапит | Ротация | +|---|---|---|---|---| +| Local | `/root/matrix-backups/backup-matrix.sh` | `30 3 * * *` | pg_dump + media + config | 7/7/30 дней | +| Offsite | `/opt/buryan-hub/scripts/offsite-backup.sh` | `0 5 * * *` | `/root/matrix-backups/` через restic | 7d/4w/12m | +| Restore test | `/opt/buryan-hub/scripts/restore-test.sh` | `0 6 * * 0` (план) | Восстановление в тестовую БД | — | + +**Restic tag:** `pve-matrix-backups`. +**Restic repo:** `145d2cea69` на vps `100.64.0.2:/backup/restic-repo`. + +### Что НЕ делать + +- ❌ Не менять `localpart_template` в `homeserver.yaml` — сломает существующих юзеров. +- ❌ Не переименовывать юзеров в Authentik — Synapse создаст **нового** пользователя. +- ❌ Не запускать `deploy-matrix-v2.sh` на проде без бэкапа — там `DROP DATABASE`. +- ❌ Не трогать `signing.key` — иначе клиенты увидят «server signing key changed». +- ❌ Не редактировать `homeserver.yaml` без бэкапа — `cp` в `.bak-$(date)`. + +### Известные проблемы + +- Display name в Element показывается как `admin` вместо `akadmin` (OIDC `{{ user.name }}`). +- Offsite через Headscale идёт по DERP-релею (~50ms latency, UDP заблокирован). +- SQLite-файл `homeserver.db.old-sqlite-20260925-153527` — удалить после 2-4 недель стабильной работы. +- `turnutils_uclient` возвращает `channel bind: 403` при тестах — это норма, не баг (утилита не создаёт permission перед bind). Реальные звонки Element работают корректно. +- Звонок самому себе в Element запрещён («You cannot place a call with yourself») — для теста WebRTC нужны 2 разных пользователя (отложено до реальных чатов). + +--- + +## 🗄 PostgreSQL (CT 151) + +Единая БД для большинства сервисов. + +| База | Владелец | Сервис | +|---|---|---| +| `matrix_db` | `matrix` | Matrix Synapse | +| `authentik_db` | `authentik_user` | Authentik | +| `n8n` | `postgres` | n8n | +| `gitea` | — | Gitea | +| `mealie_db` | `mealie_user` | Mealie | +| `immich_db` | `immich_user` | Immich | +| `nextcloud_db` | `nextcloud_user` | Nextcloud | +| `paperless_db` | `paperless_user` | Paperless | +| `firefly_db` | `firefly_user` | Firefly III | +| `buryan_hub`, `buryan_monitor`, `buryan_monitoring`, `headscale`, `n8n_central`, `n8n_prod` | разные | Внутренние | + +**Подключение из LAN:** `pg_hba.conf` разрешает `192.168.1.0/24` с `md5`. +**Не реализовано (в бэклоге):** переход на `scram-sha-256` + точечные правила. + +### Полезное + + # Список БД + pct exec 151 -- sudo -u postgres psql -P pager=off -c "\l" + + # Размер + pct exec 151 -- sudo -u postgres psql -P pager=off -tAc "SELECT pg_size_pretty(pg_database_size('matrix_db'));" + +--- + +## 📊 Мониторинг + +**Uptime Kuma:** `status.buryans.ru` (15+ мониторов). +**n8n workflow:** Uptime Kuma → Webhook → Gitea Issue → Telegram (`@BotFather` bot). +**Gitea:** `git.buryans.ru`, метка `auto-fix` (label 2) для автоматически созданных issues. + +### Push-мониторы для cron-задач + +Cron-скрипты (бэкапы) должны пушить в Uptime Kuma по завершении: + + curl -fsS -m 10 "https://status.buryans.ru/api/push/?status=up&msg=OK" > /dev/null || true + +Если пуш не приходит >24 часа → алерт в Telegram. + +**Push-токены (в бэклоге, ветка `infra-monitoring`):** +- Matrix Backup +- Offsite Backup +- Buryan-hub Backup +- Matrix Restore Test + +--- + +## 📂 Структура репо -## 📂 Ключевые файлы - `AGENTS.md` — этот файл - `ops/inventory-YYYYMMDD/` — снимок инфраструктуры - `ops/data-registry.md` — реестр БД - `ops/sprint1/`, `ops/sprintA/` — скрипты спринтов +- `docs/` — runbook'и и backlog'и +- `scripts/` — общие скрипты (в т.ч. `restore-test.sh`) +- `deploy-matrix-v2.sh` — воспроизведение Matrix-стека + +**Быстрый контекст:** + + /root/buryan-infra/ops/locate-infrastructure.sh + +--- ## 🔐 Секреты (локально на PVE, НЕ в git!) @@ -26,25 +223,86 @@ /root/.n8n_api # N8N API key /root/.bw-secrets # Bitwarden credentials -## 🎯 Ключевые сервисы +--- -| Сервис | Порт | CT | -|---|---|---| -| Uptime Kuma | 3001 | 107 | -| Gitea | 3000 | 140 | -| n8n | 5680 | 108 | -| Postgres | 5432 | 151 | -| Authentik | 9000/9443 | 114 | -| Matrix Synapse | 8008 | 155 | -| Vaultwarden | 8081 | 109 | +## 📚 Соглашения -## 🚧 Активные спринты -- **Sprint 1:** monitoring pipeline (DONE) -- **Sprint A:** 15 monitors (DONE) -- **Sprint B:** secrets + standardization (WIP) -- **Matrix Sprint:** 19 задач в Gitea (NEXT) +### Именование CT -## 🆘 Быстрый контекст +- Сервисы — по имени сервиса (`matrix`, `gitea`, `authentik`). +- Роль в скобках в мониторинге: `Authentik (CT 114)`, `Postgres (CT 151)`. - /root/buryan-infra/ops/locate-infrastructure.sh +### Работа с секретами +- **НЕ логировать** пароли, токены, ключи в stdout. +- Пароли хранить в `/root/.*-pass` (chmod 600) **временно**. +- Целевое хранилище — **Vaultwarden** (`vault.buryans.ru`). +- При ротации — обновлять и в Vaultwarden, и в файлах. + +### Бэкапы + +- **Локально:** `/root/-backups/` на pve. +- **Offsite:** restic на `vps:100.64.0.2:/backup/restic-repo`. +- **Тег:** `pve--backups`. +- **Ротация:** 7 дней локально, 7d/4w/12m в restic. + +### Git + +- Репо: `git.buryans.ru/root/buryan-infra` (IaC, deploy-скрипты). +- Ветки: `main`, `sprint/<тема>-<год-месяц>`, `infra-monitoring`. +- PR обязателен для major изменений. + +--- + +## 🤖 Для AI-агентов + +### При получении задачи + +1. Уточнить, в какой CT/на каком хосте работаем. +2. Проверить текущее состояние (`docker ps`, `pct status`, логи). +3. **Не запускать destructive-команды** без бэкапа. +4. Для изменений `homeserver.yaml` — всегда `cp .bak-$(date +%Y%m%d-%H%M%S)`. +5. Для SQL — использовать `-P pager=off`, `-tAc` для скриптов. +6. Для `pct exec` — glob-паттерны раскрываются на pve, оборачивать в `bash -c '...'`. + +### При правке конфигов + +- YAML: `python3 -c "import yaml; yaml.safe_load(open('file'))"`. +- Nginx: `nginx -t` перед `reload`. +- Docker Compose: `docker compose config` перед `up -d`. + +### При работе с секретами + +- Не выводить в чат/логи. +- Проверять длину, а не значение: `echo "length: ${#VAR}"`. +- Если нужно передать — через файл с chmod 600. + +### Инструменты диагностики + + # Matrix БД (в контейнере нет sqlite3, использовать python3) + pct exec 155 -- docker exec matrix-synapse python3 -c " + import sqlite3 + db = sqlite3.connect('/data/homeserver.db') + for row in db.execute('SELECT name FROM users'): + print(row) + " + + # Postgres — напрямую + pct exec 151 -- sudo -u postgres psql -P pager=off -d -tAc "..." + +--- + +## 🚧 Известные бэклоги + +См. `docs/backlog-*.md` в репозитории. + +**Приоритеты (актуально на 2026-09-25):** +1. 🟡 Завершить Matrix Sprint (осталось: DR-план, бэкапы остальных сервисов). +2. 🔴 Безопасность (ротация паролей, `scram-sha-256`) — **отложено до конца настройки сервиса**. +3. 🔴 Мониторинг (push-мониторы для бэкапов) — ветка `infra-monitoring`. +4. 🟡 Matrix E2EE (backup, verification) — ждём реальных юзеров. +5. 🟢 Документация (runbook'и, DR-план). + +--- + +**При вопросах** — `docs/matrix-sprint-runbook.md`, `docs/backlog-matrix.md`.