maoda-commander-tt 0.0.71 → 0.0.73

package/README.md

@@ -245,6 +245,96 @@ pnpm pub
 
 参见 [npm Trusted Publishing 文档](https://docs.npmjs.com/trusted-publishers/)。
 
+## COS 资源上传
+
+`tt assets upload <file> --key <key>` 上传一个普通本地文件并返回自己的资源入口：
+
+```bash
+tt assets upload ./story.mp3 --key yoyo/audio/story.mp3
+tt assets upload './封面 图片.webp' --key 'yoyo/images/封面 图片.webp'
+```
+
+`key` 是相对于资源根的原始名称，包含文件名；不推断项目名，不生成哈希名，不做 URL
+解码。上传实际存入 COS 的 `tt/<key>`，公开入口为 `publicBaseUrl` 加逐段 URL 编码的
+`key`。例如 `yoyo/audio/story.mp3` 存入 `tt/yoyo/audio/story.mp3`，返回
+`https://www.imaoda.com/assets/yoyo/audio/story.mp3`。若 key 自带 `tt/`，不会自动去重。
+
+只接受普通文件，拒绝目录、符号链接和特殊文件。key 最多 1021 个 UTF-8 字节，不能以
+`/` 开头或结尾，不能含空路径段、`.`、`..`、反斜杠或控制字符；中文、空格、`?`、`#`
+和字面 `%` 可用。`name%2Fpart.mp3` 是含字面 `%2F` 的名字，URL 中会编码为
+`name%252Fpart.mp3`，不被当作额外目录。
+
+同 key 默认更新目标对象，桶启用版本控制时保留版本的行为由 COS 管理。每次调用都会
+上传，不会跳过未变化文件，也不做全目录增量同步或删除其他对象；各项目可只传新增或
+明确要更新的文件。官方 `cos-nodejs-sdk-v5` 自动选择简单或分块上传，保留其重试和
+分块恢复能力；这不等于按内容去重。上传期间不要修改源文件。
+
+Content-Type 按本地文件扩展名确定，未知类型为 `application/octet-stream`，简单与
+分块上传都显式设置。缓存按**目标 key 最后一个扩展名**选择，不区分大小写，不依据本地
+文件名或 MIME：常见脚本、样式、图片、音视频、字体、PDF 和压缩包统一设置
+`Cache-Control: public, max-age=2592000, immutable`（30 天）；HTML、JSON、无扩展名
+及其他类型使用 `no-cache`。完整扩展表见
+[缓存策略](src/modules/assets/asset-cache-policy.ts)，并与 Nginx 资源规则保持一致。
+桶 ACL 或公开读配置不变。
+
+同 key 覆盖仍会更新 COS 对象，**但不会刷新客户端已有的 30 天强缓存**。发布新内容
+请使用新 key，例如 `yoyo/audio/story-v2.mp3`；命令不会强制改名或自动生成哈希。
+
+### 资源配置
+
+复用跨应用 `~/.cli_settings/settings.json` 的**单个 `cos` 字符串键**，通过既有配置
+writer 写入。它的 `value` 是包含以下五个字段的 JSON 字符串，不修改 settings 文件的
+外层 schema，也不是五个独立设置键：
+
+```json
+{
+  "secretId": "<COS SecretId>",
+  "secretKey": "<COS SecretKey>",
+  "bucket": "cdna-1253404032",
+  "region": "ap-beijing",
+  "publicBaseUrl": "https://www.imaoda.com/assets/"
+}
+```
+
+五项均为必填非空字符串，不接受额外字段。`publicBaseUrl` 必须是无账号、查询参数和
+片段的 HTTPS URL，末尾 `/` 会统一补齐；桶内 `tt/` 根目录固定，不另设 root 配置。
+命令只读取配置，不接受凭证参数，不打印配置值或 SDK 原始错误中的签名信息。
+每台调用机器配置一次即可供不同项目使用；跨应用设置路径仍可通过
+`TT_CROSS_APP_SETTINGS_FILE` 覆盖。
+
+Nginx 将 `/assets/<编码后的key>` 302 到固定 COS 桶的 `/tt/<编码后的key>`，配置见
+[资源入口路由](ops/nginx/tt-assets-location.conf)。302 保留原始 URL 编码，避免中文、
+空格及保留字符被二次解释。入口省略 `tt/`，但跳转的 Location 和浏览器网络记录仍能
+看到 COS 对象路径。常见静态资源的 Nginx 响应采用相同的 30 天强缓存策略，其他类型
+不强缓存，统一规则见 [静态缓存配置](ops/nginx/static-cache.conf) 与
+[普通静态文件路由](ops/nginx/static-files-location.conf)。更新内容或资源入口映射时，
+要考虑已经缓存的响应，使用新 key 发布新内容。
+
+### 资源上传结果
+
+stdout 是单行 JSON envelope；stderr 的周期性进度不是最终结果。命令等待 COS 确认
+上传成功后退出，成功 `data` 示例：
+
+```json
+{
+  "state": "uploaded",
+  "key": "yoyo/audio/story.mp3",
+  "url": "https://www.imaoda.com/assets/yoyo/audio/story.mp3",
+  "bytes": 1048576,
+  "contentType": "audio/mpeg",
+  "etag": "\"example-etag\""
+}
+```
+
+`etag` 和 `versionId` 仅在 COS 返回时提供。`uploaded` 表示 COS 确认完成，不意味着
+302 入口、公开权限、CORS、音频拖动或浏览器播放均已通过验收；返回 URL 不带访问签名。
+配置、输入和本地文件错误没有上传结果。进入 SDK 上传后若失败，返回非零退出码与
+`data: {state: "unconfirmed", key, url}`，并保留可确定的 HTTP 状态或错误码。
+尤其网络或超时失败时，对象可能已经写入，先核对目标再决定重试；重试同 key 会更新
+该对象。不会把“请求失败”伪称为“确定未上传”。
+
+`tt assets` 不参与网页构建和发布；继续用 `tt deploy` 发布现成站点产物。
+
 ## 静态文件部署
 
 `tt deploy` 通过 HTTPS API 将现成的文件或目录部署到 nginx 静态目录，不执行构建。