AGENTS.md: full infra guide with Matrix TURN diagnostics, deploy scripts, updated priorities
This commit is contained in:
1 parent
30f2b33b5d
commit
007cfcf414
1 file changed
+286
-28
@@ -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`.
|
||||
Reference in new issue
Block a user