# 10 静态资源部署与 Nginx History 托管

## 模块职责

定义后台 Vue 构建产物、Nginx 静态目录、History fallback、Java API 代理和 `/admin` 入口重定向的发布契约。

## 依赖关系

上游：`admin-frontend-vue/vite.config.ts` 的 `base=/admin-vue/`、`dist` 输出；Java API。

下游：浏览器访问后台、Vue Router 刷新、客户端 `/api/version/latest` 请求。

参考文件：

- `admin-frontend-vue/vite.config.ts`
- `admin-frontend-vue/deploy/nginx-admin-vue.conf.example`
- Java `AdminConsoleController.root/adminPage`

## 核心接口：原实现 → 目标实现

| 原实现 | 目标实现 |
|---|---|
| Java 重定向 `/admin.html` | Java 重定向 `/admin-vue/` |
| Java classpath `admin.html` | Nginx 独立静态目录 `/var/www/admin-vue/` |
| `admin.html` 内嵌 CSS/模板 | `dist/index.html` + hashed assets |
| Flask `serve_static` | Nginx 静态资源 location |
| 旧页面 hash 面板 | History route + fallback |

## 目录契约

```text
/var/www/admin-vue/
├── index.html
├── assets/
│   ├── index-<hash>.js
│   ├── index-<hash>.css
│   └── page-<hash>.js
└── assets/logo.jpg
```

浏览器路径：

- `/admin` → 302 `/admin-vue/`。
- `/admin-vue/` → `index.html`。
- `/admin-vue/account/users` → fallback `index.html`。
- `/admin-vue/assets/<file>` → 真实文件。
- `/api/*` → Java upstream。

## 内部结构

发布过程：

1. 在 `admin-frontend-vue` 执行依赖安装、类型检查和生产构建。
2. 对 `dist/index.html`、assets 清单和入口引用做一致性校验。
3. 上传到带版本号的临时发布目录。
4. 校验完整后原子切换 Nginx 当前目录。
5. 保留上一个版本目录用于快速回滚。

## 类型/路径映射

| 配置 | 目标值 |
|---|---|
| Vite `base` | `/admin-vue/` |
| Vite `outDir` | `dist` |
| Router history base | `/admin-vue/` |
| Nginx 静态前缀 | `/admin-vue/` |
| Java API upstream | `/api/` |
| 登录跳转 | `/login` |

## 类型映射\n\n`dist/index.html` 映射为 `/admin-vue/` 入口；`dist/assets/*` 映射为 `/admin-vue/assets/*`；Vue Router 相对 route 映射为 `/admin-vue/<route>`；`/api/*` 不进入静态资源目录。\n\n## 迁移/实现注意事项

1. Nginx 对 `/admin-vue/assets/` 必须优先匹配真实文件，不能被 fallback 到 HTML。
2. 不存在的 JS/CSS/图片必须返回 404，避免浏览器收到 HTML 后产生难以诊断的 MIME 错误。
3. `try_files` 的 fallback 只针对 `/admin-vue/` 页面路径。
4. hashed assets 可配置长期缓存；`index.html` 必须 no-cache 或短缓存。
5. 发布不能把 `dist` 复制到客户端 `frontend-vue/new_web_source`。
6. 静态资源不打进 Java JAR；Java 只承担 API 和入口重定向。
7. 生产切换前必须验证 Nginx upstream 的 Cookie、Host、X-Forwarded-* 和 HTTPS 行为。