334 lines
15 KiB
Markdown
334 lines
15 KiB
Markdown
# 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.
|
||
|
||
### Инфраструктура под 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 <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`.
|