故障排查

ClassIsland 提示插件架构不兼容

ClassIsland 日志出现 The assembly architecture is not compatible with the current process architecture 时，说明当前运行的是 x86 或 arm64 版 ClassIsland，而安装的插件包是 x64 专用构建，插件会在启动阶段直接加载失败，ClassIsland 也不会显示 RemoteCI 设置页。请升级到包含此修复的 RemoteCI.Plugin.cipx：插件程序集为 AnyCPU，可以随 ClassIsland 的 x86、x64 与 arm64 Windows 宿主一起加载。安装后重新启用插件并重启 ClassIsland。

ClassIsland 2.2 预览版上的语音与课表异常

ClassIsland 2.2 预览版（版本号 2.1.1.x）改动了部分公开 API 的类型，早期版本的 RemoteCI 插件会因此报错：日志出现 Method not found 或 MissingMethodException，表现为发送语音消息时浮窗无法打开，日志每 30 秒提示“生成或推送七日课表失败”，WebUI 与手表也拿不到课表。请升级到包含兼容层的插件版本，同一份 RemoteCI.Plugin.cipx 即可同时运行在 ClassIsland 2.0/2.1 稳定版与 2.2 预览版上。仍在使用 ClassIsland 2.1.0.1 等稳定版的用户不受影响，也不需要额外设置。

ClassIsland 插件无法连接服务器

1. 打开 ClassIsland 的“RemoteCI 设置”，先看“服务器状态”和“最近错误”，不要只依据服务端健康检查判断插件已经连通。
2. 若需检查云端开关，先在普通设置开启“显示开发者设置菜单”并重启 ClassIsland，再确认开发者设置没有关闭云端连接；云端地址应包含正确的 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. 检查证书是否受手表信任。

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

Android 手机模拟器连接慢或扫描不到插件

1. 确认电脑上的 WebUI 和 ClassIsland 插件确实在运行，并分别可访问 TCP 8080 与插件设置中的 TCP 端口（默认 8765）。模拟器里 10.0.2.2 映射到宿主机；真机请填写电脑当前的局域网 IP。
2. 模拟器扫描使用插件默认端口的短 TCP 引导探测，不依赖虚拟网卡的 UDP 广播。插件改过端口时，在连接设置中手动填写正确端口。
3. 电脑切换 Wi-Fi、开启 VPN 或更换网卡后，之前保存的插件 IP 可能失效。重新扫描或填写电脑当前地址；还应确认 Windows 防火墙允许当前网络访问 WebUI 和插件端口。
4. 新设备输入密码登录仍需要云服务器可达，插件的局域网引导不会验证账号密码。10.0.2.2:8080 若超时，应先从模拟器验证这个地址的 WebUI 连通性。

Android 手机连接慢、经常断开或课表不更新

1. 首页显示“连接已断开，正在自动重连…”或“…，稍后自动重试”属于自动恢复过程，无需反复退出重进；网络恢复后会立即重连，否则最长约 60 秒重试一次。
2. 长时间停在“请先使用账号密码登录”表示设备会话已失效或被撤销，需要重新输入密码登录。
3. 多班级账号请先在左上角“账号与设置”中确认当前班级；课表、状态和局域网直连都按当前班级显示，切换后会立即显示该班已收到的课表。
4. 只有系统管理员或当前班级的班主任可以向插件拉取课表；其他账号若一直没有课表，请先确认插件在线，再请管理员拉取或在插件中推送。
5. 校园网或公司网络阻断局域网互访时，手机会回退云端；连接仍慢时检查云服务器地址、反向代理的 WebSocket Upgrade，以及服务端认证接口是否因同一出口 IP 请求过多而限流。

局域网无法连接

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. 选择插件后应先核对手表显示的云服务器地址，再点击“安全登录”；扫描设备不会接收账号密码。

老师看不到“换课”入口或收不到换课提醒

• 确认账号的角色（或账号附加权限）开启了“老师主动换课”；强制换课按钮还需要“强制换课”权限。修改权限后重新登录或刷新页面。
• 申请提示“至少要有一节是你自己的课”时，检查课表里的教师名是否与账号用户名完全一致。
• 浏览器通知需要通过 HTTPS 或 localhost 打开 WebUI，并在“通知”页点击“开启浏览器通知”。浏览器拒绝过通知时，要先在网站设置里允许。Chrome 依赖 Google 推送服务，网络不可达时可改用 Edge 或 Firefox。
• 手机端在系统设置里确认“换课申请”通知渠道没有被关闭。
• 小米 HyperOS 等系统会对非应用商店安装的应用默认关闭“悬浮通知”，应用无法代为打开。通知只进通知栏、不弹横幅时，到系统设置的 RemoteCI 应用通知管理里打开各通知类别的“悬浮通知”。

能查看状态但不能换课

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

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

插件上线过的班级始终显示最后一次同步的课表；插件从未同步过课表时，WebUI、手机、手表和“我的日程”会先按本班“档案”页保存的班级档案推算课表并注明来源（手机或手表还没显示时，确认服务端已升级，再让手机或手表重新连接或手动刷新课表）；如果课表页提示“本班也还没有班级档案”，可以先在“档案”页上传或收集档案。要显示教室端的实际课表，仍需插件同步：

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

老师看不到任教班级或“我的日程”为空

1. 确认账号角色是内置“老师”；只有该角色会按姓名关联课表并显示“我的日程”。
2. 确认账号用户名与课表中的教师名完全一致。一科多位老师时教师名应写成 张三/李四（分隔符见功能说明中的“老师、班主任角色与我的日程”），每位老师的用户名填写其中自己的姓名；张三 李四 用空格分隔不会被拆开。用户名只能由系统管理员在“人员权限”中修改。
3. 请拥有“换课”权限的账号在 WebUI 课表页“科目教师”区检查该班科目是否已填写教师名；如果该区域提示插件不支持，请先升级教室端插件。
4. 绑定依据服务端缓存的课表计算。服务端刚重启或教室端插件离线、尚未推送课表时暂时为空，插件连接并同步课表后自动恢复。

WebUI 显示插件协议不匹配

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

音量或电源不可用

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

扩展命令失败

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

下发档案提示“恢复旧档案也失败”

旧版插件在 ClassIsland 2.1 上用“创建并启用新档案”下发时，会报“保存档案失败，恢复旧档案也失败，请检查磁盘权限：宿主未提供设置保存接口”。这不是磁盘权限问题：宿主只提供带参数的设置保存方法，旧插件找不到。此时设备上的档案文件和档案选择已经还原，新建的档案文件也已删除。升级 RemoteCI 插件后重新下发即可。

收集档案失败

• “班级设备未在线”：该班没有在线的教室电脑，等设备上线后重试。
• 提示需要升级插件：教室插件不支持 profile.read（收集）或 profile.temp-layer（作为临时层下发），升级 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 或 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 应用中心手动升级。

首次启动找不到密码

新版本不再生成初始密码：首次打开 WebUI 会进入初始化向导，在页面上创建系统管理员账号和密码。只有部署时配置了 REMOTECI_ADMIN_PASSWORD 才会跳过向导，用它预先创建登录 ID 为 admin 的系统管理员。

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

升级后“默认班级”不见了，设备显示未分配

旧版本会自动创建“默认班级”并把所有新账号加入其中。升级后，如果这个班级从未改名且已经有其他班级，会被一次性移除：其中仍在使用的设备转入“班级管理 → 未分配设备”（备注为“原默认班级”），凭据保留，分配到正确班级后即可继续使用。只有一个班级的部署会把它保留为普通班级，可以改名或删除。

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

API Key 调用返回 401 或 403

• 401 UNAUTHORIZED：确认请求头使用 Authorization: Bearer rci_... 或 X-API-Key: rci_...，并确认 Key 未被吊销、账号已启用且拥有“API 访问”权限。
• 403 FORBIDDEN：API Key 本身有效，但账号没有该操作所需权限，或不能访问目标班级。请到“人员权限”检查角色默认权限和账号附加权限。
• API Key 只在创建时显示一次。若完整 Key 已丢失，请吊销旧 Key 后重新生成，不要尝试从数据库恢复。
• 生产环境必须使用 HTTPS；不要在浏览器地址栏、查询参数、截图或公开日志中暴露 API Key。

健康检查

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

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

功能入口突然消失

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