Files
buryan-infra/ops/wiki/build_wiki.py
T
buryan-agent 43502690c9 Политика: перезапуск — класс C с подтверждением; заявки в Matrix
Перезапуск контейнера отнесён к классу C (влияет на сервис) — агент только
предлагает, владелец подтверждает. Добавлена очередь заявок
/opt/hub-agents/approvals.json и команды бота: !заявки, !одобрить N,
!отклонить N. Исполняются только разрешённые действия (restart_container).

Дорожная карта переставлена: сначала скелет и структура сервисов, работа
(ВКС/Presale) — после стабилизации. Wiki обновлена.
2026-10-21 13:18:18 +03:00

345 lines
14 KiB
Python

#!/usr/bin/env python3
"""Генерирует страницы Wiki из реестра и документов."""
import os
import re
REPO = "/root/buryan-infra"
OUT = "/root/wiki"
REG = os.path.join(REPO, "ops/registry/services.yaml")
def parse_registry():
text = open(REG, encoding="utf-8").read()
facts = {}
for m in re.finditer(r"^ (guests_ct|guests_vm|containers|domains|databases): (.+)$", text, re.M):
facts[m.group(1)] = m.group(2).strip()
services = []
cur = None
for line in text.splitlines():
if line.startswith(" - key:"):
if cur:
services.append(cur)
cur = {"key": line.split(":", 1)[1].strip().strip('"')}
elif cur is not None and line.startswith(" "):
k, _, v = line.strip().partition(":")
cur[k] = v.strip().strip('"')
if cur:
services.append(cur)
return facts, services
def page_home(facts):
return f"""# Buryans Hub — база знаний
Центральная истина проекта. Всё, что здесь описано, работает на домашнем
сервере Proxmox VE.
## Что такое Hub
Дом, который сам себя обслуживает: единый вход, единый канал уведомлений,
единый реестр сервисов, рой агентов-секретарей.
## Цифры
| Параметр | Значение |
|---|---|
| Гостей | {facts.get('guests_ct', '?')} CT + {facts.get('guests_vm', '?')} ВМ |
| Контейнеров | {facts.get('containers', '?')} |
| Доменов | {facts.get('domains', '?')} |
| Баз данных | {facts.get('databases', '?')} |
## Разделы
- [Архитектура](Architecture) — группы сервисов, потоки
- [Сервисы](Services) — карточки всех сервисов
- [Агенты](Agents) — рой и правила
- [Дорожная карта](Roadmap) — что и когда
- [Регламенты](Runbooks) — что делать при сбое
- [Решения (ADR)](ADR) — почему сделано так
- [Онбординг](Onboarding) — как добавить человека или сервис
- [Работа: ВКС/Presale](Work) — отдельный контур
## Главные документы
- `ops/audit/FULL-AUDIT-2026-10-20.md` — состояние системы
- `ops/audit/AUDIT-2026-10-21-VISION.md` — аудит развития
- `ops/registry/services.yaml` — реестр
- `ops/product/WHATS-NEW.md` — что нового для людей
## Правила
1. Нет карточки в Wiki — сервиса не существует.
2. Нет ADR — изменение не начинается.
3. У каждого сервиса есть бэкап, SSO и владелец.
4. Уведомления — не больше трёх в день человеку.
"""
def page_architecture():
return """# Архитектура
## Шесть групп
| Группа | Назначение | Агент |
|---|---|---|
| Ядро | вход, сеть, БД, бэкапы | Хранитель |
| Дом | устройства, сценарии | Домовой |
| Медиа | фильмы, музыка, книги, фото | Медиатор |
| Знания | документы, код, файлы, закладки | Библиотекарь |
| Автоматизация | n8n, боты, hub-core | Автомат |
| Наблюдаемость | метрики, алерты, логи | Страж |
Над ними — **Голова**: сводка, приоритеты, эскалация.
## Потоки
```
Пользователь → Authentik (SSO + TOTP) → сервис
Событие → hub-core / MQTT → агент → действие или журнал
Контент → библиотека → дайджест 12:00 → Matrix
Инцидент → Страж → Голова → Matrix (с приоритетом)
```
## Принципы
1. **Один вход** — Authentik.
2. **Один канал** — Matrix, с резервом в Telegram.
3. **Один реестр** — `services.yaml`.
4. **Один журнал** — действия агентов.
5. **Одна истина** — эта Wiki.
"""
def page_services(facts, services):
groups = {}
for s in services:
groups.setdefault(s.get("group", "other"), []).append(s)
names = {
"core": "Ядро", "home": "Дом", "media": "Медиа", "knowledge": "Знания",
"automation": "Автоматизация", "observability": "Наблюдаемость",
"support": "Служебные", "other": "Прочее",
}
out = [f"# Сервисы\n", f"Всего контейнеров: **{len(services)}**.\n"]
for g in ("core", "home", "media", "knowledge", "automation", "observability", "support", "other"):
items = groups.get(g) or []
if not items:
continue
out.append(f"\n## {names.get(g, g)} ({len(items)})\n")
out.append("| Сервис | CT | Образ | Критичность |")
out.append("|---|---|---|---|")
for s in sorted(items, key=lambda x: x.get("name", "")):
out.append(f"| `{s.get('name')}` | {s.get('ct')} | {s.get('image', '')[:48]} | {s.get('criticality')} |")
out.append("\n## Как добавить сервис\n")
out.append("1. Добавить в `services.yaml` (или перегенерировать реестр).")
out.append("2. Создать карточку: домен, порт, SSO, бэкап, владелец.")
out.append("3. Настроить мониторинг и бэкап.")
out.append("4. Записать анонс в `ops/product/WHATS-NEW.md`.")
return "\n".join(out)
def page_agents():
return """# Агенты
## Рой
| Агент | Группа | Отвечает |
|---|---|---|
| Хранитель | Ядро | вход, TLS, DNS, бэкапы, восстановление |
| Домовой | Дом | устройства, сценарии, Zigbee, HA |
| Медиатор | Медиа | библиотеки, каталог, метаданные |
| Библиотекарь | Знания | документы, книги, закладки, git |
| Автомат | Автоматизация | n8n, боты, сценарии |
| Страж | Наблюдаемость | метрики, алерты, SLO |
| Голова | все | сводка, приоритеты, эскалация |
## Классы действий
| Класс | Что | Кто решает |
|---|---|---|
| A | перезапуск упавшего, чистка логов, health | агент сам |
| B | обновление, ротация, переиндексация | агент + журнал |
| C | конфиг, миграция, удаление | владелец в Matrix |
| D | бэкапы, DNS, секреты | запрещено автоматизировать |
## Режимы
1. **Наблюдатель** — только читает и предлагает (первая неделя).
2. **Класс A** — безопасные действия сам.
3. **Класс B** — с записью в журнал.
4. **Класс C** — только с подтверждением.
## Журнал
`/var/lib/hub-agents/journal/` — по файлу на агента в день.
Голова агрегирует и присылает сводку только при проблемах.
"""
def page_roadmap():
return """# Дорожная карта
| Фаза | Статус | Результат |
|---|---|---|
| 0. Скелет | ✅ | реестр, Wiki, статус-страница, сверка с аудитом |
| 1. Структура сервисов | 🔄 сейчас | карточки на все сервисы, группы, связи |
| 2. Агенты + заявки C | 🔄 сейчас | 6 секретарей, DeepSeek, подтверждения в Matrix |
| 3. Гигиена B | ⏳ | логи, кэш, ротация — без влияния на доступность |
| 4. Дом и быт | ⏳ | сценарии HA, Grocy, Vikunja, бюджет |
| 5. Контент и интеллект | ⏳ | RAG, CLIP, рекомендации, аудиокниги |
| 6. Работа (Presale) | ⏳ позже | после полной структуры сервисов |
| 7. Устойчивость | ⏳ | учения, резервный канал, UPS |
## Правило порядка
Сначала **скелет и структура**: реестр, карточки, связи, агенты.
Работа (ВКС/Presale) — после того, как сервисы и процессы стабильны.
Никаких новых сервисов, пока нет карточки, бэкапа и мониторинга.
Подробно — `ops/audit/AUDIT-2026-10-21-VISION.md`.
"""
def page_runbooks():
return """# Регламенты
## Сервис не отвечает
1. `!статус` или статус-страница — что именно упало.
2. Проверить контейнер: `docker ps -a | grep <имя>`.
3. Логи: `docker logs --tail 50 <имя>`.
4. Перезапуск: `docker restart <имя>` (класс A).
5. Если не помогло — смотреть зависимости (БД, SSO, сеть).
6. Записать в журнал.
## Matrix недоступен
1. `pct exec 155 -- docker ps` — Synapse.
2. Логи Synapse.
3. Резервный канал — Telegram (userbot).
## Диск заполнен
1. `df -h`, `lvs` — что растёт.
2. Логи: journald, nginx, docker json.
3. Чистка безопасна (класс A), удаление данных — только с подтверждением.
## Бэкап не создался
1. Проверить cron и `/mnt/backups`.
2. Проверить место.
3. Запустить вручную и убедиться.
"""
def page_adr():
return """# Решения (ADR)
## ADR-001. Gitea — центральная истина
Вся документация, реестр и решения живут в Gitea. Wiki — точка входа.
Причина: знания не должны зависеть от памяти одного человека.
## ADR-002. Authentik как единый вход
Все сервисы за SSO, 2FA обязателен.
Причина: один пароль, один контур безопасности.
## ADR-003. Matrix как единый канал
Уведомления, боты, отчёты — в Matrix. Резерв — Telegram.
Причина: не десять приложений, а один канал.
## ADR-004. Реестр сервисов как код
`services.yaml` генерируется из факта и правится вручную только осознанно.
Причина: «что у нас есть» должно быть проверяемым.
## ADR-005. Агенты начинают с наблюдения
Сначала только читают и предлагают, права добавляются постепенно.
Причина: автономия без доверия опасна.
"""
def page_onboarding():
return """# Онбординг
## Добавить человека
1. Authentik → Directory → Users → создать.
2. Добавить в группы (family, медиа, книги).
3. Выдать доступы к сервисам (SSO автоматически).
4. Пользователь при первом входе настраивает TOTP.
5. Добавить в нужные Matrix-комнаты.
## Добавить сервис
1. Развернуть в отдельном CT.
2. Завести oauth2-proxy и домен.
3. Добавить в `services.yaml` (или перегенерировать).
4. Настроить бэкап (данные + конфиг).
5. Добавить монитор в Kuma/Strap.
6. Записать карточку в Wiki.
7. Анонс в `ops/product/WHATS-NEW.md`.
## Добавить агента
1. Описать ТЗ в `/opt/hub-agents/agents/<имя>.yaml`.
2. Указать группу, классы действий, расписание.
3. Запустить в режиме «наблюдатель».
4. Через неделю — включить класс A.
"""
def page_work():
return """# Работа: ВКС/Presale
Отдельный контур для рабочих задач: требования, сравнения ВКС,
заметки встреч, шаблоны КП.
## Задача
Много данных и рутины: требования заказчиков, сравнение решений,
история договорённостей, шаблоны документов.
## Стек (план)
| Блок | Инструмент |
|---|---|
| База знаний | эта Wiki + `buryan-work` |
| Заметки встреч | Whisper + Ollama |
| Задачи | Vikunja |
| CRM-lite | Twenty / EspoCRM |
| Документы | OnlyOffice / Docuseal |
| Автоматизация | n8n |
## MVP
1. Шаблоны КП, ТЗ, чек-лист.
2. Матрица сравнения ВКС.
3. Транскрипция встречи → выжимка → база.
4. Бот `!пресейл <клиент>` — история и следующие шаги.
Приватность: всё локально, без облаков.
"""
def main():
os.makedirs(OUT, exist_ok=True)
facts, services = parse_registry()
pages = {
"Home.md": page_home(facts),
"Architecture.md": page_architecture(),
"Services.md": page_services(facts, services),
"Agents.md": page_agents(),
"Roadmap.md": page_roadmap(),
"Runbooks.md": page_runbooks(),
"ADR.md": page_adr(),
"Onboarding.md": page_onboarding(),
"Work.md": page_work(),
}
for name, text in pages.items():
open(os.path.join(OUT, name), "w", encoding="utf-8").write(text)
print("страниц:", len(pages))
for name in pages:
print(" ", name)
if __name__ == "__main__":
main()