3.4. 使用 Satis 处理私有仓库

优质

小牛编辑

129浏览

2023-12-01

私有 Packagist

Private Packagist 可以为私有的商业 packages 提供专业的托管服务，并在网页上提供对私有 packages 和公共 packages 管理，以及细粒度的权限控制。Private Packagist 会为每个 package 制作 ZIP 格式的镜像，这会让 package 安装的更快（因为压缩过了），并且由于独立于其他第三方系统，所以即便 GitHub down 了，你也可以正常进行部署，因为你的 ZIP 文件是作为镜像保存在 Private Packagist。

Private Packagist 可以作为托管 SaaS 解决方案使用，也可以作为内部部署私有 Package 的站点，并可以在网页上进行简单的设置。

Private Packagist 的一部分收入将用于支付 Composer 和 Packagist.org 的开发和托管费用，这是一种在财务上维持这些开源项目的好办法。你可以在 Packagist.com 上找到关于如何设置自己的 package 的更多信息。

Satis

另一方面，Satis是开源的，它只是一个静态的 Composer 储存库生成器。它有点类似于一个超轻量的 packagist ，可以用于托管公司的私有 packages 或者保存自己的私有 packages 。可以从 GitHub 下载或者在命令行运行以下命令：

php composer.phar create-project composer/satis --stability=dev --keep-vcs

部署

假设你现在有一些需要在公司中被多个人使用的 package，但是并不想开源。OK，然后你看上了 Satis 来解决这个问题。那么首先你需要一个 JSON 格式的 Satis 配置文件，并在上面写明你的软件源（repositories）。

下面是一份例示配置，这里在 repositories 里配置了一些 VCS 储存库，Satis 支持的 repositories 类型可以在这里找到 link 。如果你在这里配置 "require-all": true ，Satis 会将你定义的 repositories 中的全部包的全部版本都加载。

译者注：这里支持将 VCS 版本控制系统, Composer e.g. packagist.org，PEAR 和 Package中的 package 加载到 Satis 中。

Satis 默认会在所在文件夹中查找名字叫 satis.json 的文件作为配置文件。

{
  "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
}

如果你只想 Satis 去加载你想要的那些 package，你可以在 require 中指明你想要的 package，并选择你需要的版本。

译者注：这里的版本限定规则和 Composer.json 中一致，若有不明请参考 link

{
  "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 public/

推荐给 Satis 设置 cron 定时任务，这样 Satis 上的 package 就可以随时保持最新。

如果你的 package 在 GitHub 的私有仓库里，你应该在 build 命令中添加 --no-interaction (或者 -n) 参数，让它直接去验证 SSH 密钥，而不是要求输入密码。这对在脚本或者依赖 CI 的系统里面是一个较好的技巧。

译者注：如果 repositories 是来自 GitHub，那么在你的 Satis 从 GitHub 获取了一定数量的 Package 之后会被提示需要 Token，GitHub 为了防止被滥用，会有这样的限制。那么你需要在 GitHub 的个人中心里配置一个 token，设置到 Composer 上。

接着你需要配置一个指向你的 build 目录 的域名，例如 packages.example.org 指向我们刚才的 public/。如果你的 PHP版本大于 5.4.0，你也可以使用内置的 CLI 服务器，作为测试时的临时方案

php -S localhost:port -t satis-output-dir/

译者注：推荐使用 Nginx

部分更新

你可以让 Satis 只更新特定的包或者仅仅更新给定URL所指定的包。这会很大程度上减少重建 package.json文件所需要的时间（特别是需要加载很多 package 而且还需要为其解决依赖的情况下）。如果在代码推送到 repositories 后使用 webhooks 触发重建 package.json 文件的情况下，这种方式将非常有用。

使用如下命令，将仅仅查找和加载 this/package 和 that/other-package 而不会去关注别的 package 。

php bin/satis build satis.json web/ this/package that/other-package

但是请注意，这仍然会去提取和扫描所有的 VCS repositories （也就是刚刚在 satis.json 里配置的那些 repositories），因为任何 VCS repositories 都可能包含你需要的库

如果只需要扫描单个储存库并更行其中找到的所有的 package ，请将 VCS repository 的 URL 作为可选参数传递，例示如下：

php bin/satis build --repository-url https://only.my/repo.git satis.json web/

译者注：不指定 package，指定 package，指定 VCS URL 并指定 package 的区别

不指定 package：将去指定的全部的 repositories 里寻找指定的全部的package，并查看是否有新的版本需要加载或者是否有版本进行了更变。
指定 package：将去指定的全部的 repositories 里，查看指定的 package 是否有新的版本需要加载或者是否有版本进行了更变。
指定 VCS URL 并指定 package ：仅仅去指定的 VCS URL 里，查看指定的 package 是否有新的版本需要加载或者是否有版本进行了更变

用法

你需要在项目的 composer.json 里添加如下字段来使用 packages.example.org 作为这个项目的 Composer 源，这个修改的影响将仅限于这个项目，而不会影响到别的项目。

{
  "repositories": [ { "type": "composer", "url": "http://packages.example.org/" } ],
  "require": {
    "company/package": "1.2.0",
    "company/package2": "1.5.2",
    "company/package3": "dev-master"
  }
}

安全

为了保护你的私有库，你可以要求客户端使用客户端证书通过 SSH/SSL 连接 Satis。你可以在 satis.json 中的 repositories 中配置它。

通过 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"
      }
    }
  }]
}

Tip: 查阅 SSH2 配置参数了解更多信息。

使用客户端证书通过 SSL/TLS（HTTPS）的方式连接的示例：

{
  "repositories": [{
     "type": "composer",
     "url": "https://example.org",
     "options": {
       "ssl": {
         "local_cert": "/home/composer/.ssl/composer.pem"
       }
     }
  }]
}

Tip: 查阅 ssl 配置参数了解更多信息。

使用自定义的HTTP header 字段进行身份验证的示例：

{
  "repositories": [{
    "type": "composer",
    "url": "https://example.org",
    "options":  {
      "http": {
        "header": [
          "API-TOKEN: YOUR-API-TOKEN"
        ]
      }
    }
  }]
}

认证

当您的私有存储库受到密码保护时，您可以永久存储身份验证详细信息。 Composer 第一次需要对某个域进行身份验证时，它会提示您输入用户名/密码，然后会询问您是否要存储它。

存储可以在 COMPOSER_HOME/auth.json 文件中全局完成（COMPOSER_HOME 在 Windows 上默认为 ~/.composer 或 %APPDATA%/Composer ）也可以直接在 composer.json 旁边的项目目录中完成。

如果需要将生产计算机配置为能够运行非交互式安装，还可以使用 config 命令手动配置这些。例如，要输入 example.org 的凭据，可以键入：

composer config http-basic.example.org username password

这会将它存储在当前目录的 auth.json 中，但是如果您想让它全局可用，您可以使用 --global (-g) 标志。

下载

当 GitHub ，GitLab 或 BitBucket 存储库镜像到您本地时，构建过程将包括这些平台提供的下载位置。这意味着存储库和您的设置取决于这些服务的可用性。

同时，这意味着托管在其它地方（在另一个服务上或在 Subversion 中）的所有代码都将没有可用的下载，因此安装通常需要更长的时间。

为了使您的安装能够为您的所有包（Git，Mercurial 和 Subversion）创建下载，请将以下内容添加到您的 satis.json 中：

{
  "archive": {
    "directory": "dist",
    "format": "tar",
    "prefix-url": "https://amazing.cdn.example.org",
    "skip-dev": true
  }
}

选项解释

directory ：必须，dist 的位置（在 output-dir 里面）
format ：可选 zip （默认）或 tar
prefix-url ：可选，下载位置，主页（来自 satis.json）默认为 directory
skip-dev：可选，默认情况下为 false ，启用时（true）表示不会为分支创建下载
absolute-directory ：可选，一个本地目录，其中 dist 文件被转储而不是输出 output-dir/directory
whitelist ：可选，如果设置为包名称列表，则只会转储这些包的 dist 文件
blacklist ：可选，如果设置为包名称列表，则不会转储这些包的 dist 文件
checksum ：可选，默认情况下为 true ，禁用时（false）不会为 dist 文件提供 sha1 校验启用后，所有下载（包括来自 GitHub 和 BitBucket 的下载）将替换为本地版本。

prefix-url

如果下载最终位置位于私有 Amazon S3 存储桶或 CDN 主机上，则使用其他主机对 URL 进行预处理特别有用。CDN 将大大缩短下载时间，从而改善软件包安装。

例如：为 https://my-bucket.s3.amazonaws.com （和 directory 设置为 dist）的 prefix-url 创建下载 URL ，如下所示： https://my-bucket.s3.amazonaws.com/dist/vendor-package-version-ref.zip 。

网络输出

output-html ：optional ，默认情况下为 true ，当禁用（false）时不会生成 output-dir/index.html 页面。
twig-template：可选，是 output-dir/index.html 页面的个性化 Twig 模板的路径。

被遗弃的包

为了使您的安装能指示某些包已被遗弃，请将以下内容添加到您的 satis.json 文件中：

{
  "abandoned": {
    "company/package": true,
    "company/package2": "company/newpackage"
  }
}

true 值表示包被真正放弃，而 "company/newpackage" 指定包被 company/newpackage 包替换。

请注意，在自己的 composer.json 文件中设置的所有包也将被标记为已放弃。

解决依赖关系

可以自动解决并添加项目的所有依赖项。这可以与“下载”功能一起使用，以获得完整的本地镜像包。将以下内容添加到您的 satis.json 中：

{
  "require-dependencies": true,
  "require-dev-dependencies": true
}

在搜索包时，satis 将尝试从列出的存储库中解析所有必须的包。因此，如果您需要 Packagist 的软件包，则需要在 satis.json 中定义它。

仅当 require-dev-dependencies 参数设置为 true 时才打包 Dev 依赖项。

其他选择

providers：可选，默认情况下为 false 启用时（true）每个包都将被转储到一个单独的包含文件中，只有在真正需要包时才由 composer 加载。加快编译器处理存储库，如 f.i 包装的巨大数量的包。
output-dir ：可选，定义在调用 build 命令时，如果没有提供参数作为参数，则输出库文件的位置。
config ：可选，允许您定义来自 composer 的所有配置选项，除了 archive-format 和 archive-dir ，因为配置项是通过 archive 完成的。有关详细信息，请参阅 config schema 上的文档。
notify-batch ：可选，指定一个用户每次安装包时调用的 URL 。参阅 notify-batch。