Развертывание Docker Compose

На этой странице описано, как развернуть Hagicode с помощью Docker Compose. Этот способ подходит для серверов, NAS, совместной работы в команде и сценариев, где нужна изоляция среды; для личного локального использования в первую очередь рассмотрите Microsoft Store или Desktop.

Почему стоит выбрать Docker Compose

• изоляция среды уменьшает конфликты зависимостей
• поддерживаемый в настоящее время стек служб Hagicode запускается за один раз
• конфигурация, обновление и обслуживание выполняются единообразно
• на хосте нужен только Docker, устанавливать Node.js или Git дополнительно не требуется

О хранилище данных по умолчанию

Поддерживаемые в настоящее время шаблоны Docker Compose организуют постоянные данные по пути локальной SQLite по умолчанию. В большинстве случаев вам не нужно отдельно готовить на хосте службу базы данных.

Видеоурок

Если вы хотите сначала увидеть весь процесс, начните с видеоурока:

Смотреть видеоурок на Bilibili

Краткое содержание видео:

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

Продолжительность видео: около 15 минут

Предварительные требования

Перед началом убедитесь, что в вашей системе установлены Docker и Docker Compose.

Установка Docker

Windows

Скачайте и установите Docker Desktop for Windows. После установки убедитесь, что Docker Desktop запущен.

macOS

Скачайте и установите Docker Desktop for Mac. После установки убедитесь, что Docker Desktop запущен.

Linux

Установите Docker Engine и плагин Docker Compose для вашего дистрибутива по официальной документации Docker: Install Docker Engine. У разных дистрибутивов разные источники пакетов и имена пакетов, поэтому не копируйте команды, предназначенные для другого дистрибутива.

После установки запустите службу Docker и включите ее автозапуск:

sudo systemctl start docker
sudo systemctl enable docker

Проверка установки

После установки выполните следующие команды, чтобы убедиться, что Docker и Docker Compose установлены правильно:

docker --version
docker compose version

Быстрый старт

1. Создайте файл конфигурации Docker Compose

Используйте Docker Compose Builder, чтобы создать docker-compose.yml. Это отдельный сайт, и правила генерации и обновления определяются им.

Генератор поддерживает:

• выбор поставщика API (Zhipu AI, Anthropic Official, пользовательский API) и настройку API URL и Token
• настройку порта, имени контейнера, каталога постоянных данных и рабочего каталога
• выбор встроенной или внешней базы данных
• автоматический учет различий между Windows и Linux и типичных проблем с правами доступа к файлам
• использование поддерживаемого образа Docker Hub

Порядок действий:

1. Откройте Docker Compose Builder.
2. Заполните конфигурацию в соответствии со своими потребностями: выберите поставщика API, настройте порт, базу данных, рабочий каталог и другие параметры.
3. Нажмите кнопку создания, чтобы получить конфигурацию docker-compose.yml.
4. Сохраните созданную конфигурацию в файл docker-compose.yml.
5. При необходимости создайте файл .env для конфиденциальных данных, чтобы не записывать Token прямо в compose-файл.

Источник образа

Генератор использует Docker Hub как поддерживаемый источник образов:

• Адрес образа: newbe36524/hagicode:{tag}
• Когда подходит: подходит пользователям, у которых работает ускорение зеркал Docker Hub
• Примечание: в некоторых регионах может потребоваться настроить ускоритель зеркал

Получение API Token

Развертывание в Docker обращается к моделям через поставщика API, настроенного в генераторе, поэтому сначала нужно подготовить рабочий API Token:

Zhipu AI: Получить API Token →

• Стабильный доступ из Китая, более быстрый отклик
• Хорошее соотношение цены и качества, подходит для повседневного использования

Anthropic Official: Получить API Token →

• Прямое использование сервисов Anthropic

В генераторе также можно выбрать пользовательский API.

2. Запустите службу

Выполните следующую команду в каталоге, где находится docker-compose.yml:

docker compose up -d

Эта команда:

• скачает и запустит контейнеры Hagicode, определенные в созданной конфигурации
• создаст и настроит сеть
• инициализирует каталог данных по умолчанию и зависимости времени выполнения

3. Проверьте состояние службы

Проверьте, запущены ли контейнеры:

docker compose ps

Службы, определенные в созданной конфигурации, должны находиться в состоянии «running».

Просмотр журналов службы:

# Показать журналы всех служб
docker compose logs

# Показать журналы службы Hagicode
docker compose logs hagicode

# Следить за журналами в реальном времени
docker compose logs -f hagicode

Доступ к приложению

После успешного запуска службы откройте в браузере:

http://localhost:45000

Если в генераторе вы изменили порт, используйте заданный вами порт хоста. При первом открытии появится мастер инициализации — продолжайте с раздела Настройка мастера инициализации.

Описание конфигурации

Если нужно изменить конфигурацию (например, сменить порт или поставщика API), вы можете:

1. Заново создать конфигурацию в Docker Compose Builder
2. Вручную отредактировать файлы docker-compose.yml и .env
3. Пересоздать контейнеры, чтобы конфигурация вступила в силу:

docker compose up -d

docker compose restart только перезапускает существующие контейнеры и не применяет изменения в docker-compose.yml или .env. После изменения конфигурации используйте docker compose up -d.

Сохранение данных

Поддерживаемый в настоящее время путь Docker Compose по умолчанию использует файлы данных SQLite и постоянные тома. Если вам нужно проверить, куда смонтированы данные, или спланировать резервное копирование, посмотрите сопоставление томов и каталогов данных в созданном файле docker-compose.yml.

Повседневное обслуживание

Остановка и запуск

# Остановить службы (контейнеры и данные сохраняются)
docker compose stop

# Запустить снова
docker compose start

# Остановить и удалить контейнеры (тома данных сохраняются)
docker compose down

Не добавляйте без необходимости -v к docker compose down: эта опция также удалит тома данных, объявленные в compose-файле.

Обновление версии

1. Перед обновлением сделайте резервную копию каталога данных (см. ниже).
2. Замените в docker-compose.yml тег образа newbe36524/hagicode:{tag} на нужную версию или заново создайте конфигурацию в генераторе.
3. Скачайте новый образ и пересоздайте контейнеры:

docker compose pull
docker compose up -d

Резервное копирование данных

Сначала выполните docker compose stop, чтобы служба перестала записывать данные, затем сделайте резервную копию каталогов или томов данных, на которые указывают сопоставления томов и каталогов данных в docker-compose.yml, и после этого выполните docker compose start, чтобы возобновить работу службы.

Дальнейшие шаги

Теперь вы успешно развернули Hagicode. Далее:

1. Прочитайте Настройка мастера инициализации, чтобы создать Hagicoder по умолчанию и первый проект.
2. В Создать сеанс разговора сначала изучите проект в режиме только для чтения, а затем при необходимости перейдите к Создать сеанс предложений.

Если вы предпочитаете настольное приложение, см. Руководство по установке Desktop.