Files
buryan-infra/AGENTS.md
T

13 KiB
Raw Blame History

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: <service>/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 <token>" \
  https://matrix.buryans.ru/_matrix/client/v3/voip/turnServer | jq

# TURN-креды (что Coturn реально принимает)
pct exec 155 -- docker exec matrix-coturn turnutils_uclient \
  -y -u "<username>" -w "<password>" -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/<TOKEN>?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/<service>-backups/ на pve.
  • Offsite: restic на vps:100.64.0.2:/backup/restic-repo.
  • Тег: pve-<service>-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 <db> -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.