NixOS/nix中的可锁定HTTP Tarball协议详解-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00725/article/details/148378360

NixOS/nix中的可锁定HTTP Tarball协议详解

nix Nix, the purely functional package manager 项目地址: https://gitcode.com/gh_mirrors/ni/nix

协议概述

在Nix生态系统中，Tarball（压缩包）是一种常见的软件包分发格式。NixOS/nix项目实现了一种名为"可锁定HTTP Tarball协议"的机制，它允许开发者通过HTTP或文件系统(file://)提供Tarball格式的Flakes，同时确保构建的可重复性。

为什么需要这个协议？

在传统方式下，当用户指定一个动态URL（如包含"latest"的URL）获取Tarball时，服务器返回的内容可能会随时间变化。这会导致构建结果不可复现，违背了Nix的核心设计理念。

可锁定HTTP Tarball协议通过以下方式解决这个问题：

允许用户指定"最新版本"的URL（如https://example.org/hello/latest.tar.gz）
服务器返回一个包含不可变URL的HTTP头
Nix将不可变URL记录在flake.lock中（如https://example.org/hello/<revision>.tar.gz）

协议实现细节

HTTP头规范

服务器需要返回一个特殊的HTTP Link头，格式如下：

Link: <flakeref>; rel="immutable"

其中：

<flakeref>必须用尖括号(< >)包裹
rel属性必须设置为immutable

flakeref的可选属性

flakeref可以包含以下Tarball Flake属性：

narHash：解压后Tarball的NAR哈希值（通过nix hash path计算）
- 如果提供，Nix会验证下载内容是否匹配此哈希
rev：修订版本标识符（如Git commit hash）
- 适用于Tarball是Git仓库镜像的情况
- Nix不会验证此值
revCount：修订计数
- 适用于版本控制系统中的提交计数
- Nix不会验证此值
lastModified：最后修改时间
- 对于Tarball Flakes，定义为Tarball中最新的文件时间戳

示例响应

Link: <https://example.org/hello/442793d9ec0584f6a6e82fa253850c8085bb150a.tar.gz
  ?rev=442793d9ec0584f6a6e82fa253850c8085bb150a
  &revCount=835
  &narHash=sha256-GUm8Uh/U74zFCwkvt9Mri4DSM%2BmHj3tYhXUkYpiv31M%3D>; rel="immutable"

注意：实际响应中不应包含换行符。

实际应用场景

在Gitea和Forgejo中的使用

Gitea（v1.22.1+）和Forgejo（v7.0.4/v8.0.0+）已支持此协议，URL格式为：

https://<域名>/<所有者>/<仓库>/archive/<引用或修订>.tar.gz

Flake配置示例

{
  inputs = {
    # 使用分支名称（动态）
    foo.url = "https://gitea.example.org/some-person/some-flake/archive/main.tar.gz";
    
    # 使用具体修订版本（静态）
    bar.url = "https://gitea.example.org/some-other-person/other-flake/archive/442793d9ec0584f6a6e82fa253850c8085bb150a.tar.gz";
    
    # 非Flake仓库
    qux = {
      url = "https://forgejo.example.org/another-person/some-non-flake-repo/archive/development.tar.gz";
      flake = false;
    };
  };
  outputs = { foo, bar, qux }: { /* 输出定义 */ };
}