307 lines
11 KiB
Markdown
307 lines
11 KiB
Markdown
# Настройка CI/CD для проекта Mnemo Cards
|
||
|
||
Этот документ описывает настройку автоматической сборки, тестирования и развертывания проекта в Forgejo.
|
||
|
||
## Архитектура CI/CD
|
||
|
||
Проект использует многоуровневую архитектуру CI/CD с разделением на отдельные компоненты:
|
||
|
||
- **Backend** (Dart) - серверная часть
|
||
- **Web App** (Flutter Web) - веб версия приложения
|
||
- **Mobile App** (Flutter) - мобильное приложение для Android/iOS
|
||
- **Common Libraries** - общие пакеты
|
||
|
||
## Структура Workflow
|
||
|
||
```
|
||
tools/ci/
|
||
├── ci-main.yml # Главный координирующий workflow
|
||
├── ci-backend.yml # CI для backend
|
||
├── ci-web.yml # CI для веб приложения
|
||
├── ci-mobile.yml # CI для мобильного приложения
|
||
├── cd-deploy.yml # CD для развертывания
|
||
├── code-quality.yml # Контроль качества кода
|
||
├── release.yml # Автоматические релизы
|
||
└── agent.yml # AI-агент для автоматической генерации кода
|
||
```
|
||
|
||
## Требуемые Secrets
|
||
|
||
Для работы CI/CD необходимо настроить следующие секреты в Forgejo:
|
||
|
||
### SSH доступ для развертывания
|
||
```
|
||
DEPLOY_SSH_PRIVATE_KEY # Приватный SSH ключ для доступа к серверу 147.45.152.129
|
||
```
|
||
|
||
### API ключи (опционально)
|
||
```
|
||
OPENAI_API_KEY # Для AI-агента
|
||
```
|
||
|
||
## Настройка серверов
|
||
|
||
### Единый сервер (147.45.152.129)
|
||
- **API Backend** (api.mnemo-cards.online): Dart SDK, systemd сервис `mnemo_cards_server.service`
|
||
- **Web App** (mnemo-cards.online): Nginx, Flutter Web приложение
|
||
- **SSL**: Let's Encrypt сертификаты для обоих доменов
|
||
- **CORS**: Правильно настроен между доменами, COEP/COOP headers отключены для совместимости
|
||
- Доступ по SSH для деплоя
|
||
|
||
## Процесс CI/CD
|
||
|
||
### 1. Code Quality Gate
|
||
- Проверка линтинга для всех проектов
|
||
- Запуск тестов с покрытием
|
||
- Сканирование на наличие секретов
|
||
- Проверка зависимостей на уязвимости
|
||
|
||
### 2. Сборка компонентов
|
||
- **Backend**: Компиляция в нативный бинарный файл
|
||
- **Web App**: Сборка Flutter web приложения
|
||
- **Mobile App**: Сборка APK для Android и app для iOS
|
||
|
||
### 3. Развертывание
|
||
- **Backend**: Автоматическое обновление сервиса
|
||
- **Web App**: Rsync на веб сервер + перезагрузка Nginx
|
||
- **Mobile App**: Создание GitHub релиза с APK
|
||
|
||
## 🚀 Быстрый старт деплоя
|
||
|
||
### ✅ Чек-лист готовности
|
||
|
||
- [ ] **SSH ключ сгенерирован и добавлен на сервер**
|
||
- [ ] **DNS домены настроены** (`mnemo-cards.online`, `api.mnemo-cards.online`, `code.mnemo-cards.online`)
|
||
- [ ] **Forgejo secrets настроены** (`DEPLOY_SSH_PRIVATE_KEY`)
|
||
- [ ] **Код готов к деплою** (все тесты проходят)
|
||
|
||
### 🎯 Запуск в 3 шага
|
||
|
||
1. **Подготовка:**
|
||
```bash
|
||
# Генерация и настройка SSH ключа
|
||
ssh-keygen -t ed25519 -C "forgejo-deploy@mnemo-cards.online" -f ~/.ssh/forgejo_deploy
|
||
ssh-copy-id -i ~/.ssh/forgejo_deploy.pub root@147.45.152.129
|
||
```
|
||
|
||
2. **Настройка Forgejo:**
|
||
- Перейти в Settings → Secrets
|
||
- Добавить `DEPLOY_SSH_PRIVATE_KEY` с содержимым `~/.ssh/forgejo_deploy`
|
||
|
||
3. **Запуск:**
|
||
```bash
|
||
git push origin main # Автоматический запуск CI/CD
|
||
```
|
||
|
||
## Запуск CI/CD
|
||
|
||
### 🔧 Предварительная настройка
|
||
|
||
#### 1. Настройка SSH доступа
|
||
```bash
|
||
# Генерация SSH ключа (если нет)
|
||
ssh-keygen -t ed25519 -C "forgejo-deploy@mnemo-cards.online" -f ~/.ssh/forgejo_deploy
|
||
|
||
# Копирование публичного ключа на сервер
|
||
ssh-copy-id -i ~/.ssh/forgejo_deploy.pub root@147.45.152.129
|
||
|
||
# Добавление приватного ключа в Forgejo secrets
|
||
# Settings → Secrets → DEPLOY_SSH_PRIVATE_KEY
|
||
cat ~/.ssh/forgejo_deploy
|
||
```
|
||
|
||
#### 2. Настройка DNS доменов
|
||
Убедитесь, что DNS записи настроены:
|
||
- `mnemo-cards.online` → `147.45.152.129`
|
||
- `api.mnemo-cards.online` → `147.45.152.129`
|
||
- `code.mnemo-cards.online` → `147.45.152.129` (для Forgejo)
|
||
|
||
#### 3. Проверка доступа к серверу
|
||
```bash
|
||
# Тест SSH подключения
|
||
ssh -i ~/.ssh/forgejo_deploy root@147.45.152.129 "echo 'SSH works!'"
|
||
|
||
# Проверка что Dart установлен
|
||
ssh root@147.45.152.129 "dart --version"
|
||
|
||
# Проверка что Nginx установлен
|
||
ssh root@147.45.152.129 "nginx -v"
|
||
```
|
||
|
||
### 🚀 Запуск деплоя
|
||
|
||
#### Автоматический запуск
|
||
CI/CD запускается автоматически при:
|
||
- Push в ветки `main`/`master`
|
||
- Создании Pull Request
|
||
- Создании тега релиза (`v*.*.*`)
|
||
|
||
#### Ручной запуск
|
||
1. Перейдите в раздел **Actions** в Forgejo
|
||
2. Выберите workflow **"Main CI Pipeline"**
|
||
3. Нажмите **"Run workflow"**
|
||
|
||
#### Ручной деплой (альтернатива)
|
||
```bash
|
||
# Деплой backend
|
||
tools/deploy/backend-build_app.sh
|
||
|
||
# Деплой web app
|
||
cd mnemo_cards_web_v2
|
||
tools/deploy/web-app/deploy.sh
|
||
```
|
||
|
||
## Мониторинг и логи
|
||
|
||
### Просмотр результатов
|
||
- Результаты тестов: `coverage/lcov.info`
|
||
- Логи сборки: В разделе Actions каждого workflow
|
||
- Артефакты сборки: Скачиваются из Actions
|
||
|
||
### Уведомления
|
||
При успешном/неуспешном завершении можно настроить уведомления через:
|
||
- Email
|
||
- Webhooks
|
||
- Forgejo notifications
|
||
|
||
## Создание релиза
|
||
|
||
### Автоматический релиз
|
||
1. Создайте git tag: `git tag v1.2.3 && git push origin v1.2.3`
|
||
2. Workflow автоматически:
|
||
- Создаст GitHub release
|
||
- Обновит версии в pubspec.yaml файлах
|
||
- Опубликует APK и другие артефакты
|
||
|
||
### Ручной релиз
|
||
Используйте существующие скрипты:
|
||
```bash
|
||
./mnemo_cards_backend/build_app.sh # Деплой backend
|
||
./mnemo_cards_web_v2/deploy/deploy.sh # Деплой web app
|
||
```
|
||
|
||
## Troubleshooting
|
||
|
||
### 🚨 Проблемы с деплоем
|
||
|
||
#### SSH подключение не работает
|
||
```bash
|
||
# Проверка SSH ключа локально
|
||
ssh -i ~/.ssh/forgejo_deploy root@147.45.152.129 "echo 'Connection OK'"
|
||
|
||
# Проверка что ключ добавлен в known_hosts
|
||
ssh-keyscan -H 147.45.152.129 >> ~/.ssh/known_hosts
|
||
|
||
# В Forgejo secrets должен быть полный приватный ключ
|
||
cat ~/.ssh/forgejo_deploy
|
||
```
|
||
|
||
#### Backend деплой падает
|
||
```bash
|
||
# Проверка что Dart установлен на сервере
|
||
ssh root@147.45.152.129 "which dart && dart --version"
|
||
|
||
# Ручной запуск build скрипта
|
||
tools/deploy/backend-build_app.sh
|
||
|
||
# Проверка статуса сервиса
|
||
ssh root@147.45.152.129 "systemctl status mnemo_cards_server"
|
||
```
|
||
|
||
#### Web app деплой падает
|
||
```bash
|
||
# Проверка что Nginx установлен
|
||
ssh root@147.45.152.129 "which nginx && nginx -v"
|
||
|
||
# Ручной запуск deploy скрипта
|
||
cd mnemo_cards_web_v2
|
||
tools/deploy/web-app/deploy.sh
|
||
|
||
# Проверка Nginx конфигурации
|
||
ssh root@147.45.152.129 "nginx -t"
|
||
```
|
||
|
||
#### SSL сертификаты не работают
|
||
```bash
|
||
# Проверка Let's Encrypt сертификатов
|
||
ssh root@147.45.152.129 "ls -la /etc/letsencrypt/live/"
|
||
|
||
# Ручное получение сертификатов
|
||
ssh root@147.45.152.129 "certbot certonly --standalone -d mnemo-cards.online -d api.mnemo-cards.online --email admin@mnemo-cards.online"
|
||
```
|
||
|
||
#### DNS проблемы
|
||
```bash
|
||
# Проверка DNS разрешения
|
||
nslookup mnemo-cards.online
|
||
nslookup api.mnemo-cards.online
|
||
nslookup code.mnemo-cards.online
|
||
|
||
# Проверка доступности портов
|
||
telnet 147.45.152.129 80
|
||
telnet 147.45.152.129 443
|
||
telnet 147.45.152.129 8443
|
||
telnet 147.45.152.129 8081
|
||
```
|
||
|
||
### Проблемы с зависимостями
|
||
```bash
|
||
# Очистка кэша
|
||
flutter clean
|
||
flutter pub cache repair
|
||
```
|
||
|
||
### Проблемы с SSH
|
||
```bash
|
||
# Проверка SSH ключа
|
||
ssh -T git@code.mnemo-cards.online
|
||
|
||
# Проверка доступа к серверам
|
||
ssh -i ~/.ssh/forgejo_deploy root@147.45.152.129
|
||
```
|
||
|
||
### Проблемы с тестами
|
||
```bash
|
||
# Запуск тестов локально
|
||
cd mnemo_cards_web_v2
|
||
flutter test --coverage
|
||
|
||
# Просмотр покрытия
|
||
genhtml coverage/lcov.info -o coverage/html
|
||
open coverage/html/index.html
|
||
```
|
||
|
||
## Безопасность
|
||
|
||
### Защита секретов
|
||
- Никогда не коммитьте реальные ключи в код
|
||
- Используйте отдельные ключи для каждого окружения
|
||
- Регулярно ротируйте SSH ключи
|
||
|
||
### Code Quality Gates
|
||
- Минимальное покрытие тестами: 80%
|
||
- Обязательный проход линтера
|
||
- Сканирование на уязвимости в зависимостях
|
||
|
||
## Расширение CI/CD
|
||
|
||
### Добавление нового компонента
|
||
1. Создайте новый workflow файл в `.forgejo/workflows/`
|
||
2. Добавьте ссылку в `ci-main.yml`
|
||
3. Настройте необходимые секреты
|
||
|
||
### Кастомные проверки
|
||
Добавьте в `code-quality.yml`:
|
||
```yaml
|
||
- name: Custom check
|
||
run: |
|
||
# Ваша логика проверки
|
||
```
|
||
|
||
## Контакты
|
||
|
||
При проблемах с CI/CD:
|
||
1. Проверьте логи в Actions
|
||
2. Убедитесь, что все секреты настроены
|
||
3. Проверьте доступ к серверам
|
||
4. Создайте issue в репозитории
|