cinnabarflower/mnemo_cards
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
mnemo_cards/tools/docs/CI_CD_SETUP.md

308 lines
11 KiB
Markdown
Raw Normal View History

stuff
2025-11-16 13:54:50 +00:00
# Настройка 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.memo-cards.online): Dart SDK, systemd сервис `mnemo_cards_server.service`
- **Web App** (memo-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 домены настроены** (`memo-cards.online`, `api.memo-cards.online`, `code.memo-cards.online`)
- [ ] **Forgejo secrets настроены** (`DEPLOY_SSH_PRIVATE_KEY`)
- [ ] **Код готов к деплою** (все тесты проходят)
### 🎯 Запуск в 3 шага
1. **Подготовка:**
```bash
# Генерация и настройка SSH ключа
ssh-keygen -t ed25519 -C "forgejo-deploy@memo-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 записи настроены:
- `memo-cards.online` → `147.45.152.129`
- `api.memo-cards.online` → `147.45.152.129`
- `code.memo-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 memo-cards.online -d api.memo-cards.online --email admin@memo-cards.online"
```
#### DNS проблемы
```bash
# Проверка DNS разрешения
nslookup memo-cards.online
nslookup api.memo-cards.online
nslookup code.memo-cards.online
# Проверка доступности портов
telnet 147.45.152.129 80
telnet 147.45.152.129 443
deploy
2025-11-16 16:31:22 +00:00
telnet 147.45.152.129 8443
stuff
2025-11-16 13:54:50 +00:00
telnet 147.45.152.129 8081
```
### Проблемы с зависимостями
```bash
# Очистка кэша
flutter clean
flutter pub cache repair
```
### Проблемы с SSH
```bash
# Проверка SSH ключа
ssh -T git@code.memo-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 в репозитории
Reference in a new issue Copy permalink