a7512a5423
- Rewrite api-reference.md: 245 endpoints across 38 modules, correct auth paths and response format - Rewrite 内置工具列表.md: all 56 real tools in 11 categories - Fix quickstart.md: local dev ports (3001/8038) vs Docker (8037/8038), --port 8038 - Add android-app-design.md: Kotlin/Compose/MVVM design with SSE, FCM, voice - Add 飞书智能体配置手册.md: all 6 bots config, capabilities, memory architecture - Add 产品化落地方案.md: PWA/voice/push/Flutter productization roadmap Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
139 lines
3.3 KiB
Markdown
139 lines
3.3 KiB
Markdown
# 快速开始指南
|
||
|
||
本文档指导在 5 分钟内完成天工智能体平台的本地部署与启动。
|
||
|
||
---
|
||
|
||
## 前置要求
|
||
|
||
| 组件 | 版本 | 说明 |
|
||
|------|------|------|
|
||
| Node.js | 18+ | JavaScript 运行时 |
|
||
| pnpm | 8+ | 前端包管理器 |
|
||
| Python | 3.11+ | 后端运行时 |
|
||
| Docker & Docker Compose | 最新 | 容器化部署（推荐） |
|
||
| MySQL | 8.0+ | 可使用腾讯云数据库 |
|
||
| Redis | 7+ | 缓存与消息队列（可用 Docker） |
|
||
|
||
---
|
||
|
||
## 使用 Docker Compose（推荐）
|
||
|
||
```bash
|
||
# 启动所有服务
|
||
docker-compose -f docker-compose.dev.yml up -d
|
||
|
||
# 查看实时日志
|
||
docker-compose logs -f
|
||
|
||
# 停止所有服务
|
||
docker-compose down
|
||
```
|
||
|
||
### 服务端口（Docker 部署）
|
||
|
||
| 服务 | 端口 | 说明 |
|
||
|------|------|------|
|
||
| 前端 (Nginx) | 8038 | 浏览器访问 `http://localhost:8038` |
|
||
| 后端 API | 8037 | API 服务 |
|
||
| Swagger 文档 | 8037/docs | Swagger UI 交互式文档 |
|
||
| Redis | 6379 | 缓存服务 |
|
||
|
||
---
|
||
|
||
## 本地开发环境
|
||
|
||
### 1. 前端启动
|
||
|
||
```bash
|
||
cd frontend
|
||
pnpm install
|
||
pnpm dev
|
||
```
|
||
|
||
前端开发服务器在 `http://localhost:3001` 启动，支持热重载，自动代理 `/api` 到 `http://127.0.0.1:8038`。
|
||
|
||
可通过环境变量覆盖代理目标：
|
||
|
||
```powershell
|
||
# PowerShell
|
||
$env:AIAGENT_API_PROXY='http://127.0.0.1:8040'; npm run dev
|
||
```
|
||
|
||
### 2. 后端启动
|
||
|
||
```bash
|
||
cd backend
|
||
|
||
# 创建并激活 Python 虚拟环境
|
||
python -m venv venv
|
||
|
||
# Windows
|
||
venv\Scripts\activate
|
||
# macOS / Linux
|
||
source venv/bin/activate
|
||
|
||
# 安装依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 配置环境变量
|
||
cp env.example .env
|
||
# 编辑 .env 文件，配置数据库连接等信息
|
||
|
||
# 运行数据库迁移
|
||
alembic upgrade head
|
||
|
||
# 启动开发服务器（必须指定 --port 8038，与前端 Vite 代理目标一致）
|
||
uvicorn app.main:app --port 8038 --reload
|
||
|
||
# 新终端窗口 — 启动 Celery Worker
|
||
celery -A app.core.celery_app worker --loglevel=info
|
||
```
|
||
|
||
### 本地开发端口
|
||
|
||
| 服务 | 端口 | 说明 |
|
||
|------|------|------|
|
||
| 前端 (Vite) | 3001 | `http://localhost:3001` |
|
||
| 后端 API | 8038 | `uvicorn app.main:app --port 8038 --reload` |
|
||
| Swagger 文档 | 8038/docs | `http://localhost:8038/docs` |
|
||
|
||
---
|
||
|
||
## 快速验证
|
||
|
||
```bash
|
||
# 登录获取 token
|
||
curl -s -X POST http://localhost:8038/api/v1/auth/login \
|
||
-H "Content-Type: application/x-www-form-urlencoded" \
|
||
-d 'username=admin&password=123456'
|
||
|
||
# 测试对话
|
||
curl -s -X POST http://localhost:8038/api/v1/agent-chat/bare \
|
||
-H "Authorization: Bearer <TOKEN>" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"message":"你好"}'
|
||
```
|
||
|
||
浏览器验证：
|
||
|
||
1. 访问 `http://localhost:3001` — 看到登录页面
|
||
2. 访问 `http://localhost:8038/docs` — 看到 Swagger API 文档
|
||
3. 调用 `/health` 端点 — 返回 `{"status": "ok"}`
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
| 问题 | 可能原因 | 解决方案 |
|
||
|------|---------|---------|
|
||
| 数据库连接失败 | .env 中配置错误 | 检查 DATABASE_URL |
|
||
| 端口被占用 | 本地已有服务占用 | 修改端口或停用冲突进程 |
|
||
| pnpm 安装失败 | Node.js 版本过低 | 升级至 18+ |
|
||
| 虚拟环境激活失败 | Python 未安装 | 确认 `python --version` >= 3.11 |
|
||
| 前端请求 500 | Vite 代理目标端口错误 | 确认后端启动在 8038，或设置 AIAGENT_API_PROXY |
|
||
|
||
---
|
||
|
||
> 参考：[部署与运维指南](./deployment-guide.md)
|