aiagent/QUICKSTART.md

快速启动指南

🚀 方式一：使用 Docker Compose（推荐）

1. 启动所有服务

docker-compose -f docker-compose.dev.yml up -d

2. 查看服务状态

docker-compose ps

3. 查看日志

# 查看所有服务日志
docker-compose logs -f

# 查看特定服务日志
docker-compose logs -f backend
docker-compose logs -f frontend

4. 停止服务

docker-compose down

5. 访问服务

• 前端: http://localhost:8038
• 后端API: http://localhost:8037
• API文档: http://localhost:8037/docs

---

💻 方式二：本地开发

前置要求

• Node.js 18+ 和 pnpm
• Python 3.11+
• PostgreSQL 15+ 和 Redis 7+（或使用Docker单独运行）

1. 启动Redis（数据库使用腾讯云MySQL）

# 使用 Docker 启动 Redis
docker run -d --name redis -p 6379:6379 redis:7-alpine

注意：数据库使用腾讯云MySQL，无需本地启动数据库服务。

2. 后端开发

cd backend

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 复制环境变量文件
cp env.example .env
# 编辑 .env 文件，配置数据库连接等
# DATABASE_URL 已配置为腾讯云MySQL，无需修改

# 运行数据库迁移（首次需要）
alembic upgrade head

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

后端将在 http://localhost:8037 启动

3. 启动 Celery Worker（新终端）

cd backend
source venv/bin/activate  # Windows: venv\Scripts\activate
celery -A app.core.celery_app worker --loglevel=info

4. 前端开发

cd frontend

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

前端将在 http://localhost:8038 启动（开发服务器内部端口3000，映射到8038）

---

🔧 常见问题

1. 数据库连接失败

检查：

• MySQL 数据库是否可访问（腾讯云数据库）
• 数据库连接信息是否正确（.env 文件）
• 网络连接是否正常（需要能访问腾讯云数据库）
• 数据库是否已创建

2. Redis 连接失败

检查：

• Redis 是否正在运行
• Redis URL 是否正确

3. 前端无法连接后端

检查：

• 后端服务是否正在运行
• 前端配置的 API URL 是否正确（vite.config.ts）
• CORS 配置是否正确

4. Celery 任务不执行

检查：

• Celery Worker 是否正在运行
• Redis 连接是否正常
• 任务是否正确注册

---

📝 下一步

1. 访问 http://localhost:8037/docs 查看 API 文档
2. 开始开发功能模块
3. 参考 方案-优化版.md 了解详细技术方案

---

🛠️ 开发工具推荐

• IDE: VS Code
• VS Code 插件:
  • Vue Language Features (Volar)
  • Python
  • ESLint
  • Prettier
• 数据库工具: DBeaver 或 pgAdmin
• API 测试: Postman 或 Insomnia