95 lines
11 KiB
Markdown
95 lines
11 KiB
Markdown
# 五端文件签名验证记录
|
||
|
||
验证日期：2026-10-29。范围为本地五个项目的实现、定向回归、构建和已登录后台页面检查。未发布服务、修改 Nacos、开启生产拦截、更新真实设备、执行数据库迁移或提交 Git。
|
||
|
||
## 已完成
|
||
|
||
| 验证 | 结果 |
|
||
| --- | --- |
|
||
| Java 请求级与业务回归 | 41 项通过，0 失败；覆盖 UPMS 文件校验/读取、版本地址、钱包和硬件导出，同时编译相关公共模块及 canteen |
|
||
| 后台自动测试 | 14 项通过，包含文件协议与已有部门导出测试 |
|
||
| H5 文件自动测试 | 14 项通过 |
|
||
| 小程序文件自动测试 | 14 项通过 |
|
||
| 跨语言协议 | Java、三端 TypeScript、Dart 使用相同公开向量；校验 UTF-8 文件名、秒级时间戳、Base64URL 原文和 HMAC 结果 |
|
||
| URL 与运行时 | 覆盖中文、空格、加号、百分号编码、历史域名、相对/绝对地址、已有 `/api` 前缀、重复签名、第三方地址；前端测试执行实际运行时包装器，H5/小程序测试执行富文本预览组件的 JS 方法；Java 使用真实 SpringMvcContract/Feign 客户端与内存传输验证文件名字面 `%2F/%2B`、重复拦截和参数顺序 |
|
||
| 后台生产构建 | `pnpm build:prod` 通过 |
|
||
| H5 构建 | `pnpm build:h5` 通过 |
|
||
| 微信小程序构建 | `pnpm build:mp-weixin` 通过 |
|
||
| Flutter 定向回归 | 56 项通过；含签名、安装包一次重试、人脸同步计划/流水线/失败记录/缓存、主副屏余额回归 |
|
||
| Android Release | FVM Flutter 3.27.4 构建通过，使用 `.file-access/production.json`；APK 约 101.9 MB |
|
||
| 新增后台 TypeScript 工具 | 独立严格类型检查通过 |
|
||
| 配置生成器 | 在临时目录重复运行，确认幂等、保留已有文件；开发/测试/生产配置和各客户端密钥相互独立 |
|
||
| 密钥与原有变更 | 扫描五个项目全部已跟踪及未忽略候选文件，未发现生成密钥泄漏；后台原有补丁可反向校验，Java 原有补丁除追加忽略规则产生的上下文差异外可反向校验 |
|
||
| Diff 检查 | 保留原有 CRLF 文件格式；使用 `git -c core.whitespace=cr-at-eol diff --check` 通过 |
|
||
|
||
APK 位置（相对本仓库）：`../pj_supermarket_cloud/build/app/outputs/flutter-apk/app-release.apk`。本次构建尚未在真实终端安装验证；发布前须核对包内环境与服务端配置一致。
|
||
|
||
Java 定向测试及各端构建命令见 [接入与发布说明](README.md)。本机详细日志保存在 `/tmp/pj-file-access-work/`，属于临时验证资料，不随仓库发布。
|
||
|
||
## 静态检查与既有问题
|
||
|
||
使用任务开始前保存的补丁还原临时代码基线，与当前代码运行同一检查后比较：
|
||
|
||
| 项目 | 当前结果与基线比较 |
|
||
| --- | --- |
|
||
| 后台 `vue-tsc` | 6 条既有解析错误，均在 `src/views/admin/system/tenant/index.vue:83`；与基线完全一致 |
|
||
| H5 `vue-tsc` | 4 条既有解析错误，在 `src/pages/tabbar/~individualOrder.vue:78-79`；与基线完全一致 |
|
||
| 小程序 `vue-tsc` | 17 条既有 TS6504（JS Vue 来源与 allowJs 配置）；规范化临时目录路径后与基线完全一致 |
|
||
| Flutter `analyze --no-pub` | 69 条提示/警告；忽略因新增代码产生的行号偏移后，诊断集合与基线完全一致，无新增项 |
|
||
|
||
因此不能把本次结果表述为“全项目类型检查通过”。H5/小程序构建仍有 TM UI 类型导出和循环依赖等构建提示；构建已成功，未在本次跨端文件改造中整理无关依赖。
|
||
|
||
## 已登录后台检查
|
||
|
||
使用用户提供的 `http://localhost:8888/` 已登录会话，检查文件管理页：
|
||
|
||
- 本系统有效图片的缩略图与放大预览加载成功，资源请求带 `appId/kid/ts/sign`，`fileName` 位于最后。
|
||
- 实测发现并修复前端 `/api` 前缀被重复保留的问题：当前开发图片服务器不带 `/api`，相对旧路径应转换为 `/admin/sys-file/oss/file`。配置含 `/api` 的部署仍保留一次前缀。
|
||
- 旧头像的一条原始文件链接返回 HTTP 200、内容长度为 0，属于当前运行后端/存储的既有异常。新 Java 读取代码已覆盖不存在和存储异常状态，但尚未发布，不能声称现场问题已修复。
|
||
- 当前后端匿名 `/admin/sys-file/oss/access-info` 返回 424 鉴权错误，说明运行环境尚未具备本次匿名校时接口；签名客户端会保留本地时间/最近偏移，不降级匿名读取。
|
||
- 点击素材下载后未出现页面错误，但浏览器下载事件未在等待窗口内返回。浏览器工具自动安全检查拒绝打开 `chrome://downloads/`（仅允许 HTTP/HTTPS），未采用其他方式绕过此限制，**下载文件实际落盘未确认**。
|
||
|
||
当前运行后端仍接受裸文件链接。上述浏览器结果证明前端签名与展示链路可用，不代表新后端严格校验已在线生效。
|
||
|
||
## 发布前仍需完成
|
||
|
||
1. 核对每个环境的公网基础地址、历史域名、密钥和活动 kid；Java 不会自动加载 `.file-access/*.yml`，须通过 Nacos 或 `SPRING_CONFIG_ADDITIONAL_LOCATION` 加载。先以 `observe` 发布 UPMS、integrated 和所有实际调用文件服务的模块。
|
||
2. 用发布后的后端确认匿名校时可达，执行 GET/HEAD、错误参数、错误/过期签名、旧 Dart 兼容、404/500、私有缓存及服务间读取联调。
|
||
3. 在真实旧 Flutter 安装包上确认图片请求 UA、图片显示及 Android 原生 APK 下载。新版包确认主副屏、缓存命中、人脸重复同步/离线恢复、取证、打印、手动/自动更新；不能用本地源码或单元测试替代设备验收。
|
||
4. 微信真机验证登录前 Logo/背景、长时间停留和恢复前台、图片预览、文件下载及打开文档；核对微信文件域名配置。后台与 H5 补充对应实际业务操作验收。
|
||
5. 至少观察一个完整业务日，确认已知入口无遗漏后再切 `enforce`；根据设备版本台账确认升级覆盖后再关闭旧 Dart 图片兼容。
|
||
|
||
当前默认保持 `observe` 与旧 Dart 图片兼容开启。回滚方法是恢复 `observe` 并保留诊断日志；业务引用和人脸记录未持久化临时签名，无需数据库回滚。
|
||
|
||
## 后台图片闪烁修复补充
|
||
|
||
2026-10-29 修复后台单张图片失败重试清空全局签名缓存的问题。重试只刷新当前文件，同一文件的并发重试合并；普通校时保留仍有效的签名。新增公共 `FileImage`，已加载图片在分钟检查、签名续期和恢复前台时保持当前画面；未加载的懒图片继续更新有效地址，放大预览在打开或切换图片时取有效签名。业务引用改变时正常加载新图。
|
||
|
||
- 后台定向回归 19 项通过，包含真实组件 setup、模板与 Vue 生命周期测试；模拟停留超过 30 分钟、恢复前台、失败重试、预览和懒加载。
|
||
- 新组件与文件工具的定向 `vue-tsc` 检查通过；后台生产构建通过。
|
||
- 已登录商户页实测：原先已加载的 24 张图片跨分钟检查后地址不变，其余慢图片随后加载完成，共 30 张图片成功、无加载占位；放大预览成功且请求带签名。
|
||
|
||
## 浏览器直接打开文件地址限制补充
|
||
|
||
2026-10-29 新增默认开启的 `block-browser-navigation`。严格模式下，携带浏览器页面导航 Fetch Metadata 的文件请求，即使签名有效也返回 403；页面图片、音视频、fetch/XHR 下载和无浏览器 Metadata 的原生/服务请求继续按原签名规则处理。成功响应 `Vary` 区分导航与子资源请求；拒绝响应 `no-store`。观察模式仅记录 `browser_navigation`。
|
||
|
||
- Java 文件访问/读取请求级测试共 12 项通过，覆盖签名正确的导航、GET/HEAD 在读取存储前拒绝、图片与下载放行、原生包下载、Dart UA 不绕过导航限制、开关和观察模式。
|
||
- 后台 20 项、H5 16 项、小程序 16 项定向测试通过。覆盖文件链接的页面内下载、H5 富文本与普通链接拦截、图片预览、本地文档打开及第三方链接保持原行为。
|
||
- 后台生产、H5、微信小程序构建通过；后台文件组件/工具定向类型检查通过。
|
||
- 配置生成器在临时目录验证：新配置含 `block-browser-navigation: true`，默认仍为 `observe`，没有修改实际运行环境配置。
|
||
|
||
这项补充尚未部署到文件服务器，不能把本地请求级测试表述为该公网地址已返回 403。上线时代理须保留 `Sec-Fetch-Mode/Dest` 和响应 `Vary`；用新签名或无旧缓存的窗口验证。后端无法收回浏览器已经取得的文件内容。旧浏览器可能不提供 Fetch Metadata，脚本也能模拟请求，因此这项规则不等于逐用户授权或防止已显示图片被保存。
|
||
|
||
## 最终调整：统一一套密钥与严格模式联调
|
||
|
||
用户明确要求所有环境使用同一套密钥，取代本文前面记录的开发/测试/生产独立密钥方案。沿用已配置的原生产密钥组，未生成新密钥；各 appId 仍使用各自固定密钥，service/package 密钥仍只存在服务端。三个前端统一使用 `.env.local`，Java 使用 `.file-access/config.yml`，Flutter 使用 `.file-access/config.json`。旧模式文件的签名字段已清理并备份，旧命令 `--environment` 不再切换密钥。
|
||
|
||
此前严格模式白图的真实原因是：浏览器按开发密钥签名，后端配置的是原生产密钥，实际响应为 `invalid_signature`。本次已通过本地 Nacos REST API 修正 `application-dev.yml`，保留 `enforce`、浏览器导航拦截和旧 Dart 兼容，公网基础地址对齐测试网关。Nacos 完整原配置保存在本机私有临时备份，发布时使用 MD5 比较避免覆盖并发编辑，生产服务配置未修改。
|
||
|
||
- 使用真实页面中的同一个签名 URL 联调：页面图片请求 200、应用下载请求 200、浏览器导航请求 403，原因为 `browser_navigation`。
|
||
- 实际后台重新加载后，首轮观察为 30 张图片中的 24 张加载成功，其余 6 张仍在慢请求中；随后浏览器自动化连接中断，未把该轮全部图片的最终状态作为已验证结果。签名已与统一密钥注册表一致。
|
||
- 真实 Vite `loadEnv` 验证三个项目共 18 个模式组合，全部使用统一密钥；生成器迁移、重复执行、原密钥保留与错误配置拒绝共 3 项测试通过。
|
||
- 后台生产、H5、微信小程序构建通过；Flutter 使用统一配置执行签名和安装包定向测试，8 项通过。
|
||
|
||
后续构建与配置准备以 README 中的统一路径为准。本文前面提到的分环境配置路径属于历史验证记录，不再作为当前操作指引。
|