跳转到内容
Hagicode Docs
博客

Docker Compose 部署

编辑此页

本页说明如何用 Docker Compose 部署 Hagicode。对大多数用户来说，这是默认部署路径，开发、测试和生产环境都可沿用。

视频教程

若你想先看完整流程，可先看视频教程：

在 B站观看视频教程

视频内容简介：

  • Docker Compose 部署的完整流程演示
  • 配置文件生成和修改说明
  • 服务启动和验证步骤
  • 常见问题和解决方案

视频时长：约 15 分钟

Docker Compose Builder

Docker Compose Builder 现已独立提供，地址：https://builder.hagicode.com/。它负责生成同类配置，更新也以该站点为准。

使用配置生成器

可直接使用 Docker Compose Builder（独立站点） 生成 docker-compose.yml。

生成器支持：

  • 自定义端口、容器名称等基础配置
  • 选择内置数据库或外部数据库
  • 自动处理 Windows / Linux 的平台差异
  • 处理常见文件权限问题
  • 使用受支持的 Docker Hub 镜像

打开生成器 →

推荐方式

Docker Compose 是多数场景下的默认部署路径，原因如下：

  • 环境隔离，依赖冲突更少
  • 可一次启动当前支持的 Hagicode 服务栈
  • 配置、升级与维护路径更统一
  • 适合本地体验、测试与团队部署

关于默认数据存储

当前支持的 Docker Compose 模板按默认本地 SQLite 数据路径组织持久化数据。大多数情况下，您不需要在主机上额外准备独立数据库服务。

前置要求

在开始之前，请确保您的系统已安装 Docker 和 Docker Compose。

安装 Docker

Windows

下载并安装 Docker Desktop for Windows

安装完成后，确保 Docker Desktop 正在运行。

macOS

下载并安装 Docker Desktop for Mac

安装完成后，确保 Docker Desktop 正在运行。

Linux

使用您的包管理器安装 Docker：

在 Ubuntu/Debian 上安装 Docker
sudo apt-get update
sudo apt-get install docker.io docker-compose-plugin

安装完成后，启动 Docker 服务：

Terminal window
sudo systemctl start docker
sudo systemctl enable docker

验证安装

安装完成后，运行以下命令验证 Docker 和 Docker Compose 是否正确安装：

Terminal window
docker --version
docker compose version

快速开始

1. 生成 Docker Compose 配置文件

使用配置生成器

推荐使用 Docker Compose Builder (独立站点) 来生成您的配置文件。

生成器支持：

  • 多种 API 提供商选择（智谱 AI、Anthropic 官方、自定义 API）
  • 自动配置 API URL 和 Token
  • 自定义端口、容器名称等基础配置
  • 配置持久化目录与工作目录
  • 自动配置 Windows/Linux 平台差异
  • 智能处理文件权限问题

🚀 立即使用生成器 →

  1. 打开 Docker Compose Builder (独立站点)
  2. 根据您的需求填写配置：
    • 选择 API 提供商（智谱 AI、Anthropic 官方或自定义）
    • 配置端口、数据库、工作目录等选项
    • 使用 Docker Hub 镜像：生成器会配置受支持的 Docker Hub 镜像
  3. 点击生成按钮，获取 docker-compose.yml 配置
  4. 将生成的配置保存为 docker-compose.yml 文件
  5. 如果需要，创建 .env 文件配置敏感信息

镜像来源

生成器使用 Docker Hub 作为受支持的镜像来源：

Docker Hub

  • 镜像地址：newbe36524/hagicode:{tag}
  • 适用场景：适合支持 Docker Hub 镜像加速的用户
  • 优点：官方镜像源，更新及时，访问稳定
  • 注意事项：部分地区可能需要配置镜像加速器

获取 API Token

您需要配置 Claude API Token 才能使用 Hagicode：

智谱 AI（推荐）：获取 API Token →

  • 国内访问稳定，响应更快
  • 性价比高，适合日常使用

Anthropic 官方：获取 API Token →

  • 直接使用 Anthropic 的服务

2. 启动服务

在 docker-compose.yml 所在目录执行以下命令：

Terminal window
docker compose up -d

此命令将：

  • 下载并启动生成配置中定义的 Hagicode 容器
  • 创建并配置网络
  • 初始化默认数据目录与运行时依赖

3. 验证服务状态

检查容器是否正在运行：

Terminal window
docker compose ps

您应该看到生成配置中定义的服务处于 “running” 状态。

查看服务日志：

Terminal window
# 查看所有服务日志
docker compose logs


# 查看 Hagicode 服务日志
docker compose logs hagicode


# 实时跟踪日志
docker compose logs -f hagicode

配置说明

如需修改配置（如更改端口、切换 API 提供商等），您可以：

  1. 重新使用 Docker Compose Builder (独立站点) 生成新配置
  2. 手动编辑 docker-compose.yml 和 .env 文件
  3. 重启服务使配置生效：
Terminal window
docker compose restart

访问应用

Web 界面

服务启动成功后，通过浏览器访问：

http://localhost:45000

数据持久化

当前支持的 Docker Compose 路径默认使用 SQLite 数据文件与持久化卷。若您需要检查数据挂载位置或备份策略，请直接查看生成后的 docker-compose.yml 中卷与数据目录映射配置。

后续步骤

现在您已经成功部署了 Hagicode。接下来请先在 Web 界面中接入一个真实项目，再继续阅读初始化向导设置或创建提案会话。

如果您更喜欢使用桌面应用方式部署，请参阅Desktop 安装指南。