pkarolyi/garden-snail

Garden Snail

Garden Snail是一个自托管的Turborepo远程缓存服务器，使用https://nestjs.com/编写。它可作为Vercel远程缓存的直接替代品，支持将构建产物存储在本地或S3兼容存储中。

快速开始

最简单的启动方式是使用已发布的https://hub.docker.com/r/pkarolyi/garden-snail。该镜像运行远程缓存服务器，默认监听3000端口。

sh
docker run \
-e AUTH_TOKENS=change_this \
-e STORAGE_PROVIDER=local \
-e LOCAL_STORAGE_PATH=blobs \
-v "$(pwd)"/blobs:/garden-snail/blobs \
-p 3000:3000 \
docker.xuanyuan.run/pkarolyi/garden-snail

您也可以自行构建和运行应用，需要NodeJS 20.15.1 和 pnpm 9.5.0：

sh
pnpm install
pnpm build
node dist/main

环境变量

sh
# 必需：逗号分隔的有效令牌列表（不含空格），例如："token1,token2,token3"
AUTH_TOKENS=

# 必需：存储提供程序，"s3" 或 "local"
STORAGE_PROVIDER=

# 当提供程序为local时必需，例如："blobs" 将指向容器内的 /garden-snail/blobs
LOCAL_STORAGE_PATH=

# 当提供程序为s3时必需
S3_BUCKET=

# 当提供程序为s3时可选
S3_ACCESS_KEY_ID=
S3_SECRET_ACCESS_KEY=
S3_REGION=
S3_SESSION_TOKEN=
S3_FORCE_PATH_STYLE=
S3_ENDPOINT=

配置Turborepo使用缓存服务器

快速启动

您需要配置Turborepo以使用自托管的远程缓存服务器。验证服务器是否工作的最快方式是运行以下命令，注意team选项必须以team_开头：

sh
turbo run build --api="https://my-server.example.com" --team "team_xxxx" --token="a_valid_auth_token"

如果看到"remote caching enabled"输出，说明已成功使用缓存。同时，远程缓存服务器应会生成相关日志。

首次构建后，删除本地缓存文件（turbo@1为node_modules/.cache，turbo@2为.turbo/cache，若使用NextJs还需删除.next），然后在不做任何更改的情况下再次运行构建。您应看到"FULL TURBO"输出，表明Turborepo正在使用远程缓存下载产物而非重新构建。

长期设置

直接使用CLI标志会将令牌暴露在shell历史中，因此建议使用环境变量配置Turborepo：

sh
# 设置远程缓存的基础URL
TURBO_API=

# 团队ID（必须以"team_"开头）
TURBO_TEAMID=

# 服务器"AUTH_TOKENS"中的一个有效令牌
TURBO_TOKEN=

# 若网络连接较慢，可设置超时时间（秒，默认60）
TURBO_REMOTE_CACHE_TIMEOUT=

如果之前使用过Vercel远程缓存，请删除.turbo/config.json以确保旧设置不会干扰自定义远程缓存。

当前版本中，任何有效的AUTH_TOKEN都可访问所有团队，因此不要使用团队进行访问控制。

存储选项

您可以选择local或s3存储来保存缓存产物。两种情况下，产物均以team/hash的结构存储。

本地存储

使用local存储时，产物将保存到LOCAL_STORAGE_PATH环境变量指定的位置。默认使用的node用户仅有权访问/garden-snail目录，因此存储路径默认相对于此目录。

您可以将指定的存储路径挂载为Docker卷，以提供持久化存储。

示例

sh
docker run \
-e AUTH_TOKENS=change_this \
-e STORAGE_PROVIDER=local \
-e LOCAL_STORAGE_PATH=blobs \
-v "$(pwd)"/blobs:/garden-snail/blobs \
-p 3000:3000 \
docker.xuanyuan.run/pkarolyi/garden-snail

S3存储

s3存储驱动支持AWS S3及任何与https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/introduction/的`@aws-sdk/client-s3`客户端兼容的S3存储，例如https://www.digitalocean.com/products/spaces或https://min.io/。

您需要创建存储桶并配置具有正确权限的用户。Garden Snail需要能够上传、获取对象以及使用分块上传存储大型产物。以下是使用garden-snail-test桶的AWS策略示例：

json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AccessBucketGardenSnailTest",
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject",
        "s3:AbortMultipartUpload",
        "s3:ListMultipartUploadParts",
        "s3:ListBucketMultipartUploads"
      ],
      "Resource": "arn:aws:s3:::garden-snail-test/*"
    }
  ]
}

然后需要指定https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-s3/的连接参数。存储桶（`S3_BUCKET`）是必需的。用户凭证（`S3_ACCESS_KEY_ID`和`S3_SECRET_ACCESS_KEY`）是可选的，但如果不使用其他方式提供桶访问权限，则需要设置。

对于更高级或自定义的设置，可能需要设置以下环境变量：

• S3_REGION - 未设置时默认值为us-east-1
• S3_ENDPOINT - 使用自定义S3提供程序时需要设置
• S3_FORCE_PATH_STYLE - 某些自定义提供程序需要设置为"true"
• S3_SESSION_TOKEN - 高级凭证设置时可能需要

远程缓存服务器不会自动删除旧产物。若需限制空间使用，可考虑设置https://docs.aws.amazon.com/AmazonS3/latest/userguide/lifecycle-expire-general-***ations.html。

示例

sh
docker run \
-e AUTH_TOKENS=change_this \
-e STORAGE_PROVIDER=s3 \
-e S3_BUCKET=your_bucket \
-e S3_ACCESS_KEY_ID=your_access_key_id \
-e S3_SECRET_ACCESS_KEY=your_secret_access_key \
-p 3000:3000 \
docker.xuanyuan.run/pkarolyi/garden-snail

注意事项

• 可通过特定标签的https://github.com/pkarolyi/garden-snail/actions/中的集成测试检查兼容性。
• 1.1.0及更早版本不包含任何授权或速率限制功能。
• 1.2.0是首个包含认证功能的版本，速率限制尚未实现。