配置

Mini-HBUT 提供高度可定制的界面外观。

主题预设

内置 5 套精心设计的主题：

界面微调选项

快捷交互方案

预定义的交互参数组合，影响圆角、字号、间距和动画速度：

• mobile_focus：适合移动端操作，大圆角、大字号、大间距、慢动画
• desktop_dense：适合桌面端，小圆角、标准字号、紧凑间距、快动画
• presentation：演示模式，中等圆角、大字号、适中间距、适中动画

缩放参数

每套主题和交互方案包含以下缩放因子（0.8 ~ 1.4）：

• radiusScale - 圆角缩放
• fontScale - 字号缩放
• spaceScale - 间距缩放
• motionScale - 动画速度缩放
• surfaceOpacity - 卡片透明度
• borderOpacity - 边框透明度

后端设置控制 Mini-HBUT 与外部服务的连接方式。进入方式：设置 → 后端。

配置源

• 启用远程配置（推荐）：应用启动时自动拉取服务端的远程配置，覆盖 OCR 端点、云同步地址等。
• 仅本地配置：关闭远程配置，完全使用本地手动填写的地址。适合网络受限或自架服务的场景。

服务地址

模块参数

以下参数影响应用的网络行为，修改后自动保存并立即生效：

功能测速

设置中心提供并发测速功能，可同时测试以下服务的延迟：

测速结果以颜色标记延迟等级：🟢 良好（<500ms）🟡 一般（500-2000ms）🔴 较差（>2000ms 或超时）。

字体设置提供 6 种中文字体选择和 3 种 CDN 线路配置。

CDN 线路设置：

• auto（推荐）：自动选择最快的节点，jsDelivr 优先，失败自动降级到 unpkg。
• jsdelivr：固定使用 jsDelivr CDN，国内通常较快。
• unpkg：固定使用 unpkg CDN，作为备用选择。

缓存机制：

• 字体文件下载后存储在 IndexedDB（hbu_font_binary_cache_v1）中。
• 字体选择存储在 localStorage（hbu_font_settings_v1）中。
• 每次启动自动恢复上次选择的字体，无需重新下载。
• 得意黑字体支持可视化下载进度条和失败重试。

在「通知」页面配置后台静默检查的行为（仅移动端 Capacitor 版支持完整后台通知）。

调试模块提供实时日志查看功能，便于排查问题。

• 日志过滤：支持按级别过滤（all / debug / info / warn / error / log）。
• 日志查看：实时滚动显示应用运行日志。
• 日志操作：支持一键复制全部日志和清空日志。
• 统计面板：显示日志总数、警告数和错误数。

OCR 服务用于登录时自动识别教务系统的验证码图片。Mini-HBUT 使用统一的 HTTP 接口调用 OCR。

接口规范

POST /api/ocr/recognize
Content-Type: application/json

请求体：
{ "image": "<base64 编码的验证码图片>" }

成功响应：
{ "success": true, "result": "ABCD" }

失败响应：
{ "success": false, "error": "识别失败" }

部署要求

• 服务器：需要一台可公网访问的服务器（或局域网内可达的服务器）。
• 端口：默认使用 5080 端口，可自定义。
• HTTPS：移动端要求 HTTPS（或者移动端添加安全例外），桌面端 HTTP 也可以。
• CORS：需要允许跨域请求（Access-Control-Allow-Origin: *）。

推荐部署方式

• Docker 部署（推荐）：可以使用常见的 OCR 服务 Docker 镜像（如 ddddocr、TesseractOCR 等基于 Python 的服务），暴露 API 接口即可。
• HuggingFace Spaces：可以在 HuggingFace 上部署免费的 OCR 服务，公共访问。
• Vercel/Cloudflare Workers：如果 OCR 库支持 Serverless 环境。

配置到客户端

1. 方式一（远程配置）：修改 remote_config.json 中的 ocr.endpoint 字段。
2. 方式二（本地覆盖）：在应用「设置 → 后端」中手动填写 OCR 服务地址。

云同步服务基于 Cloudflare Workers + KV 实现，用于跨设备同步课表、设置和学业数据。

前置条件

• Cloudflare 账号（免费即可）
• Node.js 环境
• Wrangler CLI 工具

部署步骤

1. 安装 Wrangler 并登录：

   npm i -g wrangler
   wrangler login

2. 创建 KV 命名空间：

   # 生产 KV
   wrangler kv namespace create SYNC_KV
   # 预览 KV
   wrangler kv namespace create SYNC_KV --preview

3. 配置 wrangler.toml：

   将 wrangler.toml.example 复制为 wrangler.toml，填入 KV 的 id 和 preview_id：

   name = "mini-hbut-cloud-sync"
   main = "src/index.js"
   compatibility_date = "2026-03-05"
   
   [vars]
   RATE_LIMIT_SECONDS = "60"
   RATE_LIMIT_UPLOAD_SECONDS = "120"
   RATE_LIMIT_DOWNLOAD_SECONDS = "10"
   RATE_LIMIT_PING_SECONDS = "15"
   
   [[kv_namespaces]]
   binding = "SYNC_KV"
   id = "你的生产 KV ID"
   preview_id = "你的预览 KV ID"

4. 设置鉴权令牌（推荐）：

   wrangler secret put SYNC_API_TOKEN

   如果不设置，服务将允许匿名访问。

5. 部署：

   wrangler deploy

   部署后获得 https://<worker-name>.<subdomain>.workers.dev 地址。

6. 健康检查：

   curl "https://your-worker.workers.dev/sync/ping"
   # 启用了 Token 时：
   curl -H "Authorization: Bearer <TOKEN>" "https://your-worker.workers.dev/sync/ping"

Worker API 接口

速率限制配置

• RATE_LIMIT_SECONDS：默认最小请求间隔（建议 ≥ 60s）
• RATE_LIMIT_UPLOAD_SECONDS：上传间隔
• RATE_LIMIT_DOWNLOAD_SECONDS：下载间隔
• RATE_LIMIT_PING_SECONDS：健康检查间隔

注意：Cloudflare KV 的 expiration_ttl 最小值为 60 秒。

配置到客户端

{
  "cloud_sync": {
    "enabled": true,
    "mode": "proxy",
    "proxy_endpoint": "https://your-proxy-service/api/cloud-sync",
    "secret_ref": "kv1-main"
  }
}

资料分享功能通过 WebDAV 协议连接文件服务器，你可以自行搭建 WebDAV 服务来提供学习资料共享。

推荐方案

• Nginx + WebDAV 模块：轻量高效，适合有 Linux 服务器的场景。
• Nextcloud / ownCloud：功能丰富的自建云盘，自带 WebDAV 支持。
• Caddy + WebDAV：简洁配置，自动 HTTPS。

注意事项

• CORS 配置：必须允许跨域（客户端从不同域名访问 WebDAV）。
• 认证方式：支持 Basic Auth（用户名 + 密码），在远程配置中下发。
• HTTPS：移动端要求 HTTPS 协议。
• Office 预览：如需在线预览 Word/Excel/PPT，需额外配置 Office 预览代理服务（如 ONLYOFFICE 或使用第三方转换 API）。