故障排查
WinCode 开发者模式的常见问题和解决方案
故障排查
使用开发者模式时，您可能会遇到网关连接失败、Sidecar 下载异常或 API 端点不通等问题。本文汇总了最常见的问题和对应的解决方法。
状态栏显示"开发模式不可用"
这是最常见的提示，表示开发者模式的某个前置条件未满足。
可能原因和解决方法：
-
网关服务未启动
- 确认网关服务（win-code-gateway）正在运行。
- 如果是远程网关，确认目标设备已开机且服务未被防火墙拦截。
- 在 WinCode 中重新输入网关地址并点击"配对"。
-
Sidecar 组件未就绪
- 进入 设置 > 开发者模式，查看 Sidecar 区域的状态。
- 如果显示"下载失败"或"未安装"，点击"重新下载"。
- 详见 Sidecar 管理。
-
网络连接中断
- 检查电脑是否已连接到网络。
- 如果使用 VPN，尝试暂时关闭 VPN 后重试。
网关配对失败
点击"配对"后没有响应，或提示连接被拒绝。
排查步骤：
-
确认地址正确：网关地址应包含协议前缀和端口号，例如
http://192.168.1.100:8080。注意不要有多余的斜杠或空格。 -
测试网络连通性：在浏览器中打开网关地址，看是否能正常访问。如果浏览器也无法打开，说明网络不通或网关未启动。
-
检查防火墙：确保 WinCode 和网关服务都被防火墙允许通信。在 Windows 上，可以在"Windows 安全中心 > 防火墙和网络保护"中添加例外。在 macOS 上，检查"系统设置 > 网络 > 防火墙"。
-
端口被占用：如果网关服务启动失败，可能是默认端口（8080）被其他程序占用。尝试在网关配置中更换端口。
-
重新配对：在 WinCode 中先点击"断开配对"，然后重新输入地址进行配对。
Sidecar 下载失败
下载过程中断，或完成后状态仍显示异常。
排查步骤：
-
检查网络连接：下载 Sidecar 需要稳定的网络。如果公司网络限制了对外部资源的访问，尝试使用手机热点或家庭网络。
-
重试下载：进入 设置 > 开发者模式 > Sidecar 组件，对失败的组件点击"重新下载"。
-
清除缓存后重试：如果反复失败，点击"清除所有 Sidecar 数据"，然后重新开启开发者模式让 WinCode 重新下载。
-
检查磁盘空间：确保系统盘有至少 500MB 可用空间。空间不足会导致下载中途失败。
-
检查权限：确保 WinCode 对应用数据目录有写入权限。在企业管控的电脑上，可能需要联系 IT 部门。
本地 API 端点无法连接
配置了自定义 API 地址后，对话功能无法使用。
排查步骤：
-
验证地址格式：确保地址以
http://或https://开头，且不以斜杠/结尾。 -
测试 API 可用性：在浏览器或终端中尝试访问该地址，确认服务正在运行。
-
检查认证信息：如果 API 需要密钥或 Token，确认已正确填入，注意前后不要有多余的空格。
-
检查网络连通性：确保 WinCode 所在设备可以访问 API 地址。如果 API 在内网中，确认网络路由没有问题。
-
点击"测试连接"：在 API 端点配置界面，点击"保存并测试连接"，根据返回结果判断问题所在。
-
恢复默认后重试：如果始终无法解决，点击"恢复默认"切回云端服务，确认基本功能正常后再排查本地端点。
开发者模式开启后 WinCode 变慢
开启开发者模式后，WinCode 的启动或响应速度变慢。
可能原因：
- Sidecar 正在下载或更新：首次开启或组件更新时，后台下载会占用网络和磁盘资源。等待下载完成后通常会恢复。
- 网关响应延迟：如果网关服务负载较高或网络延迟较大，通过网关转发的请求会比直连云端慢。可以考虑优化网关服务性能或切换到更近的网关。
- 本地资源不足：如果电脑内存或 CPU 使用率已经很高，额外的 Sidecar 进程可能会加剧资源竞争。关闭一些不用的程序释放资源。
获取进一步帮助
如果以上步骤都无法解决您的问题，建议：
- 记录问题现象、操作步骤和错误提示信息。
- 截图 设置 > 开发者模式 页面的完整状态。
- 联系卫宁健康 WinCode 技术支持团队，提供以上信息以便快速定位问题。