自托管快速开始
在本地运行 PuppyOne。
前提条件
- Docker & Docker Compose
- 或者:Python 3.12+, Node.js 18+, uv (opens in a new tab) 包管理器
方式一:Docker Compose(推荐)
1. 克隆仓库
git clone https://github.com/puppyone-ai/puppyone.git
cd puppyone2. 配置环境变量
cp .env.example .env编辑 .env,填入必要配置(参见下方环境变量说明)。
3. 启动服务
docker compose up --build4. 访问服务
- Frontend: http://localhost:3000 (opens in a new tab)
- Backend API: http://localhost:9090 (opens in a new tab)
方式二:手动启动
1. 克隆仓库
git clone https://github.com/puppyone-ai/puppyone.git
cd puppyone2. 启动后端
cd backend
cp .env.example .env # 配置环境变量
uv sync
uv run uvicorn src.main:app --host 0.0.0.0 --port 9090 --reload --log-level info --no-access-log3. 启动前端
cd frontend
cp .env.example .env
npm install
npm run dev4. 访问
- Frontend: http://localhost:3000 (opens in a new tab)
- Backend API: http://localhost:9090 (opens in a new tab)
环境变量
主要配置项(在 .env 文件中):
# Supabase(必填)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-supabase-anon-key
SUPABASE_SERVICE_KEY=your-supabase-service-role-key
# S3 存储
S3_BUCKET=your-bucket
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
# LLM(用于 ETL 和 Agent 对话)
OPENAI_API_KEY=sk-...
# Redis(任务队列)
REDIS_URL=redis://localhost:6379连接 Agent
自托管环境下,MCP Server URL 是:
http://localhost:9090/api/v1/mcp/server/{API_KEY}Cursor 配置:
{
"mcpServers": {
"puppyone-local": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://localhost:9090/api/v1/mcp/server/sk_xxx"]
}
}
}常见问题
端口冲突
修改 docker-compose.yml 或启动命令中的端口。
数据库连接失败
检查 SUPABASE_URL 和 SUPABASE_KEY 配置是否正确。
MCP 连接失败
确保后端服务正常运行,且 API Key 有效。