本地开发环境完整部署

本地开发环境完整部署

阅读时间：约 10 分钟

本文将指导你从零开始，在本地搭建完整的 Text-to-BI 系统开发环境。

🎯 部署目标

完成后，你将拥有：

• ✅ 完整的后端服务（FastAPI + Agno）
• ✅ 完整的前端应用（Vue 3）
• ✅ CubeJS 数据服务
• ✅ 示例数据库
• ✅ 可以运行的完整系统

📋 环境要求

必需软件

- Python 3.11+ (推荐 3.11.x)
- Node.js 18+ (推荐 18.x LTS 或 20.x LTS)
- Docker 20.10+ & Docker Compose 2.0+
- Git 2.30+

操作系统支持

• ✅ macOS 11+ (Big Sur 及以上)
• ✅ Ubuntu 20.04+ / Debian 11+
• ✅ Windows 10/11 (需要 WSL2)

检查环境

# 检查 Python
python --version  # 应该 >= 3.11

# 检查 Node.js
node --version    # 应该 >= 18

# 检查 Docker
docker --version
docker-compose --version

# 检查 Git
git --version

📥 克隆项目

Step 1: 获取代码

# 克隆仓库
git clone <your-repo-url>
cd ask-sql

# 查看项目结构
tree -L 2

项目结构：

ask-sql/
├── backend/          # 后端代码
├── frontend/         # 前端代码
├── docs/            # 文档
└── README.md

🔧 配置后端

Step 1: 创建虚拟环境

cd backend

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# macOS/Linux:
source venv/bin/activate

# Windows:
venv\Scripts\activate

Step 2: 安装依赖

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

# 验证安装
pip list | grep fastapi
pip list | grep agno

Step 3: 配置环境变量

# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件
nano .env  # 或使用你喜欢的编辑器

配置 .env：

# AI 模型配置 - DeepSeek API
OPENAI_API_KEY=sk-your-deepseek-api-key-here
# 注意：DeepSeek 使用 OpenAI 兼容的 API 格式

# CubeJS 配置
CUBEJS_URL=http://localhost:4000

# 应用配置
APP_ENV=development
LOG_LEVEL=INFO

获取 DeepSeek API Key：

1. 访问 DeepSeek 开放平台
2. 注册并登录账号
3. 进入 API Keys 页面
4. 点击"创建新的 API Key"
5. 复制 API Key 到 .env 文件的 OPENAI_API_KEY 字段

💡 提示：DeepSeek API 兼容 OpenAI 格式，因此环境变量名为 OPENAI_API_KEY

Step 4: 启动 CubeJS

cd cubejs

# 启动 CubeJS 服务
docker-compose up -d

# 检查服务状态
docker-compose ps

# 查看日志
docker-compose logs -f

验证 CubeJS：

# 测试 CubeJS API
curl http://localhost:4000/cubejs-api/v1/meta

# 应该返回数据模型信息

Step 5: 启动后端服务

cd ..  # 回到 backend 目录

# 方式1: 使用启动脚本
./start.sh

# 方式2: 直接使用 uvicorn
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# 方式3: 运行 main.py
python main.py

验证后端：

# 测试健康检查
curl http://localhost:8000/health

# 访问 API 文档
open http://localhost:8000/docs

🎨 配置前端

Step 1: 安装依赖

cd ../frontend

# 安装 npm 依赖
npm install

# 或使用 yarn
yarn install

Step 2: 配置环境变量

# 复制环境变量模板
cp .env.example .env

# 编辑 .env
nano .env

.env 配置：

# API 地址
VITE_API_BASE_URL=http://localhost:8000

# 应用配置
VITE_APP_TITLE=Ask SQL

Step 3: 启动开发服务器

# 启动 Vite 开发服务器
npm run dev

# 或使用 yarn
yarn dev

预期输出：

  VITE v5.0.0  ready in 500 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: http://192.168.1.100:5173/

Step 4: 访问应用

打开浏览器访问：http://localhost:5173

🧪 完整测试

1. 测试后端 API

# 测试聊天接口
curl -X POST "http://localhost:8000/chat/ask" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello"}'

# 测试 Workflow 接口
curl -X POST "http://localhost:8000/workflow/query-sync" \
  -H "Content-Type: application/json" \
  -d '{"message": "统计员工总数"}'

2. 测试前端功能

AI 聊天：

1. 点击"AI 聊天"
2. 输入："你好"
3. 查看 AI 响应

AI 数据分析：

1. 点击"AI 数据分析"
2. 输入："统计员工总数"
3. 查看查询结果

3. 测试流式响应

在浏览器开发者工具中：

// 打开 Console
// 测试流式请求
const response = await fetch('http://localhost:8000/workflow/query', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ message: '统计员工总数' })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(decoder.decode(value));
}

🐛 常见问题

问题 1: 后端启动失败

错误： ModuleNotFoundError: No module named 'fastapi'

解决：

# 确保虚拟环境已激活
source venv/bin/activate

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

问题 2: CubeJS 连接失败

错误： Connection refused to localhost:4000

解决：

# 检查 CubeJS 是否运行
cd backend/cubejs
docker-compose ps

# 如果没有运行，启动它
docker-compose up -d

# 查看日志
docker-compose logs

问题 3: 前端无法连接后端

错误： CORS error 或 Network error

解决：

# 1. 检查后端是否运行
curl http://localhost:8000/health

# 2. 检查 CORS 配置
# 在 backend/main.py 中确认：
allow_origins=[
    "http://localhost:5173",
    "http://127.0.0.1:5173",
]

# 3. 检查前端 API 地址
# 在 frontend/.env 中确认：
VITE_API_BASE_URL=http://localhost:8000

问题 4: API Key 无效

错误： Invalid API key

解决：

# 1. 检查 .env 文件
cat backend/.env | grep OPENAI_API_KEY

# 2. 确保 API Key 正确
# 访问 DeepSeek 平台检查 Key

# 3. 重启后端服务

问题 5: 数据库文件权限

错误： Permission denied: workflows.db

解决：

# 创建 tmp 目录
mkdir -p backend/tmp
mkdir -p backend/workflows/tmp

# 设置权限
chmod 755 backend/tmp
chmod 755 backend/workflows/tmp

# 如果问题依然存在，检查 SELinux (Linux)
# 或者直接删除旧的数据库文件重新创建
rm -f backend/tmp/workflows.db
rm -f backend/workflows/tmp/workflows.db

问题 6: 端口被占用

错误： Address already in use: 8000 或 5173

解决：

# 查找占用端口的进程
# macOS/Linux:
lsof -i :8000
lsof -i :5173

# Windows:
netstat -ano | findstr :8000
netstat -ano | findstr :5173

# 杀死进程或更改端口
# 修改后端端口：在 main.py 中更改 port 参数
# 修改前端端口：在 vite.config.ts 中配置 server.port

问题 7: Docker 容器无法启动

错误： CubeJS 容器启动失败

解决：

# 检查 Docker 服务状态
docker info

# 查看详细错误日志
docker-compose logs cubejs

# 清理并重新启动
docker-compose down -v
docker-compose up -d

# 检查端口冲突
docker ps -a

📊 服务状态检查

创建检查脚本

check_services.sh：

#!/bin/bash

echo "=== 服务状态检查 ==="
echo

# 检查后端
echo "1. 后端服务 (http://localhost:8000)"
curl -s http://localhost:8000/health > /dev/null
if [ $? -eq 0 ]; then
    echo "   ✅ 运行中"
else
    echo "   ❌ 未运行"
fi

# 检查 CubeJS
echo "2. CubeJS 服务 (http://localhost:4000)"
curl -s http://localhost:4000/cubejs-api/v1/meta > /dev/null
if [ $? -eq 0 ]; then
    echo "   ✅ 运行中"
else
    echo "   ❌ 未运行"
fi

# 检查前端
echo "3. 前端服务 (http://localhost:5173)"
curl -s http://localhost:5173 > /dev/null
if [ $? -eq 0 ]; then
    echo "   ✅ 运行中"
else
    echo "   ❌ 未运行"
fi

echo
echo "=== 检查完成 ==="

使用：

chmod +x check_services.sh
./check_services.sh

🚀 快速启动脚本

创建一键启动脚本

start_all.sh：

#!/bin/bash

echo "=== 启动 Text-to-BI 系统 ==="
echo

# 启动 CubeJS
echo "1. 启动 CubeJS..."
cd backend/cubejs
docker-compose up -d
cd ../..

# 启动后端
echo "2. 启动后端..."
cd backend
source venv/bin/activate
uvicorn main:app --reload --host 0.0.0.0 --port 8000 &
BACKEND_PID=$!
cd ..

# 等待后端启动
sleep 3

# 启动前端
echo "3. 启动前端..."
cd frontend
npm run dev &
FRONTEND_PID=$!
cd ..

echo
echo "=== 所有服务已启动 ==="
echo "后端: http://localhost:8000"
echo "前端: http://localhost:5173"
echo "CubeJS: http://localhost:4000"
echo
echo "按 Ctrl+C 停止所有服务"

# 等待中断信号
trap "kill $BACKEND_PID $FRONTEND_PID; exit" INT
wait

使用：

chmod +x start_all.sh
./start_all.sh

📝 开发工作流

日常开发流程

# 1. 启动所有服务
./start_all.sh

# 2. 开发代码
# - 后端代码修改会自动重载
# - 前端代码修改会自动刷新

# 3. 测试功能
# - 访问 http://localhost:5173
# - 使用 API 文档 http://localhost:8000/docs

# 4. 提交代码
git add .
git commit -m "feat: 添加新功能"
git push

调试技巧

后端调试：

# 在代码中添加断点
import pdb; pdb.set_trace()

# 或使用 print 调试
print(f"Debug: {variable}")

# 查看日志
tail -f backend/logs/app.log

前端调试：

// 使用 console.log
console.log('Debug:', data)

// 使用 Vue DevTools
// 安装浏览器扩展

// 查看网络请求
// 打开浏览器开发者工具 -> Network

🎯 性能优化

后端优化

# 1. 使用连接池
from sqlalchemy.pool import QueuePool

engine = create_engine(
    DATABASE_URL,
    poolclass=QueuePool,
    pool_size=5,
    max_overflow=10
)

# 2. 启用缓存
from functools import lru_cache

@lru_cache(maxsize=100)
def get_schema():
    return load_schema()

# 3. 异步处理
async def process_query(query):
    result = await async_query(query)
    return result

前端优化

// 1. 懒加载组件
const WorkflowPage = defineAsyncComponent(() =>
  import('./components/WorkflowPage.vue')
)

// 2. 防抖处理
import { debounce } from 'lodash-es'

const handleInput = debounce((value) => {
  // 处理输入
}, 300)

// 3. 虚拟滚动
// 对于大量数据使用虚拟滚动

本节小结

本节我们完成了本地开发环境的完整部署：

1. 环境准备：安装了 Python、Node.js、Docker 等必需软件
2. 后端部署：配置了虚拟环境、环境变量、CubeJS 服务
3. 前端部署：安装了依赖、配置了环境变量
4. 服务启动：成功启动了后端、前端、CubeJS 三个服务
5. 功能测试：验证了 AI 聊天和数据分析功能
6. 问题排查：掌握了常见问题的解决方法
7. 工具脚本：创建了服务检查和一键启动脚本

现在你已经拥有了一个完整可运行的 Text-to-BI 系统。

思考与练习

思考题

1. 为什么要使用虚拟环境？不使用会有什么问题？
2. 环境变量和配置文件各有什么优劣？如何选择？
3. 如何将本地开发环境迁移到生产环境？
4. Docker Compose 相比手动启动服务有什么优势？

实践练习

1. 自动化部署：

   • 编写完整的部署脚本
   • 支持一键安装所有依赖
   • 支持一键启动所有服务

2. 环境隔离：

   • 配置开发、测试、生产三个环境
   • 使用不同的配置文件
   • 测试环境切换

3. 监控告警：

   • 添加服务健康检查
   • 服务异常时自动重启
   • 发送告警通知

4. Docker 化：

   • 为后端和前端创建 Dockerfile
   • 使用 docker-compose 管理所有服务
   • 实现容器化部署

---

上一节：第 16 节：前端状态管理与优化
下一节：第 18 节：项目总结与下一步