# 中国大陆可用 Artifact 服务调研

## 背景

Linear: QIU-45

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

- Sphinx 生成的静态网页；
- 实验图片、视频、JSON、`experiment_summary.md`；
- 可在浏览器中直接打开的 HTML 页面；
- 可通过 `<video>`、缩略图或下载链接访问的 MP4/WebM 等大媒体。

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

## 硬性需求

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 下行费用清晰，可按项目和日期清理。

## 候选服务对比

| 服务 | 大陆访问 | 静态网页 | 视频/大对象 | 自动化 | 主要风险 | 结论 |
|---|---|---|---|---|---|---|
| 阿里云 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 服务 |

## 推荐方案

### 方案 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，不保存大媒体。

建议路径：

```text
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：

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

### 方案 B：腾讯云 COS + CDN

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

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

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

## 不推荐的方案

1. **Git 仓库存视频**：会膨胀仓库、影响 clone、也不适合频繁生成仿真视频。
2. **GitHub Releases/Actions artifacts 作为网页入口**：适合临时下载，不适合长期浏览器静态站点和大陆稳定访问。
3. **GitHub Pages 作为唯一入口**：跨境访问不稳定，大视频也不适合。
4. **网盘作为主入口**：人工可用，但 URL、权限、目录索引和自动化都不适合作为 artifact platform。

## 最小落地规范

### Artifact manifest

每次发布写一个轻量 JSON：

```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"
        }
      ]
    }
  ]
}
```

### HTML/视频引用

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

```html
<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。

### 权限建议

- bucket 默认私有；
- 只开放 `docs/` 和需要公开的 `artifacts/` 前缀只读；
- 写权限只放 CI/服务器，浏览器永远不保存 AK/SK；
- 如果需要内部访问，使用 CDN 鉴权 URL、临时签名 URL 或公司内网代理；
- 配置 CORS：允许文档域名 `GET/HEAD`，必要时允许 `Range` 相关响应头；
- 配置正确 MIME type：`.html=text/html`、`.mp4=video/mp4`、`.json=application/json`。

## 发布流程建议

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

```bash
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。

## 当前结论

推荐排序：

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 打开验证。

## 参考入口

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

- 阿里云 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`