pkarolyi/garden-snail

Garden Snail

Garden Snail是一个自托管的Turborepo远程缓存服务器，使用https://nestjs.com/%E7%BC%96%E5%86%99%E3%80%82%E5%AE%83%E5%8F%AF%E4%BD%9C%E4%B8%BAVercel%E8%BF%9C%E7%A8%8B%E7%BC%93%E5%AD%98%E7%9A%84%E7%9B%B4%E6%8E%A5%E6%9B%BF%E4%BB%A3%E5%93%81%EF%BC%8C%E6%94%AF%E6%8C%81%E5%B0%86%E6%9E%84%E5%BB%BA%E4%BA%A7%E7%89%A9%E5%AD%98%E5%82%A8%E5%9C%A8%E6%9C%AC%E5%9C%B0%E6%88%96S3%E5%85%BC%E5%AE%B9%E5%AD%98%E5%82%A8%E4%B8%AD%E3%80%82

快速开始

最简单的启动方式是使用已发布的https://hub.docker.com/r/pkarolyi/garden-snail%E3%80%82%E8%AF%A5%E9%95%9C%E5%83%8F%E8%BF%90%E8%A1%8C%E8%BF%9C%E7%A8%8B%E7%BC%93%E5%AD%98%E6%9C%8D%E5%8A%A1%E5%99%A8%EF%BC%8C%E9%BB%98%E8%AE%A4%E7%9B%91%E5%90%AC3000%E7%AB%AF%E5%8F%A3%E3%80%82

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/%E7%9A%84%60@aws-sdk/client-s3%60%E5%AE%A2%E6%88%B7%E7%AB%AF%E5%85%BC%E5%AE%B9%E7%9A%84S3%E5%AD%98%E5%82%A8%EF%BC%8C%E4%BE%8B%E5%A6%82https://www.digitalocean.com/products/spaces%E6%88%96https://min.io/%E3%80%82

您需要创建存储桶并配置具有正确权限的用户。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/%E7%9A%84%E8%BF%9E%E6%8E%A5%E5%8F%82%E6%95%B0%E3%80%82%E5%AD%98%E5%82%A8%E6%A1%B6%EF%BC%88%60S3_BUCKET%60%EF%BC%89%E6%98%AF%E5%BF%85%E9%9C%80%E7%9A%84%E3%80%82%E7%94%A8%E6%88%B7%E5%87%AD%E8%AF%81%EF%BC%88%60S3_ACCESS_KEY_ID%60%E5%92%8C%60S3_SECRET_ACCESS_KEY%60%EF%BC%89%E6%98%AF%E5%8F%AF%E9%80%89%E7%9A%84%EF%BC%8C%E4%BD%86%E5%A6%82%E6%9E%9C%E4%B8%8D%E4%BD%BF%E7%94%A8%E5%85%B6%E4%BB%96%E6%96%B9%E5%BC%8F%E6%8F%90%E4%BE%9B%E6%A1%B6%E8%AE%BF%E9%97%AE%E6%9D%83%E9%99%90%EF%BC%8C%E5%88%99%E9%9C%80%E8%A6%81%E8%AE%BE%E7%BD%AE%E3%80%82

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

• 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%E3%80%82

示例

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/%E4%B8%AD%E7%9A%84%E9%9B%86%E6%88%90%E6%B5%8B%E8%AF%95%E6%A3%80%E6%9F%A5%E5%85%BC%E5%AE%B9%E6%80%A7%E3%80%82
• 1.1.0及更早版本不包含任何授权或速率限制功能。
• 1.2.0是首个包含认证功能的版本，速率限制尚未实现。