#常见问题

本页面汇总了 AstraSchedule 使用过程中的常见问题及解决方法。如果你遇到的问题不在本页，欢迎在 GitHub Issues 提出。

#部署相关

#Q1：客户端连不上后端怎么办？

排查步骤：

1. 确认后端是否运行：在服务器上执行 curl http://localhost:9000/web/menu，应返回 JSON 数据。如果连接被拒绝，重启后端服务。
2. 确认客户端填写的地址正确：
   • 内网：192.168.1.100:9000 或 http://192.168.1.100:9000
   • 公网：api.your-domain.com 或 https://api.your-domain.com
   • ⚠️ 地址不要带路径（如 /web/menu），也不要以 / 结尾
3. 检查防火墙：
   • 内网环境：确认服务器防火墙已放行 9000 端口（参考 sudo ufw status）
   • 外网环境：确认 Cloudflare DNS 代理状态为 🟢 橙色云朵
4. 测试网络连通性：在客户端电脑执行 ping 服务器IP 或 telnet 服务器IP 9000

#Q2：管理端打开后显示白屏或一直加载？

排查步骤：

1. 打开浏览器开发者工具（F12）→ Network 标签页，刷新页面
2. 查看是否有请求失败（红色），通常是对后端 API 的请求
3. 如果 API 请求失败，说明后端未运行或 global.js 中 APISRV 地址配错
4. 如果 API 请求返回 403，说明 BasicAuth 密码错误（检查服务器 config.toml 中的 token）
5. 如果请求状态为 (failed) 或 net::ERR_CONNECTION_REFUSED，检查后端是否启动

#Q3：外网部署后 API 返回大量 403 错误？

这是 Cloudflare WAF 误拦截的表现。处理方式：

1. 登录 Cloudflare 控制台 → Security → Events
2. 查看最近被拦截的请求，确认触发拦截的规则名称
3. 针对误判规则，创建「跳过」规则：
   • 进入 Security → WAF → Custom rules
   • 创建规则，操作为「跳过」→ 选择被误判的托管规则
   • 将匹配范围限制为你的 API 域名

#Q4：函数计算冷启动很慢，影响使用体验？

函数计算在长时间无请求后会回收实例，下一次请求需要冷启动（通常 2-5 秒）。

解决方案：

1. 配置预留实例（推荐）：在函数计算控制台 → 弹性管理 → 配置至少 1 个预留实例。这样始终有一个实例保持活跃，不会冷启动。预留实例按较低费率计费，通常每月几元钱。
2. 定时保持活跃：使用云厂商的定时触发器，每 5 分钟访问一次 /web/menu，保持实例不被回收。
3. 接受冷启动：如果对首次访问延迟不敏感（如客户端每 10 分钟拉取一次），可以不处理。

#Q5：SQLite 和 MySQL 怎么选？

建议：不确定就选 SQLite，先用起来。以后需要迁移到 MySQL 时，通过管理端导出 JSON → 导入新后端即可，迁移过程简单。

#Q6：域名怎么配置？DNS 和 CNAME 有什么区别？

简单理解：

• DNS 是域名系统，负责把域名翻译成 IP 地址
• CNAME 是 DNS 记录的一种类型，让一个域名指向另一个域名（而不是直接指向 IP）

AstraSchedule 需要配置的内容：

1. 在域名注册商处，将域名的 DNS 服务器修改为 Cloudflare 提供的地址
2. 在 Cloudflare 控制台添加两条 CNAME 记录：
   • api.你的域名.com → 函数计算的 CNAME 地址
   • admin.你的域名.com → Netlify 提供的域名地址

配置完成后等待 DNS 生效（通常几分钟到几小时不等）。

#Q7：部署到 Netlify 后，管理端修改后端地址需要重新部署吗？

是的。src/global.js 中的 APISRV 是构建时确定的，修改后需要重新触发构建。

触发重新构建的方法：

1. 在 GitHub 上修改 src/global.js 并提交（Commit）
2. Netlify 自动检测到仓库更新，自动重新构建和部署
3. 或者登录 Netlify → 选择你的站点 → Deploys → Trigger deploy → Deploy site，手动触发

#配置相关

#Q8：作息表保存后 divider 的值会自动变化？

这是正常行为。系统会自动做 key 一致性修正：

• 你在「节次配置」中添加/删除了一个节次 → 后端自动将对应作息表中缺失的 divider[key] 补为 []，多余的自动移除

这个修正确保前端渲染和后端计算时不会因为数据不一致而出错。不需要手动干预，也不需要在意这个变化。

#Q9：复制配置失败了，提示「来源不存在」？

1. 确认要复制的来源班级已配置完整，尤其是：
   • 科目管理有内容
   • 课表已录入
   • 作息表（含常日）已配置
2. 来源和目标的学校/年级/班级层级必须正确填写
3. 如果来源班级确实存在且配置完整，尝试刷新页面后重试

#Q10：复制配置会复制哪些内容？能不能只复制一部分？

复制内容：科目、作息表、课表、通用设置（完整配置）。

当前不支持选择性复制（如只复制课表不复制作息）。如果需要精细控制，可以：

1. 导出源班级的 JSON 备份（「实用工具」→「完整导出」）
2. 手动编辑 JSON 文件，移除不需要的配置部分
3. 导入到目标班级（「实用工具」→「完整导入」）

#Q11：常日作息为什么删不掉？

「常日」是系统的兜底作息。当某一天没有匹配到任何作息表时（如周六、节假日），系统会自动回退到常日作息。

因此常日不可删除——删了之后非工作日就没有作息可用了。如果你确实不需要常日，可以将其内容清空（保留空表），但标签必须保留。

#Q12：作息表验证失败怎么办？

作息表的验证规则：

1. 必须至少有一个 divider：每个作息表必须包含课节分割信息
2. divider key 必须与节次配置匹配：在「节次配置」中定义的每个节次，在作息表中必须有对应的 divider 键
3. 时间格式正确：时间必须为 HH:MM 格式（如 08:00）

如果验证失败：

• 检查是否在节次配置中添加了新节次，但作息表中未更新
• 检查时间格式是否正确（确保是两位小时 + 冒号 + 两位分钟）
• 进入管理端的「作息验证」功能，会给出具体报错信息

#客户端相关

#Q13：客户端窗口遮挡了白板或课件？

AstraSchedule 窗口设计为半透明悬浮窗，支持以下操作：

• 鼠标悬停 → 窗口恢复不透明度，可正常查看
• 鼠标移开 → 窗口降至几乎透明，不遮挡内容
• 托盘菜单 → 可开关「窗口置顶」和「点击穿透」
  • 关闭「点击穿透」后，鼠标可以点到窗口下方的课件
  • 关闭「窗口置顶」后，其他窗口可以覆盖课表窗口

#Q14：天气不显示或显示错误？

排查步骤：

1. 检查 config.toml 中天气 API 配置是否正确：

   [apikey]
   apihost = "YOURS.re.qweatherapi.com"  # 和风天气 API 域名
   weather = "YOUR_API_KEY"               # API Key
2. 检查客户端托盘菜单 → 「当前地区」，确认选中的地区正确
3. 检查和风天气 API 调用配额：
   • API Key 方式：1000 次/天（按 IP 计数），多个客户端共用可能超限
   • JWT 方式：无调用次数限制，强烈推荐
4. 如果使用 API Key 方式且客户端数量较多（如 30+ 个班级），建议升级到 和风天气 JWT 认证，免费且不限制调用次数。

#Q15：倒数日窗口不显示？

排查步骤：

1. 确认管理端已配置倒数日（「倒数日管理」页面）
2. 检查倒数日的「生效域」是否覆盖了当前班级：
   • 在倒数日配置中，查看「生效年级」和「生效班级」
   • 确保当前班级在生效范围内
3. 检查倒数日是否已过期：过期的倒数日会自动隐藏
4. 确认倒数日的「开始日期」≤ 今天 ≤「结束日期」

#Q16：自动更新失败？

常见原因及解决：

1. 更新源设置错误：托盘菜单 → 「更新源设置」，确认 URL 正确
2. 网络不通：客户端无法访问 GitHub，尝试切换为国内镜像源
3. Windows 7 特殊情况：
   • 安装 KB2999226 和 KB2533623 补丁
   • 或手动下载安装包覆盖安装（Releases 页面 下载 .exe 安装包）

#Q17：课表上科目名称显示不对？

检查「科目管理」中的简称和全名映射关系：

• 简称：显示在课表上的文字，支持 @ 下角标语法（如 自@物 → 自ᵥ）
• 全名：完整的科目名称，用于识别

如果简称和全名对应错了，更新科目管理中的映射即可。

#Q18：为什么客户端课表没有自动更新？

客户端通过 WebSocket 接收配置变更通知。如果课表没有自动更新：

1. 手动更新：托盘菜单 → 「更新课表」，立即拉取最新配置
2. 检查 WebSocket 连接是否正常：
   • 管理端首页仪表盘查看客户端状态
   • 如果显示离线，排查网络和后端状态
3. 极低成本方案不使用 WebSocket，客户端定期轮询拉取配置。修改配置后等待下一个轮询周期（约 10 分钟）才能生效。如需立即生效，在客户端手动点击「更新课表」。

#管理端相关

#Q19：管理端显示白屏？

1. 打开浏览器开发者工具（F12），查看 Console 和 Network 标签
2. 如果请求后端 API 失败，检查：
   • 后端是否运行
   • src/global.js 中 APISRV 地址是否正确（必须与部署时配置一致）
3. 如果是 Netlify 部署，确认构建成功且 APISRV 地址包含了协议（https://）
4. 尝试清除浏览器缓存（Ctrl+Shift+Delete）

#Q20：保存配置失败？

1. 返回 401：BasicAuth 密码错误。检查你输入的密码是否与服务器 config.toml 中的 token 一致。
2. 返回 403：WAF 拦截。按 Q3 的方式排查 Cloudflare WAF 规则。
3. 返回 500：后端内部错误。查看后端日志定位具体原因（可能是数据库写入失败或数据格式不对）。
4. 请求超时：函数计算冷启动或其他网络问题，稍后重试。
5. 网络错误（Failed to fetch）：后端未运行或网络不通。

#Q21：管理端登录密码忘记了怎么办？

管理端密码存储在服务器 config.toml 中：

[secret]
token = "你的密码"

如果你可以访问服务器，查看该文件即可获取密码。如果密码被泄露需要更改，直接修改这个值并重启后端。

⚠️ 用户名固定为 ElectronClassSchedule，不可修改。只有密码（token）可以自定义。

#其他

#Q22：和风天气 API 有什么限制？免费版够用吗？

API Key 方式（免费）：

如果学校有 30 个班级，每个班级每小时刷新一次天气，一天约 30 × 8 = 240 次调用，在 1000 次限额内。但如果刷新频率更高或班级数量更多，可能会超限。

JWT 方式（免费，推荐）：

• 无调用次数限制
• 需要填写开发者认证信息（免费申请）

建议：注册和风天气开发者账号后，使用 JWT 认证方式，免费且不受调用量限制。配置方法：在 config.toml 中使用 JWT 格式的 API Key。

#Q23：浏览器兼容性如何？

管理端基于现代 Web 技术构建，建议使用以下浏览器：

不支持的浏览器：IE 全系列、旧版 Edge（EdgeHTML 内核）。

#Q24：Windows 7 上能正常运行吗？

AstraSchedule 客户端支持 Windows 7，但有以下注意事项：

1. 自动更新可能失败：Windows 7 缺少某些系统补丁，安装以下补丁后再尝试更新：
   • KB2999226（通用 C 运行时）
   • KB2533623（安全更新）
2. 字体渲染差异：Windows 7 的字体渲染与 Windows 10/11 有差异，界面可能略有不同
3. 系统托盘图标：在部分 Windows 7 系统中，托盘图标可能不显示或延迟显示，重启程序即可
4. 无法使用最新功能：一些依赖新版 Chromium 的功能（如特定 CSS 效果）在 Windows 7 上可能不可用

💡 如果条件允许，建议逐步将教室电脑升级到 Windows 10 或更高版本。

#Q25：如何迁移数据到新服务器？

1. 在旧服务器上，通过管理端「实用工具」→「完整导出」，下载 JSON 备份
2. 复制旧服务器的 config.toml 配置文件
3. 在新服务器上部署 AstraSchedule 后端
4. 将 config.toml 放到新服务器的对应位置（修改为新服务器的 IP/域名）
5. 启动新服务器后端
6. 打开管理端，进入「实用工具」→「完整导入」，选择之前下载的 JSON 备份
7. 验证所有班级配置正确
8. 更新客户端配置的后端地址，指向新服务器

#Q26：如何从 FastClassSchedule（Python 旧版）迁移到 Go 新版？

1. 确保旧版后端仍可访问
2. 在新 Go 后端的管理端中，使用「实用工具」→「完整导入」
3. 如果是 FastClassSchedule 导出的 JSON，格式兼容，可以直接导入
4. 导入后检查以下内容：
   • 作息表的 divider 是否正确（Go 后端会自动修正）
   • 科目映射是否完整
   • 班级配置的作用域是否正确
5. 确认无误后，将客户端配置更新为新的后端地址