# 360view

**Repository Path**: hzhlu/360view

## Basic Information

- **Project Name**: 360view
- **Description**: 全景图片浏览器
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-22
- **Last Updated**: 2026-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 360View —— 360 全景图片与录像浏览平台

一个开箱即用的 360 全景浏览系统：**Spring Boot（JDK 25）后端 + Vue 3 前端 + three.js 全景渲染内核**。
登录后进入主页面：**顶部菜单栏 + 底部状态栏 + 中间 360 全景展示区**，支持全景图片与全景录像。

![tech](https://img.shields.io/badge/JDK-25-blue) ![spring](https://img.shields.io/badge/Spring%20Boot-4.1.1-green) ![vue](https://img.shields.io/badge/Vue-3.x-brightgreen)

---

## 1. 功能概览

| 模块 | 说明 |
| --- | --- |
| 登录认证 | 缺省账号 `admin / 123456`；服务端签发随机令牌（内存会话，默认 120 分钟），同时以 `HttpOnly Cookie` 下发，媒体标签可直接访问受保护资源 |
| 顶部菜单栏 | 全景浏览 / 媒体库（素材抽屉）/ 帮助，右侧为「重置视角 / 自动巡航 / 全屏」与当前用户、退出登录 |
| 中间展示区 | three.js 等距柱状全景渲染：拖拽环视（带惯性）、滚轮与双指缩放（视场 20°–100°）、双击复位、自动巡航、全屏 |
| 媒体支持 | 全景图片（jpg/png/webp/avif 等）与全景录像（mp4/webm 等，支持 HTTP Range 拖动进度、播放/暂停/静音/进度条） |
| 媒体库抽屉 | 服务端自动扫描素材目录，支持类型筛选、文件名过滤、缩略图、一键刷新；显示素材根目录并可复制 |
| 本地拖拽预览 | 把本地图片/录像直接拖进画面即时预览（`blob:` 本地渲染，不上传服务端） |
| 底部状态栏 | 渲染状态、服务在线状态、当前用户与会话剩余时间、当前素材（名称/类型/分辨率/大小）、播放进度、方位角/俯仰角/视场、FPS、素材统计、时钟 |
| 健康检查 | Spring Boot Actuator（`/actuator/health`、`/actuator/info`） |

### 快捷键

`F` 全屏 · `R` 重置视角 · `空格` 播放/暂停 · `M` 静音切换 · `D` 媒体库开关 · `Esc` 关闭弹窗/媒体库

---

## 2. 技术栈

| 层 | 技术 |
| --- | --- |
| 后端 | JDK 25（Azul Zulu 25.0.3）、Spring Boot 4.1.1（spring-boot-starter-webmvc / validation / actuator）、Maven 3.9.x |
| 前端 | Vue 3（`<script setup>`）、Vite、Vue Router（history 模式）、axios、three.js |
| 通信 | REST + 统一响应体 `{code, message, data}`（`code = 0` 表示成功）；令牌支持 `Authorization: Bearer`、Cookie、`?token=` 三种携带方式 |
| 部署 | 前端构建产物并入 `classpath:/static/`，单个 JAR 即为完整应用 |

---

## 3. 目录结构

```
360View/
├── pom.xml                          # Spring Boot 4.1.1 / java 25
├── data/media/                      # 媒体根目录（可配置）
│   ├── images/                      # 全景图片（等距柱状 2:1）
│   │   └── demo-panorama.png        # 演示全景图（脚本生成）
│   └── videos/                      # 全景录像（mp4/webm）
├── scripts/
│   ├── build-all.cmd|.sh|.ps1       # 一键构建：前端 + 拷贝 + 打包 JAR；.ps1 为 Win11 PowerShell 版
│   ├── start.cmd|.ps1               # 使用 JDK 25 启动 JAR；.ps1 为 Win11 PowerShell 版
│   ├── dev-frontend.cmd             # 前端开发模式（Vite 5173）
│   └── generate-demo-panorama.py    # 程序化生成演示全景图（零依赖）
├── frontend/                        # Vue 3 单页应用
│   ├── vite.config.js               # 开发代理 /api、/media → 8080
│   └── src/
│       ├── api/                     # axios 封装（令牌注入、401 自动登出）
│       ├── stores/                  # auth / media / viewer / server / toast
│       ├── router/                  # 登录守卫 + 会话校验
│       ├── views/                   # LoginView（登录页）、HomeView（主页面）
│       └── components/
│           ├── TopMenuBar.vue       # 顶部菜单栏
│           ├── StatusBar.vue        # 底部状态栏
│           ├── MediaDrawer.vue      # 媒体库抽屉
│           ├── PanoramaViewer.vue   # three.js 360 查看器（核心）
│           ├── ViewerControls.vue   # 画面底部悬浮控制条
│           ├── HelpDialog.vue       # 帮助弹窗
│           └── ToastStack.vue       # 全局提示
└── src/main/java/com/macrolab/view360/
    ├── View360Application.java
    ├── config/  View360Properties / WebMvcConfig
    ├── auth/    AuthService / AuthInterceptor / AuthController / TokenResolver
    ├── media/   MediaService / MediaController
    ├── web/     SystemController / SpaFallbackResolver
    └── common/  ApiResult / ApiException / GlobalExceptionHandler
```

---

## 4. 快速开始

### 环境要求

- JDK 25（本机已装：`C:\Users\Administrator\.jdks\azul-25.0.3`）
- Maven 3.8+（本机已装：`C:\tools\apache-maven-3.9.5`）
- Node.js 18+（前端构建用，本机已装 v22）

### 方式一：一键构建 + 运行（生产形态，推荐）

**Windows（cmd）**

```bat
scripts\build-all.cmd     rem 前端构建 → 拷贝到 static → mvn package
scripts\start.cmd         rem java -jar target\view360.jar
```

**Windows 11（PowerShell）**

```powershell
.\scripts\build-all.ps1   # 前端构建 → 拷贝到 static → mvn package
.\scripts\start.ps1       # java -jar target\view360.jar（http://localhost:8080）
```

> 两个 `.ps1` 脚本会**固定使用 JDK 25**（`C:\Users\Administrator\.jdks\azul-25.0.3`）启动 Maven/Java，
> 与调用会话的 `JAVA_HOME` 无关；前端默认走 `yarn build`，若 Yarn 偶发无法拉起 Vite，会自动重试一次
> 并回退到 `node node_modules/vite/bin/vite.js build`，保证构建可重复。

浏览器访问 <http://localhost:8080>，使用 `admin / 123456` 登录。

### 方式二：前后端分离开发（前端使用 Yarn）

前端统一使用 **Yarn** 进行依赖安装与服务启动（项目已生成 `frontend/yarn.lock`）。

**1) 安装前端依赖**

```bat
cd frontend
# 安装依赖
yarn --registry=https://registry.npmmirror.com
yarn install
```

**2) 启动前端开发服务器**（默认 5173，已配置 `/api`、`/media` 代理到后端 8080）

```bat
yarn dev
```

**3) 另开一个终端启动后端**（默认 8080）

```bat
set JAVA_HOME=C:\Users\Administrator\.jdks\azul-25.0.3
mvn spring-boot:run
```

> 若只需本地编译生产产物（生成 `frontend/dist`），执行 `yarn build`；一键生产构建见「方式一」。

访问 <http://127.0.0.1:5173>。

### 素材接入

把素材放入 `data/media/`（目录可在 `application.yml` 的 `view360.media-root` 修改）：

- `data/media/images/` —— 等距柱状（2:1）全景图片，如 `4096x2048.jpg`
- `data/media/videos/` —— 全景录像 mp4/webm（建议 H.264 + `yuv420p` + `faststart`）

放入后在页面「媒体库 → 刷新」即可看到。项目已内置脚本生成的演示全景图
`data/media/images/demo-panorama.png`，可直接体验；重新生成：

```bash
python scripts/generate-demo-panorama.py [输出路径] [宽度]
```

---

## 5. 接口清单

统一前缀 `/api`，除登录与系统信息外均需携带令牌（`Authorization: Bearer <token>` 或 Cookie）。

| 方法 | 路径 | 说明 | 参数 |
| --- | --- | --- | --- |
| POST | `/api/auth/login` | 登录 | `{"username":"admin","password":"123456"}` |
| POST | `/api/auth/logout` | 注销并清除 Cookie | — |
| GET | `/api/auth/me` | 当前用户与会话剩余时间 | — |
| GET | `/api/media/list` | 素材清单 | `type=IMAGE/VIDEO/ALL`、`keyword=`（均可选） |
| GET | `/api/system/info` | 服务端信息（公开，登录页状态展示） | — |
| GET | `/media/**` | 媒体文件（受令牌保护，支持 Range） | — |
| GET | `/actuator/health` | 健康检查 | — |

登录响应示例：

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "token": "…",
    "tokenType": "Bearer",
    "expiresIn": 7200,
    "user": { "username": "admin", "displayName": "系统管理员", "roles": ["ADMIN"], "expiresAt": "2026-09-22T19:00:00Z", "remainingMillis": 7200000 }
  }
}
```

---

## 6. 配置项（`application.yml`）

```yaml
server:
  port: 8080                     # 服务端口

view360:
  media-root: ./data/media       # 媒体根目录（相对或绝对路径）
  spa-index: index.html          # 单页应用回退页
  security:
    token-ttl-minutes: 120       # 会话有效期（分钟）
    allowed-origins:             # 跨域来源（前端开发态）
      - http://localhost:5173
    users:                       # 账号列表，可增删
      - username: admin
        password: "123456"
        display-name: 系统管理员
        roles: [ADMIN]
```

---

## 7. 实现说明与注意事项

1. **鉴权模型**：演示级内存会话（`ConcurrentHashMap` + `SecureRandom` 令牌），重启即失效；
   密码比对使用 `MessageDigest.isEqual` 定长比较。生产环境建议接入数据库/Redis/LDAP，
   并对 `application.yml` 中的明文密码改为加密存储。
2. **媒体保护**：`/media/**` 与 `/api/**` 共用同一拦截器；`<video>`/`<img>` 标签靠
   `HttpOnly Cookie` 自动携带令牌，因此跨站部署时需保证同源或调整 Cookie 策略。
3. **SPA 回退**：`SpaFallbackResolver` 在静态资源未命中时返回 `index.html`（`/api`、`/media`、
   `/actuator` 除外），前端 Vue Router 可直接使用 history 模式深链。
4. **大图保护**：查看器会检测 GPU 最大纹理尺寸，超过上限的全景图自动等比降采样，避免黑屏。
5. **录像编码**：浏览器需可解码（H.264/VP9 + `yuv420p`）；服务端 `ResourceHttpRequestHandler`
   原生支持 HTTP Range，拖动进度条无需额外代码。
6. **端口被随机覆盖**：Spring Boot 的宽松绑定会把环境变量 `SERVER__PORT`（双下划线）识别为
   `server.port`。本工作台环境恰好注入了该变量，因此 `scripts/start.cmd|.sh` 已显式追加
   `--server.port=8080`；手动启动时如遇端口漂移，同样加该参数即可。

## 8. 验证记录

- 后端：`mvn clean test` → **Tests run: 10, Failures: 0, Errors: 0**（认证 6 + 媒体扫描 3 + 上下文装配 1）
- 一体化构建：`mvn clean package -Pfrontend` → **BUILD SUCCESS**，JAR 内含前端产物（该 profile 内部使用 Yarn 安装并构建前端）
- 接口实测：登录成功 / 密码错误 401 / 未授权 401 / 素材清单 / Cookie 访问媒体 200 /
  Range 请求 206 / 注销后 401，全部符合预期
- 前端：`yarn install` + `yarn build` 通过，产物已并入 `src/main/resources/static/`
- Windows 11 PowerShell 脚本：`scripts\build-all.ps1` → **BUILD SUCCESS**（yarn 偶发拉起 Vite 失败已自动回退 `node vite.js build`）、`scripts\start.ps1` → 应用启动、`/actuator/health`=200、`/`=200、受保护 API 返回 401，符合预期
- UI 冒烟（`scripts/ui-smoke.mjs`，真实 Edge 浏览器）：`/`→`/login` 跳转、admin/123456 登录、
  全景渲染、拖拽环视（方位 0°→103°）、滚轮缩放（75°→69°）、状态栏实时数据，**0 控制台错误**