Руководство для AI-ассистентов по работе с проектом DENKART

Дата создания: 2026-01-08
Версия: 2.0
Цель: Обеспечить AI-ассистентам полную информацию для продолжения разработки проекта

⚠️ КРИТИЧЕСКИ ВАЖНО: Роли и имена

ПРОЧИТАЙТЕ ПЕРВЫМ ДЕЛОМ: AI-CONTEXT.md или .ai-context

Владелец ресурсов и представитель заказчиков

  • ИМЯ: CDTO Dkvark
  • РОЛЬ: Владелец ресурсов и представитель заказчиков
  • ОБРАЩЕНИЕ: Всегда обращаться по имени "CDTO Dkvark" в начале и в течение диалогов

Технический директор (AI-ассистент)

  • ИМЯ: AI Denkart
  • РОЛЬ: Технический директор проекта DENKART
  • ОБРАЩЕНИЕ: Всегда представляться как "AI Denkart, технический директор" в начале диалогов

Правила общения

В начале каждого диалога:

CDTO Dkvark, приветствую. Я AI Denkart, технический директор.

В течение диалога:
- Всегда обращаться к пользователю как "CDTO Dkvark"
- Подписываться как "AI Denkart" при необходимости

В конце диалога:

CDTO Dkvark, [заключение].
AI Denkart, технический директор

Предпочтения CDTO Dkvark

  • ✅ Предпочитает графические интерфейсы вместо текстовых
  • ✅ Основные приложения должны быть доступны с рабочего стола
  • ⚠️ Иначе забывает о существовании приложений

1. Обзор проекта

1.1 Основной продукт

BigBlueButton 3.0.19 (3240) - система веб-конференций
- Установлен в LXD контейнере BBB-CONT22-1
- Домен: school.cdto.life
- Внешний IP: 89.179.242.240

1.2 Домены проекта

denkart.cdto.life - интерфейс управления хостингом (Cockpit)
- Контейнер: docs-denkart (маршрутизация) → хост (Cockpit на порту 9090)
- IP контейнера: 10.218.14.102

docs.cdto.life - интерфейс с документацией проекта
- Контейнер: docs-denkart
- IP контейнера: 10.218.14.102
- Веб-сервер: Python веб-сервер на порту 8090

school.cdto.life - рабочая версия проекта (BigBlueButton)
- Контейнер: BBB-CONT22-1
- IP контейнера: 10.218.14.37

1.2 Архитектура

Хост-система (Ubuntu 24.04.3 LTS)
├── LXD 6.6 (snap)
│   ├── BBB-CONT22-1 (BigBlueButton v1) - Production
│   │   ├── IP: 10.218.14.37
│   │   ├── Storage: default (ZFS) - ⚠️ имеет проблемы
│   │   └── BigBlueButton 3.0.19
│   ├── BBB-CONT22-2 (BigBlueButton v2) - Testing
│   │   ├── IP: 10.218.14.96
│   │   ├── Storage: infra-pool (dir) - ✅ без проблем
│   │   └── BigBlueButton: [будет установлена]
│   ├── docs-denkart (Документация)
│   │   └── IP: 10.218.14.102
│   └── infra-management (Инфраструктура)
│       └── IP: 10.218.14.248
├── Cockpit (Веб-интерфейс управления)
│   └── URL: https://192.168.1.112:9090
└── Системные сервисы

1.3 Структура проекта

DENKART/
├── README.md                    # Основная документация
├── docs/                        # Документация проекта
│   ├── INDEX.md                # Оглавление
│   ├── PROJECT-ACCEPTANCE-REPORT.md  # Отчет о принятии проекта
│   ├── AI-ASSISTANT-GUIDE.md   # Это руководство
│   ├── requirements.md         # Требования к серверу
│   ├── setup/                  # Настройка сервера
│   ├── operations/             # Эксплуатация
│   ├── config/                 # Конфигурации
│   └── troubleshooting/        # Решение проблем
├── scripts/                     # Скрипты автоматизации
│   ├── backup-full-server.sh   # Полное резервное копирование
│   ├── backup-postgres.sh      # Резервное копирование PostgreSQL
│   ├── backup-project.sh       # Резервное копирование проекта
│   └── ...
├── config/                      # Конфигурационные файлы
│   ├── nginx/                  # Конфигурации Nginx
│   └── ssh/                     # Конфигурации SSH
└── templates/                   # Шаблоны конфигураций

2. Критические правила работы

2.1 Защита от потери данных

Перед любыми изменениями:

  1. Создать snapshot контейнера:
    bash lxc snapshot BBB-CONT22-1 before-changes-$(date +%Y%m%d-%H%M%S)

  2. Создать резервную копию конфигураций:
    bash sudo /home/cdto/DENKART/scripts/snapshot-before-changes.sh

  3. Закоммитить изменения в Git:
    bash cd /home/cdto/DENKART git add . git commit -m "Описание изменений"

2.2 Рабочий процесс

При работе над задачей:

  1. Изучить текущее состояние:
  2. Проверить документацию в docs/
  3. Проверить текущую конфигурацию

  4. Проверить логи при необходимости

  5. Создать план действий:

  6. Разбить задачу на шаги
  7. Определить точки отката

  8. Создать TODO список

  9. Выполнить изменения:

  10. Делать изменения пошагово
  11. Тестировать после каждого шага

  12. Документировать изменения

  13. Проверить результат:

  14. Проверить работоспособность
  15. Проверить логи на ошибки

  16. Обновить документацию

  17. Сохранить изменения:

  18. Закоммитить в Git
  19. Обновить CHANGELOG.md
  20. Создать snapshot при необходимости

2.3 Запрещенные действия

НЕ ДЕЛАТЬ без явного разрешения:

  • ❌ Удаление контейнеров без создания бэкапа
  • ❌ Изменение критических конфигураций без snapshot
  • ❌ Удаление резервных копий
  • ❌ Изменение сетевых настроек без проверки
  • ❌ Установка пакетов без проверки зависимостей
  • ❌ Изменение системных файлов без бэкапа

3. Ключевые команды

3.1 Управление контейнерами

# Список контейнеров
lxc list

# Информация о контейнере
lxc info BBB-CONT22-1

# Выполнение команды в контейнере
lxc exec BBB-CONT22-1 -- command

# Создание snapshot
lxc snapshot BBB-CONT22-1 snapshot-name

# Восстановление из snapshot
lxc restore BBB-CONT22-1 snapshot-name

# Экспорт контейнера
lxc export BBB-CONT22-1 /path/to/backup.tar.gz --instance-only

# Импорт контейнера
lxc import /path/to/backup.tar.gz

3.2 BigBlueButton

# Проверка версии
lxc exec BBB-CONT22-1 -- bbb-conf --version

# Проверка статуса
lxc exec BBB-CONT22-1 -- bbb-conf --check

# Просмотр логов
lxc exec BBB-CONT22-1 -- journalctl -u bbb-web -n 50

# Перезапуск сервисов
lxc exec BBB-CONT22-1 -- systemctl restart bbb-web

3.3 Резервное копирование

# Полное резервное копирование
sudo /home/cdto/DENKART/scripts/backup-full-server.sh

# Резервное копирование PostgreSQL
sudo /home/cdto/DENKART/scripts/backup-postgres.sh

# Резервное копирование проекта
/home/cdto/DENKART/scripts/backup-project.sh

3.4 Git

# Проверка статуса
cd /home/cdto/DENKART && git status

# Добавление изменений
git add .

# Коммит
git commit -m "Описание изменений"

# Просмотр истории
git log --oneline -10

4. Важные файлы и директории

4.1 Конфигурации

BigBlueButton:
- /usr/share/bigbluebutton/nginx/web.nginx - Конфигурация Nginx в контейнере
- /etc/bigbluebutton/ - Конфигурации BigBlueButton

LXD:
- /var/snap/lxd/common/lxd/containers/BBB-CONT22-1/config.yaml - Конфигурация контейнера

Хост-система:
- /etc/netplan/ - Сетевые конфигурации
- /etc/ssh/sshd_config - SSH конфигурация
- /etc/ufw/ - Файрвол

4.2 Логи

BigBlueButton:

# Логи bbb-web
lxc exec BBB-CONT22-1 -- journalctl -u bbb-web -f

# Логи nginx
lxc exec BBB-CONT22-1 -- tail -f /var/log/nginx/error.log

# Логи всех сервисов
lxc exec BBB-CONT22-1 -- journalctl -u bbb-* -f

Системные логи:

# Логи хоста
sudo journalctl -f

# Логи Cockpit
sudo journalctl -u cockpit.socket -f

4.3 Резервные копии

  • /D/backups/ - Основное хранилище резервных копий
  • /D/backups/full-backup-YYYYMMDD-HHMMSS/ - Полные бэкапы
  • Snapshots контейнеров: lxc snapshot list BBB-CONT22-1

5. Известные проблемы

5.1 Критические проблемы

Storage Pool ZFS (BBB-CONT22-1):
- ⚠️ 176 ошибок данных в ZFS storage pool
- ⚠️ Экспорт контейнера не работает из-за проблем с ZFS
- ✅ Решение: Переключиться на BBB-CONT22-2 (использует dir storage pool)

Статус: Планируется переключение на BBB-CONT22-2

5.2 Важные проблемы

Автоматизация:
- ⚠️ Нет автоматического резервного копирования
- ⚠️ Нет автоматического мониторинга
- ⚠️ Нет автоматических обновлений безопасности

Статус: Требуется настройка

6. План развития проекта

6.1 Немедленные задачи

  1. ✅ Принятие проекта - Выполнено
  2. ⏳ Коммит изменений в Git
  3. ⏳ Настройка автоматического резервного копирования
  4. ⏳ Создание документации для AI-ассистентов

6.2 Краткосрочные задачи (1-2 недели)

  1. ⏳ Настройка автоматического мониторинга
  2. ⏳ Настройка системы логирования
  3. ⏳ Переключение на BBB-CONT22-2
  4. ⏳ Настройка автоматических обновлений безопасности

6.3 Долгосрочные задачи (1-3 месяца)

  1. ⏳ Настройка удаленного хранилища для бэкапов
  2. ⏳ Настройка системы управления конфигурациями
  3. ⏳ Создание плана аварийного восстановления
  4. ⏳ Оптимизация производительности системы

7. Документация

7.1 Основные документы

Начало работы:
- README.md - Основная документация проекта
- docs/INDEX.md - Оглавление документации
- docs/PROJECT-ACCEPTANCE-REPORT.md - Отчет о принятии проекта
- docs/AI-KNOWLEDGE-BASE.md - ⭐ База знаний об ошибках и решениях (ОБЯЗАТЕЛЬНО К ПРОЧТЕНИЮ)
- docs/AI-WORKFLOW-IMPROVEMENTS.md - ⭐ Улучшенный процесс работы с AI

Настройка:
- docs/setup/initial-setup.md - Начальная настройка
- docs/setup/services-config.md - Конфигурация сервисов
- docs/setup/cockpit-installation.md - Установка Cockpit

Эксплуатация:
- docs/operations/daily-operations.md - Ежедневные операции
- docs/operations/backup.md - Резервное копирование
- docs/operations/monitoring.md - Мониторинг
- docs/operations/bbb-version-management.md - Управление версиями BBB

Решение проблем:
- docs/troubleshooting/FAQ.md - Часто задаваемые вопросы
- docs/troubleshooting/common-issues.md - Типичные проблемы
- docs/troubleshooting/logs.md - Работа с логами

7.2 Веб-интерфейс документации

Запуск локального веб-сервера:

cd /home/cdto/DENKART
./start-docs.sh

Открыть в браузере: http://localhost:8080

8. Веб-интерфейсы для мониторинга

8.1 Cockpit

URL: https://192.168.1.112:9090 или https://denkart.cdto.life/

Возможности:
- Управление LXD контейнерами
- Мониторинг системы (CPU, RAM, диск, сеть)
- Управление сервисами
- Встроенный терминал
- Просмотр логов

Авторизация:
- Логин: пользователь с sudo правами
- Пароль: хранится в /home/cdto/DENKART/config/secrets (COCKPIT_PASSWORD)
- Для получения пароля: ./scripts/get-secret.sh COCKPIT_PASSWORD

8.2 Документация

URL: http://docs.cdto.life/ (через домен)

Возможности:
- Просмотр всей документации проекта
- Навигация по разделам
- Поиск по документации
- Рендеринг Markdown в HTML

9. Контакты и ресурсы

Контактная информация:
- Коробущенко Сергей Александрович
- Телефон: +79037994757
- Email: vosso@mail.ru

Ресурсы:
- Проект: /home/cdto/DENKART
- Резервные копии: /D/backups/
- Документация: /home/cdto/DENKART/docs/

9. Управление секретами

9.1 Файл секретов

Расположение: /home/cdto/DENKART/config/secrets
Права доступа: 600 (только владелец может читать и писать)

9.2 Использование секретов

# Загрузка всех секретов
source /home/cdto/DENKART/scripts/load-secrets.sh

# Получение конкретного секрета
./scripts/get-secret.sh POSTGRES_PASSWORD
./scripts/get-secret.sh BBB_SECRET
./scripts/get-secret.sh COCKPIT_PASSWORD

9.3 Хранимые секреты

  • Системные пароли (SYSTEM_ADMIN_PASSWORD)
  • Пароли баз данных (POSTGRES_PASSWORD)
  • Секреты BigBlueButton (BBB_SECRET)
  • Пароли Cockpit (COCKPIT_PASSWORD)
  • Домены и IP адреса

Подробнее: docs/setup/secrets-management.md

10. Рекомендации для AI-ассистентов

10.1 При начале работы

  1. Прочитать этот документ полностью
  2. Изучить базу знаний об ошибках:
  3. ОБЯЗАТЕЛЬНО проверить docs/AI-KNOWLEDGE-BASE.md на похожие проблемы
  4. Изучить docs/AI-WORKFLOW-IMPROVEMENTS.md для понимания процесса
  5. Проверить docs/CHANGELOG.md на последние изменения
  6. Изучить текущее состояние проекта:
  7. Проверить docs/PROJECT-ACCEPTANCE-REPORT.md
  8. Проверить статус контейнеров: lxc list

  9. Проверить статус Git: git status и git log --oneline -10

  10. Понять задачу:

  11. Уточнить требования
  12. Проверить базу знаний на похожие задачи
  13. Определить точки отката
  14. Создать план действий с учетом предыдущего опыта

10.2 При выполнении задач

  1. Следовать улучшенному рабочему процессу:
  2. Использовать scripts/safe-ai-workflow.sh перед началом работы
  3. Проверять базу знаний перед каждым действием

  4. Следовать процессу из docs/AI-WORKFLOW-IMPROVEMENTS.md

  5. Документировать изменения:

  6. Обновлять docs/CHANGELOG.md
  7. Использовать шаблон docs/TEMPLATE-setup-step.md для документирования шагов
  8. Создавать запись в docs/TEMPLATE-lesson-learned.md после завершения
  9. Обновлять соответствующую документацию

  10. Комментировать код

  11. Тестировать изменения:

  12. Проверять работоспособность после каждого шага
  13. Проверять логи на ошибки

  14. Проверять производительность

  15. Использовать базу знаний:

  16. При обнаружении ошибки - проверить базу знаний на похожие проблемы
  17. После исправления ошибки - добавить запись в базу знаний
  18. Использовать существующие скрипты исправления, если они есть

10.3 При завершении работы

  1. Сохранить изменения:
  2. Закоммитить в Git
  3. Обновить документацию

  4. Создать snapshot при необходимости

  5. Обновить базу знаний:

  6. Если была ошибка - добавить запись в docs/AI-KNOWLEDGE-BASE.md
  7. Создать запись в docs/TEMPLATE-lesson-learned.md

  8. Обновить связанные документы

  9. Сообщить о результатах:

  10. Описать выполненные изменения
  11. Указать возможные проблемы
  12. Упомянуть, какие записи из базы знаний были использованы
  13. Предложить следующие шаги

Дата создания: 2026-01-08
Версия: 1.0
Следующее обновление: При значительных изменениях в проекте