111 lines
2.5 KiB
Markdown
111 lines
2.5 KiB
Markdown
|
# 🚀 快速开始指南
|
|||
|
|
|
|||
|
|
> **Quick Start Guide**
|
|||
|
|
|
|||
|
|
本文档指导您在 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
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 服务端口
|
|||
|
|
|
|||
|
|
| 服务 | 端口 | 说明 |
|
|||
|
|
|:----|:----|:------|
|
|||
|
|
| 前端 | `8038` | 浏览器访问 `http://localhost:8038` |
|
|||
|
|
| 后端 API | `8037` | API 服务 |
|
|||
|
|
| API 文档 | `8037/docs` | Swagger UI 交互式文档 |
|
|||
|
|
| Redis | `6379` | 缓存服务（Docker） |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 💻 本地开发环境
|
|||
|
|
|
|||
|
|
### 1️⃣ 前端启动
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
cd frontend
|
|||
|
|
pnpm install
|
|||
|
|
pnpm dev
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
前端开发服务器将在 `http://localhost:8038` 启动，支持热重载。
|
|||
|
|
|
|||
|
|
### 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
|
|||
|
|
|
|||
|
|
# 启动开发服务器
|
|||
|
|
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 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
> 遇到其他问题？请参考 [部署与运维指南](./deployment-guide.md) 或提交 [Issue](#)。
|