docs: AI project context (docs/ai) and repository documentation refresh
- docs/ai/: stable, repo-verified context - README, architecture, tech-stack, edge-cases, plan (confirmed active work only), migration-tofu (the blue-green OpenTofu migration runbook and per-service findings), legacy-warning, links. - AGENTS.md: slimmed to a working contract that points at docs/ai instead of restating it; CLAUDE.md is an adapter that @-includes it. - README.md, ansible/README.md, ansible/roles/README.md, roles/lxc_docker_host/README.md: bring wording in line with the current control plane (Makefile entry point, registry, tofu, memoir-bot gone). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012uoq5AVK8mkBgg83Mq6o5V
This commit is contained in:
Dmitry
co-authored by
Claude Sonnet 5
Claude Sonnet 5
parent
5e27ba2513
commit
d2e1e6876a
@@ -0,0 +1,142 @@
|
||||
# Архитектура
|
||||
|
||||
## Контекст и точки входа
|
||||
|
||||
Репозиторий является control plane, а не приложением с единым runtime. Оператор
|
||||
запускает цели `ansible/Makefile`; Make загружает локальные secrets, применяет safety
|
||||
gates и вызывает playbooks. `ansible.cfg` выбирает inventory, roles и локально
|
||||
установленные Galaxy collections.
|
||||
|
||||
Канонические источники:
|
||||
|
||||
- хосты и группы: `ansible/inventory/hosts.yml`;
|
||||
- общий доступ и сеть: `ansible/inventory/group_vars/all/main.yml`;
|
||||
- сводные сведения о сервисах: `ansible/inventory/group_vars/all/services.yml`;
|
||||
- SSH transport: `ansible/ssh_config`;
|
||||
- ручные операции: `ansible/Makefile`.
|
||||
|
||||
Программные потребители реестра:
|
||||
|
||||
- `playbooks/reverse-proxy.yml` — сборка Caddyfile;
|
||||
- `playbooks/ru-vps-base.yml` — стек Caddy и его закреплённый образ;
|
||||
- `playbooks/pve-backup-jobs.yml` — списки VMID заданий PBS (поле `backup.job`);
|
||||
- `roles/backup_audit` — VMID для аудита (флаг `monitoring.backup_audit_vmid`);
|
||||
- `playbooks/validate.yml` — сверка реестра с фактическим состоянием Proxmox.
|
||||
|
||||
Остальное (`pve-*.yml`, `status.yml`, monitoring, SSH config) по-прежнему
|
||||
дублирует значения и должно меняться согласованно.
|
||||
|
||||
## Топология
|
||||
|
||||
- `ru-vps`: public VPS, qdevice, Caddy, OpenVPN server и SSH JumpHost.
|
||||
- `cloud-pc`, `mini-pc`: Proxmox VE nodes.
|
||||
- `lxc_infra`: PBS, OpenVPN gateway и service LXC.
|
||||
- `monitoring`: CT 146 на `cloud-pc`; Uptime Kuma активен, Prometheus stack заморожен.
|
||||
|
||||
Актуальные VMID, placement, IP, ports, domains и backup policy не копируются сюда:
|
||||
их нужно читать из `homelab_services` и сверять с `hosts.yml`.
|
||||
|
||||
## Provisioning Flow
|
||||
|
||||
1. `make deploy-<service>` загружает ignored `.env` из корня репозитория.
|
||||
2. `playbooks/pve-<service>.yml` создает или сверяет LXC.
|
||||
3. Часть playbooks вызывает `roles/pve_lxc` через Proxmox API.
|
||||
4. Остальные подключаются по SSH к PVE node и выполняют `pct create/set/start`.
|
||||
5. Следующий play настраивает LXC, runtime, systemd и health checks.
|
||||
|
||||
Два provisioner-пути имеют разные check-mode и ownership guards. Нельзя переносить
|
||||
service между ними как косметический рефакторинг.
|
||||
|
||||
## Service Runtime
|
||||
|
||||
- Большинство сервисов используют systemd units вокруг `docker run`.
|
||||
- Grimmory использует Compose и отдельный `DOCKER-USER` firewall unit.
|
||||
- Uptime Kuma и сохраненный monitoring stack используют legacy `docker-compose`.
|
||||
- `lxc_docker_host` и `compose_service` описывают будущий общий паттерн, но ни один
|
||||
production playbook их пока не вызывает.
|
||||
|
||||
## Network Flow
|
||||
|
||||
`ansible_ssh_common_args` подключает `ansible/ssh_config`. Обычный путь управления:
|
||||
|
||||
```text
|
||||
controller -> ru-vps:3422 -> 192.168.1.x target
|
||||
```
|
||||
|
||||
`pbs` и `ovpn-mini` являются direct-LAN исключениями. LXC обычно управляются как
|
||||
`root`, а PVE nodes и `ru-vps` - как service account `ansible`.
|
||||
|
||||
OpenVPN site tunnel:
|
||||
|
||||
```text
|
||||
ru-vps 10.78.0.1:8443/tcp <-> ovpn-mini 10.78.0.2 -> 192.168.1.0/24
|
||||
```
|
||||
|
||||
Публичный service flow:
|
||||
|
||||
```text
|
||||
Internet -> Caddy on ru-vps -> OpenVPN -> ovpn-mini -> LAN service
|
||||
```
|
||||
|
||||
Потеря `ru-vps` или site tunnel одновременно влияет на public upstreams и обычный
|
||||
SSH management path.
|
||||
|
||||
## Reverse Proxy
|
||||
|
||||
`playbooks/reverse-proxy.yml` выбирает записи `homelab_services` с блоком `proxy`,
|
||||
валидирует metadata и Caddyfile, обновляет marked blocks и проверяет upstreams.
|
||||
Ansible управляет Caddyfile, но не установкой и lifecycle контейнера Caddy на `ru-vps`.
|
||||
Grimmory OPDS/KOReader routes имеют специальные headers и отключение compression;
|
||||
их нельзя упрощать без device compatibility tests.
|
||||
|
||||
## Backup и Update
|
||||
|
||||
`playbooks/pve-backup-jobs.yml` задает cluster-level PBS schedules. Offsite restic
|
||||
profiles выполняются systemd timers и используют application-aware SQLite backup или
|
||||
MariaDB dump. `roles/backup_audit` проверяет freshness, `restic check` и выборочные
|
||||
restores, после чего атомарно пишет textfile metrics.
|
||||
|
||||
Update playbooks выполняют:
|
||||
|
||||
```text
|
||||
fresh backup/audit -> reapply service declaration -> health verification
|
||||
```
|
||||
|
||||
Backup является prerequisite для ручного recovery, а не автоматическим rollback.
|
||||
|
||||
## Monitoring
|
||||
|
||||
Uptime Kuma в CT 146 является активным monitoring UI. Его роль останавливает и
|
||||
отключает `homelab-monitoring`, сохраняя конфигурацию и данные Prometheus stack.
|
||||
`make monitoring` защищен `CONFIRM=1` и предназначен только для отдельно принятого
|
||||
решения о восстановлении старого stack.
|
||||
|
||||
Exporter roles, groups и backup metrics остаются в репозитории. Hardcoded Prometheus
|
||||
targets могут расходиться с inventory, пока stack заморожен.
|
||||
|
||||
## Grimmory MCP
|
||||
|
||||
`tools/grimmory-mcp/src/server.js` запускает локальный stdio MCP. Grimmory API
|
||||
используется read-only; authentication POST не меняет library data. Явно вызванные
|
||||
sync tools читают API, опционально загружают cover, атомарно обновляют managed sections
|
||||
Obsidian notes и запускают внешний vault index script.
|
||||
|
||||
Sync не является общей транзакцией: full sync может закончиться после частичного
|
||||
набора успешных book updates. Vault path и credential file защищены отдельными
|
||||
проверками, описанными в [`edge-cases.md`](edge-cases.md).
|
||||
|
||||
## Testing Boundaries
|
||||
|
||||
- Ansible имеет static lint и syntax checks, но не имеет Molecule/idempotence harness.
|
||||
- `check.yml` проверяет reachability и expected IP, а не service health.
|
||||
- `status.yml` формирует наблюдательный отчет и не является failing health gate.
|
||||
- Grimmory MCP имеет Node test suite.
|
||||
- Gitea Actions workflow существует, но runner и Actions не активированы.
|
||||
|
||||
## Неизвестно
|
||||
|
||||
- Текущие runtime versions Proxmox VE, OpenVPN, Caddy и restic не закреплены repo manifests.
|
||||
- UI-only состояние AdGuard, Uptime Kuma monitors и часть service credentials не может
|
||||
быть установлена из репозитория.
|
||||
- Наличие DHCP reservation для Grimmory и намеренность отсутствия backup CT 148
|
||||
требуют проверки оператором.
|
||||
Reference in New Issue
Block a user