Документация CacheX

CacheX — это edge CDN для кэширования артефактов CI/CD. Сократите время восстановления зависимостей и промежуточных результатов сборки в несколько раз.

Ранний доступ. API находится в бета-версии. Обратная совместимость сохраняется внутри одной мажорной версии.

Быстрый старт

Установите CLI и пройдите авторизацию:

curl -fsSL https://cachex.run/install.sh | sh
bv auth login --token <ваш_токен>

Сохраните директорию в кэш:

bv save --path ./node_modules --key "npm-$(sha256sum package-lock.json | cut -d' ' -f1)" --ttl 7d

Восстановите при следующей сборке:

bv restore --path ./node_modules --key "npm-$(sha256sum package-lock.json | cut -d' ' -f1)"

Авторизация

Все запросы к API требуют заголовок Authorization:

Authorization: Bearer <BV_TOKEN>

Токены выдаются в личном кабинете после одобрения заявки на доступ. Каждый токен привязан к одному проекту и может быть отозван в любой момент.

CLI

bv save

Упаковывает директорию и загружает в ближайший edge-узел.

bv save [флаги]

  --path   <путь>     Директория или файл для кэширования (обязательно)
  --key    <ключ>     Уникальный ключ записи (обязательно)
  --ttl    <срок>     Время жизни: 1h / 6h / 1d / 7d / 30d (по умолчанию 7d)
  --no-compress       Отключить сжатие (для уже сжатых архивов)

bv restore

Восстанавливает директорию из кэша. Возвращает код 0 при попадании, 1 при промахе.

bv restore [флаги]

  --path   <путь>     Куда распаковать (обязательно)
  --key    <ключ>     Ключ записи (обязательно)
  --fallback <ключ>  Резервный ключ при промахе основного

GET — Получить артефакт

GET /api/artifacts/{key} Скачать артефакт

Возвращает бинарное содержимое архива. Запрос маршрутизируется на ближайший к клиенту edge-узел. При отсутствии ключа возвращает 404.

curl -H "Authorization: Bearer $BV_TOKEN" \
  https://cachex.run/api/artifacts/npm-abc123 \
  -o cache.tar.zst

POST — Загрузить артефакт

POST /api/artifacts/{key} Загрузить или обновить запись

Принимает бинарный поток. Опциональный заголовок X-TTL задаёт время жизни в секундах. По умолчанию 7 дней.

curl -X POST \
  -H "Authorization: Bearer $BV_TOKEN" \
  -H "X-TTL: 604800" \
  --data-binary @cache.tar.zst \
  https://cachex.run/api/artifacts/npm-abc123

DELETE — Удалить артефакт

DELETE /api/artifacts/{key} Вытеснить запись досрочно

Немедленно удаляет запись на всех репликах. Используется для принудительной инвалидации кэша при изменении lock-файла или смене версии зависимостей. Также вызывается системой автоматически по истечении TTL.

curl -X DELETE \
  -H "Authorization: Bearer $BV_TOKEN" \
  https://cachex.run/api/artifacts/npm-abc123

GitHub Actions

# .github/workflows/build.yml
- uses: cachex/cache-action@v2
  with:
    token: ${{ secrets.BV_TOKEN }}
    paths: |
      node_modules
      .next/cache
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-npm-

GitLab CI

# .gitlab-ci.yml
build:
  before_script:
    - bv restore --path node_modules --key "$CI_COMMIT_REF_SLUG-npm"
  script:
    - npm ci && npm run build
  after_script:
    - bv save --path node_modules --key "$CI_COMMIT_REF_SLUG-npm" --ttl 7d

Shell / скрипты

#!/bin/bash
KEY="npm-$(sha256sum package-lock.json | cut -d' ' -f1)"

if ! bv restore --path ./node_modules --key "$KEY"; then
  echo "Cache miss — installing..."
  npm ci
  bv save --path ./node_modules --key "$KEY" --ttl 7d
fi