MobileModels/docs/web-ui.md

Web UI

启动方式

在项目根目录执行：

docker compose up --build -d

如果要连本地测试 MySQL：

docker compose -f docker-compose.yml -f docker-compose.test.yml up --build -d

如需自定义环境变量：

cp .env.example .env

Compose 的环境变量来源顺序：

1. 当前 shell 环境变量
2. 项目根目录 .env
3. docker-compose.yml 中的默认值

停止服务：

docker compose down

重置 MySQL 和运行期数据：

docker compose down -v

页面入口

• http://127.0.0.1:8123/web/device_query.html：设备查询
• http://127.0.0.1:8123/web/brand_management.html：数据管理
• http://127.0.0.1:8123/web/device_query.html?view=docs：相关文档

整个功能栈统一运行在 Docker Compose 中，不再依赖本地 Python。

原始数据工作空间位于项目内的 workspace/ 目录。

启动后自动完成的动作

• 从 workspace/brands 构建设备索引
• 生成 dist/device_index.json
• 导出 MySQL seed 文件
• 如开启 MYSQL_AUTO_LOAD=1，则加载 MySQL schema 与 seed 数据
• 启动项目内置的每日自动同步调度器
• 启动 Web 页面与 API 服务

首次启动默认值仍来自环境变量；之后可在 Web UI 中修改自动装载开关，运行期配置会持久化到 /data/state/mysql_settings.json。

MySQL 默认连接

• Host: 127.0.0.1
• Port: 3306
• Database: mobilemodels
• Reader User: mobilemodels_reader

如需自定义账号密码，请使用 .env 覆盖默认值。

常用变量：

• MYSQL_HOST
• MYSQL_PORT
• TZ
• MYSQL_ROOT_USER
• MYSQL_ROOT_PASSWORD
• MYSQL_DATABASE
• MYSQL_READER_USER
• MYSQL_READER_PASSWORD
• MYSQL_AUTO_LOAD
• SYNC_SCHEDULE_ENABLED
• SYNC_SCHEDULE_TIME
• GITHUB_PROXY_PREFIX

MySQL 模式

• 主配置 docker-compose.yml
  • 面向远程 MySQL
  • 默认不自动装载 schema/seed
• 测试配置 docker-compose.test.yml
  • 额外启动一个本地测试 MySQL
  • 应用容器会自动把数据加载进去

设备查询

页面顶部统一提供三个导航入口：

• 设备查询
• 数据管理
• 相关文档

设备查询页顶部包含两个页内 tab：

• SQL 查询
• 索引查询

SQL 查询

• 直接调用 Compose 内 API 查询 MySQL 主表 mobilemodels.mm_device_catalog
• 服务端先将输入归一化为 alias_norm
• 页面展示实际执行的 SQL、返回结果和 JSON
• 页面同时展示只读连接参数，便于核对配置

索引查询

• 基于 dist/device_index.json 内存索引进行快速识别
• 适合前端联调、接口对比和结果核验

平台输入建议

• Android / iOS / HarmonyOS：直接使用客户端原始上报的 model_raw
• 输入框会根据所选平台自动提供示例值
• 未输入时，系统会使用当前平台的默认示例值发起查询

数据管理

数据管理页支持：

• 品牌列表管理
• 品牌与厂商关系管理
• 品牌同义词管理
• 数据来源优先级管理
• 外部 MySQL 手动初始化
• 原始数据同步
• 每日自动同步时间点设置
• 索引数据查看与重新加载

外部 MySQL 手动初始化

• 页面入口：数据管理 -> 原始数据同步 -> 初始化外部 MySQL
• 适用于 MYSQL_AUTO_LOAD=0 的远程 MySQL
• 点击后会执行 schema 与 seed 导入，自动创建数据库，并重建 mobilemodels 相关表与视图
• 执行前请确认 MYSQL_HOST、MYSQL_PORT、MYSQL_ROOT_USER、MYSQL_ROOT_PASSWORD 指向正确且具备建库建表权限

MySQL 自动装载开关

• 页面入口：数据管理 -> 原始数据同步 -> MySQL 自动装载
• 保存后会更新运行期配置 /data/state/mysql_settings.json
• 会影响后续“开始同步原始数据”是否自动刷新 MySQL
• 也会影响容器后续启动时是否自动执行 schema 与 seed 导入

每日自动同步

• 调度器运行在项目容器内部，不依赖 GitHub Actions
• 页面入口：数据管理 -> 原始数据同步
• 可设置是否启用，以及每天执行的时间点
• 可选配置 GitHub 加速前缀，例如 https://ghfast.top/
• 运行期配置持久化在 /data/state/sync_schedule.json
• 时间按容器时区执行，默认值来自 TZ，默认 Asia/Shanghai

说明

• 原始数据、索引和 MySQL seed 运行时持久化在 Docker volume 中，不回写本地工作区
• 交付环境建议覆盖默认的 MYSQL_ROOT_PASSWORD 和 MYSQL_READER_PASSWORD