# AGENTS.md Руководство для AI-агентов, работающих с инфраструктурой buryan-hub. **Last updated:** 2026-09-25 **Maintainer:** Роман **Repo:** `git.buryans.ru/root/buryan-infra` --- ## 🏗 Архитектура Инфраструктура живёт на **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) - Headscale: CT 155 зарегистрирован как `100.64.0.4` (нода `ct155`) - 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 недель стабильной работы. - **TURN работает через VPS** (порт 3479 UDP/TCP), не напрямую. Схема: клиент → VPS DNAT → Headscale → CT 155 Coturn. Если TURN не работает — проверить `iptables` на VPS, скрипт `scripts/vps-turn-proxy-setup.sh`. - **CT 155 зарегистрирован в Headscale** (`100.64.0.4`). Если пропадёт — `pct exec 155 -- tailscale status`. - DNS внутри CT 155: `/etc/resolv.conf` **не должен** указывать на `100.100.100.100` (MagicDNS Headscale ломает резолвинг). Должен быть `192.168.1.1`. - `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!) /root/secrets-master-catalog.sh # главный каталог (права 600) /root/.gitea_api # Gitea API token /root/.n8n_api # N8N API key /root/.bw-secrets # Bitwarden credentials --- ## 📚 Соглашения ### Именование CT - Сервисы — по имени сервиса (`matrix`, `gitea`, `authentik`). - Роль в скобках в мониторинге: `Authentik (CT 114)`, `Postgres (CT 151)`. ### Работа с секретами - **НЕ логировать** пароли, токены, ключи в 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. ### Инфраструктура под Git (с 28.10.2026) - Все 26 CT с Docker описаны в `deploy/ctNNN/docker-compose.yml`. Секреты — в `.env` рядом (chmod 600), в Git только `env.example`. - Compose-файлы генеративные: `ops/scripts/docker-to-compose.py NNN --write --force --env-out`. Руками править можно, но следующая генерация перезапишет — правьте генератор. - **Перед удалением контейнеров** обязательна сверка: `python3 ops/scripts/check-compose-parity.py NNN` → должно быть 0 расхождений. Проверяет image, entrypoint, command, ключи env, монтирования, порты. - **Проверять плагин**: `pct exec NNN -- docker compose version`. Без него `up -d` молча не выполнится, а контейнеры уже удалены. Если плагина нет: `docker-compose-linux-x86_64` в `/usr/local/lib/docker/cli-plugins/` (в CT113 нужен v2.24.7: dockerd там 20.10, API 1.41). - Удалять контейнеры по одному (`docker rm -f NAME` в цикле): команда с несколькими именами прерывается на первом отсутствующем. - Снапшот невозможен на 12 CT с bind-монтированиями (103, 105, 109, 111, 117, 118, 120, 123, 125, 126, 155, 160): `pct snapshot` вернёт «snapshot feature is not available». Вместо него — `cp /etc/pve/lxc/NNN.conf`, при серьёзных работах `vzdump`. - Реестр автоматизаций генерируется: `ops/scripts/build-automations-registry.py`. ### Инструменты диагностики # 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`.