Docker Compose 部署

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

视频教程

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

在 B站观看视频教程

视频内容简介：

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

视频时长：约 15 分钟

前置要求

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

安装 Docker

Windows

下载并安装 Docker Desktop for Windows

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

macOS

下载并安装 Docker Desktop for Mac

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

Linux

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

sudo apt-get update
sudo apt-get install docker.io docker-compose-plugin

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

sudo systemctl start docker
sudo systemctl enable docker

验证安装

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

docker --version
docker compose version

快速开始

1. 生成 Docker Compose 配置文件

打开 Docker Compose Builder (独立站点)
根据您的需求填写配置：
- 选择 API 提供商（智谱 AI、Anthropic 官方或自定义）
- 配置端口、数据库、工作目录等选项
- 选择镜像源：根据您的网络环境选择合适的镜像源
点击生成按钮，获取 docker-compose.yml 配置
将生成的配置保存为 docker-compose.yml 文件
如果需要，创建 .env 文件配置敏感信息

镜像源选择

生成器支持三个镜像源选项：

Docker Hub

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

Azure Container Registry (ACR)

镜像地址：hagicode.azurecr.io/hagicode:{tag}
适用场景：适合本地网络无法访问 Docker Hub 的用户
优点：提供备选镜像源，解决网络访问问题
注意事项：镜像与 Docker Hub 保持同步，但可能存在短暂延迟

阿里云容器镜像服务（ACR）

镜像地址：registry.cn-hangzhou.aliyuncs.com/hagicode/hagicode:{tag}
适用场景：适合国内用户，网络访问稳定，下载速度快
优点：阿里云国内节点，访问速度快，稳定性高
注意事项：镜像与 Docker Hub 保持同步，通常延迟在 30 分钟内

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

配置说明

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

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

docker compose restart

访问应用

Web 界面

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

http://localhost:45000

数据持久化

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

后续步骤

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

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