This commit is contained in:
478
docs/CICD.md
Normal file
478
docs/CICD.md
Normal file
@@ -0,0 +1,478 @@
|
||||
# CI/CD Documentation
|
||||
|
||||
## 📋 Содержание
|
||||
|
||||
1. [Обзор CI/CD](#обзор-cicd)
|
||||
2. [Архитектура пайплайна](#архитектура-пайплайна)
|
||||
3. [Настройка Drone CI](#настройка-drone-ci)
|
||||
4. [Конфигурация окружений](#конфигурация-окружений)
|
||||
5. [Локальное тестирование](#локальное-тестирование)
|
||||
6. [Деплой и управление](#деплой-и-управление)
|
||||
7. [Мониторинг и уведомления](#мониторинг-и-уведомления)
|
||||
8. [Устранение неполадок](#устранение-неполадок)
|
||||
|
||||
## 🚀 Обзор CI/CD
|
||||
|
||||
CatLink использует современный CI/CD пайплайн на базе **Drone CI** для автоматизации:
|
||||
|
||||
- 🔍 **Проверка качества кода** (линтинг, форматирование)
|
||||
- 🧪 **Автоматизированное тестирование**
|
||||
- 🔒 **Сканирование безопасности**
|
||||
- 🏗️ **Сборка Docker образов**
|
||||
- 📤 **Публикация в registry**
|
||||
- 🚀 **Автоматический деплой** на staging и production
|
||||
|
||||
### Основные преимущества
|
||||
|
||||
- ✅ **Автоматизация** всех этапов развертывания
|
||||
- ✅ **Качество кода** обеспечивается проверками
|
||||
- ✅ **Безопасность** через сканирование уязвимостей
|
||||
- ✅ **Надежность** благодаря тестированию
|
||||
- ✅ **Скорость** развертывания изменений
|
||||
|
||||
## 🏗️ Архитектура пайплайна
|
||||
|
||||
### Этапы CI/CD пайплайна
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Git Push] --> B[Prepare]
|
||||
B --> C[Lint & Code Quality]
|
||||
C --> D[Build & Test]
|
||||
D --> E[Security Scan]
|
||||
E --> F[Build Production]
|
||||
F --> G[Publish Images]
|
||||
G --> H[Deploy Staging]
|
||||
H --> I[Deploy Production]
|
||||
I --> J[Notifications]
|
||||
```
|
||||
|
||||
### 1. **Prepare** - Подготовка
|
||||
- Настройка окружения
|
||||
- Установка зависимостей
|
||||
- Инициализация кэша
|
||||
|
||||
### 2. **Lint** - Проверка качества кода
|
||||
- Python: `flake8`, `black`, `isort`
|
||||
- TypeScript: `ESLint`, `Prettier`
|
||||
- Docker: `hadolint`
|
||||
- YAML: `yamllint`
|
||||
- Security: `bandit`, `safety`
|
||||
|
||||
### 3. **Build & Test** - Сборка и тестирование
|
||||
- Сборка Docker образов
|
||||
- Запуск unit тестов
|
||||
- API тестирование
|
||||
- Frontend тесты
|
||||
- Integration тесты
|
||||
|
||||
### 4. **Security Scan** - Проверка безопасности
|
||||
- Сканирование зависимостей
|
||||
- Анализ исходного кода
|
||||
- Проверка Docker образов
|
||||
- Аудит конфигураций
|
||||
|
||||
### 5. **Build Production** - Продакшен сборка
|
||||
- Оптимизированные образы
|
||||
- Multi-stage builds
|
||||
- Минимальные базовые образы
|
||||
- Метаданные и лейблы
|
||||
|
||||
### 6. **Publish** - Публикация
|
||||
- Push в Docker registry
|
||||
- Создание release notes
|
||||
- Версионирование
|
||||
- Уведомления команды
|
||||
|
||||
### 7. **Deploy** - Развертывание
|
||||
- Staging деплой для тестирования
|
||||
- Production деплой с проверками
|
||||
- Rolling updates без простоя
|
||||
- Health checks
|
||||
|
||||
## 🛠️ Настройка Drone CI
|
||||
|
||||
### Требования
|
||||
|
||||
- Drone CI сервер
|
||||
- Docker registry (Docker Hub, GitLab Registry, etc.)
|
||||
- SSH доступ к серверам
|
||||
- Переменные окружения
|
||||
|
||||
### Переменные окружения
|
||||
|
||||
#### Обязательные переменные
|
||||
|
||||
```bash
|
||||
# Docker Registry
|
||||
DOCKER_REGISTRY=registry.hub.docker.com
|
||||
DOCKER_USERNAME=your_username
|
||||
DOCKER_PASSWORD=your_password
|
||||
|
||||
# Staging Environment
|
||||
STAGING_HOST=staging.catlink.dev
|
||||
STAGING_SSH_KEY=base64_encoded_ssh_key
|
||||
STAGING_USER=deploy
|
||||
|
||||
# Production Environment
|
||||
PRODUCTION_HOST=catlink.dev
|
||||
PRODUCTION_SSH_KEY=base64_encoded_ssh_key
|
||||
PRODUCTION_USER=deploy
|
||||
PRODUCTION_SECRET_KEY=super_secret_key
|
||||
PRODUCTION_POSTGRES_PASSWORD=secure_db_password
|
||||
PRODUCTION_EMAIL_HOST=smtp.gmail.com
|
||||
PRODUCTION_EMAIL_USER=your_email@gmail.com
|
||||
PRODUCTION_EMAIL_PASSWORD=your_app_password
|
||||
```
|
||||
|
||||
#### Дополнительные переменные
|
||||
|
||||
```bash
|
||||
# Notifications
|
||||
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
|
||||
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
|
||||
|
||||
# Monitoring
|
||||
SENTRY_DSN=https://...@sentry.io/...
|
||||
PRODUCTION_SENTRY_DSN=https://...@sentry.io/...
|
||||
GOOGLE_ANALYTICS_ID=GA_MEASUREMENT_ID
|
||||
|
||||
# Backup
|
||||
PRODUCTION_BACKUP_S3_BUCKET=catlink-backups
|
||||
```
|
||||
|
||||
### Настройка SSH ключей
|
||||
|
||||
1. **Генерация SSH ключа**:
|
||||
```bash
|
||||
ssh-keygen -t rsa -b 4096 -C "deploy@catlink.dev" -f deploy_key
|
||||
```
|
||||
|
||||
2. **Кодирование в base64**:
|
||||
```bash
|
||||
cat deploy_key | base64 -w 0
|
||||
```
|
||||
|
||||
3. **Добавление публичного ключа на сервер**:
|
||||
```bash
|
||||
cat deploy_key.pub >> ~/.ssh/authorized_keys
|
||||
```
|
||||
|
||||
## ⚙️ Конфигурация окружений
|
||||
|
||||
### Staging окружение
|
||||
|
||||
**Цель**: Тестирование новых функций и изменений
|
||||
|
||||
**Характеристики**:
|
||||
- Автоматический деплой с main ветки
|
||||
- Тестовые данные
|
||||
- Менее строгие проверки безопасности
|
||||
- Быстрое развертывание
|
||||
|
||||
**URL**: `https://staging.catlink.dev`
|
||||
|
||||
### Production окружение
|
||||
|
||||
**Цель**: Рабочее приложение для пользователей
|
||||
|
||||
**Характеристики**:
|
||||
- Деплой только с тегов версий
|
||||
- Строгие проверки безопасности
|
||||
- Резервные копии перед деплоем
|
||||
- Rolling deployment без простоя
|
||||
- Полный мониторинг
|
||||
|
||||
**URL**: `https://catlink.dev`
|
||||
|
||||
## 🧪 Локальное тестирование
|
||||
|
||||
### Make команды для CI/CD
|
||||
|
||||
```bash
|
||||
# Проверка качества кода
|
||||
make ci-lint
|
||||
|
||||
# Запуск тестов
|
||||
make ci-test
|
||||
|
||||
# Проверка безопасности
|
||||
make ci-security
|
||||
|
||||
# Локальная сборка
|
||||
make ci-build
|
||||
|
||||
# Полный пайплайн
|
||||
make ci-pipeline
|
||||
|
||||
# Валидация Drone конфигурации
|
||||
make drone-validate
|
||||
```
|
||||
|
||||
### Ручной запуск скриптов
|
||||
|
||||
```bash
|
||||
# Проверка кода
|
||||
./scripts/ci/lint.sh
|
||||
|
||||
# Тестирование
|
||||
./scripts/ci/test.sh
|
||||
|
||||
# Сканирование безопасности
|
||||
./scripts/ci/security-scan.sh
|
||||
|
||||
# Сборка
|
||||
./scripts/ci/build.sh
|
||||
|
||||
# Продакшен сборка
|
||||
./scripts/ci/build-production.sh
|
||||
```
|
||||
|
||||
### Тестирование Docker образов
|
||||
|
||||
```bash
|
||||
# Сборка и тестирование
|
||||
docker build -t catlink-backend:test backend/
|
||||
docker build -t catlink-frontend:test frontend/linktree-frontend/
|
||||
|
||||
# Запуск для тестирования
|
||||
docker run -d -p 8001:8000 --name test-backend catlink-backend:test
|
||||
docker run -d -p 3001:3000 --name test-frontend catlink-frontend:test
|
||||
|
||||
# Проверка работоспособности
|
||||
curl http://localhost:8001/api/
|
||||
curl http://localhost:3001/
|
||||
|
||||
# Очистка
|
||||
docker stop test-backend test-frontend
|
||||
docker rm test-backend test-frontend
|
||||
```
|
||||
|
||||
## 🚀 Деплой и управление
|
||||
|
||||
### Автоматический деплой
|
||||
|
||||
**Staging деплой**:
|
||||
- Триггер: Push в `main` ветку
|
||||
- Время: ~10-15 минут
|
||||
- Проверки: Линтинг, тесты, безопасность
|
||||
|
||||
**Production деплой**:
|
||||
- Триггер: Создание тега `v*.*.*`
|
||||
- Время: ~20-30 минут
|
||||
- Проверки: Полная валидация + ручные проверки
|
||||
|
||||
### Ручной деплой
|
||||
|
||||
```bash
|
||||
# Staging
|
||||
make ci-deploy-staging
|
||||
|
||||
# Production (осторожно!)
|
||||
make ci-deploy-production
|
||||
```
|
||||
|
||||
### Создание релиза
|
||||
|
||||
```bash
|
||||
# Создание тега для production деплоя
|
||||
git tag v1.2.3
|
||||
git push origin v1.2.3
|
||||
|
||||
# Drone автоматически запустит production деплой
|
||||
```
|
||||
|
||||
### Откат изменений
|
||||
|
||||
```bash
|
||||
# SSH на сервер
|
||||
ssh production
|
||||
|
||||
# Откат к предыдущей версии
|
||||
cd /opt/catlink
|
||||
./manage-production.sh restore /opt/catlink/backups/backup-production-YYYYMMDD-HHMMSS.sql.gz
|
||||
|
||||
# Или через Docker образы
|
||||
docker-compose -f docker-compose.production.yml down
|
||||
# Измените версию в docker-compose.production.yml
|
||||
docker-compose -f docker-compose.production.yml up -d
|
||||
```
|
||||
|
||||
## 📊 Мониторинг и уведомления
|
||||
|
||||
### Health checks
|
||||
|
||||
**Автоматические проверки**:
|
||||
- API доступность (`/api/health/`)
|
||||
- Frontend загрузка (`/`)
|
||||
- Database подключение
|
||||
- Redis доступность
|
||||
|
||||
**Мониторинг производительности**:
|
||||
```bash
|
||||
# Статус сервисов
|
||||
./manage-production.sh status
|
||||
|
||||
# Проверка здоровья
|
||||
./manage-production.sh health
|
||||
|
||||
# Мониторинг ресурсов
|
||||
./monitor-production.sh
|
||||
```
|
||||
|
||||
### Уведомления
|
||||
|
||||
**Slack интеграция**:
|
||||
```bash
|
||||
# Настройка в Drone secrets
|
||||
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
|
||||
```
|
||||
|
||||
**Discord интеграция**:
|
||||
```bash
|
||||
# Настройка в Drone secrets
|
||||
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
|
||||
```
|
||||
|
||||
**Email уведомления**:
|
||||
- Критические ошибки деплоя
|
||||
- Проблемы с безопасностью
|
||||
- Завершение деплоя в production
|
||||
|
||||
### Логи и мониторинг
|
||||
|
||||
```bash
|
||||
# Просмотр логов деплоя
|
||||
ssh production
|
||||
cd /opt/catlink
|
||||
./manage-production.sh logs
|
||||
|
||||
# Мониторинг в реальном времени
|
||||
./monitor-production.sh
|
||||
|
||||
# Логи конкретного сервиса
|
||||
./manage-production.sh logs web
|
||||
./manage-production.sh logs frontend
|
||||
```
|
||||
|
||||
## 🔧 Устранение неполадок
|
||||
|
||||
### Частые проблемы
|
||||
|
||||
#### 1. Ошибка аутентификации Docker registry
|
||||
|
||||
**Проблема**: `Error response from daemon: pull access denied`
|
||||
|
||||
**Решение**:
|
||||
```bash
|
||||
# Проверьте переменные
|
||||
echo $DOCKER_USERNAME
|
||||
echo $DOCKER_PASSWORD
|
||||
|
||||
# Перелогиньтесь
|
||||
docker logout
|
||||
docker login
|
||||
```
|
||||
|
||||
#### 2. SSH подключение не работает
|
||||
|
||||
**Проблема**: `Permission denied (publickey)`
|
||||
|
||||
**Решение**:
|
||||
```bash
|
||||
# Проверьте SSH ключ
|
||||
ssh-keygen -y -f ~/.ssh/id_rsa
|
||||
|
||||
# Проверьте формат в Drone
|
||||
cat ~/.ssh/id_rsa | base64 -w 0
|
||||
|
||||
# Добавьте ключ на сервер
|
||||
ssh-copy-id user@server
|
||||
```
|
||||
|
||||
#### 3. Деплой завис
|
||||
|
||||
**Проблема**: Деплой не завершается
|
||||
|
||||
**Решение**:
|
||||
```bash
|
||||
# Проверьте статус контейнеров
|
||||
docker-compose ps
|
||||
|
||||
# Проверьте логи
|
||||
docker-compose logs
|
||||
|
||||
# Перезапустите сервисы
|
||||
docker-compose restart
|
||||
|
||||
# В крайнем случае - полный перезапуск
|
||||
docker-compose down
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
#### 4. Тесты падают в CI
|
||||
|
||||
**Проблема**: Тесты проходят локально, но падают в CI
|
||||
|
||||
**Решение**:
|
||||
```bash
|
||||
# Запустите тесты локально как в CI
|
||||
make ci-test
|
||||
|
||||
# Проверьте переменные окружения
|
||||
env | grep -E "(TEST_|CI_|DJANGO_)"
|
||||
|
||||
# Проверьте зависимости
|
||||
pip list
|
||||
npm list
|
||||
```
|
||||
|
||||
### Отладка Drone пайплайна
|
||||
|
||||
```bash
|
||||
# Валидация конфигурации
|
||||
make drone-validate
|
||||
|
||||
# Локальный запуск
|
||||
drone exec
|
||||
|
||||
# Просмотр логов
|
||||
drone build ls smartsoltech/links
|
||||
drone build logs smartsoltech/links <build_number>
|
||||
```
|
||||
|
||||
### Откат деплоя
|
||||
|
||||
```bash
|
||||
# 1. Быстрый откат через Docker
|
||||
docker tag catlink-backend:previous catlink-backend:latest
|
||||
docker tag catlink-frontend:previous catlink-frontend:latest
|
||||
docker-compose up -d
|
||||
|
||||
# 2. Откат через бэкап
|
||||
./manage-production.sh restore backup-file.sql.gz
|
||||
|
||||
# 3. Откат к конкретной версии
|
||||
# Измените версию в docker-compose.production.yml
|
||||
# Перезапустите сервисы
|
||||
```
|
||||
|
||||
### Контакты для поддержки
|
||||
|
||||
- **Email**: support@catlink.dev
|
||||
- **Slack**: #devops-support
|
||||
- **Документация**: [docs/](./README.md)
|
||||
- **Issues**: GitHub Issues
|
||||
|
||||
---
|
||||
|
||||
## 📚 Дополнительные ресурсы
|
||||
|
||||
- [Drone CI Documentation](https://docs.drone.io/)
|
||||
- [Docker Best Practices](https://docs.docker.com/develop/dev-best-practices/)
|
||||
- [Django Deployment](https://docs.djangoproject.com/en/stable/howto/deployment/)
|
||||
- [Next.js Deployment](https://nextjs.org/docs/deployment)
|
||||
- [Docker Security](https://docs.docker.com/engine/security/)
|
||||
|
||||
**Последнее обновление**: $(date)
|
||||
**Версия документации**: 1.0
|
||||
Reference in New Issue
Block a user