开发环境与首次启动
目标是在独立开发环境启动后端、Web和小程序，不依赖本机已有local-tools。不要把在线测试数据库URL复制到新环境后执行初始化。运行前先读系统架构。
获取固定源码
在工作目录运行：
git clone --recurse-submodules https://github.com/YunStack-IoT/YunStack-IoT.git
cd YunStack-IoT
git submodule update --init --recursive
python3 tools/workspace.py check需要各组件访问权限。子模块通常为detached HEAD，这是复现固定版本的正常状态；开始修改前切工作分支（后端master，其余主组件main）。不要使用submodule update --remote代替版本恢复，它会前进到组件分支而不是总仓库固定提交。
工具与基础服务
| 组件 | 工具基线 | 说明 |
|---|---|---|
| 后端 | Node24、pnpm11.0.8 | 与后端Actions一致；Prisma7使用生成客户端和pg adapter |
| Web | Actions为Node20/pnpm10 | 本机Node24亦有既有验证；以锁文件安装，build包含类型检查 |
| 小程序 | Node24/pnpm11本机验证环境，微信开发者工具 | 编译Build后上传开发版；真机日志仍用开发者工具 |
| 文档 | Node与pnpm，VitePress1.6系列锁文件 | pnpm docs:build；Cloudflare控制台构建设置需管理员核实 |
| 固件 | ESP-IDF6.1、Python虚拟环境、C编译器 | 不使用旧工程目录名推断IDF版本 |
本地准备独立PostgreSQL、Redis；需要历史再配置InfluxDB2的org/bucket/token；文件上传使用local或有权限的私有OSS。MQTT端到端联调需要带可信TLS和HTTP认证的Broker，本地只调HTTP先设MQTT_ENABLED=false。该开关只关闭MQTT，不隔离共享数据库；本地修改共享数据仍会影响远程，不建议用共享环境初始化。
后端
在yunstack-backend/执行：
pnpm install --frozen-lockfile
cp .env.example .env编辑.env而非直接使用示例默认值：DATABASE_URL指向独立库；JWT_SECRET与SALT_SECRET设独立随机值；REDIS_URL/DB指向开发Redis；MQTT_ENABLED=false；SERVER_PORT_HTTP显式设9875（Joi缺省9876，示例与反代采用9875）。Influx缺省时服务可以启动，但历史查询会为空并产生日志。
接着按数据库初始化与升级完成空库基线。 迁移目录有历史顺序问题，不能直接照搬migrate deploy作为空库第一条命令。数据库准备好后：
pnpm db:generate
pnpm start:dev另一终端验证curl -fsS http://127.0.0.1:9875/api/v1，应返回JSON成功包装和Hello World!。非production可打开http://127.0.0.1:9875/api-docs。启动失败先看Joi变量错误、PostgreSQL/Redis连接、端口占用；健康成功只说明基本HTTP可用，不证明登录、MQTT或历史正常。
首次账号/角色使用隔离库seed时注意脚本内置默认管理员密码且会打印，初始化后立即修改，不把它作为公网登录材料。MP_APPID/MP_SECRET仅微信真实code登录需要，缺失时不使用mock绕过。
Web
在yunstack-web/执行pnpm install --frozen-lockfile、pnpm dev，默认端口3000。开发.env的/dev-api代理到127.0.0.1:9875，核对vite.config.ts与实际端口；production API指向远程测试地址。调试登录时先确认请求真正落在哪个后端，避免误操作线上设备。
小程序
在yunstack-uniapp/执行pnpm install --frozen-lockfile、pnpm type-check、pnpm build:mp-weixin，微信开发者工具导入dist/build/mp-weixin。开发热编译用pnpm dev:mp-weixin，目录为dist/dev/mp-weixin，不能误把它作为CI Build上传目录。
当前开发与生产.env的VITE_APP_API_URL都指向远程测试后端，编译为开发版不自动改成本地。若调本地API，显式更改本地配置，并满足手机可达、HTTPS及微信域名要求；手机127.0.0.1不是开发电脑。BLE/DHCP实测使用正常可分配IP的WiFi。
文档
在yunstack-docs/运行pnpm install --frozen-lockfile、pnpm docs:dev；构建pnpm docs:build，预览pnpm docs:preview。文档能构建不说明示例已操作线上。新成员接下来阅读模块实现、设备接入或运维。