80 lines
2.8 KiB
Markdown
80 lines
2.8 KiB
Markdown
# 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 行为。
|
||
|