📦 部署前准备

无论选择哪种方式，请确保你的环境满足以下要求：

  • Docker Engine：24.0 或更高版本。
  • Docker Compose：v2.20 或更高版本。
  • 硬件资源：至少 8 GB RAM 和 20 GB 可用磁盘空间（16 GB 内存为佳）。
  • 操作系统：Linux、macOS 或 Windows（通过 WSL 2）。
  • 关键限制：平台中的 code-executor 服务需要 privileged: true 权限，因此无法在 AWS Fargate 或 Google Cloud Run 等不支持特权容器的托管平台上运行。

🚀 第一步：本地快速体验（约 5 分钟）

这是最快的启动方式，适合在本地机器上评估和试用 Future AGI 的全部功能。

1. 克隆仓库并启动
打开终端，执行以下命令克隆项目并运行一键安装脚本。该脚本会自动拉取预构建的镜像并启动所有服务。

1
2
3
git clone https://github.com/future-agi/future-agi.git
cd future-agi
./bin/install

对于 Windows PowerShell 用户，可以运行 .\bin\install.ps1。

脚本会在后台启动一系列容器，当后端日志显示 Application startup complete 时，表示启动完成，整个过程大约需要 30 秒到几分钟（取决于镜像拉取速度）。

2. 访问并创建账户
启动完成后，在浏览器中打开 http://localhost:3000。首次访问时，你可以直接在界面上注册一个本地账户，无需邮件验证。如果安装脚本提示你通过命令行创建用户，也可以按照提示输入邮箱、姓名和密码来完成。

3. 开始使用

  • 核心入口：登录后，你将看到主仪表板。可以开始创建项目，并获取 API 密钥（Settings -> API Keys），用于 SDK 集成。
  • 服务端口：
    • 前端界面：http://localhost:3000
    • 后端 API：http://localhost:8000
    • PeerDB UI（数据复制工具）：http://localhost:3001

🛡️ 第二步：生产环境部署

在生产环境中使用，切勿使用本地安装的默认配置。你需要通过“生产 overlay”文件来强制覆盖不安全的默认值。

1. 生成并配置生产环境变量
首先，从示例文件创建生产环境配置文件：

1
cp deploy/.env.production.example deploy/.env.production

然后，你必须用安全的方式生成并填入以下必需的变量。openssl 命令可以帮助你生成随机密钥：

1
2
3
4
5
6
7
8
# 生成 Django SECRET_KEY, 网关内部通信密钥等
SECRET_KEY=$(openssl rand -hex 32)
AGENTCC_INTERNAL_API_KEY=$(openssl rand -hex 32)
AGENTCC_ADMIN_TOKEN=$(openssl rand -hex 32)

# 生成数据库和存储密码
PG_PASSWORD=$(openssl rand -base64 24)
MINIO_ROOT_PASSWORD=$(openssl rand -base64 24)

将这些生成的值以及你的前端 URL (FRONTEND_URL) 和 API 地址 (VITE_HOST_API) 填入 deploy/.env.production 文件。

2. 锁定生产镜像版本
生产环境应使用不可变的版本标签。在 deploy/.env.production 中，将以下变量的值设置为具体的版本号（例如 v1.38.1），而不是 latest：

  • FUTURE_AGI_VERSION (后端)
  • FRONTEND_VERSION (前端)
  • AGENTCC_GATEWAY_VERSION (网关)
  • SERVING_VERSION (模型服务)
  • CODE_EXECUTOR_VERSION (代码执行器)

3. 使用生产配置启动
使用生产 overlay 文件启动服务。Compose 会检查 deploy/.env.production 中的变量，如果有任何必需变量为空，容器将拒绝启动。

1
2
docker compose --env-file deploy/.env.production \
  -f docker-compose.yml -f deploy/docker-compose.production.yml up -d

你也可以使用便捷脚本 ./deploy/setup.sh，它会以交互方式引导你完成密钥生成和启动过程。

4. 生产环境后续步骤

  • 反向代理与 TLS：在 frontend 服务前配置反向代理（如 Nginx、Caddy）以启用 HTTPS。你有两种拓扑选择：分域名（前端和 API 使用不同子域名）或单域名路径路由（如 /api/* 路由到后端）。
  • 切换后端模式：在环境变量中设置 ENV_TYPE=prod，并配置 GRANIAN_WORKERS 为你的 CPU 核心数，以获得最佳性能。
  • 数据存储：考虑将 Compose 自带的 Postgres、ClickHouse 等数据存储替换为托管服务（如 AWS RDS、ClickHouse Cloud）。注意，相关的主机地址需要在 docker-compose.yml 文件中修改，而非 .env。

🔧 常见问题与维护

1. 隐私与遥测
自托管实例在首次启动时会向 Future AGI 发送一次注册信息，包括活动管理员的邮箱地址和域名。要禁用此行为，请在 .env 中设置 FUTURE_AGI_TELEMETRY_DISABLED=1。完全静默需要在网络边缘切断连接。

2. 管理命令

  • 停止服务：docker compose down
  • 清除所有数据：docker compose down -v（警告：此操作会删除所有数据）
  • 查看日志：docker compose logs -f backend（或替换为其他服务名）
  • 手动创建用户：docker exec -it futureagi-backend-1 python manage.py create_user

3. 端口冲突
如果默认端口被占用，你可以在 .env 文件中修改所有服务的端口映射。例如，要同时运行两个独立的 Future AGI 实例，可以复制 .env 为 .env.stackB，修改所有端口，然后使用 docker compose --env-file .env.stackB -p stackb up 启动第二个实例。

完成部署后，你可以参考官方文档，通过 Python 或 TypeScript SDK 将你的 AI 应用接入平台，开始追踪和评估。