# MIPS

**Repository Path**: aeizzz/mips

## Basic Information

- **Project Name**: MIPS
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-04
- **Last Updated**: 2026-10-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MIPS 多媒体信息发布系统

服务端已实现设备管理、内容类型/分类/区域管理、内容上传、节目编排与发布任务（立即/定时生效）。页面由 Thymeleaf 渲染，运行概览、设备、分组、账号、操作记录均在独立菜单。Android 客户端可按区域领取并轮播网页、图片、视频及已上传的 PPT；按节目快照播放的对接进行中。另有网页播放终端（`/player`）供 Linux/树莓派通过 HDMI 输出全屏画面，见 [linux-client](linux-client/README.md)。对应进度见[开发任务与进度](docs/开发任务与进度.md)。

## 目录

| 路径 | 内容 |
| --- | --- |
| `server/` | Java 21、Spring Boot、Maven 服务端；内置管理网页 |
| `android/` | Android TV 与 Android 手机共用的原生客户端工程；`adb-batch-install.sh` 为盒子批量安装脚本 |
| `linux-client/` | Linux/树莓派网页播放终端：cage + Chromium kiosk 安装脚本与部署文档 |
| `docs/` | 架构说明与任务进度 |
| `多媒体信息发布系统-需求文档.md` | 需求讨论稿 |

## 启动服务端

需要 Java 21 和 Maven 3.9+。直接启动后，在服务器本机打开 `http://127.0.0.1:8080/`，页面会引导创建管理员账号和终端激活码：

```bash
cd server
mvn spring-boot:run
```

Windows PowerShell 在 `server` 目录执行 `mvn spring-boot:run`。初始化完成后，从局域网中的电脑打开 `http://服务器IP:8080/`，会先看到登录页面；登录成功后进入设备管理控制台。首次初始化仅允许服务器本机访问，避免局域网内其他人抢先创建管理员。也可以在首次启动前设置 `MIPS_ADMIN_USER`、`MIPS_ADMIN_PASSWORD`（至少 12 位）、`MIPS_ACTIVATION_CODE`（至少 8 位）自动初始化账号。

### Docker 部署

服务端提供 `server/Dockerfile` 与 `server/docker-compose.yml`，镜像内置 LibreOffice 与中文字体（PPT 转换依赖）和健康检查。在 `server/` 目录执行：

```bash
cd server
MIPS_ADMIN_USER=admin MIPS_ADMIN_PASSWORD='至少12位的密码' MIPS_ACTIVATION_CODE='至少8位的激活码' docker compose up -d --build
```

首次启动用 `MIPS_ADMIN_USER`、`MIPS_ADMIN_PASSWORD`、`MIPS_ACTIVATION_CODE` 自动初始化；网页上的首次初始化仅允许服务器本机访问，从局域网访问容器时不开放（也可以 `docker exec -it mips-server bash` 后在容器内用本机回环地址完成）。初始化完成后这几个变量可以移除，重启不会重置账号。

H2 数据库与素材统一保存在 `mips-data` 卷的 `/app/data`，升级或重建容器不丢数据；备份该卷即同时覆盖数据库和素材目录。使用 PostgreSQL 时在 `docker-compose.yml` 或 `.env` 中覆盖 `MIPS_DB_URL`、`MIPS_DB_USER`、`MIPS_DB_PASSWORD`。宿主机端口默认 8080，可 `MIPS_PORT=8081 docker compose up -d` 修改。健康检查：`docker compose ps`，或 `curl http://服务器IP:8080/actuator/health`。

### 数据库

**未配置数据库时使用本地 H2 文件**，默认保存在 `server/mips-data.mv.db`；可用 `MIPS_DB_PATH` 更改文件路径。使用 PostgreSQL 时，先创建空数据库，再设置以下环境变量：

```bash
export MIPS_DB_URL='jdbc:postgresql://127.0.0.1:5432/mips'
export MIPS_DB_USER='mips'
export MIPS_DB_PASSWORD='your-database-password'
mvn spring-boot:run
```

Windows PowerShell：

```powershell
cd server
$env:MIPS_DB_URL = 'jdbc:postgresql://127.0.0.1:5432/mips'
$env:MIPS_DB_USER = 'mips'
$env:MIPS_DB_PASSWORD = 'your-database-password'
mvn spring-boot:run
```

启动时会自动建表。H2 与 PostgreSQL 是两套独立数据；切换数据库不会自动迁移已有设备、账号和配置，请先做好备份并单独迁移。当前尚未提供自动迁移工具。

已有旧版 H2 管理账号的安装，在升级后的首次启动仍需提供原 `MIPS_ACTIVATION_CODE` 一次，以便把激活码校验值写入数据库；已连接终端的令牌不受影响。

管理页可以创建只读账号、停用/启用账号、审批终端、创建分组并修改终端名称、方向、音量预设和服务器地址；设备列表可按类型筛选并查看每台终端当前生效的节目，操作记录支持关键词搜索并记录登录事件。修改配置、分组或区域会触发终端刷新，也可在设备管理页手动点击“刷新应用”。设备管理页还提供“重启播放器”远程指令：终端在下次心跳（约 10 秒内）领取指令，重启播放器进程后回执结果，成功/失败及原因显示在设备列表的配置列。健康检查：`http://服务器IP:8080/actuator/health`。默认监听 `0.0.0.0:8080`，通过 `MIPS_BIND_ADDRESS` 和 `MIPS_PORT` 修改。后续重启不会因为环境变量变化而重置已有管理员密码或激活码。

### 备份与恢复

“运行概览 → 待机画面”可配置终端无内容时展示的文案与背景图。登录后在“运行概览 → 系统维护”点击“备份数据”，会生成并下载 `mips-backup-时间戳.zip`（含 `database.sql` 数据库快照和 `assets/` 素材目录）。外部 PostgreSQL 请用 `pg_dump` 备份，素材目录可直接归档。

恢复步骤：停止服务端并保留旧数据；将 zip 解压到临时目录；用 H2 工具执行 `RUNSCRIPT FROM 'database.sql'` 重建数据库（例如 `java -cp h2.jar org.h2.tools.Shell -url jdbc:h2:./mips-data` 后执行该命令）；把 `assets/` 拷回素材目录（默认 `server/data/assets/`）；启动服务端。Docker 部署先把 `mips-data` 卷挂载出来执行同样步骤。恢复演练建议在测试环境先行验证。

下载接口支持 HTTP Range 断点续传；下载并发默认上限 8 路（`MIPS_DOWNLOAD_MAX_CONCURRENT` 可调），超出请求排队 10 秒后返回 503，避免大量终端同时下载拖垮局域网。

### 内容管理

登录后通过左侧导航进入 `/manage/content`、`/manage/types`、`/manage/categories` 和 `/manage/regions`。先建立区域，再在 `/manage/devices` 把终端分配给区域。内容可选择类型、分类和目标区域；未选择区域代表所有区域。每条内容可设置展示时长与刷新时间：展示时长为 0 表示永久展示、不切换下一条，刷新时间为 0 表示不刷新、由应用自行刷新；两者都为 0 即内容常驻屏幕且不重载。图片、视频可上传文件或填写终端可访问的 URL；网页填写 URL。图片可选择显示策略：适应（完整显示）或裁切（铺满屏幕）。上传 PPT/PPTX 时，服务器使用 LibreOffice 转为 PDF 供终端逐页展示，需安装 `soffice` 或设置 `MIPS_PRESENTATION_CONVERTER` 为可执行文件路径。内容先保存为草稿，点击“发布”后才进入终端清单。上传文件默认放在 `server/data/assets/`，可用 `MIPS_STORAGE_PATH` 更改；备份需同时包含数据库和该目录。

已批准设备使用 `GET /api/device/v1/contents` 获取所属区域与全区域的已发布内容；文件通过返回的 `source` 路径、携带同一 Bearer 令牌下载。文件接口按设备审批和区域校验访问权限。Android 客户端每 10 秒同步配置和内容，下载文件并校验 SHA-256。当前按发布顺序循环播放，尚未提供拖拽排序和排期。展示时长为 0 的内容常驻屏幕、不切换下一条（视频循环播放，PPT 按每页 15 秒循环翻页）；刷新时间大于 0 时网页定时重载、URL 图片定时重新拉取，为 0 时不强制刷新，由应用自行刷新。

### 局域网发现（双向互联）

服务端与客户端通过 UDP 广播互相发现（协议 `MIPS-DISCOVERY/1`，默认端口 8088，`MIPS_DISCOVERY_PORT` 可改，`MIPS_DISCOVERY_ENABLED=false` 可关闭）：

- **客户端发现服务端**：服务端每 10 秒广播自身信标（`HERE`，含管理端口）；客户端也可广播 `WHERE` 探测，服务端单播 `HERE` 回复到来源地址。客户端用报文来源 IP 加管理端口即可得到服务器地址，无需手工填写。
- **服务端发现客户端**：客户端上线后周期广播 `HELLO`（含安装标识、名称、类型），服务端记录其 IP；“设备管理 → 发现的客户端”展示地址与注册状态，点“扫描局域网”会广播 `SCAN`，在线客户端立即回报。

报文均为 UTF-8 JSON，例如 `{"proto":"MIPS-DISCOVERY/1","kind":"HERE","role":"server","name":"MIPS","webPort":8080}`；`HELLO` 携带 `installationId`、`name`、`type`、`appVersion`。发现信息只用于寻址，登录与终端令牌鉴权照常。广播仅在同一二层局域网内有效；Docker 部署需 `network_mode: host`（Linux）或至少映射 UDP 8088。

## 启动 Android 客户端

使用 Android Studio 打开 `android/`，安装 Android SDK 36 后构建 `app`，或在该目录执行 `./gradlew assembleDebug`（Windows 用 `gradlew.bat assembleDebug`）。同一应用可安装在 Android TV 和 Android 手机上；设备类型由系统运行模式识别。

首次启动输入服务器地址、激活码和设备名称。地址可填写 `192.168.1.10:8080` 或完整的 `http(s)://` 地址，客户端会规范化后显示和保存。手机通过同一局域网 Wi-Fi 访问服务器。批准且收到发布内容后，客户端切换为全屏展示；右上角“设置”可进入独立配置页，查看连接状态、服务器地址和设备信息，或返回展示。暂无内容时直接显示配置页，并在收到发布内容后自动进入全屏展示。配置页可修改服务器地址（切换前验证新地址）和设备名称（同步到服务端）。设备 ID 和设备类型只读。

Android TV 在首次注册和修改服务器地址时提供“用手机扫码填写”。电视连接局域网 Wi-Fi 或网线后显示二维码；同一局域网的手机扫码打开电视上的临时填写页，提交地址后自动回填电视输入框。二维码有效期 5 分钟、仅可提交一次；电视仍需确认注册或保存，原有连接验证照常执行。此页面由电视临时提供，无需服务端支持。

TV 播放页没有遮挡内容的设置按钮。遥控器菜单键直接进入设置；在播放页按返回键可选择进入设置、继续播放或退出应用。设置页的按钮和输入框在获得遥控器焦点时显示醒目的描边与高亮，按返回键回到播放页。手机端仍通过播放页右上角的设置按钮进入。

注册后终端处于“待审批”状态；管理员在后台批准后，客户端可领取配置和内容。客户端在前台每 10 秒发送一次心跳，并在配置版本变化时获取设置、刷新播放画面、尝试连接新服务器地址、回执成功或失败。有生效的发布任务时，客户端按节目快照顺序轮播（每项独立展示时长与刷新时间），预下载素材后回执 DOWNLOADED、开始播放后回执 ACTIVE、失败时回执原因；没有任务时回退到按区域发布的内容清单。心跳还会携带远程指令（如“重启播放器”），客户端执行后回执结果。音量值目前仅保存为播放预设，尚未改变系统媒体音量。上传 PPT 由服务端转 PDF 后逐页播放；直接填写外部 PPT 文件 URL 时无法保证 Android 可以渲染，请优先上传。

仅 Debug 构建允许局域网 HTTP 以便开发联调；Release 构建禁用明文连接。正式部署需要 HTTPS、证书分发和凭据保护。不要将开发示例的账号或激活码用于正式环境。

### 电视盒子 / Android TV 播放与差异

电视盒子（机顶盒）与 Android TV 一体机对本系统是同一类终端：无触摸屏、HDMI 输出到电视、遥控器操作，安装同一个 APK、注册为 TV 类型、走同一套服务端接口。内容呈现方式：图片全屏等比轮播；视频由系统硬解播放 MP4（建议 H.264 + AAC、1080p 以内）；网页由系统 WebView 全屏显示；PPT 由服务端转 PDF 后逐页翻页，盒子上不需要安装 Office。播放页全屏沉浸、屏幕常亮，断网即停、恢复自动续播。

两类设备的差异主要在系统与兼容性：认证 Android TV 系统统一、WebView 更新及时；杂牌盒子的系统 WebView 可能较旧（网页类内容需真机验证），视频解码能力取决于盒子芯片。少数盒子不上报 TV 运行模式，会被识别为手机类型注册（字号偏小、播放页出现设置按钮），选购测试时注意这一点。部分盒子的 ADB 端口不是 5555，批量安装时写成 `IP:端口`。

### 开机自启与默认桌面

客户端内置开机自启：设备重启或应用更新后自动进入全屏播放（仅对已注册设备生效，未注册设备不会被拉起）。Android 10 以上部分设备限制后台拉起界面，配合默认桌面更可靠：

1. 在设置页点击“设为默认桌面（Home 键回到播放）”；
2. 在系统弹出的桌面选择中选中本应用并选“始终”；未弹出时，在盒子设置里把默认桌面（主屏幕应用）改为本应用。

设置后遥控器按 Home 键即回到播放画面，开机由系统自动进入播放。默认桌面模式下遥控器“退出应用”会立即回到播放（无人值守的 kiosk 行为）。认证版 Google TV 电视更换默认桌面受限（常需 ADB），此时主要依赖开机自启；盒子普遍可以直接换桌面。

### adb 批量安装

`android/adb-batch-install.sh` 通过网络 adb 批量连接盒子并安装 APK，自动识别并处理安装时屏幕上的安全确认弹窗：

```bash
# 直接给 IP（默认端口 5555）
./android/adb-batch-install.sh 192.168.1.21 192.168.1.22

# 或从文件读设备列表（每行一个 IP[:端口]，# 开头为注释）
./android/adb-batch-install.sh -f devices.txt
```

默认安装 `android/apk/app-debug.apk`；`-a` 指定其他 APK，`-t` 调单台安装超时（默认 120 秒），`-w` 调等待调试授权的时间（默认 60 秒），`-u` 安装前先卸载旧版（签名不一致时用，会丢失设备注册信息，需重新注册）。脚本逐台执行，结尾输出结果汇总表，任一台失败退出码为 1。Windows 可在 Git Bash / WSL 中运行。

安全确认的处理：安装过程中脚本每 2 秒检查屏幕焦点窗口，检测到安装/安全确认弹窗时，先用 `uiautomator` 按按钮文字（“继续安装”“安装”“允许”“确定”等）自动点击确认；界面树不可用时回退发送遥控器确认键（先右移一格再确认，避免焦点停在“取消”上被误取消）。自动确认最多尝试 5 次，仍卡住则报告卡在哪个弹窗，提示到盒子前人工确认。

常见问题：首次连接时盒子屏幕会弹“允许 USB 调试吗？”，需人工点一次允许（勾选“一律允许”），脚本会等待授权；小米盒子需登录账号并在 设置→账号与安全 中开启“USB 安装”，否则报 `INSTALL_FAILED_USER_RESTRICTED`；`INSTALL_FAILED_UPDATE_INCOMPATIBLE` 表示签名变化，用 `-u` 重装；版本降级自动改用 `-d` 重试。盒子需先在开发者选项中开启“网络 ADB / USB 调试”，并与本机同一局域网。

## Linux / 树莓派网页播放终端

无桌面 Linux 或树莓派通过 HDMI 输出画面时，使用服务端托管的网页播放终端（`/player`）：终端只运行 cage + Chromium 全屏打开该页面，注册为 `LINUX` 类型设备，走与 Android 客户端相同的设备协议（10 秒心跳、节目快照轮播、素材 SHA-256 校验与缓存、DOWNLOADED/ACTIVE/FAILED 回执、离网即停、RESTART_PLAYER/CLEAR_CACHE 远程指令）。播放页渲染网页、图片、视频，PPT 由服务端转 PDF 后经 pdf.js 逐页展示（每页 15 秒循环翻页）。适合网页为主、视频较少的内容。

一键安装与细节见 [linux-client/README.md](linux-client/README.md)：

```bash
cd linux-client
sudo ./install.sh 192.168.1.10:8080 123456 一楼大厅屏幕
sudo reboot
```

安装脚本配置 tty1 自动登录与 `consoleblank=0`，开机即全屏播放；带激活码安装时生成 `#setup` 注册链接，首次开机免键盘自动注册。注册后在管理端「设备列表」批准即可发布节目。

## 验证

在 `server/` 执行 `mvn test`。测试覆盖首页、初始化、登录、设备注册与配置、内容上传、类型/分类/区域、区域过滤发布清单及文件授权下载、网页播放终端页面与 Linux 终端注册。

版本选择参考：[Spring Boot 3.5 系统要求](https://docs.spring.io/spring-boot/3.5/system-requirements.html)、[Android Gradle Plugin 与 Gradle 兼容表](https://developer.android.com/build/releases/about-agp)。