aiagent/docs/quickstart.md

# 快速开始指南

本文档指导在 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)