环境安装与本地运行
约 899 字大约 3 分钟
2026-10-16
本页用于修改平台本身。只有调用平台 API、开发独立应用时，使用应用环境准备，不需要安装平台源码工程。
1. 取得源码并确认版本
通过授权渠道取得仓库地址，检出本次开发分支。先阅读根目录 AGENTS.md，再阅读修改范围内的规则。
git clone '<authorized-repository-url>' platform
cd platform
git rev-parse HEAD保存该提交作为本次开发基线。后端 Go 最低版本看 backend/go.work 与相关 go.mod；前端 Node 要求同时满足 Vite，建议 Node 22 LTS，pnpm 使用 apps/web/package.json 的 packageManager，当前为 10.14.0。
2. 安装开发工具
按 Go 官方说明和 Node.js 官方说明安装对应版本。Ubuntu/WSL 可先准备基础工具：
sudo apt-get update
sudo apt-get install -y git curl ca-certificates build-essential python3 jq unzip default-jre-headless protobuf-compiler
export PATH="/usr/local/go/bin:$(go env GOPATH)/bin:$PATH"
corepack enable
go version
node --version前端生成客户端需要 Java 运行时；SQLite 测试需要 C 编译器与 CGO。数据库、时序库、Redis、NATS、对象存储、MQTT 等运行依赖按所选入口配置准备，不能把某个功能不需要的依赖视为全平台都可省略。
平台生成代码使用仓库锁定的定制 goctl，安装入口如下：
bash shell/install-goctl.sh
goctl --version
protoc --version
goctl env check --verbose当前 Things 生成脚本检查 goctl 1.9.2-1 与 protoc 3.21.12，Go 插件由服务脚本校验。执行前查看该分支实际要求；不要用自动安装最新版替换已经锁定的生成器。自己新建应用 RPC 可按应用指南使用公开 goctl，两个工具链分开管理。
3. 准备本机运行配置
AllInOne 入口在 backend/cmd/allInOne/，该目录的 etc/README.md 解释配置加载、数据库和隔离运行方式。按入口准备本地配置，确认关系库、时序库、消息总线和 Broker 的连接关系。
confSuffix 会选择对应的配置变体；容器内服务名和宿主机地址不能混用。使用隔离 Compose 前检查项目名、端口、卷与网络，使用自己的隔离配置，不连接历史测试环境或生产库。首次启动可能执行数据库迁移和种子初始化，目标必须是确认过的开发库。
准备完成后，从主仓根目录执行：
cd backend/cmd/allInOne
go run .启动失败时先根据首个错误检查配置、基础服务和功能开关，不通过注释服务初始化掩盖缺失依赖。健康检查路径和端口以所选配置为准。
4. 启动一个管理前端
在另一个终端，从主仓根目录执行：
cd apps/web
pnpm install --frozen-lockfile
BACKEND_URL=http://127.0.0.1:7850 pnpm dev:iot将示例中的本机后端地址改为实际监听地址。BACKEND_URL 只调整开发代理；若应用配置使用绝对 API 地址，需一并核对。启动成功后检查登录、企业和项目选择、实际 API 请求目标。
完成标准
- 后端运行配置已指向自己的开发依赖，能处理目标 API。
- 指定前端可以登录并取得授权数据，刷新与页面直达正常。
- 记录本次提交与工具版本，未把地址、凭据或本地覆盖文件提交到仓库。
更新日志
2026/10/16 17:31
查看所有更新日志
1a4a7-docs(开发指南): 重建平台与应用开发路线于