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（推荐）

# 启动所有服务
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. 前端启动

cd frontend
pnpm install
pnpm dev

前端开发服务器在 http://localhost:3001 启动，支持热重载，自动代理 /api 到 http://127.0.0.1:8038。

可通过环境变量覆盖代理目标：

# PowerShell
$env:AIAGENT_API_PROXY='http://127.0.0.1:8040'; npm run dev

2. 后端启动

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

---

快速验证

# 登录获取 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

---

参考：部署与运维指南