120 lines
5.7 KiB
Markdown
120 lines
5.7 KiB
Markdown
# Микросервис "Marquiz Metrica Connector" (v2.0)
|
||
|
||
**Версия:** 2.0
|
||
**Статус:** Staging-окружение развернуто и готово к интеграции.
|
||
|
||
---
|
||
|
||
## 1. Назначение проекта
|
||
|
||
**Marquiz Metrica Connector** — это backend-микросервис, который предоставляет безопасный, стабильный и гибкий API для управления счетчиками и целями в Яндекс.Метрике. Он служит "мостом" между frontend-частью Marquiz и сложным Management API Яндекса.
|
||
|
||
**Ключевые функции:**
|
||
* 🔐 **Безопасная OAuth 2.0 авторизация** пользователей.
|
||
* 📊 **Управление счетчиками:** получение списка, создание.
|
||
* 🎯 **Управление целями:** получение списка, создание кастомных целей, массовое удаление.
|
||
|
||
---
|
||
|
||
## 2. Стек и архитектура
|
||
|
||
| Компонент | Технология |
|
||
| :--- | :--- |
|
||
| **Язык** | Python 3.11+ |
|
||
| **Фреймворк** | FastAPI (асинхронный) |
|
||
| **Сервер** | Gunicorn + Uvicorn (production-ready) |
|
||
| **Зависимости** | Poetry |
|
||
| **Тестирование** | Pytest |
|
||
| **Контейнеризация** | Docker (multi-stage build) |
|
||
| **CI/CD** | Gitea + Drone |
|
||
| **Управление секретами** | **git-crypt** |
|
||
|
||
---
|
||
|
||
## 3. Локальная разработка
|
||
|
||
### 3.1. Первоначальная настройка
|
||
|
||
1. **Установите необходимое ПО:**
|
||
```bash
|
||
# Для Debian/Ubuntu
|
||
sudo apt-get update && sudo apt-get install -y git-crypt poetry
|
||
```
|
||
|
||
2. **Получите мастер-ключ проекта** (`marquiz-metrics.key`) от администратора репозитория.
|
||
|
||
3. **Клонируйте репозиторий:**
|
||
```bash
|
||
git clone [ssh_url_репозитория] marquiz-metrics
|
||
cd marquiz-metrics
|
||
```
|
||
|
||
4. **"Отомкните" репозиторий**, чтобы расшифровать секретные файлы:
|
||
```bash
|
||
git-crypt unlock /путь/к/вашему/marquiz-metrics.key
|
||
```
|
||
|
||
5. **Создайте локальные файлы конфигурации** из шаблонов.
|
||
```bash
|
||
# Создаем .env с вашими тестовыми секретами
|
||
cp envs/staging.env .env
|
||
|
||
# Создаем docker-compose.yml для локального запуска
|
||
cp docker-compose.base.yml docker-compose.yml
|
||
```
|
||
> **Примечание:** Файлы `.env` и `docker-compose.yml` находятся в `.gitignore` и не попадут в репозиторий.
|
||
|
||
6. **Установите зависимости проекта:**
|
||
```bash
|
||
make install
|
||
```
|
||
|
||
### 3.2. Полезные команды (`Makefile`)
|
||
|
||
Для удобства все рутинные операции вынесены в `Makefile`.
|
||
|
||
* **Запустить сервис локально:**
|
||
```bash
|
||
make dev-up
|
||
```
|
||
* **Остановить сервис:**
|
||
```bash
|
||
make dev-down
|
||
```
|
||
* **Смотреть логи:**
|
||
```bash
|
||
make dev-logs
|
||
```
|
||
* **Запустить автотесты:**
|
||
```bash
|
||
make test
|
||
```
|
||
* **Сделать коммит и push в текущую ветку:**
|
||
```bash
|
||
make save msg="feat: Описание ваших изменений"
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Процесс CI/CD (Gitea + Drone)
|
||
|
||
Проект использует CI/CD для автоматического тестирования и развертывания на Staging-окружение.
|
||
|
||
* **Триггер:** `git push` в ветку `staging`.
|
||
* **Пайплайн (`.drone.yml`):**
|
||
1. **Login:** Drone логинится в Docker Hub для скачивания образов-инструментов.
|
||
2. **Test:** Запускаются автотесты `pytest`. В случае ошибки пайплайн останавливается.
|
||
3. **Deploy:** Если тесты прошли, Drone подключается к Staging VDS по SSH и запускает скрипт `scripts/deploy.sh`.
|
||
* **Скрипт `deploy.sh` (на VDS):**
|
||
1. `git pull`: Скачивает последнюю версию кода. `git-crypt` на сервере **автоматически расшифровывает** секреты.
|
||
2. `cat ... > .env.staging`: Собирает финальный файл с переменными окружения.
|
||
3. `make staging-up`: Пересобирает и перезапускает Docker-контейнер с новым кодом и конфигурацией.
|
||
|
||
---
|
||
|
||
## 5. Управление секретами (git-crypt)
|
||
|
||
* Секреты для каждого окружения (`staging`, `prod`) хранятся в папке `envs/` в **зашифрованном** виде прямо в Git.
|
||
* Файл `.gitattributes` в корне проекта указывает `git-crypt`, какие именно файлы (`envs/*.env`) подлежат шифрованию.
|
||
* Шифрование/расшифровка происходят **прозрачно и автоматически** при выполнении команд `git commit` / `git pull` на "отпертом" репозитории.
|
||
* Доступ к секретам получают только те разработчики и серверы, у которых есть **мастер-ключ**. Ключ **никогда не хранится в Git**. |