13 KiB
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 |
| ... | ... | ... |
При добавлении нового сервиса:
- Authentik → Applications → Create with Provider.
- Provider type: OAuth2/OpenID.
- Redirect URI:
<service>/oauth2/callback(или как требует сервис). - Client type: Confidential.
- Signing key: RSA (не ECC).
- Сохранить Client ID + Secret в Vaultwarden.
💬 Matrix (matrix.buryans.ru)
Стек:
- Synapse (CT 155,
:8008), Dockermatrixdotorg/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-агентов
При получении задачи
- Уточнить, в какой CT/на каком хосте работаем.
- Проверить текущее состояние (
docker ps,pct status, логи). - Не запускать destructive-команды без бэкапа.
- Для изменений
homeserver.yaml— всегдаcp .bak-$(date +%Y%m%d-%H%M%S). - Для SQL — использовать
-P pager=off,-tAcдля скриптов. - Для
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):
- 🟡 Завершить Matrix Sprint (осталось: DR-план, бэкапы остальных сервисов).
- 🔴 Безопасность (ротация паролей,
scram-sha-256) — отложено до конца настройки сервиса. - 🔴 Мониторинг (push-мониторы для бэкапов) — ветка
infra-monitoring. - 🟡 Matrix E2EE (backup, verification) — ждём реальных юзеров.
- 🟢 Документация (runbook'и, DR-план).
При вопросах — docs/matrix-sprint-runbook.md, docs/backlog-matrix.md.