CraftOSS Dart SDK 与 CLI #

第一版客户端同时提供可嵌入 Dart/Flutter 项目的 SDK，以及 craft-oss 命令行入口。当前覆盖 HMAC v1、健康检查、Object 数据面，以及带本地恢复状态的 Multipart 大文件上传。

安装 #

dart pub add craft_oss

本项目使用 GPL-3.0 许可证，使用和再分发前请确认你的项目符合相应许可要求。

本地运行 #

cd client/packages/craft_oss
dart pub get
dart run bin/craft_oss.dart health

数据面命令从环境变量读取凭证：

CRAFT_OSS_ENDPOINT
CRAFT_OSS_APP_ID
CRAFT_OSS_ACCESS_KEY_ID
CRAFT_OSS_ACCESS_KEY_SECRET

CRAFT_OSS_ENDPOINT 缺省为 http://127.0.0.1:9606。Secret 不提供命令行参数，避免被 shell 历史和进程列表记录。

dart run bin/craft_oss.dart object put demo-assets images/logo.png .\logo.png --content-type image/png
dart run bin/craft_oss.dart object list demo-assets --prefix images/
dart run bin/craft_oss.dart object get demo-assets images/logo.png .\downloaded-logo.png
dart run bin/craft_oss.dart object delete demo-assets images/logo.png
dart run bin/craft_oss.dart object presign-put demo-assets images/logo.png .\logo.png --content-type image/png --expires 600
dart run bin/craft_oss.dart object generate-video-cover video demo.mp4 --frame-ms 1000 --width 640

Multipart 上传会在源文件旁保存不含 Secret 的恢复状态；中断后重复执行同一命令即可只补传服务端缺失的 Part：

dart run bin/craft_oss.dart multipart upload demo-assets archive/movie.mp4 .\movie.mp4 --part-size 8388608
dart run bin/craft_oss.dart multipart parts mp_xxx
dart run bin/craft_oss.dart multipart abort mp_xxx

可用 --state-file 指定状态文件位置。--restart 会尝试取消状态文件中的旧任务，然后建立新任务。

SDK 示例 #

final CraftOssClient client = CraftOssClient(
  endpoint: Uri.parse('http://127.0.0.1:9606'),
  credentials: const CraftOssCredentials(
    appId: 'app_xxx',
    accessKeyId: 'ak_xxx',
    accessKeySecret: 'secret',
  ),
);

调用结束后执行 client.close() 释放连接池。应用代码不要输出或持久化 accessKeySecret。

视频和封面图片都上传完成后，可通过 bindVideoCover 建立默认封面关系，并使用 getVideoCover 获取包含公开地址的封面 Object。覆盖源视频后旧绑定自动失效，需要重新绑定。 generateVideoCover 可请求服务端通过 FFmpeg 直接生成并绑定 WebP 封面。

可信服务可调用 client.presignPutObject(...) 生成最长 1 小时的短期 PUT URL，再把返回的 url、method 与 headers 交给浏览器或 Flutter 客户端。URL 会绑定对象路径、文件摘要和 Content-Type，公开客户端不需要 AccessKey Secret。

下载默认拒绝覆盖已存在的文件；明确需要覆盖时使用 object get ... --force。

应用版本发布 #

release publish 会上传版本化安装包，再通过管理接口把真实大小、SHA-256 和公开地址登记到发布数据库。配置可放在独立 .env 中：

dart run bin/craft_oss.dart release publish `
  --env-file ..\..\..\scripts\release\.env `
  --version 1.6.0 `
  --description "修复同步问题" `
  D:\build\ViewX-1.6.0.exe

仓库根目录提供了更短的 Python 入口和完整说明，见 scripts/release/README.md。