42 设置共享状态缓存镜像站

本文介绍如何设置托管共享状态产物的服务器，让连接到服务器的机器复用这些产物。

“共享状态”的概念见 Yocto Project 概述与概念手册的 Setscene 任务与共享状态一节。这些产物是默认放在共享状态目录（SSTATE_DIR ）中的文件。

本文介绍如何通过 SSTATE_MIRRORS 变量共享该目录内容。

42 使用场景

设置共享状态缓存镜像站最常见的场景，是基础设施中有一台专用机器定期构建镜像，因而频繁填充共享状态缓存目录。该机器通常属于 CI/CD 环境。

由于这台机器的共享状态目录包含加速新构建所需的大部分内容，可以将其共享给远程客户端，让它们通过网络连接机器并获取产物：

                   +---------------------+
                   |                     |
        +----------+    Build Machine    +-------------+
        |          |                     |             |
        |          +--------+------------+             |
        |                   |                          |
        |                   |                          |
        |                   |                          |
        |                   |                          |
        |                   |                          |
+-------v------+    +-------v------+           +-------v------+
|              |    |              |           |              |
|   Client 1   |    |   Client 2   |   . . .   |   Client N   |
|              |    |              |           |              |
+--------------+    +--------------+           +--------------+

这种配置假定：

客户端通过 HTTP 等协议连接服务器。实际应使用 BitBake 支持的协议，见支持的获取器。
构建机器的共享状态目录（SSTATE_DIR ）对客户端只读。
因此，客户端会在自己的共享状态目录中保存产物副本。

42 服务器设置

文件托管服务器有多种设置方式。本文使用 Python http.server 模块启动基本 HTTP 服务器作为示例。

假定服务器共享构建机器 Build Directory 中的共享状态：

build/
├── ...
├── sstate-cache/
└── ...

使用 Python http.server 模块，按如下方式启动服务器：

$ python3 -m http.server -d .../build/sstate-cache
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...

42 客户端配置

通过 configuration file 配置客户端，例如 site.conf 文件。设置连接只需要 SSTATE_MIRRORS 变量:

SSTATE_MIRRORS = "file://.* http://127.0.0.1:8000/PATH;downloadfilename=PATH"

上述内容取决于服务器配置。本例使用本地 IP 地址 127.0.0.1，即客户端与服务器在同一机器上，文件通过 8000 端口提供。

这样客户端便会从服务器下载共享状态产物。下载根据即将执行任务的签名自动进行，因此只获取相关产物。

运行一次构建后，客户端由 SSTATE_DIR 指定的本地共享状态目录中，会包含从服务器下载的文件。

42 进一步配置

建议在构建机器上同时运行哈希等价服务和共享状态镜像站，进一步加快构建。更多信息见 Yocto Project 开发任务手册的设置哈希等价服务器一节。
如果镜像站需要用户名和密码，应配置 build host，使构建系统能通过身份验证下载共享状态缓存。

推荐在 $HOME/.netrc 中设置以下参数，其中 $HOME 为 build host 上的用户主目录:
```
machine someserver.tld
login <user>
password <password>
```
此文件的权限必须设为 400 或 600，防止其他用户读取：
```
$ chmod 600 "$HOME/.netrc"
```
另一种方法是在 SSTATE_MIRRORS 的 URL 中通过 user 和 pswd 参数直接配置用户名和密码:
```
SSTATE_MIRRORS ?= "\
    file://.* https://someserver.tld/share/sstate/PATH;user=<user>;pswd=<password>;downloadfilename=PATH \
"
```
如果客户端将 BB_NO_NETWORK 设为 "1" 来禁用网络访问，可以使用 SSTATE_MIRROR_ALLOW_NETWORK 作为例外，允许从共享状态镜像站获取。

SSTATE_MIRRORS 可以指定多个共享状态来源，例如:

SSTATE_MIRRORS = "\
   file://.* https://someserver.com/PATH;downloadfilename=PATH \
   file://.* https://someotherserver.com/PATH;downloadfilename=PATH \
"

将按变量中指定的顺序搜索远程位置，查找共享状态产物。

也可以通过 file:// 获取器，从本地目录获取共享状态产物，例如 NFS 挂载目录:
```
SSTATE_MIRRORS = "file://.* file:///path/to/shared-state/PATH;downloadfilename=PATH"
```
共享状态镜像站可以结合 GPG 签名，确保下载文件的真实性。更多信息见 Yocto Project 安全手册的共享状态签名一节。
服务器共享状态目录可能随时间增大。可以使用 sstate-cache-management.py 脚本删除重复文件，也可以用标准 find 命令删除一定时间内未访问的文件。例如，删除两个月未访问的文件：
```
$ find sstate-cache/ -type f -atime +60 -delete
```

42 故障排查

确认文件是否从服务器下载，最直接的方法通常是检查服务器日志。例如， Python http.server 模块会显示如下日志：

127.0.0.1 - - [20/Jul/2026 14:36:23] "HEAD /d1/75/sstate%3Afile%3Ax86-64-v3-oe-linux%3A5.48%3Ar0%3Ax86-64-v3%3A14%3Ad175b18b8adc9cc3003edfc62f112fd421505bc715d41f36b4d04eef05d226ad_packagedata.tar.zst HTTP/1.1" 200 -
127.0.0.1 - - [20/Jul/2026 14:36:23] "HEAD /f4/11/sstate%3Aos-release%3Aall-oe-linux%3A1.0%3Ar0%3Aallarch%3A14%3Af411b2f27319283694ab13bf0d8965a7dd26428431418dfb7505f3d1cdd0dbfd_package_write_ipk.tar.zst HTTP/1.1" 404 -

某些产物可以找到，如上面的 200 返回码。另一些可能因客户端所需产物不在服务器上而找不到，此时客户端会重新构建任务及其依赖。