快速开始

RemoteCI 有三项运行组件：ClassIsland 插件、RemoteCI 服务端和 Wear OS / Android 手机 客户端。只在同一局域网内使用时可以直连插件；需要跨网络、账号管理或集中控制时，应部署服务端。

准备工作

组件	要求
教室电脑	已安装并可正常运行的 ClassIsland 2.x
手表	Wear OS 3 或更高版本，RemoteCI 手表应用 3.2.1.4
服务端	支持 Docker 的 NAS 或 Linux 服务器，建议有域名和 HTTPS
网络	局域网直连默认使用 TCP 8765，设备扫描固定使用 UDP 48765；服务端默认使用 TCP 8080

发布包从 GitHub Releases 获取：服务端提供 linux-x64 与 win-x64 压缩包，插件提供 CIPX，手表提供 APK。如果 Releases 尚无可用版本，需要从 RemoteCI 源码自行构建，见文档同步规则。

一、部署服务端

按照服务端部署使用仓库自带的 compose.yaml 完成部署。服务端不再生成随机初始密码，也不再自动创建“默认班级”。首次在浏览器打开 WebUI 时会进入初始化向导：

1. 创建系统管理员：填写登录 ID（默认 admin）、显示名称和密码。系统管理员拥有全部权限，并且只能由本人修改，其他管理员不能编辑、停用、重置密码或删除它。
2. 新建第一个班级：填写班级名称。之后可以在“班级管理”中继续添加班级。

完成后进入概览页。新建的账号也不会自动加入任何班级：在“人员权限”新建学生或班主任时选择所属班级，老师按课表中的教师姓名自动绑定任教班级。

二、连接 ClassIsland 插件

1. 在 ClassIsland 中安装 RemoteCI 插件（3.2.1.4）。
2. 打开“设置”中的“RemoteCI 设置”。
3. 普通设置中确认局域网端口（默认 8765）；局域网服务默认开启。若需连接开关或语音接收测试，开启“显示开发者设置菜单”并重启 ClassIsland。
4. 填写云端服务端的完整地址；普通设置不提供关闭云端中转的开关。
5. 登录服务端 WebUI，确认右上角选中的是要连接的班级，在概览页点击“生成插件配对码”，把显示的一次性配对码填入插件设置。
6. 保存设置并重启 ClassIsland。
7. 回到“RemoteCI 设置”，确认“服务器状态”为已连接；若仍在等待配对或重试，查看最近错误并点击“测试服务器连接”。

配对码在使用前持续有效，成功配对后立即作废；插件换到长期凭据后会清空本地配对码。

首次硬切迁移

3.2.1.2 是从旧 v3.2.0 三段稳定标签切换后首个实际发布的 ClassIsland 四段纯数字版本。旧安装不会自动发现新标签，首次升级请手动安装服务端或 FPK、RemoteCI.Plugin.cipx 和 RemoteCI.Watch-3.2.1.2.apk；后续稳定版使用四段数字标签自动更新，v3.x.x-beta.y 仅用于测试。

地址写法

本机测试可以填写 http://localhost:8080。手表真机跨网络访问时，应填写带 HTTPS 的公网地址，例如 https://remoteci.example.com。

三、创建手表账号

登录服务端 WebUI 的“人员权限”页面，为手表使用者创建账号：

• ID：登录唯一标识，3-32 位字母、数字、点、下划线或短横线。
• 用户名：显示名，1-40 个字符，会出现在通知的“由用户名发送：”前缀中。
• 初始密码：8-128 位，也可以留空；密码只用于登录，不会下发到插件或写入手表。留空时账号处于“待设置密码”状态：使用者首次在 WebUI 登录页或手机 App 登录页输入 ID、密码留空直接登录，即进入设置密码页面，设好密码后再正常登录。已设置密码的账号留空密码登录会提示 ID 或密码错误。
• 角色：学生、班主任、老师、自定义角色或管理员；管理员固定拥有全部权限。学生、班主任等角色需要同时选择归属班级；老师不选班级，按用户名与课表中的教师名自动关联任教班级，因此老师的用户名应填写课表里使用的教师姓名。班主任（原“班管理员”）除管理本班外，也和老师一样按用户名在侧栏“我的日程”查看自己在各班的课次，因此班主任的用户名也建议填写课表中的教师姓名。
• 附加权限：概览、人员管理、发送与清除通知、换课、扩展功能、主界面、电源控制（含音量）、API 访问。旧版协议中的部分权限位会继续保留，但当前不在权限设置中提供入口。

如果 ID、用户名或初始密码校验失败，页面只清空对应的无效字段，其他输入、角色与权限勾选保持不变。服务端错误响应不会回传密码或其他表单原值。

建议只授予实际需要的权限。普通用户默认可以查看当前课程和 WebUI 七日课表，需要操作时再按需勾选。勾选“API 访问”后，该账号可在“个人账号”页创建 API Key；学生角色默认不授予该权限，管理员和班主任默认拥有。用户名只能由系统管理员修改，因为它同时是老师关联课表的依据。

需要创建多个账号时，管理员可在同一页面下载 Excel 模板，填写后批量导入；已存在的 ID 和非法字段会列出行号与原因。批量导出默认不包含密码列，并可按班级分组导出后修改，再使用“覆盖导入”更新文件中出现的成员关系；文件中缺失的关系会保留。

四、连接 Android 手机客户端

3.3.0.2 完善了桌面小组件、上课状态通知和扫码登录，并提供老师换课申请与插件扩展设置；完整更新内容见 3.3.0.2 发布说明。

1. 在手机浏览器打开可被手机访问的 RemoteCI WebUI，登录后在概览页点击“生成登录二维码”，页面会显示“手机扫码登录”二维码。
2. 打开 Android 手机应用，在登录页点击扫码按钮，进入竖屏扫码页（光线不足时可打开手电筒，也可从相册选择二维码截图）；扫描后应用会直接用二维码中的一次性票据登录当前账号，无需再输入密码。
3. 二维码 5 分钟内有效且只能使用一次。二维码里的服务器地址必须能被手机实际访问；电脑上的 localhost 对手机无效。WebUI 经反向代理访问或内外网地址不同时，系统管理员可在“系统配置 → 手机扫码登录”中指定二维码使用的服务器地址。也可点击“扫描局域网插件”，确认插件返回的云服务器地址后再登录。
4. 管理员创建账号时未设置密码的，在登录页输入服务器地址和 ID、密码留空点击“登录”，App 会显示“首次登录 · 设置密码”，设置后自动登录。在“账号与设置 → 连接与服务器”切换到这类账号时同样留空密码，App 会回到登录页完成设置。
5. 登录后可以在“账号与设置 → 外观”选择显示模式和统一配色，有“人员管理”权限的账号可在“管理”页管理访客访问、角色、账号与插件配对码，修改密码和设备会话在“账号与设置 → 密码与设备会话”；更多操作可点“管理”页底部的“WebUI”链接，直接以当前账号在浏览器中打开 WebUI。

手机登录后，首页右上角的扫码按钮可以反过来扫描电脑上 WebUI 登录页“手机扫码”中的二维码，确认后电脑直接登录，无需在电脑上输入密码。App 打开时会自动检查新版本并弹窗提示。

手机应用保存设备会话后会先尝试局域网直连，失败时再回退到云端。Android 模拟器的广播可能被虚拟网卡拒绝，扫描会直接短探测宿主机映射地址 10.0.2.2:8765；电脑插件使用其他端口时需要手动填写。实体手机使用当前电脑的局域网 IP，不能把 10.0.2.2 当作电脑地址。

五、连接 Wear OS 客户端

1. 打开手表端“设置 → 连接”。
2. 填写服务端创建的 ID（不是显示名）；密码只用于本次登录，不写入手表设置。
3. 已知云服务器地址时可以直接填写并登录，服务端会把插件的局域网地址与端口补充到手表。
4. 不知道云服务器地址时，在登录页点击“扫描局域网设备”，选择运行 ClassIsland 的电脑；手表会从插件读取并显示云服务器地址。
5. 确认显示的云服务器域名或 IP 正确后点击“安全登录”。密码只发往云服务器，不会经过插件。

登录成功后，30 天设备会话由 Android Keystore 加密保存在手表上。云端先连接时，插件上报的全部局域网候选地址和端口会补充到手表；局域网扫描先连接时，插件会反向补充云服务器地址。应用依次尝试局域网候选地址并记住第一个成功地址，局域网失败时再自动续登云端。Android 模拟器访问宿主机时可使用 10.0.2.2；真机不能使用这个地址。

只有“设置 → 开发者”允许关闭云端中转或局域网直连。即使开发者关闭云端后退出账号，下一次密码登录也会临时使用云端完成认证，不需要先恢复开关。

登录后可在“设置 → 外观”切换 Material Design 3 配色方案（默认淡紫，另含经典紫、蓝、绿、橙、粉），选择会保存在手表本机。

六、确认连接

• 手机或手表首页在上课中显示当前课程；下课或即将上课时改为显示下一节课，而不是连接错误。
• ClassIsland 的“RemoteCI 设置”显示服务器已连接，主动连接测试成功。
• 服务端概览显示插件在线；Android 手机会显示为独立的移动端连接，不计入在线手表数。
• ClassIsland 切换课程状态后，手机或手表能收到更新。
• 有权限的账号可以提交一次非破坏性操作（例如发送通知）并看到真实回执。

如果其中一步失败，请查看连接方式和故障排查。