环境准备

开发环境要求

必需环境

环境	版本要求	说明
Python	3.11+	后端运行环境
Node.js	18+	Web 前端和移动端
pnpm	8+	Web 前端包管理器
PostgreSQL	14+	推荐的主数据库
Redis	6+	缓存、会话、任务队列

可选环境

环境	版本要求	说明
MySQL	8+	可替代 PostgreSQL
Qdrant	1.7+	AI 知识库向量数据库
Minio	最新版	对象存储（可用本地存储替代）
HBuilderX	最新版	UniApp 开发工具

安装开发环境

Python 环境

推荐使用 Miniconda 管理 Python 环境：

bash

# 创建虚拟环境
conda create -n zq-fastapi python=3.11
conda activate zq-fastapi

或使用 venv：

bash

python3.11 -m venv venv
source venv/bin/activate  # macOS/Linux
# venv\Scripts\activate   # Windows

Node.js 环境

推荐使用 nvm 管理 Node.js 版本：

bash

nvm install 18
nvm use 18

安装 pnpm：

bash

npm install -g pnpm

PostgreSQL

macOS (Homebrew)Ubuntu/DebianDocker

bash

brew install postgresql@14
brew services start postgresql@14

bash

sudo apt install postgresql-14
sudo systemctl start postgresql

bash

docker run -d \
  --name postgres \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=your_password \
  -e POSTGRES_DB=fastapi_db \
  -p 5432:5432 \
  postgres:14

Redis

macOS (Homebrew)Ubuntu/DebianDocker

bash

brew install redis
brew services start redis

bash

sudo apt install redis-server
sudo systemctl start redis

bash

docker run -d \
  --name redis \
  -p 6379:6379 \
  redis:7

Qdrant（可选，AI 功能需要）

bash

docker run -d \
  --name qdrant \
  -p 6333:6333 \
  -p 6334:6334 \
  qdrant/qdrant

工具	用途	推荐插件
VS Code	全栈开发	Python、Volar、Tailwind CSS IntelliSense
PyCharm	后端开发	内置 Python 支持
HBuilderX	UniApp 开发	uni-app 插件

工具	用途
Postman / Apifox	API 接口调试
Redis Insight	Redis 可视化管理
pgAdmin / DBeaver	数据库可视化管理
微信开发者工具	小程序调试

OAuth 单点登录配置

系统支持多种 OAuth 平台的单点登录，每个平台需要配置相应的环境变量。

支持的平台

平台	配置前缀	说明
Gitee	`GITEE_`	Gitee 开放平台
GitHub	`GITHUB_`	GitHub OAuth Apps
QQ	`QQ_`	QQ 互联
Google	`GOOGLE_`	Google OAuth 2.0
微信	`WECHAT_`	微信开放平台
Microsoft	`MICROSOFT_`	Microsoft 账户
钉钉	`DINGTALK_`	钉钉开放平台
飞书	`FEISHU_`	飞书开放平台
企业微信	`WECOM_`	企业微信

环境变量配置示例

bash

# Gitee
GITEE_CLIENT_ID=your_client_id
GITEE_CLIENT_SECRET=your_client_secret
GITEE_REDIRECT_URI=http://localhost:5173/oauth/gitee/callback

# GitHub
GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret
GITHUB_REDIRECT_URI=http://localhost:5173/oauth/github/callback

# QQ（使用 APP_ID 和 APP_KEY）
QQ_APP_ID=your_app_id
QQ_APP_KEY=your_app_key
QQ_REDIRECT_URI=http://your-domain.com/oauth/qq/callback

# Google
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REDIRECT_URI=http://localhost:5173/oauth/google/callback

# 微信
WECHAT_APP_ID=your_app_id
WECHAT_APP_SECRET=your_app_secret
WECHAT_REDIRECT_URI=http://your-domain.com/oauth/wechat/callback

# Microsoft
MICROSOFT_CLIENT_ID=your_client_id
MICROSOFT_CLIENT_SECRET=your_client_secret
MICROSOFT_REDIRECT_URI=http://localhost:5173/oauth/microsoft/callback

# 钉钉
DINGTALK_APP_ID=your_app_key
DINGTALK_APP_SECRET=your_app_secret
DINGTALK_REDIRECT_URI=http://your-domain.com/oauth/dingtalk/callback

# 飞书
FEISHU_APP_ID=your_app_id
FEISHU_APP_SECRET=your_app_secret
FEISHU_REDIRECT_URI=http://localhost:5173/oauth/feishu/callback

# 企业微信
WECOM_CORP_ID=your_corp_id
WECOM_APP_SECRET=your_app_secret
WECOM_AGENT_ID=your_agent_id
WECOM_REDIRECT_URI=http://your-domain.com/oauth/wecom/callback

# OAuth 用户是否自动授予管理员权限
GRANT_ADMIN_TO_OAUTH_USER=false

OAuth 应用注册

Gitee

访问 https://gitee.com/oauth/applications
点击「创建应用」，填写应用信息
回调地址：http://localhost:5173/oauth/gitee/callback
获取 Client ID 和 Client Secret

GitHub

访问 https://github.com/settings/developers
点击「New OAuth App」
回调地址：http://localhost:5173/oauth/github/callback
获取 Client ID 和 Client Secret

Google

访问 https://console.cloud.google.com/
创建项目 → API 和服务 → 凭据 → OAuth 客户端 ID
配置 OAuth 同意屏幕
重定向 URI：http://localhost:5173/oauth/google/callback

钉钉

访问 https://open.dingtalk.com/
创建企业内部应用
在「登录与分享」中配置回调域名

飞书

访问 https://open.feishu.cn/
创建企业自建应用
在「安全设置」中配置重定向 URL
申请权限：contact:user.base:readonly

企业微信

访问 https://work.weixin.qq.com/
创建自建应用，获取 AgentId 和 Secret
在「网页授权及 JS-SDK」中配置可信域名

注意

QQ 互联和微信开放平台要求回调地址必须是已备案的域名
微信开放平台需要企业资质
详细配置说明请参考 SSO 单点登录

环境准备

开发环境要求

必需环境

可选环境

安装开发环境

Python 环境

Node.js 环境

PostgreSQL

Redis

Qdrant（可选，AI 功能需要）

推荐开发工具

IDE

调试工具

验证环境

OAuth 单点登录配置

支持的平台

环境变量配置示例

OAuth 应用注册

Gitee

GitHub

Google

钉钉

飞书

企业微信

环境准备 ​

开发环境要求 ​

必需环境 ​

可选环境 ​

安装开发环境 ​

Python 环境 ​

Node.js 环境 ​

PostgreSQL ​

Redis ​

Qdrant（可选，AI 功能需要） ​

推荐开发工具 ​

IDE ​

调试工具 ​

验证环境 ​

OAuth 单点登录配置 ​

支持的平台 ​

环境变量配置示例 ​

OAuth 应用注册 ​

Gitee ​

GitHub ​

Google ​

钉钉 ​

飞书 ​

企业微信 ​

环境准备

开发环境要求

必需环境

可选环境

安装开发环境

Python 环境

Node.js 环境

PostgreSQL

Redis

Qdrant（可选，AI 功能需要）

推荐开发工具

IDE

调试工具

验证环境

OAuth 单点登录配置

支持的平台

环境变量配置示例

OAuth 应用注册

Gitee

GitHub

Google

钉钉

飞书

企业微信