Watchdog Web 操作手册
Watchdog Web 用于守护 GatewayRuntime 进程，并提供项目包管理、运行日志、备份恢复、隧道客户端和运行参数配置。现场维护时，通常先确认仪表盘状态，再进行项目应用、备份恢复或隧道配置。
登录
访问 http://<网关IP>:6200，输入 Watchdog 用户名和密码。随包配置正式支持普通 HTTP IP 访问，不要求把地址改成 localhost 或使用浏览器安全上下文。
| 配置项 | 说明 |
|---|---|
| 用户名 | 默认账号为 admin，可在“设置”页面修改。修改后需要使用新用户名登录。 |
| 密码 | 默认密码为 111111，首次部署后建议立即修改。 |
提交登录时，页面会自动获取两分钟有效、只能使用一次的公钥挑战，并使用 RSA-OAEP-SHA256 加密密码。登录成功后，Watchdog 签发八小时有效的不透明 Bearer 会话；登出会撤销当前会话，Watchdog 重启也会使现有会话失效。
登录后先进入“仪表盘”。如果浏览器直接跳回登录页，说明会话已过期、Watchdog 刚重启或账号密码不正确，需要重新登录。
一次性公钥挑战只额外保护登录或初始化密码。普通 HTTP 下的 Bearer Token、修改密码请求、项目包、备份和其他管理数据仍没有 TLS 保护；公网或不可信网络优先使用 HTTPS。
仪表盘巡检
菜单路径：仪表盘。
仪表盘用于确认 Watchdog 是否在线、GatewayRuntime 是否运行、当前项目是否正确、API 端口和健康检查策略是否符合预期。
| 区域 | 说明 |
|---|---|
| 顶部状态横幅 | 显示 Watchdog 在线状态、GatewayRuntime 运行状态、运行时长、版本、进程 ID、当前项目和最后错误。 |
| 启动失败次数 | 统计连续启动失败次数，正常情况下应为 0。 |
| 健康检查间隔 | Watchdog 检查 GatewayRuntime 健康状态的间隔，来自“设置”页面。 |
| API 端口 | Watchdog 用于检查 GatewayRuntime 的 API 端口，应与 GatewayRuntime Web/API 实际监听端口一致。 |
| 最大启动失败次数 | 达到该阈值后需要重点检查项目包、运行时文件和端口占用。 |
| 操作按钮 | 支持重启网关、停止网关、查看日志和刷新状态。 |
| 实时日志 | 默认读取最近日志并自动滚动，用于观察启动、停止和异常信息。 |
重启或停止 GatewayRuntime
- 在仪表盘点击“重启网关”或“停止网关”。
- 阅读确认提示后再执行。
- 操作完成后观察顶部状态横幅、进程 ID 和实时日志。
- 如果状态未变化，点击“刷新”，再到“日志查看”页面读取更完整的日志。
重启或停止 GatewayRuntime 会中断采集、规则处理和数据转发。生产环境执行前，应先确认上位系统、现场设备和数据接收端允许短时中断。
项目管理
菜单路径：项目管理。
项目管理用于上传、应用、下载、删除 GatewayRuntime 项目包。当前项目会带有“当前”标识，当前项目不能删除，也不能再次应用。
| 列或操作 | 说明 |
|---|---|
| 勾选框 | 选择非当前项目后，可执行批量删除。 |
| 项目名称 | 显示项目包名称；当前运行项目会显示状态点和“当前”标识。 |
| 最后修改时间 | 项目包最后修改时间，用于识别上传或更新顺序。 |
| 大小 | 项目包文件大小。 |
| 下载 | 将项目包下载到本地，文件名没有扩展名时浏览器会补为 .zip。 |
| 应用 | 将该项目应用为当前 GatewayRuntime 项目。 |
| 删除 | 删除非当前项目。当前项目的删除按钮禁用。 |
| 上传 | 打开项目上传弹窗。 |
| 刷新 | 重新读取项目列表和当前项目状态。 |
上传项目包
点击“上传项目”，打开上传弹窗。弹窗支持拖拽文件，也支持点击选择文件。
| 配置项 | 说明 |
|---|---|
| 项目文件 | 支持 .zip 和 .db。ZIP 通常来自 Studio 导出或发布包，DB 用于直接上传项目数据库。 |
| 上传区域 | 将文件拖入区域后立即上传；上传成功后列表自动刷新。 |
上传后建议检查三件事：项目名称是否符合预期、文件大小是否明显异常、最后修改时间是否为本次上传时间。
应用项目
- 在项目列表中找到目标项目。
- 点击“应用”。
- 在确认框中确认操作。
- 等待操作完成后刷新列表和仪表盘。
- 在“日志查看”页面确认 GatewayRuntime 是否按新项目启动。
应用项目会改变 GatewayRuntime 当前运行工程。执行前建议先在“备份管理”创建备份，或者确认 Studio/现场已有可回滚的项目包。
下载和删除项目
| 操作 | 使用场景 | 注意事项 |
|---|---|---|
| 下载 | 将当前项目回传给 Studio、留存现场版本、故障排查前备份。 | 下载的是项目包，不等同于运行日志或 Watchdog 配置。 |
| 删除 | 清理历史项目包，释放磁盘空间。 | 当前项目不能删除；批量删除只会选中非当前项目。 |
日志查看
菜单路径：日志查看。
日志查看用于读取 Watchdog 运行日志。与仪表盘实时日志相比，该页面适合查看更多行数、导出日志和持续观察启动过程。
| 配置项 | 说明 |
|---|---|
| 条数 | 控制本次读取的日志行数，可选 50、100、200、500。排查启动失败时建议选择 200 或 500。 |
| 自动刷新 | 开启后页面自动刷新日志；长时间排查时可保持开启。 |
| 导出 | 刷新当前日志后导出为 watchdog-logs-时间.txt。 |
| 刷新 | 手动重新读取日志。 |
| 行号 | 日志流显示行号，便于和同事定位同一段异常。 |
常见排查顺序：
- 先在仪表盘确认最后错误和启动失败次数。
- 打开“日志查看”，选择 200 或 500 行。
- 点击“刷新”，从最近一次重启或应用项目的时间点开始查看。
- 发现端口占用、项目包损坏、运行时缺失、插件缺失等信息后，再回到对应页面处理。
备份管理
菜单路径：备份管理。
备份管理用于创建、恢复、删除当前项目备份。页面底部会显示当前备份数量和“设置”中配置的最大备份数量。
| 列或操作 | 说明 |
|---|---|
| 创建备份 | 对当前项目创建备份，需要确认后执行。 |
| 勾选框 | 选择备份后可执行批量删除。 |
| 备份名称 | 备份文件名称，通常用于识别时间和项目。 |
| 创建时间 | 备份创建时间。 |
| 大小 | 备份文件大小。 |
| 恢复 | 将该备份恢复为当前项目，需要警告确认。 |
| 删除 | 删除单个备份，需要警告确认。 |
| 批量删除 | 删除选中的多个备份。 |
| 最大备份数量 | 来自“设置 > 备份策略”的最大备份数量。设置为 0 时不保留自动清理后的备份。 |
推荐备份策略
| 场景 | 建议 |
|---|---|
| 上传新项目之前 | 先创建备份，保留当前可运行版本。 |
| 恢复备份之前 | 确认当前项目是否还需要留存，必要时先创建新备份。 |
| 备份数量达到上限 | 新建备份后会按上限清理较早备份；重要版本建议先下载或迁移保存。 |
| 恢复后运行异常 | 立即查看日志，并恢复到上一个确认可运行的备份。 |
恢复备份会改变当前 GatewayRuntime 项目内容。恢复前请确认该备份对应的现场版本、插件和运行时环境都可用。
隧道管理
菜单路径：隧道管理。
Watchdog 端隧道客户端会主动连接 Studio 端 Broker，将内网 GatewayRuntime 服务暴露到指定对外地址。该页面同时提供卡片视图和表格视图，状态每 10 秒自动刷新，也可以手动点击“刷新”。
| 区域或操作 | 说明 |
|---|---|
| 启用隧道 | 全局开关，控制 Watchdog 隧道客户端功能。 |
| 新增客户端 | 打开配置抽屉并追加一条客户端配置。 |
| 卡片/表格 | 切换客户端展示方式。表格视图支持批量删除。 |
| 全部激活 | 激活所有已配置客户端。 |
| 全部停用 | 停用所有客户端。 |
| 刷新 | 立即刷新客户端状态和配置。 |
| 配置 | 打开隧道配置抽屉。 |
| 客户端状态 | 显示客户端名称、连接状态、隧道 ID、源地址、对外地址和活跃连接数。 |
隧道配置抽屉
点击“配置”，打开隧道配置抽屉。
| 配置项 | 说明 |
|---|---|
| 启用隧道 | 保存后控制全局隧道开关。页面顶部开关也会同步该值。 |
| 客户端配置 | 展示当前已保存的客户端。每个客户端可展开编辑。 |
| 添加客户端 | 在抽屉中追加一条客户端表单。 |
| 保存 | 校验客户端名称、服务器地址、端口、源地址和对外地址后保存。 |
新增客户端配置
点击“新增客户端”或抽屉内“添加客户端”，填写客户端表单。
| 配置项 | 说明 |
|---|---|
| 客户端名称 | 同一个 Watchdog 内必须唯一，保存前会校验重复。 |
| 启用 | 控制该客户端是否纳入激活范围。 |
| 隧道服务器地址 | Studio Broker 所在服务器 IP 或域名。Watchdog 必须能从现场网络访问该地址。 |
| 隧道服务器端口 | Studio Broker 监听端口，范围 1-65535，应与 Studio Web“内网穿透”中保存的隧道端口一致，常用为 7789；只有 Studio Broker 确实改成其它端口时才填写其它值。 |
| 认证令牌 | 与 Studio Broker 的认证令牌一致。该值用于客户端连接 Broker，大小写和空格都需要一致。 |
| 访问密钥 | 与 Studio Broker 的访问密钥一致。Studio 端填写访问密钥时，Watchdog 必须填写相同值才能绑定端点；不使用二次校验时两端保持为空，便于排查。 |
| 源地址 | Watchdog 所在网络中要暴露的服务地址，例如 127.0.0.1:6100。如果 GatewayRuntime 与 Watchdog 不在同一台机器，应填写 Watchdog 能访问到的网关地址。 |
| 对外地址 | Studio Broker 侧对外监听地址，例如 0.0.0.0:8889。外部访问者会访问 Studio 服务器上的该端口。 |
| 重连间隔（秒） | 断开后自动重连的等待时间，最小为 1 秒。网络抖动频繁时可适当增大，避免连续快速重连。 |
| 删除 | 删除当前客户端配置；已连接客户端删除前会先停用。 |
隧道联调步骤
- 在 Studio Web 的“内网穿透”页面保存 Broker 配置并启动服务。
- 在 Watchdog Web 的“隧道管理”中启用隧道。
- 新增客户端，填写 Studio Broker 地址、端口和认证令牌；Studio 端使用访问密钥时，这里填写相同访问密钥。
- 填写源地址，例如 GatewayRuntime Web/API 地址
127.0.0.1:6100。 - 填写对外地址，例如
0.0.0.0:8889。 - 保存配置后点击“激活”。
- 回到 Studio Web 的“内网穿透 > 端点信息”查看是否出现绑定端点。
- 使用外部网络访问对外地址，确认能进入 GatewayRuntime Web 或调用 API。
设置
菜单路径：设置。
设置页面按左侧导航分为账号安全、网关运行、备份策略和安全四组。修改参数后，需要点击页面底部“保存”才会持久化；点击“重置”会恢复为本次打开页面时读取到的值。
| 分组 | 配置项 | 说明 |
|---|---|---|
| 账号安全 | 用户名 | Watchdog 登录用户名。 |
| 账号安全 | 修改密码 | 打开密码修改弹窗。 |
| 网关运行 | 自动启动网关 | Watchdog 启动后是否自动启动 GatewayRuntime。随包配置默认为开启，适合断电恢复或服务重启后自动恢复采集。 |
| 网关运行 | 启动参数 | Watchdog 启动 GatewayRuntime 时附加的命令行参数。只有需要指定监听地址、环境参数或运行时参数时填写；不了解参数含义时保持为空。 |
| 网关运行 | API 端口 | GatewayRuntime API 端口，范围 1-65535。随包配置常用 6100。Watchdog 会在本机请求 http://localhost:<API端口>/api/health/health；这里不是 Watchdog 登录端口，填错时仪表盘可能显示网关停止并触发重启。 |
| 网关运行 | 健康检查间隔 | Watchdog 检查 GatewayRuntime 状态的间隔，单位秒，最小为 1。随包配置为 30 秒；间隔越短发现异常越快，也会更频繁访问 API。 |
| 网关运行 | API 检查超时 | 等待 GatewayRuntime API 响应的超时时间，单位秒，最小为 1。随包配置为 60 秒；网络慢或网关启动较慢时可适当增大。 |
| 网关运行 | 最大启动失败次数 | 连续启动失败达到该次数后需要人工处理，最小为 0。随包配置为 3 次；设置过小会更早暴露启动问题，设置过大可能延后告警。 |
| 备份策略 | 最大备份数量 | 备份管理页面保留的备份数量上限，最小为 0。随包配置为 10 个；设置为 0 时，新建备份后会被清理，不适合作为保留备份策略。 |
| 安全 | 允许的来源 | 允许跨域访问 Watchdog API 的 Web 访问来源，多个来源用英文逗号分隔，例如 http://a.com,http://b.com。留空允许全部来源；公开网络部署时只填写可信 Web 来源。 |
点击“修改密码”，打开密码修改弹窗。
| 配置项 | 说明 |
|---|---|
| 旧密码 | 当前登录密码。 |
| 新密码 | 要设置的新密码。 |
| 确认密码 | 再次输入新密码，必须与新密码一致。 |
修改 API 端口、健康检查间隔、最大启动失败次数等运行参数后，建议回到仪表盘观察至少一个健康检查周期，确认状态读取正常。
Studio 联动流程
| 目标 | 操作顺序 |
|---|---|
| 从 Studio 发布新工程 | Studio 新建或导入工程 → Studio 配置 Watchdog 服务并测试连接 → Studio 上传工程 → Watchdog 项目管理确认项目 → Watchdog 仪表盘和日志确认运行状态。 |
| 从现场回传工程 | Watchdog 项目管理确认目标项目 → Studio“从网关下载”选择 Watchdog 和项目 → Studio 导入后检查工程名称和插件。 |
| 远程访问内网网关 | Studio 启动 Broker → Watchdog 配置并激活隧道客户端 → Studio 查看端点 → 外部访问对外地址。 |
| 发布前保底 | Watchdog 备份管理创建备份 → Studio 上传工程 → Watchdog 应用项目 → Watchdog 日志确认成功。 |
常见问题
| 现象 | 处理建议 |
|---|---|
| 登录失败 | 检查用户名、密码和 Watchdog 服务端口；忘记密码时需要按现场维护流程重置配置。 |
localhost 正常但 IP 无法访问 | 检查 Watchdog 是否监听 0.0.0.0:6200，远程管理和普通 HTTP 开关是否开启，并放行防火墙端口。 |
页面提示 importKey 错误 | 清除浏览器和代理缓存并重新发布完整前端静态资源；当前页面不依赖 subtle.importKey，登录时所需动态资源必须能正常加载。 |
| 提示登录挑战无效 | 重新提交登录以获取新挑战；挑战两分钟过期且只能使用一次。 |
| Watchdog 重启后跳回登录页 | 内存 Bearer 会话已失效，重新登录即可。 |
| 仪表盘显示网关已停止 | 检查当前项目是否存在、API 端口是否正确、运行时文件是否完整，并查看日志。 |
| 启动失败次数持续增加 | 优先查看日志中的端口占用、插件缺失、项目数据库异常和运行时缺失信息。 |
| 项目上传失败 | 检查文件格式是否为 .zip 或 .db，文件是否损坏，磁盘空间和服务权限是否正常。 |
| 应用项目后状态未变化 | 刷新项目管理和仪表盘；如果仍未变化，查看日志确认应用动作是否失败。 |
| 备份恢复后项目异常 | 恢复到上一个确认可运行备份，并检查恢复目标的运行时和插件版本。 |
| 隧道显示未激活 | 确认全局“启用隧道”已开启，并检查客户端是否已保存。 |
| 隧道已连接但不能访问 | 检查源地址在 Watchdog 机器上是否可访问、对外地址端口是否被占用、防火墙是否放行。 |
| Studio 端看不到端点 | 检查 Studio Broker 是否运行，认证令牌是否一致；Studio 端填写访问密钥时，还要确认 Watchdog 访问密钥完全一致；不使用二次校验时两端都应留空。 |