故障排查

手表一直显示连接失败

1. 确认用户名和密码正确，账号未被停用。
2. 确认服务端健康检查可以访问。
3. 真机不要使用 10.0.2.2 或 localhost。
4. 检查反向代理是否允许 WebSocket 升级。
5. 检查证书是否受手表信任。

如果曾在开发者设置关闭云端后退出账号，不需要重新寻找普通连接页开关：填写密码登录时应用会临时使用云端完成认证。若仍失败，请确认云端地址可达；开发者开关只控制认证后的连接回退，不会跳过密码认证。

局域网无法连接

1. 确认 ClassIsland 已重启并加载插件。
2. 确认手表“设置 → 开发者”中的“局域网直连”已开启，并确认插件中已启用局域网服务。
3. 在手表“设置 → 连接”检查自动同步的电脑 IP 和端口；插件修改端口后必须重启 ClassIsland 并重新连接云端才会再次上报。
4. 多网卡电脑会向手表发送多个候选 IP，手表会依次尝试；若仍失败，可手动填写当前 Wi-Fi 或有线网卡地址。
5. 从同一局域网的另一台设备测试电脑 IP 是否可达，并检查 Windows 防火墙和 Wi-Fi 客户端隔离。

登录页扫描不到插件

1. 确认插件“RemoteCI 开发者设置”中的局域网服务已开启，并在修改后重启 ClassIsland。
2. 确认手表和电脑位于允许设备互访的同一 Wi-Fi；访客网络、校园网客户端隔离和部分手机热点会阻断广播。
3. 在 Windows 防火墙的专用网络范围放行 RemoteCI/ClassIsland 使用 UDP 48765；插件实际直连端口仍是设置中的 TCP 端口。
4. 扫描仍不可用时可手动填写电脑 IP、插件端口与云服务器地址，不影响原有连接方式。
5. 选择插件后应先核对手表显示的云服务器地址，再点击“安全登录”；扫描设备不会接收账号密码。

能查看状态但不能换课

• 确认账号拥有“管理课表”权限。
• 确认插件在线。
• 重新打开课表，避免使用已经过期的课表版本提交操作。
• 查看操作结果中的错误信息；超时通常表示服务端未在规定时间内收到插件响应。
• 插件授权镜像超过 24 小时未更新时，所有管理命令都会被拒绝，即使权限正常。

WebUI 或手表一直没有七日课表

1. 先确认插件在线；WebUI 页头应显示“可执行”，手表应处于局域网直连或云端中转状态。
2. WebUI 在“课表”页面点击“立即向插件拉取课表”，或在手表课表页点击“向插件拉取”；已有旧课表时也可以强制刷新。两端都会显示拉取进度，成功后 WebUI 会用插件返回的完整课表覆盖服务端旧缓存。
3. 也可以在 ClassIsland 的“RemoteCI 设置”点击“立即推送当前课表”，由插件主动发送当前七日课表。
4. 如果手动拉取有效，可在 WebUI 同一页面设置每 15 分钟、每小时、每 6 小时或每天自动拉取。
5. 如果界面提示已有课表任务正在执行，请等待该任务成功、失败或 15 秒超时，其他入口不会重复生成课表。
6. 如果等待 15 秒后超时或仍无数据，检查插件日志以及 ClassIsland 当前档案是否能生成未来七日课表；日志中的“目标计算机积极拒绝 127.0.0.1:8080”表示服务端未监听或正在重启。定时请求不会在插件离线时排队，但插件重新连接后服务端会自动再拉取一次。

音量或电源不可用

• 确认账号拥有“主界面与电源控制”（SystemControl）权限。
• 音量页不可用时，说明插件上报的状态中音量控制不可用，常见原因是电脑不是 Windows 或没有默认播放设备。
• 休眠入口只在插件报告 Windows 已启用休眠时显示；没有该入口不代表功能异常。
• 主界面显隐与电源操作同样需要 SystemControl 权限，且只能控制运行插件的教室电脑。

扩展命令失败

• INVALID_REQUEST：扩展未注册，或参数表单缺少必填参数。
• FORBIDDEN：当前账号没有扩展声明的所需权限，或授权镜像已过期。
• INTERNAL_ERROR：扩展执行时抛出异常，RemoteCI 插件本身不受影响。
• 先确认扩展已在插件端注册、账号权限正确，再重新提交。

更新失败

• 检查服务端或手表能否访问 GitHub；网络受限时更新检查会失败。
• WebUI 提示“当前平台暂无可用的更新包”时，需要到 GitHub Releases 手动下载对应平台压缩包。
• Windows 或裸机 Linux 更新会先启动独立更新器；若页面退出后没有自动恢复，检查数据库旁 updates/版本/update.log，并确认运行目录可写且系统能找到 dotnet。
• WebUI 提示“更新包版本不匹配”时，说明 release 附件名与包内版本不一致，应改用正确发布包，不能强制覆盖。
• 正式版渠道不会显示 GitHub 预发布；需要测试预发布时切换到 Beta 渠道，Beta 渠道仍会包含正式版。
• “强制更新”只用于重新下载并覆盖当前版本，不能安装更低版本，也不会跳过平台包、包内版本或 APK 签名检查。
• Visual Studio 调试或 dotnet run 使用 Development 环境时，WebUI 会提示由开发工具管理并禁用在线更新；修改源码后应停止旧进程并重新构建/启动。若曾用旧版更新器在源码目录拉起 release，请先结束命令行为项目目录下 RemoteCI.Server.dll 的孤立 dotnet 进程，再从 IDE 重新启动。
• 手表更新失败时，先确认已连接 WebUI、目标 APK 版本不高于 WebUI，并确认新 APK 与当前安装包签名一致；首次安装正式签名版后，后续更新才能在同一签名下覆盖。
• 飞牛 fnOS 不在 WebUI 内更新，请直接到 fnOS 应用商店检查版本。

首次启动找不到密码

如果没有配置 REMOTECI_ADMIN_PASSWORD 与 REMOTECI_PLUGIN_PAIR_CODE，初始密码和一次性插件配对码只会写入首次启动日志。先检查容器的完整日志。

若数据库已经初始化，修改环境变量不会重置现有管理员密码。不要删除数据库来“重置密码”，这会同时删除账号和设备会话。

插件配对码在使用前持续有效，成功配对后立即作废。需要新配对码时，在 WebUI 概览页点击“生成插件配对码”。

健康检查

Invoke-RestMethod https://remoteci.example.com/api/health

正常响应包含 status: ok 和协议版本。健康检查成功只说明 Web 服务已运行，不代表插件和手表已经在线。