AGENTS.md: full infra guide with Matrix TURN diagnostics, deploy scripts, updated priorities

This commit is contained in:
root committed 2026-09-25 20:13:50 +03:00
1 parent 30f2b33b5d
commit 007cfcf414
1 file changed
+286 -28
+286 -28
View File
@@ -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 <vmid> -- <cmd> # внутри 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: `<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)
- 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 недель стабильной работы.
- `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!)
@@ -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/<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`.