Files
buryan-infra/AGENTS.md
T

334 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`.