sim-dashboard 快速开始¶
本指南引导你完成 sim-dashboard 应用的本地安装和运行。
前置条件¶
- Node.js 18+（或等效运行时）
- npm 或 pnpm 包管理器
- Inklet 后端运行在
http://localhost:4000（认证所需）
安装¶
克隆仓库并安装依赖：
或使用 pnpm：
配置¶
在项目根目录创建 .env 文件：
| 变量 | 描述 |
|---|---|
VITE_AUTH_URL |
Inklet 后端 API 的 URL。用于认证和设备 API 调用。 |
说明
VITE_ 前缀是 Vite 向前端暴露变量所必需的。Fastify 服务器的配置是单独读取的。
运行¶
同时启动 Fastify 服务器和 Vite 开发服务器：
这将启动：
- Fastify 服务器，地址
http://localhost:3001--- 接收 sim-hw 的帧缓冲，WebSocket 广播 - React 前端，地址
http://localhost:5173--- 带有电子墨水屏渲染的用户界面
使用仪表盘¶
第 1 步：打开仪表盘¶
在浏览器中访问 http://localhost:5173。
第 2 步：登录¶
点击 Sign In 并使用你的 Inklet 账户凭据进行认证。这与你在门户中使用的账户或通过 Auth API 创建的账户相同。
还没有账户？
通过 API 注册新账户：
第 3 步：查看你的设备¶
登录后，仪表盘会显示绑定到你账户的所有设备。每张设备卡片显示：
- 设备名称（Thing 名称）
- 在线/离线状态
- 电量
- 最后可见时间戳
- 实时电子墨水屏预览
如果没有绑定设备，仪表盘将为空。请参阅设备绑定来绑定模拟设备。
第 4 步：启动模拟设备¶
在另一个终端中启动 sim-hw 实例：
模拟设备将：
- 连接到 AWS IoT Core
- 向后端发送心跳
- 请求配对码（如果未绑定）
- 将帧缓冲推送到
http://localhost:3001
第 5 步：绑定并交互¶
设备运行并绑定到你的账户后（参见设备绑定），你将在仪表盘中看到其实时电子墨水屏显示。发送到设备的任何命令都会实时更新显示。
公开设备视图¶
每个设备都有一个无需认证的公开 URL：
将 {hwid} 替换为设备的硬件 UUID。此页面显示：
- 设备当前的电子墨水屏内容
- 通过 WebSocket 的实时更新
- 设备状态信息
分享
公开设备 URL 适用于演示、监控仪表盘，或与没有 Inklet 账户的人分享设备显示内容。
开发¶
项目结构¶
sim-dashboard/
├── server/ # Fastify 服务器
│ ├── index.ts # 服务器入口
│ ├── routes/ # HTTP 路由（帧缓冲、健康检查）
│ └── ws/ # WebSocket 处理器
├── src/ # React 前端
│ ├── components/ # UI 组件
│ ├── pages/ # 路由页面
│ ├── hooks/ # React hooks
│ └── lib/ # 工具函数和 API 客户端
├── .env # 环境配置
├── package.json
└── vite.config.ts
热重载¶
Fastify 服务器和 React 前端都支持热模块替换。源文件的修改会立即反映在浏览器中，无需完整刷新页面。
故障排除¶
登录时出现"Failed to fetch"¶
确认 Inklet 后端在 VITE_AUTH_URL 指定的地址上运行：
设备不显示帧缓冲¶
- 确认 sim-hw 正在运行且配置了
--sim-url http://localhost:3001 - 检查 Fastify 服务器日志中是否有传入的 POST 请求
- 在浏览器开发者工具中检查 WebSocket 连接（Network > WS 标签页）
端口冲突¶
如果端口 3001 或 5173 已被占用，检查其他运行中的进程：