Перейти к содержанию

Правила разработки проектов и сервисов на сервере

Общие принципы

  1. Язык общения: Все ответы и комментарии в коде должны быть на русском языке
  2. Документирование: Все значимые изменения должны быть задокументированы
  3. Безопасность: Секреты и пароли никогда не коммитятся в git
  4. Логирование: Важные события должны логироваться
  5. Версионирование: Все изменения фиксируются в git с осмысленными сообщениями

Работа с Git

Основные правила:

  • Изменения в проектах (/opt/<project-name>) должны быть закоммичены и запушены в Gitea. Документация /root/docs в Gitea не пушится (локальная).
  • Сообщения коммитов должны быть понятными и описывать суть изменений
  • Формат сообщения коммита — см. ниже

Формат сообщения коммита

  • Синтаксис: Тип: краткое описание — одно слово типа, двоеточие, пробел, описание на русском.
  • Типы: Fix, Feature, Refactor, Docs, Update.

Примеры:

  • Fix: исправление обработки ошибок при таймауте
  • Feature: добавлен endpoint /api/health
  • Refactor: вынесена логика валидации в отдельный модуль
  • Docs: обновлён README, секция установки
  • Update: обновлены зависимости в requirements.txt

Структура репозиториев:

  • Gitea (общий репозиторий): https://git.gen7x.ru/
  • Документация: /root/docs — исходники MkDocs (docs.gen7x.ru); в Gitea не пушится, только локально.
  • Проекты: /opt/<project-name> → репозиторий в Gitea <project-name>; все изменения проектов пушатся в Gitea с этого сервера. URL репозитория: https://git.gen7x.ru/<project-name>.git.
  • Каждый проект должен иметь README.md с описанием проекта.

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

Файлы документации:

  1. /root/docs/docs/history.md - История изменений платформы:

  2. Формат: ## YYYY-MM-DD HH:MM UTC – Описание изменения

  3. Должна содержать: проблему, решение, изменения, команды проверки

  4. Обновляется после каждого значимого изменения платформы

  5. HISTORY.md - История изменений проекта (обязательно для каждого проекта):

  6. Должен быть в корне каждого проекта: /opt/<project-name>/HISTORY.md

  7. Формат: ## YYYY-MM-DD HH:MM UTC – Описание изменения
  8. Должен содержать: проблему, решение, изменения, команды проверки
  9. Обновляется после каждого значимого изменения проекта

  10. Пример: /opt/gen7x/backup/ ведёт свою историю

  11. /root/docs/secrets/mysecrets.md - Секреты и пароли:

  12. Хранит пароли, токены, ключи доступа

  13. НЕ коммитится в git (должен быть в .gitignore)

  14. Формат: структурированный markdown с секциями

  15. README.md - Полная документация проекта (обязательно для каждого проекта):

  16. Должен быть в корне каждого проекта

  17. Обязательные секции:
    • Описание проекта и его назначение
    • Требования и зависимости
    • Установка и настройка
    • Конфигурация (с примерами .env.example)
    • Использование и примеры
    • Структура проекта
    • Docker Compose конфигурация
    • Volumes и их назначение
    • Логирование (где и как смотреть логи)
    • Резервное копирование (какие данные бэкапятся)
    • Восстановление из бэкапа
    • Troubleshooting
    • Команды управления
  18. Примеры команд и конфигураций

Правила оформления:

  • Используйте Markdown форматирование
  • Добавляйте примеры кода с синтаксической подсветкой
  • Структурируйте информацию по секциям
  • Обновляйте документацию синхронно с кодом

Безопасность и секреты

Хранение секретов:

  • Все секреты хранятся в /root/docs/secrets/mysecrets.md
  • Используйте переменные окружения (.env файлы) для конфигурации
  • .env файлы НЕ должны коммититься в git
  • Добавляйте .env.example с шаблонами (без реальных значений)

Правила работы с паролями:

  • Никогда не хардкодите пароли в код
  • Используйте переменные окружения
  • При создании .env файлов используйте шаблоны
  • Пароли администраторов должны быть сильными

Доступ к серверу:

  • SSH доступ только по ключам (PasswordAuthentication no)
  • SSH порт изменен с 22 на 55133
  • UFW настроен для защиты сервера
  • Fail2ban для защиты от брутфорса

Логирование

Обязательные требования для проектов:

  • Все проекты должны логировать важные события
  • Логи должны быть структурированными и информативными
  • Используйте уровни логирования: INFO, WARNING, ERROR
  • Логируйте входные данные пользователей (без секретов)
  • Логи должны быть доступны для просмотра и анализа

Правила логирования:

  • Все сервисы должны логировать важные события
  • Логи должны быть структурированными и информативными
  • Используйте уровни логирования: INFO, WARNING, ERROR
  • Логируйте входные данные пользователей (без секретов)
  • Для Docker проектов: используйте docker compose logs или перенаправление в файлы

Расположение логов:

  • Docker проекты: docker compose logs -f <service-name> или файлы в volumes
  • Systemd сервисы: journalctl -u <service-name>
  • Файловые логи: /var/log/<project-name>/ (если используются)
  • Настройка logrotate для ротации файловых логов
  • Логи должны ротироваться автоматически

Структура логов для проектов:

/opt/<project-name>/
├── logs/                  # Логи проекта (опционально, если не через journalctl)
│   ├── app.log           # Основной лог приложения
│   └── error.log         # Лог ошибок

Или через Docker: 

# docker-compose.yml
services:
  app:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

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

# Docker проекты
cd /opt/<project-name>
docker compose logs -f <service-name>
docker compose logs --since "10 minutes ago" <service-name>

# Systemd сервисы
journalctl -u <service-name> -f
journalctl -u <service-name> --since "10 minutes ago"

# Файловые логи
tail -f /var/log/<project-name>/<log-file>
tail -f /opt/<project-name>/logs/app.log

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

Обязательные требования для каждого проекта:

  1. Контейнеризация: Все проекты должны быть контейнеризированы через Docker
  2. Документация: Каждый проект должен иметь полную документацию
  3. История изменений: Каждый проект должен вести историю изменений
  4. Логирование: Все проекты должны логировать важные события
  5. Резервное копирование: Данные проектов должны быть включены в систему бэкапа

Стандартная структура:

/opt/<project-name>/
├── README.md              # Полное описание проекта (обязательно)
├── HISTORY.md             # История изменений проекта (обязательно)
├── .env                   # Конфигурация (не в git)
├── .env.example           # Шаблон конфигурации (обязательно)
├── docker-compose.yml      # Docker Compose конфигурация (обязательно)
├── requirements.txt       # Зависимости (для Python)
├── deploy.sh              # Скрипт установки/развертывания
├── manage.sh              # Скрипт управления (start/stop/restart)
├── <project>.service      # Systemd unit файл (если нужен)
├── logs/                  # Логи проекта (если файловые логи)
└── src/                   # Исходный код

Python проекты:

  • Используйте виртуальные окружения (venv) или Docker
  • requirements.txt для зависимостей
  • .env для конфигурации
  • Docker Compose для запуска (предпочтительно) или Systemd сервисы
  • Все зависимости должны быть зафиксированы

Docker проекты (обязательно для всех):

  • docker-compose.yml для оркестрации (обязательно)
  • Отдельные конфигурационные файлы в поддиректориях
  • Volumes для персистентных данных (должны быть включены в бэкап)
  • Networks для изоляции сервисов
  • Health checks для мониторинга
  • Все volumes должны быть задокументированы в HISTORY.md

Systemd сервисы

Правила создания:

  • Unit файлы в /etc/systemd/system/
  • Используйте Type=simple или Type=notify
  • Restart=always для автоматического перезапуска
  • User и Group для безопасности
  • WorkingDirectory для правильной работы

Управление:

sudo systemctl enable <service>
sudo systemctl start <service>
sudo systemctl restart <service>
sudo systemctl status <service>
journalctl -u <service> -f

Docker и контейнеризация

Правила:

  • Используйте docker-compose.yml для оркестрации
  • Версионируйте образы через теги
  • Используйте volumes для персистентных данных
  • Настройте networks для изоляции
  • Health checks для мониторинга

Структура docker-compose:

  • Сервисы с понятными именами
  • Environment variables через .env файлы
  • Volumes для конфигураций и данных
  • Networks для связи между сервисами
  • Restart policies для надежности

Nginx и обратный прокси

Правила конфигурации:

  • Конфигурации в /opt/gen7x/nginx/conf.d/
  • Один файл конфигурации на домен
  • SSL сертификаты через Cloudflare Origin SSL
  • Basic auth для защиты контента (если требуется)
  • Логирование в отдельные файлы

Структура:

/opt/gen7x/nginx/
├── conf.d/
│   ├── domain1.conf
│   └── domain2.conf
└── auth/
    └── domain.htpasswd

Мониторинг и обслуживание

Health checks:

  • Регулярные проверки работоспособности сервисов
  • Уведомления администратора при ошибках
  • Логирование состояния сервисов

Обновления:

  • Регулярное обновление системы (unattended-upgrades)
  • Обновление зависимостей проектов
  • Резервное копирование важных данных

Обработка ошибок

Правила:

  • Все ошибки должны логироваться
  • Пользователю показывать понятные сообщения
  • Fallback механизмы при ошибках сети/API
  • Не падать при временных ошибках (retry логика)

Примеры:

  • Timeout ошибки обрабатываются с повторными попытками
  • Fallback сообщения при ошибках отправки
  • Валидация входных данных
  • Проверка состояния перед критическими операциями

Тестирование

Правила:

  • Тестируйте изменения перед коммитом
  • Проверяйте логи после изменений
  • Тестируйте на реальных данных (осторожно)
  • Документируйте известные проблемы

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

Автоматическая система бэкапа:

На сервере настроена автоматическая система резервного копирования в S3 (Backblaze B2):

  • Расписание: Ежедневно в 03:30 UTC через systemd timer
  • Хранилище: S3-совместимое хранилище (Backblaze B2)
  • Шифрование: Все бэкапы шифруются через age перед отправкой
  • Retentions:
  • Daily: 14 дней
  • Weekly: 8 недель (каждое воскресенье)
  • Monthly: 12 месяцев (1-го числа)

Что бэкапится автоматически:

  1. PostgreSQL: Логические дампы всех баз данных
  2. Docker Volumes: Все volumes из /opt/gen7x/backup/include-volumes.txt
  3. Nginx SSL: Сертификаты из /opt/gen7x/nginx/ssl/

Правила для проектов:

  • Обязательно: Все персистентные данные должны храниться в Docker volumes
  • Обязательно: Все volumes проекта должны быть добавлены в /opt/gen7x/backup/include-volumes.txt
  • Обязательно: Базы данных должны использовать PostgreSQL (бэкапится автоматически)
  • Обязательно: Конфигурации должны быть в git (не секреты)
  • Обязательно: Секреты хранятся отдельно в /root/docs/secrets/mysecrets.md

Добавление проекта в бэкап:

  1. Добавьте volume в /opt/gen7x/backup/include-volumes.txt: 
    docker_<project>_data
  2. Убедитесь, что volume создан и используется в docker-compose.yml
  3. Протестируйте бэкап: systemctl start gen7x-backup.service
  4. Проверьте загрузку в S3: rclone ls b2s3:gen7x-backups/gen7x/ --s3-no-check-bucket

Восстановление:

  • Используйте /opt/gen7x/backup/restore.sh для восстановления
  • Документация: /root/docs/docs/backup.md

Коммуникация и отчетность

После выполнения задач:

  1. Обновить HISTORY.md проекта с описанием изменений (обязательно)
  2. Обновить /root/docs/docs/history.md если изменения касаются платформы
  3. Обновить README.md проекта если изменилась структура или использование
  4. Закоммитить и запушить все изменения
  5. Проверить работоспособность сервисов
  6. Проверить логи после изменений
  7. Убедиться, что volumes добавлены в бэкап (если созданы новые)

Формат отчетов в HISTORY.md:

## YYYY-MM-DD HH:MM UTC – Описание изменения

**Проблема**: Краткое описание проблемы или задачи

**Решение**: 
- Что было сделано
- Какие изменения внесены

**Изменения**:
- Список изменённых файлов
- Новые файлы/директории
- Изменения в конфигурации

**Результат**:
- Что получилось
- Статус (работает/требует проверки)

**Проверка**:
```bash
# Команды для проверки работоспособности

## Специфичные правила для проектов

### Telegram боты:

* Используйте aiogram для разработки
* Логирование всех взаимодействий
* Обработка ошибок API Telegram
* Fallback при timeout ошибках
* Поддержка нескольких администраторов (опционально)

### Web сервисы:

* Используйте Nginx как reverse proxy
* SSL сертификаты через Cloudflare
* Basic auth для защиты (если требуется)
* Логирование запросов

### Базы данных:

* Используйте Docker для PostgreSQL/Redis
* Персистентные volumes для данных
* Регулярное резервное копирование
* Правильные права доступа

## Контрольный список перед коммитом

* [ ] Код протестирован
* [ ] Логи проверены после изменений
* [ ] README.md проекта обновлен (если нужно)
* [ ] HISTORY.md проекта обновлен (обязательно для значимых изменений)
* [ ] /root/docs/docs/history.md обновлен (если изменения касаются платформы)
* [ ] Секреты не в коде
* [ ] .env файлы не коммитятся
* [ ] .env.example обновлен (если изменилась конфигурация)
* [ ] Docker volumes добавлены в бэкап (если созданы новые)
* [ ] docker-compose.yml проверен и работает
* [ ] Сообщение коммита понятное (формат: `Тип: описание`, типы: Fix, Feature, Refactor, Docs, Update)
* [ ] Изменения проекта зафиксированы в git и запушены в Gitea (docs не пушатся)

## Создание нового проекта и инициализация Git

При создании нового проекта в `/opt/<project-name>` репозиторий должен быть инициализирован **автоматически**:

1. Создать структуру проекта (README.md, HISTORY.md, .env.example, docker-compose.yml, код и т.д.).
2. В корне проекта выполнить:
   ```bash
   cd /opt/<project-name>
   git init
   git remote add origin https://git.gen7x.ru/<project-name>.git
   git add .
   git commit -m "Docs: начальная структура проекта"
   git branch -M main
   git push -u origin main
   ```
3. Репозиторий в Gitea (https://git.gen7x.ru/) должен быть создан заранее (пустой); в URL подставляется только имя проекта.

Дальнейшая работа: обычный workflow (add, commit, push) только для проектов в `/opt/`.

## Полезные команды

```bash
# Git (только для проектов в /opt/; docs в Gitea не пушатся)
cd /opt/<project> && git add . && git commit -m "Тип: описание" && git push

# Systemd
sudo systemctl restart <service>
journalctl -u <service> -f

# Docker
cd /opt/gen7x && docker-compose restart <service>
docker-compose logs -f <service>

# Логи
tail -f /var/log/<project>/<log-file>
journalctl -u <service> --since "10 minutes ago"