快速开始
本节帮助您快速搭建开发环境并启动项目。
环境要求
| 工具 | 版本 | 说明 |
|---|---|---|
| Node.js | >= 18.0.0 | 运行时环境 |
| pnpm | >= 8.0.0 | 包管理器 |
| PostgreSQL | >= 15.0 | 业务数据库 |
| Redis | >= 7.0 | 缓存服务 |
| InfluxDB | >= 2.0 | 时序数据库（可选） |
项目初始化
bash
# 1. 克隆仓库
git clone https://github.com/YunStack-IoT/yunstack-backend.git
git clone https://github.com/YunStack-IoT/yunstack-web.git
git clone https://github.com/YunStack-IoT/yunstack-uniapp.git
git clone https://github.com/YunStack-IoT/yunstack-docs.git
# 2. 安装全局工具（可选）
npm install -g pnpm @nestjs/cli后端开发
bash
cd yunstack-backend
# 1. 安装依赖
pnpm install
# 2. 配置环境变量
cp .env.example .env
# 编辑 .env 填写数据库连接等信息
# 3. 初始化数据库
pnpm db:generate # 生成 Prisma Client
pnpm db:migrate # 运行数据库迁移
pnpm prisma db seed # 填充初始数据
# 4. 启动开发服务器
pnpm start:dev # 默认 http://localhost:9876
# 5. 访问 API 文档
open http://localhost:9876/api-docs常用命令
| 命令 | 说明 |
|---|---|
pnpm start:dev | 开发模式（热重载） |
pnpm build | 构建生产版本 |
pnpm start:prod | 生产模式 |
pnpm lint | 代码检查 |
pnpm format | 代码格式化 |
pnpm test | 运行测试 |
pnpm test:cov | 测试覆盖率 |
pnpm db:studio | Prisma 可视化编辑器 |
Web 管理后台
bash
cd yunstack-web
# 1. 安装依赖
pnpm install
# 2. 配置环境变量
# 编辑 .env.development 配置 API 地址
# 3. 启动开发服务器
pnpm dev # 默认 http://localhost:5173常用命令
| 命令 | 说明 |
|---|---|
pnpm dev | 开发模式 |
pnpm build | 构建生产版本 |
pnpm preview | 预览构建结果 |
pnpm lint:eslint | ESLint 检查 |
pnpm type-check | TypeScript 检查 |
小程序开发
bash
cd yunstack-uniapp
# 1. 安装依赖
pnpm install
# 2. 启动微信小程序开发
pnpm dev:mp-weixin
# 3. 用微信开发者工具打开 dist/dev/mp-weixin多端开发命令
| 命令 | 平台 |
|---|---|
pnpm dev:mp-weixin | 微信小程序 |
pnpm dev:h5 | H5 网页 |
pnpm dev:app | App |
ESP32 固件开发
YunStack-IoT 的硬件产品（四路继电器、环境传感器）基于 ESP32 + ESP-IDF 开发。
环境要求
| 工具 | 版本 | 说明 |
|---|---|---|
| ESP-IDF | v5.2+ | 推荐 v5.2.2 |
| Python | >= 3.8 | IDF 工具链依赖 |
| CMake | >= 3.16 | 构建系统 |
| 串口驱动 | CP210x / CH340 | USB 转串口 |
安装 ESP-IDF
bash
# macOS
brew install cmake ninja dfu-util
git clone --recursive https://github.com/espressif/esp-idf.git -b v5.2.2
cd esp-idf && ./install.sh esp32
# Linux (Ubuntu)
sudo apt install git wget flex bison gperf python3 python3-pip python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0
git clone --recursive https://github.com/espressif/esp-idf.git -b v5.2.2
cd esp-idf && ./install.sh esp32激活环境
每次新终端需要激活：
bash
source ~/esp-idf/export.sh # 或 . ~/esp-idf/export.sh编译与烧录
bash
# 以环境传感器为例
cd EnvSense-Box/Software/esp32/env_sense_box
# 配置项目
idf.py set-target esp32
idf.py menuconfig # 按需配置 WiFi/串口等
# 编译
idf.py build
# 烧录（替换 /dev/ttyUSB0 为实际串口）
idf.py -p /dev/ttyUSB0 flash
# 查看串口输出
idf.py -p /dev/ttyUSB0 monitor
# 退出: Ctrl+]常用命令
| 命令 | 说明 |
|---|---|
idf.py build | 编译项目 |
idf.py flash | 烧录固件 |
idf.py monitor | 串口监控 |
idf.py flash monitor | 烧录并监控 |
idf.py menuconfig | 图形化配置 |
idf.py fullclean | 清理所有构建产物 |
idf.py size | 查看固件大小 |
文档开发
bash
cd yunstack-docs
# 1. 安装依赖
pnpm install
# 2. 启动文档开发服务器
pnpm docs:dev # 默认 http://localhost:5173
# 3. 构建
pnpm docs:build # 输出到 .vitepress/dist部署
详见 部署指南