Docker Compose

使用 Docker Compose 在虚拟机或本地机器上部署 Onlook。这是一个简单的单容器部署，适合小团队和基础自托管需求。对于需要高可用性和可扩展性的企业级部署，请使用云部署选项。

前提条件

系统要求：

• 4核以上 CPU
• 8GB 以上内存（推荐16GB）
• 50GB 以上可用磁盘空间
• Docker 20.10 及以上，Docker Compose 2.0 及以上

软件要求：

• Bun - 包管理器和运行时
• Node.js v20.16.0及以上（避免使用 v20.11.0）
• Git
• Docker 和 Docker Compose

基础部署

注意：这是一个适合小团队和测试的简单部署。开发时请在代码库根目录使用 bun dev。

1. 克隆代码库

git clone https://github.com/onlook-dev/onlook.git
cd onlook

# 安装依赖
bun install

2. 设置环境变量

对于 Docker Compose 部署，需要创建环境变量文件。

# 运行交互式环境设置
bun run setup:env

必填变量：

• Supabase：生产数据库 URL 和 API 密钥
• OpenRouter API Key：AI 聊天功能所需
• CodeSandbox Token：用于开发容器

有关获取这些 API 密钥的详细说明，请参见开发设置指南。

3. 启动后端服务

bun backend:start

此命令将在本地启动 Supabase，包含 PostgreSQL 数据库、身份验证和存储服务。这将启动一个单独的 Docker Compose 服务。若连接生产 Supabase，请在 .env 文件中更改 Supabase API 密钥。

4. 初始化数据库

# 推送数据库架构
bun db:push

5. 使用 Docker Compose 部署

在代码库根目录部署生产容器：

docker-compose up -d

该命令构建并启动：

• Web 应用：生产构建的 Next.js 应用（端口 3000）
• 健康检查：自动容器健康监控
• 自动重启：容器失败时自动重启

注意：Docker 容器使用 network_mode: "host" 来访问运行在主机上的本地 Supabase 服务。这样容器可以连接到 http://127.0.0.1:54321（Supabase API）和 127.0.0.1:54322（PostgreSQL）。

6. 验证部署

• 主应用：http://localhost:3000
• Supabase 仪表盘：http://localhost:54323（由 backend:start 启动）

检查服务运行状态：

docker-compose ps
curl http://localhost:3000

故障排除

常见问题：

• 端口 3000 被占用：停止其它服务或更换端口
• Docker 构建失败：运行 docker system prune 后重试
• 数据库连接失败：确认 bun backend:start 正在运行且 Supabase 可通过 http://127.0.0.1:54321 访问
• 容器无法连接 Supabase：确保在 docker-compose.yml 中设置了 network_mode: "host" 以访问本地主机

限制与注意事项

此部署追求简单性，不保证高可靠性：

限制：

• 单容器（单点故障）
• 无内置负载均衡或自动扩展
• 备份和灾难恢复需手动操作
• 只支持纵向扩展
• 无高可用保障

适用场景：

• 小团队（小于 10 用户）
• 开发/测试环境
• 概念验证部署
• 基础自托管需求

不适用场景：

• 关键生产工作负载
• 需要高可用性的大团队
• 需要 99.9% 以上运行时间的环境

企业级部署请使用具备冗余和可扩展能力的云部署选项。