puppyone

环境要求

• 已安装 Docker（自托管部署的唯一前置条件）
• 已安装 npm，用于安装 puppyone CLI（可选，用于命令行管理工作区）
• 自托管默认监听 3000/9090/8000/9001 端口，需保证端口未被占用
• 如需在自托管环境中使用智能体对话，需准备 ANTHROPIC_API_KEY

安装与启动步骤

1. 1克隆项目仓库

   从 GitHub 拉取 puppyone 源码，后续 Docker 配置都在仓库的 docker 目录下。

   git clone https://github.com/puppyone-ai/puppyone.git

   复制

2. 2进入目录并配置环境

   切换到 docker 目录，把示例环境变量文件复制为 .env，供 compose 读取。

   cd puppyone/docker
   cp .env.example .env

   复制

3. 3启动 Docker 全栈

   一条命令拉起 PostgreSQL、Auth、API 网关、Redis、MinIO、前后端全部服务，数据库表结构首次运行自动初始化。

   docker compose up -d

   复制

4. 4确认容器状态

   首次启动约需 1-2 分钟；若页面暂时打不开，用该命令检查各容器是否正常运行。

   docker compose ps

   复制

5. 5安装并登录 CLI

   全局安装 puppyone 命令行工具并登录；首次运行会提示选择 Cloud / Local / Custom URL。

   npm install -g puppyone
   puppyone auth login

   复制

6. 6创建第一个上下文驱动器

   创建项目并将其设为当前活动项目，也可以直接在 Web 应用里创建。

   puppyone project create "My Project"
   puppyone project use "My Project"

   复制

7. 7添加第一条内容

   通过 URL 方式向 Context Drive 添加网页内容，并用 --scope 指定目标路径。

   puppyone access add url https://example.com --scope /refs

   复制

关键配置

如何确认成功

打开 http://localhost:3000 能正常访问即成功；若打不开，执行 docker compose ps 检查容器状态。

常见问题

注意事项

• 本地 Docker 栈通过共享宿主机 Docker 守护进程来实现沙箱，方便自托管，但远程或多租户部署建议改用 SANDBOX_TYPE=e2b 并配置 E2B_API_KEY。
• Docker 默认配置已区分浏览器访问地址（localhost）与容器内部服务地址（api、kong），客户端和 Next.js 服务端请求都可正常工作。
• 前端在 http://localhost:3000，后端 API 在 http://localhost:9090，Supabase API 在 http://localhost:8000，MinIO 控制台在 http://localhost:9001。
• 修改 docker/.env 后需重新执行 docker compose up -d 使配置生效。