AutoGen Studio 容器化部署与维护指南

发表于 2025年05月29日
服务器
更新于 2025年10月25日 16:23:15 下午

适用于 macOS + OrbStack/Docker 环境

1. 安装前准备

1.1 系统要求

macOS 10.15 或更高版本（支持 Intel 和 Apple Silicon 芯片）
已安装 OrbStack 或 Docker Desktop
终端基础操作能力（需熟悉 bash 命令）

1.2 环境验证

# 验证 Docker 是否就绪

docker --version # 示例输出: Docker version 24.0.6

docker-compose --version # 示例输出: Docker Compose version v2.23.0

2. 初始安装步骤

2.1 创建项目目录

mkdir -p ~/autogen-studio/data/.autogenstudio

cd ~/autogen-studio

2.2 编写配置文件

Dockerfile

# 文件名必须为 "Dockerfile"（无扩展名）

FROM python:3.10-slim

# 安装系统依赖

RUN apt-get update && apt-get install -y \

curl \

build-essential \

&& curl -fsSL https://deb.nodesource.com/setup_16.x | bash - \

&& apt-get install -y nodejs \

&& rm -rf /var/lib/apt/lists/*

# 安装前端工具链

RUN npm install -g gatsby-cli yarn

# 安装 AutoGen Studio

RUN pip install --no-cache-dir autogenstudio

# 暴露端口

EXPOSE 8081

# 启动命令

CMD ["autogenstudio", "ui", "--port", "8081", "--host", "0.0.0.0", "--appdir", "/data/.autogenstudio"]

docker-compose.yml

services:

autogenstudio:

build: .

container_name: autogenstudio

ports:

- "8081:8081"

volumes:

- ./data:/data

restart: always

2.3 构建并启动容器

1 2	docker compose up -d --build

3. 数据持久化

3.1 数据目录结构

~/autogen-studio/

├── Dockerfile

├── docker-compose.yml

└── data/

└── .autogenstudio/

├── agents.json

├── chat_sessions.json

├── settings.json

└── ...

3.2 持久化原理

所有运行时产生的数据都保存在 ./data/.autogenstudio 。
通过 volumes 将宿主机 data 映射到容器内 /data ，保证数据不会因容器重建而丢失。

4. 日常使用

4.1 服务管理命令

# 启动服务

docker compose up -d

# 停止服务

docker compose down

# 查看日志

docker compose logs -f

# 重启服务

docker compose restart

4.2 访问 Web 界面

浏览器访问：

1 2	http://localhost:8081

5. 更新到新版本

5.1 更新操作流程

# 停止并移除现有容器

docker compose down

# 完全重建镜像（例如 AutoGen Studio 发布了新版本）

# 重新拉取最新依赖（如 Dockerfile 中版本无锁定）

docker compose build --no-cache

# 启动服务（原有数据自动挂载）

docker compose up -d

5.2 注意事项

性能开销： --no-cache 会显著增加构建时间（需重新下载所有依赖）。
旧镜像清理：重建后建议清理旧镜像： docker image prune # 删除悬空镜像
数据安全：如果希望同时重置数据，需手动删除挂载目录： rm -rf ./data/.autogenstudio

5.3 回滚旧版本

若需回滚，请提前备份 data/ 目录，并恢复旧版 Dockerfile 。

6. 备份与恢复

6.1 数据备份

1 2	tar -czf backup-autogenstudio-$(date +%F).tar.gz data/

6.2 数据恢复

1 2	tar -xzf backup-autogenstudio-xxxx-xx-xx.tar.gz

7. 故障排除

7.1 常见问题

问题描述	解决方案
无法访问网页	确保容器正常运行，访问的是 `localhost:8081`
数据丢失	检查 `volumes` 是否挂载正确
日志中报错	查看详细日志 `docker compose logs -f`
更改配置未生效	重启容器或重新构建 `docker compose up -d --build`