478 lines
13 KiB
Markdown
478 lines
13 KiB
Markdown
# 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 |