crawler-plugin/docs/specs/10-static-deployment-nginx.md

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

目录契约

/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\ndist/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 行为。