Автоматическая синхронизация документации с docs.cdto.life

Дата настройки: 2026-01-10
Статус: ✅ Настроено и работает

Требование к регулярности: Синхронизация документации с docs.cdto.life должна выполняться не реже 1 раза в неделю. Текущая настройка (timer каждые 5 минут) это обеспечивает; при отключённом таймере выполнять вручную: sudo /home/cdto/DENKART/scripts/sync-docs-to-web.sh.

Описание

Автоматическая синхронизация документации из /home/cdto/DENKART/docs/ в веб-сервер docs.cdto.life (контейнер docs-denkart) настроена через:

  1. Systemd Timer - периодическая синхронизация каждые 5 минут
  2. Git Post-Commit Hook - уведомление о необходимости синхронизации после коммита
  3. Ручная синхронизация - скрипт для немедленной синхронизации

Настройка автоматической синхронизации

Первоначальная настройка

sudo /home/cdto/DENKART/scripts/setup-docs-auto-sync.sh

Этот скрипт автоматически:
- Создает systemd service и timer
- Устанавливает git post-commit hook
- Настраивает логирование
- Запускает автоматическую синхронизацию

Проверка статуса

# Проверка статуса timer
sudo systemctl status docs-sync.timer

# Проверка следующего запуска
sudo systemctl list-timers docs-sync.timer

# Проверка последнего запуска service
sudo systemctl status docs-sync.service

Как работает автоматическая синхронизация

Systemd Timer

Таймер: docs-sync.timer
- Интервал: Каждые 5 минут
- Первый запуск: Через 2 минуты после загрузки системы
- Точность: ±1 минута

Service: docs-sync.service
- Проверяет изменения в документации через git
- Синхронизирует только при обнаружении изменений
- Логирует все действия в /var/log/docs-sync.log

Git Post-Commit Hook

Файл: /home/cdto/DENKART/.git/hooks/post-commit

После каждого коммита, который изменяет файлы в директории docs/, hook:
- Определяет измененные файлы
- Выводит уведомление о необходимости синхронизации
- Напоминает о ручной синхронизации (если требуется)

Примечание: Git hook не запускает синхронизацию автоматически, так как для этого требуется sudo. Timer обработает изменения автоматически в течение 5 минут.

Ручная синхронизация

Для немедленной синхронизации после изменений:

sudo /home/cdto/DENKART/scripts/sync-docs-to-web.sh

Или через systemd service:

sudo systemctl start docs-sync.service

Работа с автоматической синхронизацией

Просмотр логов

# Просмотр логов service
sudo journalctl -u docs-sync.service -f

# Просмотр файла логов
sudo tail -f /var/log/docs-sync.log

# Просмотр последних 50 строк
sudo tail -n 50 /var/log/docs-sync.log

Управление автоматической синхронизацией

# Включить автоматическую синхронизацию
sudo systemctl enable docs-sync.timer

# Выключить автоматическую синхронизацию
sudo systemctl disable docs-sync.timer

# Запустить timer (если остановлен)
sudo systemctl start docs-sync.timer

# Остановить timer
sudo systemctl stop docs-sync.timer

# Перезагрузить timer после изменения конфигурации
sudo systemctl daemon-reload
sudo systemctl restart docs-sync.timer

Настройка интервала синхронизации

Интервал синхронизации настраивается в файле /etc/systemd/system/docs-sync.timer:

[Timer]
# Запуск каждые 5 минут (по умолчанию)
OnBootSec=2min
OnUnitActiveSec=5min
AccuracySec=1min

Для изменения интервала:
1. Отредактируйте файл /etc/systemd/system/docs-sync.timer
2. Измените значение OnUnitActiveSec (например, 10min для синхронизации каждые 10 минут)
3. Выполните:
bash sudo systemctl daemon-reload sudo systemctl restart docs-sync.timer

Рекомендации:
- 1-5 минут - для активной разработки
- 10-15 минут - для обычной работы
- 30-60 минут - для редких изменений

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

Рекомендуемый рабочий процесс

  1. Внесение изменений в документацию:
    bash # Редактирование файлов в /home/cdto/DENKART/docs/ nano docs/troubleshooting/FAQ.md

  2. Коммит изменений (если используется git):
    bash git add docs/troubleshooting/FAQ.md git commit -m "Обновление FAQ"

Git hook выведет уведомление о необходимости синхронизации.

  1. Автоматическая синхронизация:
  2. Systemd timer автоматически обнаружит изменения в течение 5 минут
  3. Синхронизация выполнится автоматически

  4. Результат будет записан в /var/log/docs-sync.log

  5. Или ручная синхронизация (для немедленного обновления):
    bash sudo /home/cdto/DENKART/scripts/sync-docs-to-web.sh

  6. Проверка результата:

  7. Откройте https://docs.cdto.life/
  8. Проверьте обновленные файлы

Без использования git

Если документация изменяется напрямую (без коммитов):
- Systemd timer все равно обнаружит изменения через git (если репозиторий инициализирован)
- Или используйте ручную синхронизацию после изменений

Мониторинг синхронизации

Проверка последней синхронизации

# Время последней синхронизации
sudo journalctl -u docs-sync.service -n 1 --no-pager | grep "Синхронизация завершена"

# Последний проверенный коммит
cat /var/tmp/docs-sync-last-check

Проверка измененных файлов

# Последние изменения в документации
cd /home/cdto/DENKART
git log --oneline --name-only -5 -- docs/

# Изменения, которые еще не синхронизированы
cd /home/cdto/DENKART
LAST_SYNC=$(cat /var/tmp/docs-sync-last-check 2>/dev/null || echo "")
if [ -n "$LAST_SYNC" ]; then
    git log --oneline --name-only "$LAST_SYNC..HEAD" -- docs/
fi

Устранение неполадок

Timer не запускается

# Проверка статуса
sudo systemctl status docs-sync.timer

# Проверка активации
sudo systemctl is-enabled docs-sync.timer

# Включение и запуск
sudo systemctl enable docs-sync.timer
sudo systemctl start docs-sync.timer

Синхронизация не выполняется

# Проверка логов на ошибки
sudo journalctl -u docs-sync.service -n 50

# Проверка контейнера docs-denkart
lxc info docs-denkart

# Ручной запуск для диагностики
sudo /home/cdto/DENKART/scripts/sync-docs-to-web.sh

Изменения не отображаются на docs.cdto.life

# Проверка синхронизации
sudo systemctl start docs-sync.service
sudo tail -f /var/log/docs-sync.log

# Проверка файлов в контейнере
lxc exec docs-denkart -- ls -la /var/www/denkart-docs/docs/troubleshooting/

# Перезапуск веб-сервера в контейнере
lxc exec docs-denkart -- systemctl restart docs-web-server.service

Очистка логов

# Очистка старых логов (старше 30 дней)
sudo journalctl --vacuum-time=30d

# Очистка файла логов
sudo truncate -s 0 /var/log/docs-sync.log

Файлы и скрипты

Основные файлы

  • Service: /etc/systemd/system/docs-sync.service
  • Timer: /etc/systemd/system/docs-sync.timer
  • Скрипт синхронизации: /home/cdto/DENKART/scripts/sync-docs-to-web.sh
  • Service скрипт: /home/cdto/DENKART/scripts/docs-sync-service.sh
  • Скрипт установки: /home/cdto/DENKART/scripts/setup-docs-auto-sync.sh
  • Git hook: /home/cdto/DENKART/.git/hooks/post-commit
  • Логи: /var/log/docs-sync.log
  • Метаданные: /var/tmp/docs-sync-last-check

Шаблоны

  • Service template: /home/cdto/DENKART/templates/docs-sync.service
  • Timer template: /home/cdto/DENKART/templates/docs-sync.timer

Безопасность

  • Service выполняется от имени root для доступа к контейнерам LXD
  • Timer ограничен точностью ±1 минута для снижения нагрузки
  • Логи доступны только root
  • Git hook не выполняет автоматическую синхронизацию без sudo

Производительность

  • Проверка изменений через git выполняется быстро
  • Синхронизация выполняется только при обнаружении изменений
  • Использование tar для копирования оптимизировано
  • Интервал 5 минут обеспечивает баланс между актуальностью и нагрузкой

Обновление конфигурации

После изменения шаблонов service или timer:

# Копирование обновленных шаблонов
sudo cp /home/cdto/DENKART/templates/docs-sync.service /etc/systemd/system/
sudo cp /home/cdto/DENKART/templates/docs-sync.timer /etc/systemd/system/

# Перезагрузка systemd
sudo systemctl daemon-reload

# Перезапуск timer
sudo systemctl restart docs-sync.timer

Последнее обновление: 2026-01-10