17. 中国大陆可用 Artifact 服务调研

17.1. 背景

Linear: QIU-45

目标是给 SimKit 找一个可长期使用的 artifact 服务，用来存放：

  • Sphinx 生成的静态网页；

  • 实验图片、视频、JSON、experiment_summary.md；

  • 可在浏览器中直接打开的 HTML 页面；

  • 可通过 <video>、缩略图或下载链接访问的 MP4/WebM 等大媒体。

这份调研延续 documentation-platform-research.md 的“双层发布”结论：Git 仓库保存文档源、轻量脚本和 summary；大媒体与构建后的网页放到对象存储/CDN/静态 HTTP 服务。

17.2. 硬性需求

  1. 中国大陆网络可访问：面向大陆团队成员打开网页/视频时应稳定，不依赖 GitHub Pages、Cloudflare R2、海外 S3 等跨境路径。

  2. 静态网站能力：支持 index.html、错误页、目录式访问或自定义域名，能直接承载 sphinx-build -b html 输出。

  3. 大文件能力：支持 MP4/WebM/PNG/JSON 等对象上传，单文件大小和带宽适合仿真视频。

  4. 浏览器播放/下载：支持 HTTP GET、Range Request、正确 MIME type、CORS 配置。

  5. 自动化发布：有 CLI/SDK 或 S3-compatible 工具链，能在 CI/cron 中同步目录。

  6. 权限分层：能做到公网只读、写入凭证只在 CI/服务器侧保存，浏览器不持有长期 AK/SK。

  7. 成本可控：对象存储 + CDN 下行费用清晰，可按项目和日期清理。

17.3. 候选服务对比

服务

大陆访问

静态网页

视频/大对象

自动化

主要风险

结论

阿里云 OSS + CDN

强，节点和生态成熟

支持静态网站、默认首页、错误页、自定义域名

支持大对象、Range、CDN 回源；可配置 MIME/CORS

ossutil、SDK、S3-compatible 工具

公开站点需要备案/域名/CDN 配置；权限策略要谨慎

首选

腾讯云 COS + CDN

强，文档和控制台成熟

支持静态网站配置和自定义域名

支持对象存储、Range、CDN；适合视频分发

coscli、SDK、S3-compatible 工具

跨账号权限、Referer 防盗链、CORS 需单独配置

备选首选

华为云 OBS + CDN

强，适合已有华为云账号/OBS 数据

支持静态网站托管能力

支持大对象和 CDN 分发

obsutil、SDK

文档入口和配置项命名与 OSS/COS 不同；团队若无华为云账号会增加维护成本

适合已有 OBS 资产时使用

火山引擎 TOS + CDN

大陆可用，性价比可评估

有对象存储和静态网站/自定义域名能力

支持视频类大对象和 CDN

SDK/CLI

团队熟悉度可能低于 OSS/COS；需验证控制台与 IAM 流程

可作为价格/账号侧备选

七牛云 Kodo + CDN

大陆 CDN 生态成熟

可做静态资源分发

适合媒体分发

qshell、SDK

更偏媒体/CDN 平台；静态站点和权限组织需额外约定

媒体分发备选

GitHub Pages

大陆访问不稳定

支持静态网页

不适合大视频

GitHub Actions

跨境访问、容量和大文件限制

不推荐作为大陆主入口

Cloudflare R2 / 海外 S3

海外访问好

静态站点需额外 Worker/Pages

支持大对象

S3 工具链成熟

大陆可访问性和跨境链路不可控

只作海外镜像/备份

网盘/云盘

人工分享方便

不能稳定承载 HTML 站点

可存大文件

自动化差

URL、预览、权限、索引不稳定

只作冷备份，不作主 artifact 服务

17.4. 推荐方案

17.4.1. 方案 A：阿里云 OSS + CDN（推荐默认）

适合 SimKit 当前需求：

  • sphinx-build -b html docs docs/_build/html 输出整体同步到 OSS；

  • debug/<experiment>/ 中的 MP4/PNG/JSON/summary 同步到 artifacts/ 前缀；

  • CDN 域名提供浏览器入口；

  • Git/Linear 中只保存 URL 和 manifest，不保存大媒体。

建议路径：

oss://<bucket>/simkit/
  docs/<git-commit>/html/
  docs/latest/                 # 可选：指向最新构建
  artifacts/<issue>/<run-id>/
    experiment_summary.md
    summary.json
    overlay_stats.json
    video.mp4
    thumbnail.jpg

建议 URL：

https://artifacts.example.com/simkit/docs/<commit>/html/index.html
https://artifacts.example.com/simkit/artifacts/QIU-5/20260508/video.mp4

17.4.2. 方案 B：腾讯云 COS + CDN

如果团队已有腾讯云账号或更偏好腾讯云控制台，则 COS 与 OSS 功能定位接近，也适合做主 artifact 服务。路径约定与 OSS 相同，只替换同步工具和 bucket URL。

17.4.3. 方案 C：华为 OBS / 火山 TOS / 七牛 Kodo

这些更适合作为已有云账号或价格/带宽策略驱动下的备选。若 SimKit 的数据平台本身已经在 OBS 上，优先用 OBS 可减少跨云搬运；若主要是公开媒体分发，可以评估七牛或火山 CDN 成本。

17.5. 不推荐的方案

  1. Git 仓库存视频：会膨胀仓库、影响 clone、也不适合频繁生成仿真视频。

  2. GitHub Releases/Actions artifacts 作为网页入口：适合临时下载，不适合长期浏览器静态站点和大陆稳定访问。

  3. GitHub Pages 作为唯一入口：跨境访问不稳定，大视频也不适合。

  4. 网盘作为主入口：人工可用，但 URL、权限、目录索引和自动化都不适合作为 artifact platform。

17.6. 最小落地规范

17.6.1. Artifact manifest

每次发布写一个轻量 JSON：

{
  "project": "simkit",
  "commit": "<git-sha>",
  "published_at": "2026-05-08T20:00:00+08:00",
  "provider": "aliyun-oss",
  "base_url": "https://artifacts.example.com/simkit/",
  "issues": [
    {
      "identifier": "QIU-45",
      "title": "调研中国大陆可用的 artifact 服务",
      "artifacts": [
        {
          "kind": "doc",
          "path": "docs/mainland-china-artifact-services.html",
          "url": "https://artifacts.example.com/simkit/docs/<commit>/html/mainland-china-artifact-services.html"
        }
      ]
    }
  ]
}

17.6.2. HTML/视频引用

文档页面应引用稳定 URL，而不是本地绝对路径：

<video controls preload="metadata" width="720" src="https://artifacts.example.com/simkit/artifacts/QIU-5/run.mp4"></video>

大视频页面建议同时提供：

  • 缩略图；

  • MP4 链接；

  • summary JSON；

  • experiment_summary.md；

  • Linear issue URL；

  • git commit hash。

17.6.3. 权限建议

  • bucket 默认私有；

  • 只开放 docs/ 和需要公开的 artifacts/ 前缀只读；

  • 写权限只放 CI/服务器，浏览器永远不保存 AK/SK；

  • 如果需要内部访问，使用 CDN 鉴权 URL、临时签名 URL 或公司内网代理；

  • 配置 CORS：允许文档域名 GET/HEAD，必要时允许 Range 相关响应头；

  • 配置正确 MIME type：.html=text/html、.mp4=video/mp4、.json=application/json。

17.7. 发布流程建议

首版不需要复杂平台，先实现可复制流程：

uv run sphinx-build -b html docs docs/_build/html
# 示例：用具体云厂商 CLI 同步，不把凭证写入命令或日志
# ossutil sync docs/_build/html oss://<bucket>/simkit/docs/<commit>/html
# ossutil sync debug/<experiment> oss://<bucket>/simkit/artifacts/<issue>/<run-id>

然后在 Linear comment / 文档状态块中记录：

  • provider；

  • bucket 前缀；

  • public URL；

  • commit hash；

  • 验证命令和 exit code。

17.8. 当前结论

推荐排序：

  1. 阿里云 OSS + CDN：作为默认主线；

  2. 腾讯云 COS + CDN：作为等价备选；

  3. 华为 OBS + CDN：如果数据源或团队账号已经在华为云；

  4. 火山 TOS / 七牛 Kodo + CDN：作为成本或媒体分发优化备选；

  5. GitHub Pages / R2 / 海外 S3 / 网盘：不作为大陆主入口。

QIU-45 的最小完成标准可以是：本调研文档入库、加入 docs index、Sphinx HTML 构建通过。后续如果要真正上线，应拆分新的实施 issue：配置 OSS/COS bucket、域名/CDN、CI 同步脚本、artifact manifest 生成和一次真实 MP4 打开验证。

17.9. 参考入口

本轮验证过的公开文档入口（仅记录产品能力入口，不在仓库保存凭证）：

  • 阿里云 OSS 静态网站托管文档入口：https://help.aliyun.com/zh/oss/

  • 腾讯云 COS 静态网站文档入口：https://cloud.tencent.com/document/product/436/9512

  • 火山引擎 TOS 文档入口：https://www.volcengine.com/docs/6349/79896

  • SimKit 既有文档发布调研：docs/documentation-platform-research.md