This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Развертывание и CI/CD

Эта страница описывает процесс сборки Docker-образов, настройки контейнерной среды и автоматизации процессов непрерывной интеграции и доставки (CI/CD) в Forgejo.

Архитектура развертывания

Проект использует Docker для обеспечения изоляции среды выполнения и воспроизводимости. Основные компоненты:

1. Dockerfile — определяет среду выполнения приложения, установку зависимостей и запуск сервиса.
2. docker-compose.yml — оркеструет сервисы (MCP-сервер и опционально MinerU).
3. Forgejo CI/CD — автоматизирует сборку образов и публикацию в Container Registry.

Для быстрого начала работы с контейнерами см. Быстрый старт.

Контейнеризация

Dockerfile

Файл сборки расположен в корне репозитория: Dockerfile.

Ключевые особенности образа:

• Базовый образ: python:3.14-slim (облегченная версия для минимизации размера).
• Многоэтапность: Зависимости устанавливаются до копирования исходного кода для лучшего кэширования слоев.
• Безопасность: Приложение запускается от непривилегированного пользователя mcpuser.
• Автоматические тесты: Тесты (pytest) запускаются внутри контейнера на этапе сборки. Если тесты падают, сборка прерывается.

# Пример фрагмента из Dockerfile
FROM python:3.14-slim
...
# Запуск тестов при сборке
RUN python -m pytest tests/ -v
...
# Безопасность
RUN useradd -m -u 1000 mcpuser && chown -R mcpuser:mcpuser /app
USER mcpuser
...
CMD ["python", "-m", "mineru_mcp.main"]

Docker Compose

Файл docker-compose.yml позволяет запустить сервис локально или в staging-среде.

services:
  mineru-mcp:
    build: .
    container_name: mineru-mcp
    ports:
      - "8001:8001"
    environment:
      - MINERU_URL=http://mineru:8000
      - MINERU_BACKEND=hybrid-engine
      # ... другие переменные из [Конфигурации](configuration)
    restart: unless-stopped

Настройка CI/CD в Forgejo

Пайплайн настроен с использованием файлов workflows в директории .forgejo/workflows.

1. Сборка и публикация Docker-образа

Основной workflow отвечает за сборку образа и его отправку в Forgejo Container Registry. Файл конфигурации: .forgejo/workflows/ci-cd.yml.

Триггеры запуска

• Push в main: Автоматическая сборка и публикация образа с тегом latest.
• Push тегов (v*): Сборка и публикация образа с версионным тегом (например, v0.2.5).
• Workflow Dispatch: Ручной запуск через интерфейс Forgejo с возможностью указания кастомного тега.

Этапы пайплайна

1. Checkout: Клонирование репозитория.
2. Setup Docker Buildx: Подготовка инструментов сборки Docker.
3. Login: Авторизация в Forgejo Container Registry с использованием секрета REGISTRY_TOKEN.
4. Extract Version: Извлечение версии приложения из pyproject.toml для метаданных.
5. Build & Push: Сборка образа и отправка в реестр git.maydayoffice.kz/maydayoffice/mineru-mcp-server.

Необходимые секреты (Secrets)

Для работы пайплайна в настройках репозитория (Settings > Secrets) необходимо добавить:

• REGISTRY_TOKEN: Access Token с правами на запись в Container Registry (write:packages).

2. Генерация Wiki (AI Wiki)

Отдельный workflow генерирует документацию на основе кода с помощью LLM. Файл конфигурации: .forgejo/workflows/wiki-gen.yml.

Он запускается при пуше тегов или вручную. Использует скрипт generate_wiki.py из репозитория инструментов.

Локальная сборка и тестирование

Чтобы собрать образ локально (например, для отладки перед пушем в реестр), выполните:

# Сборка образа
docker build -t mineru-mcp-server:test .

# Проверка запуска
docker run --rm -p 8001:8001 mineru-mcp-server:test

Если на этапе сборки упадут тесты (см. раздел Тестирование), сборка завершится ошибкой. Это гарантирует, что в реестр попадают только стабильные сборки.

Управление версиями образов

Стратегия тегирования образов следующая:

• Теги вида vX.Y.Z соответствуют релизам проекта.
• Тег latest всегда указывает на последнюю успешную сборку ветки main.

Вы можете использовать образ из реестра в своем docker-compose.yml, заменив блок build на image:

services:
  mineru-mcp:
    image: git.maydayoffice.kz/maydayoffice/mineru-mcp-server:v0.2.5
    # ...

См. также

• Конфигурация — Полный список переменных окружения для настройки контейнера.
• Устранение неполадок — Решение проблем с доступностью контейнеров и сетью.
• Руководство разработчика — Как работать с кодом и тестами вне Docker.