Docker Compose 部署

本指南介绍如何使用 Docker Compose 一键部署完整的 Hagicode 系统。这是推荐的部署方式，适合大多数用户，特别是开发、测试和生产环境。

视频教程

为了帮助您更好地理解 Docker Compose 部署过程，我们提供了详细的视频教程：

视频内容简介：

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

此命令将：

下载并启动 PostgreSQL 容器
下载并启动 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

数据库连接

如果您需要直接连接到 PostgreSQL 数据库，可以通过 docker exec 命令进入容器：

# 进入 PostgreSQL 容器并连接到数据库
docker exec -it hagicode-postgres psql -U postgres -d hagicode

容器内连接信息：

主机: localhost 或 127.0.0.1（容器内）
端口: 5432（PostgreSQL 默认端口）
用户名: postgres
密码: postgres
数据库: hagicode

后续步骤

现在您已经成功部署了 Hagicode，请继续创建第一个项目以开始使用。

如果您更喜欢使用软件包方式部署，请参阅软件包部署指南。