用于 Conda 包的开源服务器

Quetz

Quetz 项目是一个开源的 Conda 包服务器。它是基于 FastAPI 并采用 API 首先的方法构建的。Quetz 服务器可以有多个用户、通道和包。使用 Quetz，可以在通道和包名称级别实现细粒度的权限。

Quetz 有一个可选的客户端 quetz-client，可用于将包上传到 Quetz 服务器实例。

使用方法

您应该已经安装了 mamba 或 conda。

获取 Quetz 源代码

git clone https://github.com/mamba-org/quetz.git

然后创建一个环境

cd quetz
mamba env create -f environment.yml
conda activate quetz
ln -s "${CONDA_PREFIX}" .venv  # Necessary for pyright.

安装 Quetz

如果您是开发者并且想利用 Quetz 的 reload 选项，请使用可编辑模式 -e

pip install -e .

使用 CLI 创建 Quetz 实例

quetz run test_quetz --copy-conf ./dev_config.toml --dev --reload

链接

• http://localhost:8000/ - 使用您的 github 账户登录
• http://localhost:8000/api/dummylogin/alice - 使用测试用户，例如 [alice | bob | carol | dave]
• http://localhost:8000/docs - 该 REST 服务的 Swagger UI

下载 xtensor 作为测试包

./download-test-package.sh

要上传包，请安装 quetz-client

mamba install quetz-client

要运行上传，您需要设置 quetz API 密钥（用于验证您）和 quetz 服务器 URL 的环境变量。由于我们向 quetz 传递了 --dev 标志，因此在 quetz 的输出中可以找到一个测试 API 密钥，您可以用它来演示。

export QUETZ_API_KEY=E_KaBFstCKI9hTdPM7DQq56GglRHf2HW7tQtq6si370
export QUETZ_SERVER_URL=http://localhost:8000
quetz-client post_file_to_channel channel0 xtensor/linux-64/xtensor-0.24.3-h924138e_1.tar.bz2
quetz-client post_file_to_channel channel0 xtensor/osx-64/xtensor-0.24.3-h1b54a9f_1.tar.bz2
quetz-client post_file_to_channel channel0 xtensor/osx-arm64/xtensor-0.24.3-hf86a087_1.tar.bz2

使用 conda 安装测试包

mamba install --strict-channel-priority -c http://localhost:8000/get/channel0 -c conda-forge xtensor

输出

...
  Package  Version  Build          Channel                                                     Size
─────────────────────────────────────────────────────────────────────────────────────────────────────
  Install:
─────────────────────────────────────────────────────────────────────────────────────────────────────

  xtensor   0.16.1  0              http://localhost:8000/get/channel0/osx-64                 109 KB
  xtl       0.4.16  h04f5b5a_1000  conda-forge/osx-64                                         47 KB

  Summary:

  Install: 2 packages

  Total download: 156 KB

─────────────────────────────────────────────────────────────────────────────────────────────────────
...

浏览通道： http://localhost:8000/get/channel0/

S3 后端

要启用 S3 后端，您首先需要 s3fs 库

mamba install -c conda-forge s3fs

然后，在您的 config.toml 中将您的访问密钥和秘密密钥添加到 s3 部分，如下所示

[s3]
access_key = "AKIAIOSFODNN7EXAMPLE"
secret_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
url = "https://..."
region = ""
bucket_prefix="..."
bucket_suffix="..."

如果您不使用 AWS，请确保设置 url 和 region 字段。

通道的创建具有以下语义

{bucket_prefix}{channel_name}{bucket_suffix}

S3 后端目前设计为每个通道一个存储桶。将所有通道放入一个存储桶中可能是可能的，但这需要一些代码调整。

如果您使用 IAM 角色，请不要设置 access_key 和 secret_key 或将它们设置为空字符串 ""。

Google OAuth 2.0 OpenID Connect

要启用通过 Google 的身份验证，您需要在以下位置注册一个应用程序：https://console.developers.google.com/apis/credentials

然后，将客户端密钥和 ID 添加到您的 config.toml 中的 google 部分

[google]
client_id = "EXAMPLEID420127570681-6rbcgdj683l3odc3nqearn2dr3pnaisq.apps.googleusercontent.com"
client_secret = "EXAMPLESECRETmD-7UXVCMZV3C7b-kZ9yf70"

PostgreSQL

默认情况下，Quetz 将使用 sqlite 数据库运行，这对于本地测试和较小的本地实例来说效果很好。但是，如果您计划在生产环境中运行 Quetz，我们建议您使用 PostgreSQL 数据库进行配置。在您的本地机器或生产服务器上安装 PostgreSQL 服务器有几个选项，其中之一是官方的 PostgreSQL Docker 映像。

使用 docker 运行 PostgreSQL 服务器

您可以从Docker Hub获取PostgreSQL镜像，并使用以下命令启动服务器：

docker pull postgres
docker run --name some-postgres -p 5432:5432 -e POSTGRES_PASSWORD=mysecretpassword -d postgres

这将使用用户postgres和密码mysecretpassword启动服务器，该密码将监听localhost的5432端口。

然后您可以在PostgreSQL中创建一个用于quetz表的数据库。

sudo -u postgres psql -h localhost -c 'CREATE DATABASE quetz OWNER postgres;'

使用PostgreSQL后端部署Quetz

然后在您的配置文件（如dev_config.toml）中，将[sqlalchemy]部分替换为以下内容：

[sqlalchemy]
database_url = "postgresql://postgres:mysecretpassword@localhost:5432/quetz"

最后，您可以根据此配置创建并运行一个新的quetz部署（我们假设您将其保存在文件config_postgres.toml中）。

quetz run postgres_quetz --copy-conf config_postgres.toml

请注意，此配方将创建一个短暂的PostgreSQL数据库，当some-postgres容器停止并删除后，它将删除所有数据。为了使数据持久化，请检查postgres 镜像或您的容器编排系统（Kubernetes或类似系统）的文档。

使用PostgreSQL后端运行测试

要使用PostgreSQL数据库而不是默认的SQLite运行测试，请按照上面的步骤启动PG服务器。然后创建一个新的数据库

psql -U postgres -h localhost -c 'CREATE DATABASE test_quetz OWNER postgres;'

您将被要求输入DB密码，这是您在启动PG服务器时定义的。在上面的基于docker的说明中，我们将其设置为mysecretpassword。

要使用此数据库运行测试，您需要配置QUETZ_TEST_DATABASE环境变量

QUETZ_TEST_DATABASE="postgresql://postgres:mysecretpassword@localhost:5432/test_quetz" pytest -v ./quetz/tests

前端

Quetz附带一个初始前端实现。您可以在quetz_frontend中找到它。要构建它，需要安装以下内容

mamba install 'nodejs>=14'
cd quetz_frontend
npm install
npm run build
# for development
npm run watch

这将构建javascript文件并将它们放置在/quetz_frontend/dist/中，然后它们会被quetz服务器自动获取。

使用quetz

创建一个频道

首先，请确保您已登录到Web应用。

然后，使用<deployment url>:<port>/docs中的swagger文档，将您的频道名称和描述POST到/api/channels

{
  "name": "my-channel",
  "description": "Description for my-channel",
  "private": false
}

这将创建一个新的名为my-channel的频道，您将是该频道的所有者。

生成API密钥

API密钥按频道、用户以及可选的包进行范围划分。要生成API密钥，以下条件必须成立

1. 首先，请确保您已登录到Web应用。

2. 用户必须是目标频道的成员（您可能需要先创建一个频道，请参阅上一节中关于如何通过swagger文档创建频道的内容）

3. 转到<deployment url>:<port>/docs中的swagger文档，并POST到/api/api-keys

   {
     "description": "my-test-token",
     "roles": [
       {
         "role": "owner",
         "channel": "my-channel"
       }
     ]
   }
   

4. 然后，通过GET访问/api/api-keys以检索您的令牌

5. 最后，将QUETZ_API_KEY环境变量设置为此值，以便您可以使用quetz-client与服务器交互。

创建一个代理频道

代理频道“镜像”另一个频道，通常是来自不同服务器的频道，以便可以从代理处安装包，就像直接从该服务器安装一样。所有下载的包都会在本地缓存，并且缓存始终是最新的（没有提供陈旧包的风险）。使用代理频道的原因是限制原始服务器的流量或为无法从公司防火墙访问的频道提供服务。

要创建代理频道，请在/api/channels端点的POST方法中使用属性mirror_channel_url=URL_TO_SOURCE_CHANNEL和mirror_mode='proxy'。例如，要从Anaconda Cloud服务器代理名为btel的频道，您可能需要使用以下请求数据

{
  "name": "proxy-channel",
  "private": false,
  "mirror_channel_url": "https://conda.anaconda.org/btel",
  "mirror_mode": "proxy"
}

您可以直接将数据复制到Swagger Web界面下的POST /api/channels部分，或者使用命令行的cURL工具。假设您在本地机器上部署了端口8000（默认）的quetz服务器，您可以使用以下cURL命令进行请求

export QUETZ_API_KEY=...
curl -X POST "http://localhost:8000/api/channels" \
    -H  "accept: application/json" \
    -H  "Content-Type: application/json" \
    -H  "X-API-Key: ${QUETZ_API_KEY}" \
    -d '{"name":"proxy-channel",
         "private":false,
         "mirror_channel_url":"https://conda.anaconda.org/btel",
         "mirror_mode":"proxy"}'

其中 QUETZ_API_KEY 变量的值应该是创建 quetz 部署时打印的 API 密钥，或者如第 生成 API 密钥 小节所述，使用 API 获取。

然后您可以使用 conda 或 mamba 以标准方式从通道安装软件包。

mamba install --strict-channel-priority -c http://localhost:8000/get/proxy-channel nrnpython

创建镜像通道

镜像通道是另一个通道的精确副本，通常来自不同的（anaconda 或 quetz）服务器。软件包从该服务器下载并添加到镜像通道。镜像通道支持标准的 Quetz API，但排除会添加或修改软件包的请求（例如 POST /api/channels/{name}/files）。镜像通道可用于减轻主服务器的流量，或在公司内部网络中创建通道克隆。

创建镜像通道类似于创建代理通道，除了您需要将 mirror_mode 属性的值从 proxy 更改为 mirror（显然选择一个更合适的通道名称）

{
  "name": "mirror-channel",
  "private": false,
  "mirror_channel_url": "https://conda.anaconda.org/btel",
  "mirror_mode": "mirror"
}

或者使用 cURL

export QUETZ_API_KEY=...
curl -X POST "http://localhost:8000/api/channels" \
    -H  "accept: application/json" \
    -H  "Content-Type: application/json" \
    -H  "X-API-Key: ${QUETZ_API_KEY}" \
    -d '{"name":"mirror-channel",
         "private":false,
         "mirror_channel_url":"https://conda.anaconda.org/btel",
         "mirror_mode":"mirror"}'

镜像通道是只读的（您不能在这些通道中添加或更改软件包），但除此之外，它们是完全功能性的 Quetz 通道，支持所有标准的读取（GET）操作。例如，您可以使用 GET /api/channels/{channel_name}/packages 端点列出所有软件包。

curl http://localhost:8000/api/channels/mirror-channel/packages

如果主服务器上添加或修改了原始提取的软件包，它们不会自动在镜像通道中更新。但是，您可以使用 PUT /api/channels/{channel_name}/actions 端点手动触发此类同步。

curl -X PUT localhost:8000/api/channels/mirror-channel/actions \
   -H "X-API-Key: ${QUETZ_API_KEY}" \
   -d '{"action": "synchronize"}'

只有通道所有者或维护者可以触发同步，因此您必须提供一个有效的高级用户 API 密钥。

插件

Quetz 提供了本存储库的插件文件夹中的插件以及独立安装。以下插件目前可用

许可

我们使用共享版权模式，允许所有贡献者保留其贡献的版权。

此软件根据 BSD-3-Clause 许可证进行许可。有关详细信息，请参阅 LICENSE 文件。