docs: update 3 reference docs + add Android design, Feishu bot config, productization plan
- 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>
This commit is contained in:
renjianbo
@@ -1,27 +1,23 @@
|
||||
# 🚀 快速开始指南
|
||||
# 快速开始指南
|
||||
|
||||
> **Quick Start Guide**
|
||||
|
||||
本文档指导您在 5 分钟内完成天工智能体平台的本地部署与启动。
|
||||
本文档指导在 5 分钟内完成天工智能体平台的本地部署与启动。
|
||||
|
||||
---
|
||||
|
||||
## 📋 前置要求
|
||||
## 前置要求
|
||||
|
||||
| 组件 | 版本要求 | 说明 |
|
||||
|:----|:---------|:-----|
|
||||
| 组件 | 版本 | 说明 |
|
||||
|------|------|------|
|
||||
| Node.js | 18+ | JavaScript 运行时 |
|
||||
| pnpm | 8+ | 前端包管理器 |
|
||||
| Python | 3.11+ | 后端运行时 |
|
||||
| Docker & Docker Compose | 最新版 | 容器化部署（推荐） |
|
||||
| MySQL | 8.0+ | 使用腾讯云数据库 |
|
||||
| Docker & Docker Compose | 最新 | 容器化部署（推荐） |
|
||||
| MySQL | 8.0+ | 可使用腾讯云数据库 |
|
||||
| Redis | 7+ | 缓存与消息队列（可用 Docker） |
|
||||
|
||||
---
|
||||
|
||||
## 🐳 使用 Docker Compose（推荐）
|
||||
|
||||
### 启动服务
|
||||
## 使用 Docker Compose（推荐）
|
||||
|
||||
```bash
|
||||
# 启动所有服务
|
||||
@@ -34,20 +30,20 @@ docker-compose logs -f
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
### 服务端口
|
||||
### 服务端口（Docker 部署）
|
||||
|
||||
| 服务 | 端口 | 说明 |
|
||||
|:----|:----|:------|
|
||||
| 前端 | `8038` | 浏览器访问 `http://localhost:8038` |
|
||||
| 后端 API | `8037` | API 服务 |
|
||||
| API 文档 | `8037/docs` | Swagger UI 交互式文档 |
|
||||
| Redis | `6379` | 缓存服务（Docker） |
|
||||
|------|------|------|
|
||||
| 前端 (Nginx) | 8038 | 浏览器访问 `http://localhost:8038` |
|
||||
| 后端 API | 8037 | API 服务 |
|
||||
| Swagger 文档 | 8037/docs | Swagger UI 交互式文档 |
|
||||
| Redis | 6379 | 缓存服务 |
|
||||
|
||||
---
|
||||
|
||||
## 💻 本地开发环境
|
||||
## 本地开发环境
|
||||
|
||||
### 1️⃣ 前端启动
|
||||
### 1. 前端启动
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
@@ -55,15 +51,23 @@ pnpm install
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
前端开发服务器将在 `http://localhost:8038` 启动，支持热重载。
|
||||
前端开发服务器在 `http://localhost:3001` 启动，支持热重载，自动代理 `/api` 到 `http://127.0.0.1:8038`。
|
||||
|
||||
### 2️⃣ 后端启动
|
||||
可通过环境变量覆盖代理目标：
|
||||
|
||||
```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
|
||||
@@ -74,37 +78,61 @@ pip install -r requirements.txt
|
||||
|
||||
# 配置环境变量
|
||||
cp env.example .env
|
||||
# ⚠️ 编辑 .env 文件，配置数据库连接等信息
|
||||
# 编辑 .env 文件，配置数据库连接等信息
|
||||
|
||||
# 运行数据库迁移
|
||||
alembic upgrade head
|
||||
|
||||
# 启动开发服务器
|
||||
uvicorn app.main:app --reload
|
||||
# 启动开发服务器（必须指定 --port 8038，与前端 Vite 代理目标一致）
|
||||
uvicorn app.main:app --port 8038 --reload
|
||||
|
||||
# （新终端窗口）启动 Celery Worker
|
||||
# 新终端窗口 — 启动 Celery Worker
|
||||
celery -A app.core.celery_app worker --loglevel=info
|
||||
```
|
||||
|
||||
---
|
||||
### 本地开发端口
|
||||
|
||||
## ✅ 验证部署
|
||||
|
||||
1. 浏览器访问 `http://localhost:8038` → 看到登录/注册页面
|
||||
2. 浏览器访问 `http://localhost:8037/docs` → 看到 Swagger API 文档
|
||||
3. 尝试调用 `/health` 端点 → 返回 `{"status": "ok"}`
|
||||
| 服务 | 端口 | 说明 |
|
||||
|------|------|------|
|
||||
| 前端 (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` 配置 |
|
||||
| 端口被占用 | 本地已有服务占用端口 | 修改 `docker-compose.dev.yml` 中的端口映射 |
|
||||
| pnpm 安装失败 | Node.js 版本过低 | 升级 Node.js 至 18+ |
|
||||
|------|---------|---------|
|
||||
| 数据库连接失败 | .env 中配置错误 | 检查 DATABASE_URL |
|
||||
| 端口被占用 | 本地已有服务占用 | 修改端口或停用冲突进程 |
|
||||
| pnpm 安装失败 | Node.js 版本过低 | 升级至 18+ |
|
||||
| 虚拟环境激活失败 | Python 未安装 | 确认 `python --version` >= 3.11 |
|
||||
| 前端请求 500 | Vite 代理目标端口错误 | 确认后端启动在 8038，或设置 AIAGENT_API_PROXY |
|
||||
|
||||
---
|
||||
|
||||
> 遇到其他问题？请参考 [部署与运维指南](./deployment-guide.md) 或提交 [Issue](#)。
|
||||
> 参考：[部署与运维指南](./deployment-guide.md)
|
||||
|
||||
Reference in New Issue
Block a user