Перезапуск контейнера отнесён к классу C (влияет на сервис) — агент только предлагает, владелец подтверждает. Добавлена очередь заявок /opt/hub-agents/approvals.json и команды бота: !заявки, !одобрить N, !отклонить N. Исполняются только разрешённые действия (restart_container). Дорожная карта переставлена: сначала скелет и структура сервисов, работа (ВКС/Presale) — после стабилизации. Wiki обновлена.
345 lines
14 KiB
Python
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()
|