ccache 与 sccache 共享编译缓存

本页适用于 Depsilo v0.11.0。ccache 和 sccache 可以通过 Depsilo 在开发机与 CI 之间复用编译产物，适合多个构建节点重复编译相同输入的场景。先完成启动与首次设置，再单独启用编译缓存。

客户端	版本与协议	HTTPS 要求
ccache	建议 4.7+，HTTP remote storage	4.13+，并安装 storage helper
sccache	建议 v0.15.0+，原生 WebDAV backend	原生支持，无需 ccache helper

两种客户端使用同一套 namespace、凭据与容量管理，但缓存条目分开存储，不能互相命中。依赖包缓存与编译缓存也各自计量容量。

1. 启用服务端

在现有 config.toml 中加入下面的配置。path 使用推荐 Docker 部署已经持久化的 /root/.depsilo 目录；二进制部署请换成服务进程可写、独立于包缓存的持久化绝对路径。

[compile_cache]
enabled = true
public_url = "http://127.0.0.1:23333"
allow_insecure_http = false
max_size_gb = 20
max_entries = 500000
max_entry_size_mb = 512
namespace_max_size_gb = 20
namespace_max_entries = 250000

[compile_cache.storage]
type = "local"
path = "/root/.depsilo/data/compile-cache"

上面的地址用于本机验证。共享给其他机器时，将 public_url 改为客户端能访问的 HTTPS origin，例如 https://depsilo.example.com，并配置 TLS 反向代理。这个字段用于校验和生成客户端配置，不会自动启用 HTTPS；后端端口应只对代理、loopback 或受信网络开放。

只有明确位于可信 LAN/VPN 时，才使用远程 HTTP 并设置 allow_insecure_http = true。重启服务后，以管理员或 Operator 身份打开实例的 /admin/compile-cache。

2. 创建机器凭据

在 Admin 的「编译缓存」页面创建凭据，指定 namespace（例如 linux-ci）、权限和有效期。创建成功时保存一次性 token，以及生成的客户端配置；关闭弹窗后完整 token 不会再次显示。

权限	分配对象	行为
readwrite	受信 CI / 构建节点	读取缓存，并在 miss 后上传编译产物
readonly	只消费团队缓存的开发机	读取已有条目，miss 后不会回填远端

每个凭据只绑定一个 namespace。它与 Admin API token、首次设置用的 bootstrap token 不通用。将实际 token 存入 CI secret 或密钥管理器，不要提交到项目配置。

3. 连接客户端

下面是变量模板；所有 REPLACE_WITH_… 都需要替换为 Admin 创建凭据时提供的值。只在当前构建 shell 或对应 CI job 设置，随后按项目已有方式让编译命令经过所选客户端。

ccache

将 Admin 生成的完整 ccache_remote_storage 值放入环境变量，保留其中的 token 属性和只读选项：

export CCACHE_REMOTE_STORAGE='REPLACE_WITH_ADMIN_GENERATED_VALUE'

默认先查本地缓存，再查 Depsilo。临时 CI 节点如果只需远端缓存，可额外设置 CCACHE_REMOTE_ONLY=true；readonly 凭据的生成值已包含 read-only=true。使用默认 subdirs 或 flat 布局，不要设置 layout=bazel。

ccache 的 HTTPS 配置不同

内置 HTTP backend 只处理 http://。HTTPS 需要 ccache 4.13+，并按官方 helper 安装说明安装 ccache-storage-https。Admin 会为 HTTPS 生成带 @bearer-token 的值，不要手动改成 HTTP 使用的 bearer-token 属性。参见 ccache 4.13.6 手册。

sccache

使用 Admin 生成的 sccache endpoint 和 token，或复制它提供的 [cache.webdav] 配置。环境变量形式如下：

export SCCACHE_WEBDAV_ENDPOINT='REPLACE_WITH_ADMIN_GENERATED_ENDPOINT'
export SCCACHE_WEBDAV_TOKEN='REPLACE_WITH_CREATED_MACHINE_TOKEN'

endpoint 的路径是 /sccache/v1/<namespace>。HTTP 和 HTTPS 都由原生 WebDAV backend 处理。已经运行的 sccache daemon 需要在新环境下重启后再构建；在没有构建任务运行时执行 sccache --stop-server 和 sccache --start-server。

本页按 sccache v0.15.0 配置，不添加尚未包含在该版本中的 rw_mode 或 SCCACHE_WEBDAV_RW_MODE。该版本通过 .sccache_check 写探针检测权限；只读凭据拒绝写入后，客户端按只读 backend 使用。

设置远端地址不会自动替换构建系统中的编译器调用。确认项目确实通过 ccache 或 sccache 执行编译，再用对应的 --show-stats 查看统计。

4. 验证远端命中

第二次编译更快或显示 cache hit，都不能单独证明命中了 Depsilo。 客户端本地缓存可能已满足请求；只清零统计也不会清空本地缓存。

在 Linux 或 macOS 上，可以运行 v0.11.0 仓库提供的真实客户端验证。它要求已安装 Git、Make、ccache 4.7+、官方 sccache v0.15.0+ 和 GCC/Clang；HTTPS 还要求 ccache 4.13+ 与上述 helper。使用刚创建的 readwrite 凭据和对应 namespace 的 endpoint：

git clone --branch v0.11.0 --depth 1 https://github.com/depsilo/depsilo.git depsilo-cache-check
cd depsilo-cache-check
bash -c '
  read -rp "Namespace endpoint from Admin: " COMPILER_CACHE_ENDPOINT
  read -rsp "Readwrite token: " COMPILER_CACHE_TOKEN
  printf "\n"
  export COMPILER_CACHE_ENDPOINT COMPILER_CACHE_TOKEN
  make test-compiler-cache
'

endpoint 应以 /ccache/v1/<namespace> 或 /sccache/v1/<namespace> 结尾，不包含 ccache 的 |bearer-token=… 属性。token 通过隐藏输入传入，不会写入命令历史。

脚本为两个客户端各执行一次独立的编译 miss 和远端写入，移除隔离的本地缓存后再次编译，并通过客户端统计确认 remote hit。sccache 验证还会移除隔离的 disk L0 并重启测试 daemon，排除本地命中。缺少工具或版本过旧会失败，不会跳过；测试会在指定 namespace 留下少量可由 LRU 回收的条目。

容量与使用边界

• 独立存储与配额。 编译缓存执行全局和单 namespace 的容量、条目数限制，超限后按 LRU 回收。为上传暂存额外预留空间；默认 max_inflight_upload_size_mb 为 1024。Admin 可查看状态、撤销凭据和手动清理。
• 写入方需要受信。 有写权限的机器能影响同一 namespace 消费的编译产物。不要将 readwrite token 分配给不受信设备；撤销后后续认证失效，已通过认证的在途上传不会主动中断。
• S3 是内部存储。 可为编译缓存单独配置 S3 bucket，但 Depsilo 不提供 S3-compatible 客户端 endpoint。sccache 应连接上面的 WebDAV 路径，也不能绕过 Depsilo 直接使用该 bucket。
• 单实例运行。 不要让多个 Depsilo 实例共享编译缓存数据库、目录或 bucket。这里提供的是共享编译缓存，不是通用 WebDAV 服务或 sccache-dist 远程执行服务。

完整容量、并发、超时和存储配置见 Depsilo v0.11.0 编译缓存指南。