故障排查

ClassIsland 插件无法连接服务器

1. 打开 ClassIsland 的“RemoteCI 设置”，先看“服务器状态”和“最近错误”，不要只依据服务端健康检查判断插件已经连通。
2. 确认“RemoteCI 开发者设置”没有关闭云端连接，云端地址包含正确的 http:// 或 https://、域名和端口。
3. 修改服务器地址后保存并重启 ClassIsland；首次配对或凭据失效时，在 WebUI 概览页重新生成一次性插件配对码并保存。
4. 点击“测试服务器连接”。已有连接时会直接验证真实 WebSocket 通道；断线时会跳过 5 秒至 2 分钟的自动重连退避，并实际执行配对、WebSocket 鉴权和初始化。若测试超时，继续检查 HTTPS 证书、反向代理 WebSocket Upgrade 和内网穿透的 TCP/HTTPS 配置。
5. 设置页错误经过凭据脱敏；需要网络异常的完整调用信息时再查看 ClassIsland 日志，反馈问题时不要公开配对码或长期凭据。

WebUI 可以访问但 WebSocket 握手返回 401 或 403 时，插件会清除被服务端拒绝的旧长期凭据；如果已经保存新配对码，下一次重试会自动重新配对。404、5xx 等路径或代理错误不会清除凭据。

手表一直显示连接失败

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”表示服务端未监听或正在重启。定时请求不会在插件离线时排队，但插件重新连接后服务端会自动再拉取一次。

WebUI 显示插件协议不匹配

WebUI 检测到 ClassIsland 插件发送的协议号不是整数 3 时，会在概览页列出插件协议和 WebUI 协议。请升级 ClassIsland 插件到协议 V3；如果插件来自更高协议，还需要同步升级 WebUI/服务端。警告会在插件断开后保留，兼容插件真正发送 V3 消息后自动清除，因此不会再把协议错误伪装成普通离线。

音量或电源不可用

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

扩展命令失败

• 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 来自四段纯数字稳定 Release 或 v3.x.x-beta.y Beta Release，且不低于当前手表版本，并确认新 APK 与当前安装包签名一致；首次安装正式签名版后，后续更新才能在同一签名下覆盖。旧三段 v3.x.x 稳定标签不会作为新候选，V4 也不会显示为 V3 手表的自动更新候选。
• 旧 v3.2.0 安装不会自动发现首个实际发布的四段稳定版本 3.2.1.2；首次硬切迁移请手动安装对应服务端或 FPK、RemoteCI.Plugin.cipx 和 RemoteCI.Watch-3.2.1.2.apk。
• 飞牛 fnOS 不在 WebUI 内更新，请从 GitHub Release 下载新版本在线或对应架构离线 FPK，再到 fnOS 应用中心手动升级。

首次启动找不到密码

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

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

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

健康检查

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

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

功能入口突然消失

V3 基础能力基线自 3.1.0 引入，WebUI 按服务端与当前主插件的能力交集显示功能，手表还会与自身能力再取一次交集。管理员可在 WebUI 概览的“连接诊断”查看各连接的软件版本、能力来源、有效能力和缺失能力。旧 V3 端未上报能力时会回退到基础能力；若仍缺少入口，应确认实际接收命令的主插件是否已经切换、断开或未声明对应能力。权限不足和能力缺失是两套独立检查，能力存在不代表账号一定获准执行。