FAQ

注意事项 ​

Notes ​

  • .cas 的逐片 MD5 与多文件结构依赖可选扩展字段，单文件五字段与参考项目字节级兼容。
  • 中转秒传要求中间存储支持同步原生复用或 PutURL。
  • 重算要求源文件已存在于服务端。
  • 生成的 .torrent 是合法 BT 文件，但 OpenList 本身不作为 BT peer。
  • 所有种子解析均受字节数、文件数、深度与路径穿越限制。
  • .cas per-piece MD5 and multi-file support rely on optional extension fields; the single-file five fields remain byte-compatible with the reference project.
  • Relayed transfer requires an intermediate storage with synchronous native reuse or PutURL.
  • Recalculation requires the source file to already exist on the server.
  • The generated .torrent is a valid BT file, but OpenList itself is not a BT peer.
  • All seed parsing is bounded by byte, file-count, depth, and path-traversal limits.

常见问题 ​

Common questions ​

生成的 .cas 被标记为 Legacy CAS 是什么原因？ ​

Legacy CAS 只包含 name、size、md5、聚合 sliceMd5 与创建时间五个字段，缺少逐片 MD5 列表，因此转换时会丢失分片信息。新版生成会写入 slice_md5s / slice_size 保存逐片 MD5，预览时若已含分片哈希则不再提示 Legacy CAS。

为什么只有 MD5 的种子无法转成 .torrent？ ​

.torrent 遵循 BT v1 规范，必须包含 SHA-1 完整哈希与分片哈希。只有 MD5 时无法生成有效的 pieces，转换前会明确诊断缺失 SHA-1 分片。

多文件转 .torrent 为什么报「a file boundary splits a piece」？ ​

BT v1 中所有文件共享同一个分片序列。多文件时除最后一个文件外，其余每个文件的大小都必须能被 piece_size 整除，否则某个分片会被文件边界截断，无法合法拆分。请调整分片大小或改用单文件，使其大小对齐。

秒传为什么会提示 unavailable？ ​

目标驱动无法复用当前种子内的哈希时会提示 unavailable，系统不会静默退化为普通上传，以保证行为可预期。请确认种子里包含目标驱动所需的哈希（参见秒传矩阵）。

中转秒传为什么不支持异步离线下载？ ​

异步离线下载无法保证中间存储先落盘完成，无法稳定地服务器端复制到最终目标。因此中转要求中间存储支持同步原生复用或 PutURL。

生成的 .torrent 能直接用 BT 客户端下载吗？ ​

生成的 .torrent 是合法的 BT v1 文件，可通过 magnet 交给离线工具下载；但 OpenList 本身不作为 BT peer，能否通过通用 BT 客户端下载取决于 tracker/webseed 的部署情况。

重算为什么要求源文件在服务端？ ​

重算是重读服务端已有文件重新计算哈希，不从外部来源下载。若文件不在服务端，请先将文件上传或保存到服务端后再重算。

上传时如何启用自动生成侧车？ ​

上传接口通过请求头控制：设置 X-Seed-Sidecars（如 oss,torrent,cas）直接指定格式；或 X-Generate-Seed: on 配合存储级 seed_policy 与全局 seed_auto_generate_policy 判定。默认全局策略为 off，即默认不生成。

为什么异步上传（as_task=true）不能生成侧车？ ​

侧车生成需要完整读取上传流边传边哈希。异步任务无法保证在同一进程内拿到完整流并同步落盘侧车，因此上传接口在「启用侧车 + 异步上传」组合下直接返回 400。

哈希矩阵全空是什么意思？ ​

内容矩阵六个值（md5/sha1/sha256 × whole/pieces）全为 false 时，系统视为「尽量多算」，等价于全部勾选。若希望生成最小种子，请显式勾选需要的那几项。

.torrent 里的 x-openlist 是什么？ ​

x-openlist 是 OpenList 的无损扩展键，把完整 .oss 种子做 bencode 化嵌入标准 torrent 中。OpenList 客户端解析时能据此完整还原 MD5/SHA256、注释、渠道、分享等元数据；解析时还会校验它与 info 字典的一致性，防止伪造。

为什么异步种子生成任务在服务重启后会丢失？ ​

超过 1 GiB 的生成请求会转为后台任务，但异步任务不持久化；服务重启后未完成的任务会丢失，需要重新发起生成。小文件（≤ 1 GiB）同步生成，不受影响。

Why is my generated .cas flagged as Legacy CAS? ​

A legacy CAS only carries the five fields name, size, md5, aggregate sliceMd5, and creation time, with no per-piece MD5 list, so conversion is lossy. Newer generation writes slice_md5s / slice_size to preserve per-piece MD5, and the preview no longer shows the Legacy CAS warning when piece hashes are present.

Why can’t a seed with only MD5 convert to .torrent? ​

.torrent follows the BT v1 spec and requires SHA-1 whole + piece hashes. MD5 alone cannot produce a valid pieces field; conversion reports the missing SHA-1 pieces explicitly.

Why does multi-file .torrent conversion report "a file boundary splits a piece"? ​

All files in a BT v1 torrent share one piece sequence. In multi-file mode, every file except the last must have a size divisible by piece_size; otherwise a piece is cut by a file boundary and cannot be legally divided. Adjust the piece size or use a single file so sizes align.

Why does rapid upload report unavailable? ​

When the destination drive cannot reuse the hashes in the current seed, the operation reports unavailable instead of silently degrading to a normal upload. Make sure the seed contains the hashes the target drive requires (see the rapid upload matrix).

Why can’t relayed transfer use asynchronous offline download? ​

Asynchronous offline download cannot guarantee the intermediate storage has fully landed before the server-side copy to the final drive. Relaying therefore requires the intermediate storage to support synchronous native reuse or PutURL.

Can a generated .torrent be downloaded by a generic BT client? ​

The generated .torrent is a valid BT v1 file and can be handed to an offline tool via magnet. However, OpenList itself is not a BT peer; whether generic BT clients can download depends on the tracker/webseed deployment.

Why does recalculation require the source file on the server? ​

Recalculation re-reads an existing server-side file to recompute hashes; it never downloads from an external source. Upload or save the file to the server first if it is not already there.

How do I enable automatic sidecar generation on upload? ​

The upload API is controlled by headers: set X-Seed-Sidecars (e.g. oss,torrent,cas) to specify formats directly, or combine X-Generate-Seed: on with the storage-level seed_policy and the global seed_auto_generate_policy. The global policy defaults to off, so nothing is generated by default.

Why can’t asynchronous upload (as_task=true) generate sidecars? ​

Sidecar generation must read the full upload stream and hash it in one pass. An async task cannot guarantee the complete stream is available in the same process and written synchronously, so the upload API returns 400 for the "sidecars + async upload" combination.

What does an all-empty hash matrix mean? ​

When all six flags (md5/sha1/sha256 × whole/pieces) are false, the system treats it as "compute as much as possible", equivalent to selecting everything. To produce a minimal seed, explicitly select only the hashes you need.

What is x-openlist inside a .torrent? ​

x-openlist is OpenList’s lossless extension key that bencode-embeds the full .oss seed into a standard torrent. OpenList clients use it to fully reconstruct MD5/SHA256, comments, channels, and shares; parsing also validates its consistency with the info dictionary to prevent forgery.

Why are background seed-generation tasks lost on restart? ​

Requests over 1 GiB are queued as background tasks, but those tasks are not persisted; an unfinished task is lost when the service restarts and must be re-triggered. Small files (≤ 1 GiB) are generated synchronously and are unaffected.

Contributors

Edit this page on GitHub

Last updated: