Preserve known legacy failures by reviewed identity, probe material delivery before and after releases, and retain originals and downloads.
136 lines
16 KiB
Markdown
136 lines
16 KiB
Markdown
# 素材预览只读验收
|
||
|
||
正式发布入口 `scripts/git-incremental-deploy.ps1` 已接入只读预览门禁,Mac 入口抽取同一份模板。它不修复图片、不修改引用、不执行 Schema DDL、不调用模型,也不改原素材或下载文件。新增脚本提交并推送只证明代码已纳入发布;是否已在生产安装首份审核基线、实际执行哪个阶段,必须以对应私有回执为准,不能用离线测试代替生产验收。
|
||
|
||
## 实际发布门禁
|
||
|
||
每次真实发布均执行三阶段:`capture` 在旧容器停止前,`candidate` 在切流前,`post` 在代理目标验证通过后、写入当前版本记录前。direct replacement 的 candidate/post 失败调用现有 `fail_direct_replace_with_restore`;保留的蓝绿代码分别调用已有的切流前失败处理和切流后回滚处理。没有跳过开关。Mac 与 PowerShell 都从构建机**精确 Git checkout**生成门禁模块,并通过现有 SSH stdin 执行,不要求旧镜像内已有新脚本,不向应用目录复制代码。
|
||
|
||
`material-preview-release-gate.mjs` 复用现有清点器、直连网络防护和 Sharp 全像素解码。在只读 RepeatableRead 事务中枚举全部未删除 `Material.previewUrl`,包含缺地址或不支持检查的记录,不用 `HISTORY_IMPORT`。全元数据索引与 SHA 保留在每份回执;图片 GET 仅覆盖:
|
||
|
||
- **全部仍指向独立旧桶的活跃引用**,本轮预计 472 项,实时枚举,不硬编码数量掩盖新增或遗漏。
|
||
- 十二项关键材质,按固定素材 ID 核对,不允许减少或改成其它样本。
|
||
- 与上次已接受全元数据索引相比,新增或预览源地址改变的当前素材。
|
||
|
||
其余未变化的当前源与原有不受支持的预览明确登记为 `unverified`,不能记健康。新增或变化后变成不可检查的引用直接阻止发布。并发上传/删除造成候选或 post 库存 SHA 与 capture 不同,也停止并保留旧版本;不会通过重新抽样、忽略新记录或无限重试来抹平差异。
|
||
|
||
固定预算为每阶段最多 768 次单次 GET、4 并发、正文总量 128 MiB、总时长 360 秒;单项仍受 8 MiB、10 秒、2500 万像素限制,不重试、不跟随跳转。范围超过预算时停止,需另行安排独立全量验收,不能临时提高预算或清空基线。
|
||
|
||
候选与 post 使用 capture 的**同一份探测清单及 SHA**,逐项核对素材 ID、源地址 SHA、角色、结果数量、解码与正文 SHA;同时比较规范化索引和原始登记值的库存摘要。既有健康 URL 的内容在未改地址时变化、新失败、原失败类型或完整失败正文改变、漏项、检测器不可用均不通过。472 项既有 FRP 404 可以作为人工审核的事故基线保留,但每个阶段均实际重读并明确报告 `knownFailures`、`allSelectedHealthy=false`;它们不能成为正常图片,也不能自动容纳新失败。某项已恢复健康后若下一阶段再次失败,会阻止发布。
|
||
|
||
首次故障准入还绑定版本化 `scripts/fixtures/material-preview-known-legacy-20261023.json` 的 **472 对精确素材 ID + 规范化源地址 SHA**,并固定 489 字节、正文 SHA `967e369d3be4fab5eb1229ec015b2923abf6bc81ebe3aaa662cb095cbec81023` 的已核实 FRP 页。集合 SHA 固定为 `953e6b1c9e10ea05e30e289ebbd5364569d918b5dd4a1273af52abc531fe475c`,生成依据是独立只读逐项审计原文件 SHA `40eb8d834d5c6bd9edcdc49e69ae227a83be2374bb9b525a0cec0bcd652c4e0d`。proof 只有 ID/摘要,没有名称、URL 或凭据;构建时校验后内联,不能在首次 bootstrap 时根据现场新失败自动重建。第 473 项、删一项换入另一 ID、同 ID 变更源,均不能混入已知故障,即使返回完全相同的 FRP 页。
|
||
|
||
登记源与实际同桶 canonical 交付地址分别探测、分别保留结果。只复用现有“当前桶的旧兼容域名交付到当前公开入口”语义,不改变桶或 key;独立旧桶永远保持原址,不使用域名替换掩盖故障。新花色01的旧登记域名网络失败,只能在其固定素材 ID 的 canonical 图片完整解码为 768×1600、原正文 SHA `b40687cac0cbd537e209f8caa56c642bf501a658d0c3585140e8b9950937da53` 一致时单列;不能把前者改写为健康,也不能将其它当前源失败一概豁免。
|
||
|
||
URL 重写、代理、S3 或网络识别五个源码文件的精确指纹,与**上次接受基线、当前容器、目标 checkout**三方比较。即使现场已被绕过门禁改成 B、此次目标也为 B,旧基线 A 仍会触发扩大范围。非秘密配置 `S3_ENDPOINT`、`S3_BUCKET`、`S3_FILE_PATH`、`S3_PUBLIC_DOMAIN`、`S3_REGION`、`SERVER_IP`、`MINIO_API_PORT`、`APP_PUBLIC_URL` 同样做三方指纹比较;目标来自真实部署 env 文件的白名单,脚本控制的公开 URL 按真正 Docker 参数覆盖,不读取或记录 access key/secret 字段,拒绝 URL userinfo、query、片段和重复目标键。缺少完整目标配置直接停止;candidate/post 实际配置必须与 capture 记录的目标一致,不能只靠公开 URL 仍然可读放行内部回源变化。这些交付代码/配置变化会扩大为全部当前预览;超预算会 fail-closed,要求独立全量验收后再安排该类发布。本入口不提供跳过保护的维护参数。
|
||
|
||
审计位置固定属于本项目:
|
||
|
||
```text
|
||
/mnt/PoolOne/apps/youyidian-3d/local-proxy/youyidian-3d-material/material-preview-health/
|
||
accepted-pointer.json
|
||
bootstrap-<审核编号>/bootstrap.json
|
||
release-<commit前12位>-<随机串>/
|
||
accepted.json
|
||
accepted-pointer-before.json
|
||
gate-module.url
|
||
capture.json
|
||
candidate.json
|
||
post.json
|
||
```
|
||
|
||
根目录和单次目录为 0700,文件为 0600。`accepted-pointer.json` 是唯一原子更新的指针,包含已审核/已接受文件的相对路径和**原文件字节 SHA**。读取时拒绝软链接、越界路径、摘要不符或超过 32 MiB 的基线。首次缺少指针或基线时,在停止旧容器前失败;不自动创建“全部正常”的基线。完整发布验收后才原子推进指针;旧回执、旧指针快照、失败报告仍留存,不混入素材或客户端临时目录。
|
||
|
||
### 首次审核基线(独立、显式步骤)
|
||
|
||
首次不把两万余条未探测的当前源伪装为健康,也不因它们全是“新索引项”而自动下载两万张图片。由已核对的项目运维操作者完成一次 bootstrap:读取全库存元数据,探测全部独立旧桶和十二项关键材质,审核其结果后固定原文件 SHA。正常发布永远不能自动重建 bootstrap。
|
||
|
||
1. 在已审核的精确 checkout 中生成模块 URL:`node scripts/material-preview-release-gate.mjs bundle`。模块不含 Key 或数据库 URL。通过已核对的本项目 SSH 将输出作为 0600 文件存入新的私有 `bootstrap-<审核编号>/gate-module.url`,不要写入镜像或源码目录。
|
||
2. 使用本项目当前容器的依赖和环境运行下面的**只读** bootstrap。调用前仍需核对 NAS、当前容器、部署 SHA 和目录身份;`<已核对40位SHA>` 必须替换为真实值。创建新目录与审计文件属于保存证据,不是修改数据库。
|
||
|
||
```sh
|
||
python3 - <新的bootstrap目录>/gate-module.url <已核对40位SHA> <<'PY' | docker exec -i -w /app <已核对当前容器> node --input-type=module - > <新的bootstrap目录>/bootstrap.json
|
||
import json, pathlib, sys
|
||
module = pathlib.Path(sys.argv[1]).read_text()
|
||
request = dict(version=1, stage='bootstrap', commit=sys.argv[2])
|
||
print('const {runReleaseStage}=await import('+json.dumps(module)+');')
|
||
print('try {const r=await runReleaseStage('+json.dumps(request)+');console.log(JSON.stringify(r));process.exitCode=r.passed?0:1;} catch(e) {console.log(JSON.stringify({passed:false,code:"bootstrap_failed"}));process.exitCode=1;}')
|
||
PY
|
||
```
|
||
|
||
3. 独立审核该文件的库存数量、完整性、十二项材质、旧桶全部引用数量、每项失败类型、正文 SHA/尺寸、`knownFailures`、`unverified` 和预算。`passed=true` 只表示满足有明确已知事故基线的发布比较要求,不代表旧桶已恢复。原登记 URL 或数据库链接不应粘贴到公开日志。
|
||
4. 用 `sha256sum bootstrap.json` 获得精确原文件 SHA,审核后以相对路径及该**已核对 SHA**写入 0600 的 `accepted-pointer.json`。指针结构示例:`{"version":1,"file":"bootstrap-审核编号/bootstrap.json","sha256":"<已核对64位SHA>"}`。不得把示例 SHA、空结果或重新运行后的不同文件替代已审核基线;正常发布只读取,不自动安装。
|
||
5. 用相同精确门禁模块执行当前容器的 capture→candidate→post 只读演练,并保留三个实际回执。程序化调用后三阶段时除 `accepted`、`capture`、`candidate` 对应回执外,还必须传 `targetDeliveryConfig`;当前容器演练可用审核后的 `accepted.deliveryConfig`,正式发布则由 PS1 白名单解析待部署 env 与实际 Docker 覆盖值。演练没有替换镜像/切换代理,不能写成真实候选切流验收。正式发布时同三个函数自动执行,审计清单由 capture 固定。
|
||
|
||
跨平台演练须核对目标 checkout 与同一 Git 提交的原始 blob 字节。Windows 的 CRLF 工作副本可能与生产 LF 不同,应在新的受限目录按 Git blob 构建匹配字节快照;不能通过忽略或归一化行尾放宽门禁。正式构建的模块指纹与 Docker 上下文均来自同一精确 checkout。
|
||
|
||
## 导出并逐批检查
|
||
|
||
在已核对数据库身份、具备项目运行依赖的环境执行,输出目录必须是新目录;不要将连接凭据写入命令或报告。
|
||
|
||
```sh
|
||
node scripts/export-material-preview-health-manifest.mjs --output-dir /tmp/material-preview-inventory-20261023 --baseline-host s3.1080p.hk --baseline-count 483
|
||
node scripts/check-material-preview-health.mjs --manifest <新目录>/manifest-000001.json
|
||
```
|
||
|
||
导出器在 PostgreSQL `RepeatableRead` 事务中设置 `SET TRANSACTION READ ONLY`,读取全部 `deletedAt: null` 素材,不按 `HISTORY_IMPORT` 标记筛选,不导出人员字段。产物为 `audit.json` 和 `manifest-000001.json` 等清单,每批最多 50 项;须逐批运行检查器,并另存每批 JSON 输出及退出码。
|
||
|
||
输出路径须为运行环境内的绝对路径,父目录须已存在。导出不发图片 GET。先核对 `audit.json` 的 `activeCount`、`exportedCount`、`uncheckableCount`、`inventoryComplete` 和 `legacyHostCounts`。`inventoryComplete` 只说明库存枚举完整,不代表图片健康;缺少预览、源地址不受支持、未检查或检查失败的项目均不能记为健康。2026-10-23 恢复前基线为 483 条活跃旧域名预览引用,只作对照,不能代替本次实时导出。11 项材质精确恢复后,若同期没有其它变动,应为 472;`legacyBaseline.delta = -11` 是预期的本轮变化,并非其余 472 项已恢复。基线不匹配只报告差额,不自动写库或隐藏引用。
|
||
|
||
检查器按清单中的精确登记地址执行有界单次 GET,不重试、不跟随跳转,并核对 HTTP、MIME、图片魔数及 **Sharp 完整像素解码**;仅头部可识别不足以通过。8 MiB、10 秒、2500 万像素上限保持固定,解码器按运行环境惰性 `createRequire` 加载,不执行安装。保留清单、清单哈希和全部批次报告。`audit.batches[].sha256` 对应原文件字节,`manifestSha256` 对应检查器的同名字段(紧凑 JSON 哈希),二者须分别核对。单批 50 项通过、或 12 项材质通过,均不能写成“全库存通过”。
|
||
|
||
完整图片验收需另行安排流量预算,逐一运行所有 `audit.batches` 并对齐哈希、素材 ID、数量及退出码。2026-10-23 已完成 472 项旧源单次 GET,以及发布检查三阶段每次 485 个固定地址的实际探测;没有执行两万余张当前源全量 GET。**不因导出了两万余项元数据而将它们标记为健康**,未运行的批次保留为未检查。首次基线安装、三阶段原文件 SHA、已知失败与现场范围见 `docs/material-preview-incident-2026-10-23.md`。
|
||
|
||
## 尚未部署脚本时的 stdin 适配
|
||
|
||
当前生产镜像尚未复制这些新脚本及其 registry 依赖。可从已核对本地源码生成以下 stdin 载荷,在目标容器 `/app` 的依赖环境执行;不向运行目录复制源码,不新增依赖。下例只导出元数据,不读取图片。`/tmp` 输出目录仍必须新建且不与历史验收重名。载荷中不包含数据库 URL、Token 或 Key。
|
||
|
||
在仓库根目录运行以下 JavaScript(本地 Node 的 `--input-type=module -`)。将 stdout 通过已核对的本项目 SSH/`docker exec -i -w /app <当前容器> node --input-type=module -` 管道传入,不要在尚未核对容器身份时执行:
|
||
|
||
```js
|
||
import { readFile } from 'node:fs/promises'
|
||
import { LEGACY_DOMAINS } from './scripts/check-legacy-storage-boundaries.mjs'
|
||
const data = s => 'data:text/javascript;base64,' + Buffer.from(s).toString('base64')
|
||
const runtimeBase = 'file:///app/package.json'
|
||
const adapt = s => s.replaceAll('import.meta.url', JSON.stringify(runtimeBase))
|
||
const registry = data(`export const LEGACY_DOMAINS=${JSON.stringify(LEGACY_DOMAINS)}`)
|
||
const health = data(adapt(await readFile('scripts/check-material-preview-health.mjs', 'utf8'))
|
||
.replace("'./check-legacy-storage-boundaries.mjs'", JSON.stringify(registry)))
|
||
const exporter = data(adapt(await readFile('scripts/export-material-preview-health-manifest.mjs', 'utf8'))
|
||
.replace("'./check-legacy-storage-boundaries.mjs'", JSON.stringify(registry))
|
||
.replace("'./check-material-preview-health.mjs'", JSON.stringify(health)))
|
||
const args = ['--output-dir', '/tmp/material-preview-inventory-20261023-after11',
|
||
'--baseline-host', LEGACY_DOMAINS[0], '--baseline-count', '483']
|
||
process.stdout.write(`const {main}=await import(${JSON.stringify(exporter)});
|
||
try { const r=await main(${JSON.stringify(args)});
|
||
console.log(JSON.stringify({readOnly:true,outputDirectory:r.outputDirectory,
|
||
activeCount:r.audit.activeCount,exportedCount:r.audit.exportedCount,
|
||
uncheckableCount:r.audit.uncheckableCount,legacyHostCounts:r.audit.legacyHostCounts,
|
||
legacyBaseline:r.audit.legacyBaseline,inventoryComplete:true,healthChecksExecuted:false}));
|
||
process.exitCode=r.audit.readyForHealthChecks?0:1;
|
||
} catch { console.log(JSON.stringify({readOnly:true,inventoryComplete:false,code:'inventory_export_failed'}));process.exitCode=1; }`)
|
||
```
|
||
|
||
stdin 中的 `createRequire('file:///app/package.json')` 使用容器已有的 `@prisma/client`/Sharp;不是读取本机另一套数据库配置。若依赖不存在、数据库事务失败或输出中途失败,退出非零,不能把残留文件当完整清单。导出器在所有批次成功写入后才写 `audit.json`。导出完成后再由调用方按需取回只读审计文件,本命令不清理文件。
|
||
|
||
## 发布接入函数
|
||
|
||
当前正式策略仍为 direct replacement,没有恢复蓝绿发布入口。接入点按函数语义定位:
|
||
|
||
| 位置 | 应保留的验收证据 |
|
||
| --- | --- |
|
||
| `direct_replace_active_container` 中 `docker stop` 前 | `prepare_material_preview_release` 验证已审核指针;`run_material_preview_release_gate ... capture` 清点全库存并固定探测清单 |
|
||
| `verify_candidate_brand_and_storage_dependencies` 后、切流前 | `run_material_preview_release_gate ... candidate` 验证同清单与库存;失败走现有 immutable image 恢复 |
|
||
| `verify_proxy_target` 成功后、`write_current_container` 前 | `run_material_preview_release_gate ... post` 通过公开存储 URL 实际 GET/解码同清单;失败走现有恢复 |
|
||
| 当前版本记录成功后 | `accept_material_preview_release` 核对三个阶段同 commit/清单/库存,原子推进指针 |
|
||
|
||
macOS wrapper 从同一 PowerShell 源码抽取发布逻辑,不另复制一套条件。已有 shell 回归验证 capture 失败时没有 stop/switch、candidate 失败时没有 switch、post 失败时调用一次现有回滚,且失败不推进基线。该只读探测验证公开存储交付路径,不能代替登录态页面、私有下载资格或客户端实际 UI 的单独验收。
|
||
|
||
11 项材质预览恢复属于独立的精确 CAS 数据补丁:先验证新对象,再以原值为条件更新并保留回退记录;不得混入本只读检查器,也不代表高清原件或其余历史依赖已恢复。
|
||
|
||
相关离线回归:
|
||
|
||
```sh
|
||
node --test scripts/check-material-preview-health.test.mjs scripts/export-material-preview-health-manifest.test.mjs scripts/material-preview-release-gate.test.mjs scripts/git-incremental-deploy.test.mjs
|
||
```
|