# 唐侦探素材 COS 迁移

## 当前状态（2026-09-08）

**尚未上传，也没有切换真实 COS 地址。** 数据库端口可达，但其 TLS 自签名证书不受 Node.js 默认信任库、项目 `server/public/cacert.pem` 或本机系统信任库信任。没有关闭证书/主机名校验，没有读取到 COS 密钥，没有执行任何 COS 写操作，也没有改数据库或桶权限。

需提供配置数据库的可信 CA 证书文件路径，或已授权可用的 SSH 连接名；不要把数据库密码、COS 密钥或登录 token 发到聊天、清单或前端文件中。自签名证书不等于一定存在安全问题，但不能把“能连通”当成“身份已验证”。

473 个原字节快照文件中：160 个 JPG、44 个 MP3、0 个视频，共 204 个原路径、24,052,082 字节，按内容与扩展名去重后为 180 个对象。此次范围为实际迁入游戏的媒体，不包括源码外的草稿、试听实验或重新生成素材。原目录与 `native/tang-detective/` 均保留。

## 上传与校验

独立工具位于 `scripts/tang-cos/`，不会加入小程序运行时。使用 Node.js 22 或更新版本，在前端根目录运行：

```sh
npm ci --prefix scripts/tang-cos --ignore-scripts --no-audit --no-fund
node scripts/tang-cos/upload.mjs inventory
node --test scripts/tang-cos/upload.test.mjs
```

在得到服务器管理员提供的可信 CA 文件后，将 `TANG_DB_CA_FILE` 设为该文件路径；若证书已受系统信任，可用 Node.js 的 `--use-system-ca`。不得把抓取到的陌生对端证书直接设为信任根。工具始终启用证书链和主机名校验。

```sh
node scripts/tang-cos/upload.mjs inspect
node scripts/tang-cos/upload.mjs upload
```

`inspect` 只通过只读 SQL 查询 `server/config/database.php` 配置的 `${prefix}config` 表中 `storage/default`、`storage/qcloud` 两项。仅输出目标桶、地域、公开域名和凭据存在状态，不输出数据库连接秘密或 COS 密钥。当前没有 `server/.env`；若以后新增，工具会停止而非猜测 PHP 环境解析规则，应在原生服务器运行环境中确认配置读取方式。

`upload` 使用腾讯官方 `cos-nodejs-sdk-v5`，只执行逐对象 HEAD/PUT，不经过会写文件表的后台上传接口。每个对象键为：

```text
tang-detective/season-01/media-v1/<完整SHA256>.<原扩展名>
```

上传前核验所有快照文件；已有对象必须大小及 SHA-256 元数据相符，否则停止。PUT 使用 MD5 传输校验、SHA-256 元数据及禁止覆盖请求头，不设置 ACL、不删除对象。内容寻址降低误覆盖风险；禁止覆盖请求头不能替代已有对象检查。

每个对象上传后必须通过**无凭据的精确 HTTPS 地址**完整下载，核对大小、SHA-256 和媒体类型；音频/视频还检查 `Range` 分段读取。首个对象无法公开读取便停止，绝不自动把桶改为公开。此时最多留下首个已写入对象，由回执记录，工具不自动删除。

只有全部对象成功后才生成 `build/tang-detective-cos-manifest.json`，一一保留 204 个原路径映射。该文件不存在时构建继续使用本地媒体；不得手写虚假成功清单。逐对象上传/复用及验证证据写入 `build/tang-detective-cos-upload-receipt.json`；每次显式上传均有独立运行ID，旧回执保留到 `build/tang-detective-cos-upload-attempts/`。前置配置失败也记录为本次失败，不能借用上次成功结论。PUT 发出前持久化 `unknown`，响应不确定时做只读复查，未能确认则保持未知，不写成“确定未上传”。工具错误只输出脱敏错误码，不输出签名 URL 或原始 SDK 错误。数据库建连、查询和关闭分别有8秒、8秒、2秒截止时间，超时仅销毁本任务连接。

## 后续验收边界

本轮已执行的本地验证：

- `npm run test:tang`：72/72通过（既有44项、远程素材13项、上传工具15项）；远程测试只用独占临时目录中的模拟地址与响应。
- 微信生产构建、H5生产构建均退出0；未启动网页预览或开发服务。
- 实际微信产物校验通过：24页、204媒体、`mediaMode: local`。原始文件总量32,595,927字节、主包3,157,378字节，和原本地模式一致；**不能把模拟远程输出的节省量说成实际包体积已解决**。
- 本机微信编译器检查24页WXML/WXSS通过；不等于模拟器交互或真机运行。
- 原来源和迁入快照各473文件逐项SHA-256复核，无漂移。
- 默认本地模式以及模拟远程模式的相对模块依赖检查均通过；远程模式覆盖120页原图哈希、112正式/8临时层级、8段第一回试听状态、断网图片最终文字回退、迟到事件、分享坏缓存和输出符号链接保护。
- 真实COS上传、无凭据远程下载、真实音频Range和微信合法域名尚未验证；没有真实启用清单或上传回执。

完整下载哈希证明文件传输一致，不代表声音已获听审、商用/克隆授权、医学审核或微信真机通过。第一回内部试听与未配置的后续整页音频审核状态均不得因上传而提升。

完成真实上传、地址切换和构建后，仍需核对微信后台的请求/下载合法域名及对应 HTTPS 证书，实测首屏、翻页、分享、试听、后台暂停和断网回退。此次未修改微信后台配置，也未部署服务器或发布小程序。