aiagent/docs/quickstart.md

🚀 快速开始指南

Quick Start Guide

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

服务端口

服务	端口	说明
前端	8038	浏览器访问 http://localhost:8038
后端 API	8037	API 服务
API 文档	8037/docs	Swagger UI 交互式文档
Redis	6379	缓存服务（Docker）

---

💻 本地开发环境

1️⃣ 前端启动

cd frontend
pnpm install
pnpm dev

前端开发服务器将在 http://localhost:8038 启动，支持热重载。

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

# 启动开发服务器
uvicorn app.main:app --reload

# （新终端窗口）启动 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"}

---

❗ 常见问题

问题	可能原因	解决方案
数据库连接失败	.env 中数据库配置错误	检查 DATABASE_URL 配置
端口被占用	本地已有服务占用端口	修改 docker-compose.dev.yml 中的端口映射
pnpm 安装失败	Node.js 版本过低	升级 Node.js 至 18+
虚拟环境激活失败	Python 未安装	确认 python --version >= 3.11

---

遇到其他问题？请参考 部署与运维指南 或提交 Issue。