Локальный кеш пакетов (pkg-cache)

Общесистемный локальный кеш для Composer (Packagist), Node/npm (и pnpm) и Python (pip, pip-tools, Poetry), позволяющий выполнять composer install, npm install и pip install / poetry install офлайн после наполнения кеша. Использует локальный сквозной прокси-сервер с автоматическим переключением на вышестоящий источник при отсутствии или повреждении кеша.

Быстрый старт (на новой машине)

1. Однократная настройка (создаёт структуру кеша, запускает прокси, проверяет зависимости):

   cd /path/to/composer-cache
   ./setup.sh
   

   Или в Windows:

   cd /d C:\path\to\composer-cache
   setup.cmd
   

   Или через CLI:

   export PATH="/path/to/composer-cache/bin:$PATH"
   pkg-cache setup
   

   В Windows добавьте bin в PATH или используйте bin\pkg-cache.cmd.

2. Для каждого проекта: укажите проекту путь к локальному прокси (переменные окружения после этого не нужны). Composer, npm и pip используют глобальную/пользовательскую конфигурацию (composer.json, .npmrc и .pip проекта не изменяются) — репозиторий не меняется для этих инструментов; только Poetry может добавить источник в pyproject.toml.

   pkg-cache setup-project /path/to/your/project
   # или из папки проекта:
   pkg-cache setup-project
   

3. Работа как обычно: запустите composer install, npm install (или pnpm install), для Python — pip install -r requirements.txt или poetry install в проекте. Прокси отдаёт данные из кеша или загружает с packagist, npm или PyPI и кеширует ответ.

4. Опционально — наполнить кеш перед переходом в офлайн:

   pkg-cache populate /path/to/project1 /path/to/project2
   

   После этого можно работать офлайн; прокси будет отдавать данные из локального кеша.

5. Опционально — автозапуск прокси при входе в систему (macOS / Windows):

   pkg-cache launchagent install
   

   Устанавливает LaunchAgent, запускающий прокси при входе в систему. Логи пишутся в ~/.local-package-cache/proxy-launchd.log. Для отключения: pkg-cache launchagent uninstall.

   В Windows используется Планировщик заданий:

   scripts\install-startup.cmd install
   

   Создаёт задачу, запускающую прокси через 30 секунд после входа в систему.

Требования

• Composer — getcomposer.org
• Node.js и npm (или pnpm) — nodejs.org или nvm
• Python — для проектов pip/Poetry: python.org, pip и опционально Poetry или pip-tools
• jq — jqlang.org/download/ — процессор JSON (опционально, улучшает отображение конфигурации Composer)
  • Windows: winget install jqlang.jq
  • macOS: brew install jq
  • Linux: apt install jq или yum install jq
• Bash (macOS/Linux) или cmd.exe (Windows)

Windows

Все команды имеют эквиваленты .cmd в Windows. Используйте их аналогично bash-версии:

bin\pkg-cache.cmd setup
bin\pkg-cache.cmd setup-project [path]
bin\pkg-cache.cmd teardown-project [path]
bin\pkg-cache.cmd populate [paths...]
bin\pkg-cache.cmd status [--verbose|-v]
bin\pkg-cache.cmd cleanup [--annihilate]
bin\pkg-cache.cmd stop

Запуск прокси напрямую:

node proxy\server.js

Установка/удаление автозапуска при входе (Планировщик заданий):

scripts\install-startup.cmd install
scripts\install-startup.cmd uninstall

Интеграционный тест:

scripts\test-composer-cache.cmd
scripts\test-composer-cache.cmd --no-cleanup

Конфигурация

Прокси-URL формируется автоматически как http://<HOST>:<PORT>.

Подключите scripts/config.sh (или scripts/config.cmd в Windows), чтобы установить эти переменные, или экспортируйте их перед запуском setup.sh или прокси.

Команды

• pkg-cache setup — Выполнить начальную настройку (setup.sh): создать корень кеша, проверить Composer/Node/npm, запустить прокси, самопроверка.
• pkg-cache setup-project [path] — Настроить проект для использования локального прокси. Composer, npm и pip используют глобальную/пользовательскую конфигурацию (файлы проекта не изменяются для этих инструментов); только Poetry может добавить источник в pyproject.toml. Если не указан путь, используется текущий каталог.
• pkg-cache teardown-project [path] — Вернуть проект к работе только через интернет (без кеша): сбрасывает настройки прокси и восстанавливает из резервных копий. Настройки Composer, npm и pip — глобальные/пользовательские, поэтому отключение затрагивает все проекты на этой машине для этих инструментов; для Poetry откат выполняется для каждого проекта отдельно. Если не указан путь, используется текущий каталог.
• pkg-cache populate [paths...] — Запустить composer install, npm ci (или pnpm install) и pip/poetry install в указанных проектах, чтобы прокси наполнил кеш. Проекты уже должны быть настроены на использование прокси (сначала выполните setup-project). Без указания путей используется текущий каталог. Автоматически определяет проекты Laravel Sail (запускает sail composer install при наличии ./vendor/bin/sail и Docker-сокета).
• pkg-cache launchagent install — (macOS) Установить LaunchAgent для автозапуска прокси при входе в систему. Использует scripts/config.sh для порта и корня кеша.
• pkg-cache launchagent uninstall — (macOS) Удалить LaunchAgent и отключить автозапуск прокси.
• pkg-cache status [--verbose | -v] — Показать сводку кеша: состояние прокси, корень кеша, дата последнего обновления, объём на диске и общее количество кешированных пакетов с разбивкой по менеджерам (Composer, Node/npm, Python). С флагом --verbose (или -v) показывает список каждого кешированного пакета с версиями.
• pkg-cache cleanup [--annihilate] — Очистка (prune) (по умолчанию): удаляет устаревшие версии пакетов — для Node/npm и Python оставляет только новейшую версию каждого пакета; Composer не очищается. --annihilate: полностью очищает кеш всех трёх менеджеров и сбрасывает cache.json.
• pkg-cache stop — Остановить прокси-сервер: находит PID процесса на настроенном порту и завершает его.

Возврат к работе только через интернет (без кеша)

Запустите pkg-cache teardown-project [path] (или ./scripts/unsetup-project.sh [path]). Эта команда отключает прокси для Composer/npm/pip/Poetry и восстанавливает конфигурацию из резервных копий (с суффиксом .pkg-cache-backup). Composer, npm и pip используют глобальную/пользовательскую конфигурацию, поэтому отключение затрагивает все проекты на этой машине для этих инструментов; Poetry откатывается для каждого проекта отдельно.

Ручные альтернативы:

• Composer: composer config --global --unset repo.packagist
• npm: восстановить пользовательский ~/.npmrc из ~/.npmrc.pkg-cache-backup
• pip: восстановить ~/.config/pip/pip.conf из pip.conf.pkg-cache-backup
• Poetry: восстановить pyproject.toml из pyproject.toml.pkg-cache-backup или удалить блок [[tool.poetry.source]] для pkg-cache

Python (pip / Poetry)

После pkg-cache setup-project pip использует прокси через пользовательскую конфигурацию ~/.config/pip/pip.conf (index URL http://127.0.0.1:<port>/pypi/simple/); файлы проекта для pip не изменяются. Poetry настраивается с записью [[tool.poetry.source]] в pyproject.toml и локальным репозиторием через poetry config repositories.pkg-cache <url> --local, так что poetry install использует прокси (Poetry остаётся привязанным к проекту).

Поиск и устранение неисправностей: “Нет кешированных пакетов” / “Последнее обновление никогда” (Composer)

Кеш заполняется только когда установка проходит через прокси. Если pkg-cache status показывает 0 пакетов Composer и “последнее обновление никогда”, проверьте:

1. Composer указывает на прокси Выполните: composer config -g repo.packagist Должен отобразиться URL вида http://127.0.0.1:4873/composer. Если отображается https://repo.packagist.org или “There is no packagist repository defined”, запустите pkg-cache setup-project снова в проекте Composer. Скрипт использует jq (если доступен) для записи глобальной конфигурации Composer в форме, отображаемой Composer; без jq установки всё равно могут использовать прокси, но composer config -g repo.packagist может не показывать его — установите jq и повторно запустите pkg-cache setup-project.

2. Прокси запущен Прокси должен быть запущен во время выполнения composer install. Запустите его через pkg-cache setup или node proxy/server.js (из папки проекта), или установите LaunchAgent: pkg-cache launchagent install.

3. Composer “не разрешает подключения к http://…” URL прокси — HTTP. Composer по умолчанию блокирует не-HTTPS репозитории. pkg-cache setup-project глобально устанавливает secure-http: false, чтобы Composer разрешил прокси. Если вы настраивали прокси вручную, выполните composer config --global secure-http false.

4. Один и тот же корень кеша везде Прокси и pkg-cache status используют LOCAL_PACKAGE_CACHE_ROOT (по умолчанию ~/.local-package-cache). Если вы запустили прокси с другим окружением (например, из папки проекта с LOCAL_PACKAGE_CACHE_ROOT=.local-package-cache), а затем запустили status без этого окружения, status будет смотреть в другой каталог. Используйте одинаковое значение в обоих местах или полагайтесь на значение по умолчанию.

После исправления вышеуказанного выполните composer install (или composer update) в проекте, использующем прокси; после этого pkg-cache status должен показать кеш Composer.

Интеграционный тест: Запустите ./scripts/test-composer-cache.sh (или scripts\test-composer-cache.cmd в Windows), чтобы запустить прокси, настроить Composer, выполнить минимальный composer update и проверить наполнение кеша. Флаг --no-cleanup оставляет тестовый каталог и работающий прокси для изучения.

Отказоустойчивость

Если кеш повреждён или прокси не отвечает, прокси переключается на вышестоящий источник (packagist.org, registry.npmjs.org, pypi.org), так что установка всё равно работает. Если процесс прокси не запущен, перезапустите его через ./setup.sh, вручную (node proxy/server.js) или используйте pkg-cache launchagent install для автозапуска при входе (macOS).

Прокси также автоматически повторяет запросы (до 2 дополнительных попыток) при ошибках EOF, разрыве соединения или сбросе соединения.

Структура проекта

• docs/ARCHITECTURE.md — Архитектура и дизайн.
• scripts/config.sh, scripts/config.cmd — Общая конфигурация (корень кеша, порт, URL прокси).
• setup.sh, setup.cmd — Начальная настройка для новой машины.
• proxy/server.js — Сквозной прокси-сервер (Composer, npm, PyPI).
• bin/pkg-cache, bin/pkg-cache.cmd — Точка входа CLI (setup, setup-project, teardown-project, populate, launchagent, status, cleanup, stop).
• bin/npmcc.cmd — Утилита Windows: запускает npm cache clean --force, затем передаёт все аргументы в npm.
• scripts/setup-project.sh, scripts/setup-project.cmd, scripts/setup-project.js — Настройка прокси для проекта (кроссплатформенный Node.js бэкенд). При обнаружении проектной конфигурации (в .npmrc, composer.json, .pip/pip.conf) автоматически переносит настройки на глобальный/пользовательский уровень.
• scripts/unsetup-project.sh, scripts/unsetup-project.cmd, scripts/unsetup-project.js — Отключение прокси для проекта (teardown-project).
• scripts/populate.sh, scripts/populate.cmd — Наполнение кеша из проекта(ов).
• scripts/install-launchagent.sh — Установка/удаление LaunchAgent для macOS (автозапуск прокси при входе).
• scripts/install-startup.cmd — Установка/удаление задачи в Планировщике заданий Windows (автозапуск прокси при входе).
• scripts/cache-status.sh, scripts/cache-status.cmd, scripts/cache-status.js — Состояние кеша (сводка и опциональный подробный список пакетов).
• scripts/cache-cleanup.sh, scripts/cache-cleanup.cmd, scripts/cache-cleanup.js — Очистка кеша (удаление старых версий или полная очистка).
• scripts/cache-stop.sh, scripts/cache-stop.cmd — Остановка прокси-сервера.
• scripts/test-composer-cache.sh, scripts/test-composer-cache.cmd — Интеграционное тестирование: прокси + настройка Composer + composer update с проверкой кеша.

Дополнительная информация

• Прокси перезаписывает URL не только registry.npmjs.org, но также registry.npmmirror.com и cdn.npmmirror.com/packages в ответах npm-метаданных, чтобы загрузки архивов проходили через локальный кеш.
• Для Python прокси перезаписывает URL https://files.pythonhosted.org в HTML/JSON-ответах PyPI на http://127.0.0.1:<port>/pypi/files/, так что pip/Poetry загружают wheel-файлы через кеш.
• В корне кеша создаётся файл cache.json, отслеживающий lastPopulate, projects и lockfileHashes.
• При настройке pkg-cache setup-project существующие файлы конфигурации автоматически сохраняются с суффиксом .pkg-cache-backup для возможности восстановления.
• pkg-cache populate автоматически определяет проекты Laravel Sail по наличию ./vendor/bin/sail и Docker-сокета, запуская sail composer install вместо обычного.