使用 Docker 本地运行 Playground

当你需要验证自己的 API Client、账号权限和真实设备时，可以在本机或受控服务器中运行 Playground。官方镜像已经包含 Web 页面和后端服务，不需要安装 Go、Node.js，也不需要下载项目源码。

如果只是了解功能和交互流程，优先使用在线 Playground。

运行前准备

已安装 Docker。
已创建 API Client，并取得 clientId 和 clientSecret。
API Client 至少具有 device:read；设备控制和配置功能需要额外权限。
本地端口 8090 可用。

权限规则详见权限范围。

保护测试凭据

请使用专用测试账号和测试设备，不要配置生产凭据。只授予本次验证需要的权限；不需要设备管理时，不要授予 device:manage。

1. 创建环境变量文件

新建一个空目录，并在目录内创建 .env：

dotenv

WLTE_BASE_URL=https://openapi.svnwi.com
WLTE_CLIENT_ID=替换为你的-clientId
WLTE_CLIENT_SECRET=替换为你的-clientSecret
WLTE_WS_ENABLED=true

限制文件权限：

chmod 600 .env

不要把 .env 提交到 Git，也不要把 clientSecret 放入浏览器代码、移动端应用或公开日志。

2. 拉取并启动最新镜像

docker pull wlte/wlte-openapi-playground:latest

docker run -d \
  --name wlte-openapi-playground \
  --env-file .env \
  -p 127.0.0.1:8090:8090 \
  wlte/wlte-openapi-playground:latest

端口只绑定到本机回环地址，不会直接向局域网或公网开放。

3. 检查运行状态

docker ps --filter name=wlte-openapi-playground
docker logs --tail=100 wlte-openapi-playground
curl --fail http://127.0.0.1:8090/healthz

健康检查成功后，打开：

http://127.0.0.1:8090

4. 开始验证

确认设备列表与账号中的设备一致。
打开一台设备，检查外设区域是否与设备能力一致。
分别选择 HTTP 和 WebSocket，执行一次实时状态刷新。
只对测试设备执行继电器或 RS-485 操作。
在 Protocol Inspector 中核对请求、响应和事件消息。

如果页面显示权限错误，请在 API Key 中调整 API Client 权限，然后重新启动容器以使用更新后的凭据。

可选配置

以下配置已有默认值，只有在需要调整超时、事件缓冲或日志时才需要写入 .env：

环境变量	默认值	用途
`WLTE_REQUEST_TIMEOUT`	`15s`	REST API 请求超时
`PLAYGROUND_WS_EVENT_BUFFER`	`256`	WebSocket 事件缓冲区大小
`PLAYGROUND_WS_EVENT_HISTORY`	`200`	页面保留的事件数量
`PLAYGROUND_WS_PING_INTERVAL`	`20s`	WebSocket Ping 间隔
`PLAYGROUND_TRAFFIC_HISTORY`	`200`	Protocol Inspector 保留的消息数量
`PLAYGROUND_LOG_FORMAT`	`json`	日志格式
`PLAYGROUND_LOG_LEVEL`	`info`	日志级别

停止并移除

docker rm -f wlte-openapi-playground

从源码构建

只有需要验证未发布代码或修改 Playground 本身时，才需要从 Dockerfile 构建：

docker build \
  --build-arg VERSION=local \
  -t wlte-openapi-playground:local \
  .

docker run -d \
  --name wlte-openapi-playground \
  --env-file .env \
  -p 127.0.0.1:8090:8090 \
  wlte-openapi-playground:local

Dockerfile 会先构建 Vue 页面，再将页面嵌入 Go 服务。最终镜像只运行一个非 root 进程，.env 不会被复制进镜像。

常见问题

页面无法打开

确认容器仍在运行，并检查 .env 没有设置 PLAYGROUND_LISTEN_ADDR=127.0.0.1:8090。容器内必须监听 0.0.0.0:8090，官方镜像已经使用该默认值。

设备列表为空

确认 API Client 具有 device:read，并且其账号可以访问设备。继续查看常见失败。

是否可以部署到公网

Playground 本身没有操作者登录功能。需要共享时，应在它前面增加 HTTPS、身份认证或网络访问限制，并使用权限受限的专用测试凭据。

使用 Docker 本地运行 Playground ​

运行前准备 ​

1. 创建环境变量文件 ​

2. 拉取并启动最新镜像 ​

3. 检查运行状态 ​

4. 开始验证 ​

可选配置 ​

停止并移除 ​

从源码构建 ​

常见问题 ​

页面无法打开 ​

设备列表为空 ​

是否可以部署到公网 ​

相关页面 ​