快速安装

克隆项目

git clone https://github.com/jiangzhikj/zq-platform.git
cd zq-platform-enterprise

后端安装

1. 创建虚拟环境

cd backend-fastapi

# 使用 conda
conda create -n zq-fastapi python=3.11
conda activate zq-fastapi

# 或使用 venv
python3.11 -m venv venv
source venv/bin/activate

2. 安装依赖

pip install -r requirements.txt

主要依赖：

包	版本	说明
fastapi	0.121.1	Web 框架
uvicorn	0.24.0	ASGI 服务器
sqlalchemy	2.0.23	异步 ORM
pydantic	2.5.2	数据验证
redis	5.0.1	缓存
apscheduler	4.0.0a6	任务调度
openai	2.9.0	AI 调用
qdrant-client	1.12.1	向量数据库

3. 配置环境变量

# 复制示例配置
cp env/example.env env/dev.env

编辑 env/dev.env，修改以下关键配置：

# 环境标识
ENV=dev
DEBUG=true

# 应用配置
APP_NAME=ZQ Platform
APP_HOST=0.0.0.0
APP_PORT=8000

# 数据库配置（PostgreSQL）
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=your_password
DB_NAME=fastapi_db

# Redis 配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

# 向量数据库（可选，AI 功能需要）
VECTOR_STORE_TYPE=qdrant
QDRANT_HOST=localhost
QDRANT_PORT=6333

4. 初始化数据库

# 创建数据库
psql -U postgres -c "CREATE DATABASE fastapi_db;"

# 执行数据库迁移
alembic upgrade head

5. 启动后端服务

python main.py

服务启动后访问：

• API 文档：http://localhost:8000/docs
• ReDoc 文档：http://localhost:8000/redoc

Web 前端安装

1. 安装依赖

cd web
pnpm install

2. 配置环境

前端通过 Vite 代理访问后端 API，默认代理到 http://localhost:8000。

如需修改，编辑 apps/web-ele/vite.config.mts：

server: {
  proxy: {
    '/basic-api': {
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/basic-api/, ''),
      target: 'http://localhost:8000',  // 后端地址
      ws: true,
    },
  },
},

3. 启动开发服务器

pnpm dev

访问 http://localhost:5173 即可看到登录页面。

UniApp 移动端安装

方式一：HBuilderX（推荐）

1. 下载并安装 HBuilderX
2. 打开 HBuilderX，选择 文件 → 导入 → 从本地目录导入
3. 选择 uniapp-zq 目录
4. 选择运行平台：
   • 运行 → 运行到浏览器（H5）
   • 运行 → 运行到小程序模拟器（微信小程序）
   • 运行 → 运行到手机或模拟器（App）

方式二：命令行

cd uniapp-zq

# 安装依赖
pnpm install

# H5 开发
pnpm dev:h5

# 微信小程序
pnpm dev:mp-weixin

# App
pnpm dev:app

H5 模式访问 http://localhost:5174。

验证安装

安装完成后，确认以下服务正常运行：

服务	地址	说明
后端 API	http://localhost:8000	FastAPI 服务
API 文档	http://localhost:8000/docs	Swagger UI
Web 前端	http://localhost:5173	Vue 3 应用
移动端 H5	http://localhost:5174	UniApp H5

常见安装问题

后端依赖安装失败

# 升级 pip
pip install --upgrade pip

# 使用国内镜像
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

前端依赖安装失败

# 清除缓存
pnpm store prune

# 使用国内镜像
pnpm config set registry https://registry.npmmirror.com
pnpm install

数据库连接失败

• 确认 PostgreSQL 服务已启动
• 检查 env/dev.env 中的数据库配置
• 确认数据库已创建：psql -U postgres -l

Redis 连接失败

• 确认 Redis 服务已启动：redis-cli ping
• 检查 env/dev.env 中的 Redis 配置