尧图网站建设 
Composer 私有包托管实战指南用 Satis 构建企业级私有仓库【免费下载链接】composerDependency Manager for PHP项目地址: https://gitcode.com/gh_mirrors/co/composer本篇技术指南聚焦 Composer 生态中的私有包托管方案核心讲解开源方案 Satis——一个轻量级、基于静态文件的 Composer 仓库生成器从satis.json配置、构建发布、增量更新到仓库安全加固SSH / TLS 客户端证书 / 自定义 Header、本地化下载archive、废弃包标记与依赖自动解析。读完本文你将能够自建一套可部署在企业内网或公网服务器的私有 Composer 仓库并让项目平滑引用私有包。文章以官方文档 handling-private-packages.md 为主线并结合本仓库Composer 源码中的实现细节加以佐证。两种私有包托管方案Private Packagist 与 Satis当团队有若干包需要跨项目复用、又不想开源时Composer 官方提供了两条私有托管路径Private Packagist商业化的包托管产品提供专业支持、基于 Web 的包管理与细粒度访问权限。它为包的 zip 文件提供镜像使安装更快且不依赖第三方系统——例如即使 GitHub 宕机由于 zip 文件已被镜像你依然可以完成部署。它既可以作为 SaaS 托管服务也提供可交互式安装的本地on-premise自托管版本。Private Packagist 的部分收入用于赞助 Composer 与 Packagist.org 的开发和托管。Satis开源方案但只是一个静态的composer仓库生成器。它就像一版超轻量、基于静态文件的 Packagist可用于托管公司私有包的元数据。两种方案的定位差异决定了选型需要托管、权限、镜像等一体化能力且愿意付费选 Private Packagist希望完全自控、免费、只求把私有包元数据静态化选 Satis。下文围绕 Satis 展开完整实操。Satis 的安装方式Satis 可以通过 Composer 从源码运行也可以以 Docker 容器方式运行# 源码方式克隆 satis 仓库后通过 composer 安装依赖 php bin/satis build 配置文件 构建输出目录在继续之前请先了解 Composer 的 仓库repositories体系——Satis 配置的核心就是列出你精选的仓库集合。Setup编写 satis.json 并构建私有仓库Satis 默认在仓库根目录寻找satis.json配置文件文件名其实可以任意命名。配置的核心是列出你要收录的仓库这里以多个 VCS 仓库为例——它们可以是 repositories 文档支持的任何类型{ name: my/repository, homepage: http://packages.example.org, repositories: [ { type: vcs, url: https://github.com/mycompany/privaterepo }, { type: vcs, url: http://svn.example.org/private/repo }, { type: vcs, url: https://github.com/mycompany/privaterepo2 } ], require-all: true }其中require-all: true表示选取所有已定义仓库中所有包的所有版本。如果你希望精准挑选包可以把想要的包列在经典的 composerrequire键中使用*约束确保选取所有版本或者用更具体的约束锁定特定版本{ repositories: [ { type: vcs, url: https://github.com/mycompany/privaterepo }, { type: vcs, url: http://svn.example.org/private/repo }, { type: vcs, url: https://github.com/mycompany/privaterepo2 } ], require: { company/package: *, company/package2: *, company/package3: 2.0.0 } }配置就绪后执行构建命令php bin/satis build configuration file build dir例如php bin/satis build satis.json web/。构建命令会抓取各 VCS 仓库、解析包元数据并在构建目录下生成 Composer 可识别的packages.json等静态文件。定期构建cron 化流程稳定后典型的做法是把该命令放进服务器上的 cron 任务让它像 Packagist 一样周期性更新所有包信息# 每天凌晨执行一次构建 0 2 * * * cd /path/to/satis php bin/satis build satis.json web/ --no-interaction两个实战要点如果私有包托管在 GitHub 上服务器应配置一个可访问这些仓库的SSH key并在命令中加上--no-interaction或-n标志确保认证回退到 ssh key 而不是交互式提示输入密码。这也是持续集成CI服务器上的推荐做法。部署时设置一个指向构建目录中web/目录的虚拟主机例如packages.example.org。临时方案可以使用 PHP 内置服务器php -S localhost:port -t satis-output-dir/要求 PHP 5.4.0。Partial Updates选择性增量构建Satis 支持只更新特定包或只处理指定 URL 的仓库从而大幅缩短重建packages.json的时间——当你在某个仓库有代码推送时配合自定义webhook 触发重建非常有用。按包名重建多个包名依次追加在命令行末尾php bin/satis build satis.json web/ this/package that/other-package注意即便如此Satis 仍然需要拉取并扫描所有VCS 仓库因为任何 VCS 仓库的任意分支都可能包含被选中的包。如果你希望只扫描被选中的包、跳过全部 VCS 仓库扫描需要为每个包声明name该优化仅对type: vcs的仓库生效{ repositories: [ { name: company/privaterepo, type: vcs, url: https://github.com/mycompany/privaterepo }, { name: private/repo, type: vcs, url: http://svn.example.org/private/repo }, { name: mycompany/privaterepo2, type: vcs, url: https://github.com/mycompany/privaterepo2 } ] }如果只想扫描单个仓库并更新其中所有包通过可选参数--repository-url传入该 VCS 仓库 URLphp bin/satis build --repository-url https://only.my/repo.git satis.json web/Usage在项目中消费私有仓库构建并部署完成后项目端只需要新增一个 Composer 仓库URL 指向packages.example.org然后直接 require 私有包即可。你不再需要在每个项目里复制一大堆仓库配置——只有一个会自我更新的统一仓库入口{ repositories: [ { type: composer, url: http://packages.example.org/ } ], require: { company/package: 1.2.0, company/package2: 1.5.2, company/package3: dev-master } }Security私有仓库的安全访问要保护私有仓库可以基于 SSH 或使用客户端证书的 SSL 托管。在项目中通过仓库定义的options参数指定连接选项。基于 SSH 的自定义仓库需要 SSH2 PECL 扩展{ repositories: [{ type: composer, url: ssh2.sftp://example.org, options: { ssh2: { username: composer, pubkey_file: /home/composer/.ssh/id_rsa.pub, privkey_file: /home/composer/.ssh/id_rsa } } }] }基于 SSL/TLSHTTPS的客户端证书{ repositories: [{ type: composer, url: https://example.org, options: { ssl: { local_cert: /home/composer/.ssl/composer.pem } } }] }基于自定义 HTTP Header 的令牌认证{ repositories: [{ type: composer, url: https://example.org, options: { http: { header: [ API-TOKEN: YOUR-API-TOKEN ] } } }] }从本仓库源码可以印证这些options的实际消费链路在 CurlDownloader.php 中local_cert被映射为 PHP cURL 的CURLOPT_SSLCERThttp.header被映射为CURLOPT_HTTPHEADER而在 BaseIO.php 中客户端证书会从配置中读取local_cert、local_pk、passphrase三个键并做过滤若缺少必需的local_cert会输出明确的警告信息。Authentication认证的多种玩法仓库访问的认证可以通过多种方式处理完整方法见官方文档 authentication-for-private-packages.md覆盖 http-basic、HTTP Bearer、自定义 Header、gitlab-oauth / gitlab-token、github-oauth、bitbucket-oauth、forgejo-token 与客户端 TLS 证书等。认证凭据可存储于项目级auth.json、全局auth.json、composer.json本身或COMPOSER_AUTH环境变量。在源码层面认证注入发生在 AuthHelper.php 的addAuthenticationOptions当配置的密码为bearer时会向请求头写入Authorization: Bearer token当密码为custom-headers时会将配置的 header 数组逐一追加到请求头中。也就是说仓库options里的自定义 Header 与全局auth.json的custom-headers最终殊途同归都会被翻译成实际发出的 HTTP 请求头。Downloads让私有仓库拥有本地化下载当 GitHub、GitLab 或 Bitbucket 仓库被镜像到本地 Satis 时构建过程会包含这些平台提供的下载dist地址——这意味着仓库和你的部署依赖于这些外部服务的可用性。与此同时托管在其他服务如 Subversion的代码则没有现成下载可用安装通常会慢得多。要启用 Satis 为所有包Git、Mercurial、Subversion生成下载在satis.json中添加{ archive: { directory: dist, format: tar, prefix-url: https://amazing.cdn.example.org, skip-dev: true } }启用后所有下载包括来自 GitHub 和 Bitbucket 的都会被替换为本地版本。archive 选项详解选项必填/默认说明directory必填dist 文件存放位置位于output-dir之内format可选默认zip压缩格式zip或tarprefix-url可选下载地址的前缀默认取satis.json中的homepage后接directoryskip-dev可选默认false设为true时不为主干分支branches生成下载absolute-directory可选一个本地目录dist 文件将输出到该目录而非output-dir/directorywhitelist可选包名列表设置后只导出这些包的 dist 文件blacklist可选包名列表设置后不导出这些包的 dist 文件checksum可选默认true设为false时不为 dist 文件提供 sha1 校验和prefix-url 实战为下载 URL 前缀指定另一主机特别适合 dist 文件落到私有 Amazon S3 bucket 或 CDN 场景——CDN 能显著提升下载速度从而加快包安装。例如prefix-url设为https://my-bucket.s3.amazonaws.com且directory为dist时生成的下载 URL 形如https://my-bucket.s3.amazonaws.com/dist/vendor-package-version-ref.zipWeb outputs控制生成页面output-html可选默认true。设为false时不生成output-dir/index.html页面。twig-template可选指定用于渲染output-dir/index.html页面的个性化模板路径。Satis 使用 Twig 模板引擎渲染该页面你可以基于默认模板定制品牌样式。Abandoned packages标记废弃包要让 Satis 在仓库中标注某些包已废弃添加如下配置{ abandoned: { company/package: true, company/package2: company/newpackage } }语义清晰true表示该包被彻底废弃而company/newpackage表示该包被company/newpackage替代。此外所有在其自身composer.json中声明为 abandoned 的包也会被自动标记为废弃。Resolving dependencies自动解析依赖Satis 可以自动解析并收录项目所需的所有依赖配合 Downloads 功能可实现完整的包本地镜像。在satis.json中添加{ require-dependencies: true, require-dev-dependencies: true }搜索包时Satis 会尝试从列出的仓库中解析所有被依赖的包。因此如果你需要依赖 Packagist 上的包就必须把它显式定义进satis.json。dev 依赖只有在require-dev-dependencies为true时才会被打包。Other options其他常用配置providers可选默认false。启用true后每个包会被导出到独立的 include 文件仅在真正被 require 时由 Composer 加载。对于像 packagist 这样拥有海量包的仓库能显著加速 Composer 的处理。output-dir可选定义构建输出目录。若在调用build命令时未提供输出目录参数则使用此配置。config可选允许你定义 Composer 的所有 config 选项但archive-format与archive-dir除外它们通过上文 archive 配置而非 composer config详见 config schema。notify-batch可选指定一个 URL每当用户安装包时该 URL 会被调用。详见 notify-batch 一节。关于notify-batch的底层实现可从 ComposerRepository.php 中印证读取仓库元数据时若存在notify-batch字段则将其规范化canonicalizeUrl后保存为仓库的通知 URL旧版 Composer 仓库使用的notify字段同样被兼容读取并在输出时以notification-url的形式出现在下载请求中供仓库服务端统计下载/安装事件。小结至此你已经掌握了用 Satis 搭建私有 Composer 仓库的完整链路编写satis.jsonrequire-all 或精准 require、通过build命令构建并用 cron --no-interaction自动化、借助 Partial Updates 与 webhook 实现增量重建、通过archive让所有包拥有本地/ CDN 化的 dist 下载再用 SSH / TLS 客户端证书 / 自定义 Header / 各类 OAuth token 加固访问。最后配合 authentication-for-private-packages.md 中关于auth.json与COMPOSER_AUTH的认证细节即可在企业环境中安全、高效地分发私有包。【免费下载链接】composerDependency Manager for PHP项目地址: https://gitcode.com/gh_mirrors/co/composer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Composer 私有包托管实战指南：用 Satis 构建企业级私有仓库
Composer 私有包托管实战指南用 Satis 构建企业级私有仓库【免费下载链接】composerDependency Manager for PHP项目地址: https://gitcode.com/gh_mirrors/co/composer本篇技术指南聚焦 Composer 生态中的私有包托管方案核心讲解开源方案 Satis——一个轻量级、基于静态文件的 Composer 仓库生成器从satis.json配置、构建发布、增量更新到仓库安全加固SSH / TLS 客户端证书 / 自定义 Header、本地化下载archive、废弃包标记与依赖自动解析。读完本文你将能够自建一套可部署在企业内网或公网服务器的私有 Composer 仓库并让项目平滑引用私有包。文章以官方文档 handling-private-packages.md 为主线并结合本仓库Composer 源码中的实现细节加以佐证。两种私有包托管方案Private Packagist 与 Satis当团队有若干包需要跨项目复用、又不想开源时Composer 官方提供了两条私有托管路径Private Packagist商业化的包托管产品提供专业支持、基于 Web 的包管理与细粒度访问权限。它为包的 zip 文件提供镜像使安装更快且不依赖第三方系统——例如即使 GitHub 宕机由于 zip 文件已被镜像你依然可以完成部署。它既可以作为 SaaS 托管服务也提供可交互式安装的本地on-premise自托管版本。Private Packagist 的部分收入用于赞助 Composer 与 Packagist.org 的开发和托管。Satis开源方案但只是一个静态的composer仓库生成器。它就像一版超轻量、基于静态文件的 Packagist可用于托管公司私有包的元数据。两种方案的定位差异决定了选型需要托管、权限、镜像等一体化能力且愿意付费选 Private Packagist希望完全自控、免费、只求把私有包元数据静态化选 Satis。下文围绕 Satis 展开完整实操。Satis 的安装方式Satis 可以通过 Composer 从源码运行也可以以 Docker 容器方式运行# 源码方式克隆 satis 仓库后通过 composer 安装依赖 php bin/satis build 配置文件 构建输出目录在继续之前请先了解 Composer 的 仓库repositories体系——Satis 配置的核心就是列出你精选的仓库集合。Setup编写 satis.json 并构建私有仓库Satis 默认在仓库根目录寻找satis.json配置文件文件名其实可以任意命名。配置的核心是列出你要收录的仓库这里以多个 VCS 仓库为例——它们可以是 repositories 文档支持的任何类型{ name: my/repository, homepage: http://packages.example.org, repositories: [ { type: vcs, url: https://github.com/mycompany/privaterepo }, { type: vcs, url: http://svn.example.org/private/repo }, { type: vcs, url: https://github.com/mycompany/privaterepo2 } ], require-all: true }其中require-all: true表示选取所有已定义仓库中所有包的所有版本。如果你希望精准挑选包可以把想要的包列在经典的 composerrequire键中使用*约束确保选取所有版本或者用更具体的约束锁定特定版本{ repositories: [ { type: vcs, url: https://github.com/mycompany/privaterepo }, { type: vcs, url: http://svn.example.org/private/repo }, { type: vcs, url: https://github.com/mycompany/privaterepo2 } ], require: { company/package: *, company/package2: *, company/package3: 2.0.0 } }配置就绪后执行构建命令php bin/satis build configuration file build dir例如php bin/satis build satis.json web/。构建命令会抓取各 VCS 仓库、解析包元数据并在构建目录下生成 Composer 可识别的packages.json等静态文件。定期构建cron 化流程稳定后典型的做法是把该命令放进服务器上的 cron 任务让它像 Packagist 一样周期性更新所有包信息# 每天凌晨执行一次构建 0 2 * * * cd /path/to/satis php bin/satis build satis.json web/ --no-interaction两个实战要点如果私有包托管在 GitHub 上服务器应配置一个可访问这些仓库的SSH key并在命令中加上--no-interaction或-n标志确保认证回退到 ssh key 而不是交互式提示输入密码。这也是持续集成CI服务器上的推荐做法。部署时设置一个指向构建目录中web/目录的虚拟主机例如packages.example.org。临时方案可以使用 PHP 内置服务器php -S localhost:port -t satis-output-dir/要求 PHP 5.4.0。Partial Updates选择性增量构建Satis 支持只更新特定包或只处理指定 URL 的仓库从而大幅缩短重建packages.json的时间——当你在某个仓库有代码推送时配合自定义webhook 触发重建非常有用。按包名重建多个包名依次追加在命令行末尾php bin/satis build satis.json web/ this/package that/other-package注意即便如此Satis 仍然需要拉取并扫描所有VCS 仓库因为任何 VCS 仓库的任意分支都可能包含被选中的包。如果你希望只扫描被选中的包、跳过全部 VCS 仓库扫描需要为每个包声明name该优化仅对type: vcs的仓库生效{ repositories: [ { name: company/privaterepo, type: vcs, url: https://github.com/mycompany/privaterepo }, { name: private/repo, type: vcs, url: http://svn.example.org/private/repo }, { name: mycompany/privaterepo2, type: vcs, url: https://github.com/mycompany/privaterepo2 } ] }如果只想扫描单个仓库并更新其中所有包通过可选参数--repository-url传入该 VCS 仓库 URLphp bin/satis build --repository-url https://only.my/repo.git satis.json web/Usage在项目中消费私有仓库构建并部署完成后项目端只需要新增一个 Composer 仓库URL 指向packages.example.org然后直接 require 私有包即可。你不再需要在每个项目里复制一大堆仓库配置——只有一个会自我更新的统一仓库入口{ repositories: [ { type: composer, url: http://packages.example.org/ } ], require: { company/package: 1.2.0, company/package2: 1.5.2, company/package3: dev-master } }Security私有仓库的安全访问要保护私有仓库可以基于 SSH 或使用客户端证书的 SSL 托管。在项目中通过仓库定义的options参数指定连接选项。基于 SSH 的自定义仓库需要 SSH2 PECL 扩展{ repositories: [{ type: composer, url: ssh2.sftp://example.org, options: { ssh2: { username: composer, pubkey_file: /home/composer/.ssh/id_rsa.pub, privkey_file: /home/composer/.ssh/id_rsa } } }] }基于 SSL/TLSHTTPS的客户端证书{ repositories: [{ type: composer, url: https://example.org, options: { ssl: { local_cert: /home/composer/.ssl/composer.pem } } }] }基于自定义 HTTP Header 的令牌认证{ repositories: [{ type: composer, url: https://example.org, options: { http: { header: [ API-TOKEN: YOUR-API-TOKEN ] } } }] }从本仓库源码可以印证这些options的实际消费链路在 CurlDownloader.php 中local_cert被映射为 PHP cURL 的CURLOPT_SSLCERThttp.header被映射为CURLOPT_HTTPHEADER而在 BaseIO.php 中客户端证书会从配置中读取local_cert、local_pk、passphrase三个键并做过滤若缺少必需的local_cert会输出明确的警告信息。Authentication认证的多种玩法仓库访问的认证可以通过多种方式处理完整方法见官方文档 authentication-for-private-packages.md覆盖 http-basic、HTTP Bearer、自定义 Header、gitlab-oauth / gitlab-token、github-oauth、bitbucket-oauth、forgejo-token 与客户端 TLS 证书等。认证凭据可存储于项目级auth.json、全局auth.json、composer.json本身或COMPOSER_AUTH环境变量。在源码层面认证注入发生在 AuthHelper.php 的addAuthenticationOptions当配置的密码为bearer时会向请求头写入Authorization: Bearer token当密码为custom-headers时会将配置的 header 数组逐一追加到请求头中。也就是说仓库options里的自定义 Header 与全局auth.json的custom-headers最终殊途同归都会被翻译成实际发出的 HTTP 请求头。Downloads让私有仓库拥有本地化下载当 GitHub、GitLab 或 Bitbucket 仓库被镜像到本地 Satis 时构建过程会包含这些平台提供的下载dist地址——这意味着仓库和你的部署依赖于这些外部服务的可用性。与此同时托管在其他服务如 Subversion的代码则没有现成下载可用安装通常会慢得多。要启用 Satis 为所有包Git、Mercurial、Subversion生成下载在satis.json中添加{ archive: { directory: dist, format: tar, prefix-url: https://amazing.cdn.example.org, skip-dev: true } }启用后所有下载包括来自 GitHub 和 Bitbucket 的都会被替换为本地版本。archive 选项详解选项必填/默认说明directory必填dist 文件存放位置位于output-dir之内format可选默认zip压缩格式zip或tarprefix-url可选下载地址的前缀默认取satis.json中的homepage后接directoryskip-dev可选默认false设为true时不为主干分支branches生成下载absolute-directory可选一个本地目录dist 文件将输出到该目录而非output-dir/directorywhitelist可选包名列表设置后只导出这些包的 dist 文件blacklist可选包名列表设置后不导出这些包的 dist 文件checksum可选默认true设为false时不为 dist 文件提供 sha1 校验和prefix-url 实战为下载 URL 前缀指定另一主机特别适合 dist 文件落到私有 Amazon S3 bucket 或 CDN 场景——CDN 能显著提升下载速度从而加快包安装。例如prefix-url设为https://my-bucket.s3.amazonaws.com且directory为dist时生成的下载 URL 形如https://my-bucket.s3.amazonaws.com/dist/vendor-package-version-ref.zipWeb outputs控制生成页面output-html可选默认true。设为false时不生成output-dir/index.html页面。twig-template可选指定用于渲染output-dir/index.html页面的个性化模板路径。Satis 使用 Twig 模板引擎渲染该页面你可以基于默认模板定制品牌样式。Abandoned packages标记废弃包要让 Satis 在仓库中标注某些包已废弃添加如下配置{ abandoned: { company/package: true, company/package2: company/newpackage } }语义清晰true表示该包被彻底废弃而company/newpackage表示该包被company/newpackage替代。此外所有在其自身composer.json中声明为 abandoned 的包也会被自动标记为废弃。Resolving dependencies自动解析依赖Satis 可以自动解析并收录项目所需的所有依赖配合 Downloads 功能可实现完整的包本地镜像。在satis.json中添加{ require-dependencies: true, require-dev-dependencies: true }搜索包时Satis 会尝试从列出的仓库中解析所有被依赖的包。因此如果你需要依赖 Packagist 上的包就必须把它显式定义进satis.json。dev 依赖只有在require-dev-dependencies为true时才会被打包。Other options其他常用配置providers可选默认false。启用true后每个包会被导出到独立的 include 文件仅在真正被 require 时由 Composer 加载。对于像 packagist 这样拥有海量包的仓库能显著加速 Composer 的处理。output-dir可选定义构建输出目录。若在调用build命令时未提供输出目录参数则使用此配置。config可选允许你定义 Composer 的所有 config 选项但archive-format与archive-dir除外它们通过上文 archive 配置而非 composer config详见 config schema。notify-batch可选指定一个 URL每当用户安装包时该 URL 会被调用。详见 notify-batch 一节。关于notify-batch的底层实现可从 ComposerRepository.php 中印证读取仓库元数据时若存在notify-batch字段则将其规范化canonicalizeUrl后保存为仓库的通知 URL旧版 Composer 仓库使用的notify字段同样被兼容读取并在输出时以notification-url的形式出现在下载请求中供仓库服务端统计下载/安装事件。小结至此你已经掌握了用 Satis 搭建私有 Composer 仓库的完整链路编写satis.jsonrequire-all 或精准 require、通过build命令构建并用 cron --no-interaction自动化、借助 Partial Updates 与 webhook 实现增量重建、通过archive让所有包拥有本地/ CDN 化的 dist 下载再用 SSH / TLS 客户端证书 / 自定义 Header / 各类 OAuth token 加固访问。最后配合 authentication-for-private-packages.md 中关于auth.json与COMPOSER_AUTH的认证细节即可在企业环境中安全、高效地分发私有包。【免费下载链接】composerDependency Manager for PHP项目地址: https://gitcode.com/gh_mirrors/co/composer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考