Red Hat Quay 故障排除

Red Hat Quay 3.14

Red Hat Quay 故障排除

Red Hat OpenShift Documentation Team

法律通告

摘要

Red Hat Quay 故障排除

前言

红帽提供管理员用于为您的 Red Hat Quay 部署收集数据的工具。您可以使用此数据自行对 Red Hat Quay 部署进行故障排除，或提交一个支持问题单。

第 1 章获取支持

如果您在执行本文档所述的某个流程或 Red Hat Quay 时遇到问题，请访问红帽客户门户。通过红帽客户门户网站：

搜索或者浏览红帽知识库，了解与红帽产品相关的文章和解决方案。
提交问题单给红帽支持。
访问其他产品文档。

要识别部署的问题，您可以使用 Red Hat Quay 调试工具，或者检查部署的健康端点，以获取有关问题的信息。在对部署进行调试或获取健康信息后，您可以在解决方案或提交支持票据中搜索红帽知识库。

如果您对本文档有任何改进建议，或发现了任何错误，请向 ProjectQuay 项目提交 JIRA 问题。提供具体详情，如章节名称和 Red Hat Quay 版本。

1.1. 关于红帽知识库

红帽知识库提供丰富的内容以帮助您最大程度地利用红帽的产品和技术。红帽知识库包括文章、产品文档和视频，概述了安装、配置和使用红帽产品的最佳实践。另外，您还可以搜索已知问题的解决方案，其提供简洁的根原因描述和补救措施。

Red Hat Quay 支持团队还为 Red Hat Quay 维护一个整合的故障排除文档，该文章详细介绍了常见问题的解决方案。这是一个演进的文档，可帮助用户有效地导航各种问题。

1.2. 搜索红帽知识库

如果出现 Red Hat Quay 问题，您可以执行初始搜索来确定红帽知识库中是否已存在解决方案。

先决条件

您有红帽客户门户网站帐户。

流程

登录到红帽客户门户网站。
在主红帽客户门户网站搜索字段中，输入与问题相关的关键字和字符串，包括：
- Red Hat Quay 组件( 如数据库)
- 相关步骤（比如安装）
- 警告、错误消息和其他与输出与特定的问题相关
点 Search。
选择 Red Hat Quay 产品过滤器。
在内容类型过滤中选择 Knowledgebase。

1.3. 提交支持问题单

先决条件

您有红帽客户门户网站帐户。
您有红帽标准订阅或高级订阅。

步骤

登录到红帽客户门户网站并选择 Open a 支持问题单。
选择 Troubleshoot 选项卡。
对于 Summary，输入简洁但描述性的问题概述，以及所遇到症状的更多详情，以及您的预期。
查看推荐的红帽知识库解决方案列表，它们可能会与您要报告的问题相关。如果建议的文章没有解决这个问题，请继续以下步骤。
对于产品，请选择 Red Hat Quay。
选择您使用的 Red Hat Quay 版本。
点 Continue。
可选。拖放、粘贴或浏览以上传文件。这可以是从 Red Hat Quay 部署收集的调试日志。
点 Get support 来提交您的票据。

第 2 章以 debug 模式运行 Red Hat Quay

红帽建议在提交支持问题单时收集您的调试信息。以 debug 模式运行 Red Hat Quay 提供了详细日志记录，以帮助管理员找到有关各种问题的更多信息。启用调试模式可以加快重复错误的过程，并验证解决方案，如地理复制部署、Operator 部署、独立的 Red Hat Quay 部署、对象存储问题等。另外，这有助于红帽支持执行根本原因分析。

2.1. Red Hat Quay 调试变量

Red Hat Quay 提供了两个配置字段，它们可添加到 config.yaml 文件中，以帮助诊断问题或帮助获取日志信息。

表 2.1. 调试配置变量
变量	类型	描述
DEBUGLOG	布尔值	是否启用或禁用调试日志。必须为 `true` 或 `false`。
USERS_DEBUG	整数.`0` 或 `1`。	用于以明文中调试 LDAP 操作，包括密码。必须与 `DEBUGLOG=TRUE` 一起使用。重要设置 `USERS_DEBUG=1` 以明文形式公开凭据。该变量应该在调试后从 Red Hat Quay 部署中删除。使用此环境变量生成的日志文件应该被清理，在发送到其他用户前应删除密码。请谨慎使用。

2.2. 以 debug 模式运行独立的 Red Hat Quay 部署

以 debug 模式运行 Red Hat Quay 提供了详细日志记录，以帮助管理员找到有关各种问题的更多信息。启用调试模式可加快进程重现错误并验证解决方案。

使用以下步骤以 debug 模式运行独立 Red Hat Quay 部署。

步骤

输入以下命令以 debug 模式运行独立 Red Hat Quay 部署：

$ podman run -p 443:8443 -p 80:8080 -e DEBUGLOG=true  -v /config:/conf/stack -v /storage:/datastorage -d {productrepo}/{quayimage}:{productminv}

要查看调试日志，请输入以下命令：
```
$ podman logs <quay_container_name>
```

2.3. 以 debug 模式运行 LDAP Red Hat Quay 部署

使用以下步骤以 debug 模式运行 Red Hat Quay 的 LDAP 部署。

步骤

输入以下命令以 debug 模式运行 LDAP Red Hat Quay 部署：

$ podman run -p 443:8443 -p 80:8080 -e DEBUGLOG=true -e USERS_DEBUG=1  -v /config:/conf/stack -v /storage:/datastorage -d {productrepo}/{quayimage}:{productminv}

要查看调试日志，请输入以下命令：
```
$ podman logs <quay_container_name>
```
重要
设置 USERS_DEBUG=1 以明文形式公开凭据。该变量应该在调试后从 Red Hat Quay 部署中删除。使用此环境变量生成的日志文件应该被清理，在发送到其他用户前应删除密码。请谨慎使用。

2.4. 以 debug 模式运行 Red Hat Quay Operator

使用以下步骤以 debug 模式运行 Red Hat Quay Operator。

步骤

输入以下命令来编辑 QuayRegistry 自定义资源定义：

$ oc edit quayregistry <quay_registry_name> -n <quay_namespace>

更新 QuayRegistry 以添加以下参数：

spec:
  - kind: quay
    managed: true
    overrides:
      env:
      - name: DEBUGLOG
        value: "true"

在 Red Hat Quay Operator 在启用了调试的情况下重启后，尝试从 registry 中拉取镜像。如果仍较慢，将所有日志从所有 Quay pod 转储到文件，并检查这些文件以了解更多信息。

第 3 章 Red Hat Quay 的日志信息

使用获取日志信息对于管理、监控和故障排除容器或 pod 中运行的应用程序的各种方法都很有用。获取日志信息的一些原因包括：

调试和故障排除 ：日志可让您了解应用程序内发生的情况，允许开发人员和系统管理员识别和解决问题。通过分析日志消息，可以识别应用程序执行期间可能发生的错误、异常、警告或意外行为。
性能监控 ：监控日志有助于跟踪应用程序及其组件的性能。监控响应时间、请求率和资源利用率等指标有助于优化和扩展应用程序来满足需求。
安全分析 ：日志在审核和检测潜在安全漏洞方面至关重要。通过分析日志，可以识别日志、可疑的活动、未经授权的访问尝试或任何异常行为，有助于检测和响应安全威胁。
跟踪用户行为 ：在某些情况下，日志可用于跟踪用户活动和行为。对于处理敏感数据的应用程序，这尤其重要，其中跟踪用户操作对审计和合规性很有用。
容量规划 ：日志数据可用于了解资源利用率模式，从而有助于容量规划。通过分析日志，可以识别峰值使用周期，预见资源需求，并相应地优化基础架构。
错误分析 ：发生错误时，日志可以提供导致错误所发生情况的有价值的上下文。这有助于了解问题的根本原因，并促进调试过程。
验证部署 ：在部署过程中的日志记录可帮助验证应用程序是否已正确启动，以及所有组件是否都按预期工作。
持续集成/持续部署(CI/CD) ：在 CI/CD 管道中，日志记录对于捕获构建和部署状态非常重要，允许团队监控每个阶段的成功或失败。

3.1. 获取 Red Hat Quay 的日志信息

可为所有类型的 Red Hat Quay 部署获取日志信息，包括地理复制部署、独立部署和 Operator 部署。也可以为已镜像的存储库获取日志信息。它可帮助您对身份验证和授权问题进行故障排除，以及对象存储问题。获得必要的日志信息后，您可以搜索 Red Hat Knowledgebase for a solution，或使用 Red Hat Support 团队提交支持问题单。

使用以下步骤获取 Red Hat Quay 部署的日志。

步骤

如果您在 OpenShift Container Platform 上使用 Red Hat Quay Operator，请输入以下命令来查看日志：
```
$ oc logs <quay_pod_name>
```

如果您在独立的 Red Hat Quay 部署中，请输入以下命令：

$ podman logs <quay_container_name>

输出示例

...
gunicorn-web stdout | 2023-01-20 15:41:52,071 [205] [DEBUG] [app] Starting request: urn:request:0d88de25-03b0-4cf9-b8bc-87f1ac099429 (/oauth2/azure/callback) {'X-Forwarded-For': '174.91.79.124'}
...

3.2. 检查详细日志

但是，Red Hat Quay 没有详细日志，但执行以下步骤，您可以获取数据库 pod 或容器的详细状态检查。

注意

如果您使用以下方法之一部署了 Red Hat Quay，则可以返回额外的调试信息：

您已通过传递 DEBUGLOG=true 变量来部署 Red Hat Quay。
您已通过传递 DEBUGLOG=true 和 USERS_DEBUG=1 变量，启用了 LDAP 身份验证部署 Red Hat Quay。
您已通过更新 QuayRegistry 资源在 OpenShift Container Platform 上配置 Red Hat Quay，使其包含 DEBUGLOG=true。

如需更多信息，请参阅"以 debug 模式运行 Red Hat Quay"。

步骤

输入以下命令检查详细的数据库日志。

如果您在 OpenShift Container Platform 上使用 Red Hat Quay Operator，请输入以下命令：

$ oc logs <quay_pod_name> --previous

$ oc logs <quay_pod_name> --previous -c <container_name>

$ oc cp <quay_pod_name>:/var/lib/pgsql/data/userdata/log/* /path/to/desired_directory_on_host

如果使用独立部署 Red Hat Quay，请输入以下命令：

$ podman logs <quay_container_id> --previous

$ podman logs <quay_container_id> --previous -c <container_name>

$ podman cp <quay_container_id>:/var/lib/pgsql/data/userdata/log/* /path/to/desired_directory_on_host

第 4 章 Red Hat Quay 的配置信息

检查配置 YAML 可帮助识别和解决与 Red Hat Quay 配置相关的各种问题。检查配置 YAML 可帮助您解决问题：

配置参数不正确 ：如果数据库按预期运行或遇到性能问题，您的配置参数可能处于故障状态。通过检查配置 YAML，管理员可以确保正确设置所有必需的参数，并与数据库的预期设置匹配。
资源限值 ：配置 YAML 可能会为数据库指定资源限值，如内存和 CPU 限制。如果数据库在资源约束中运行，或者与其他服务竞争，调整这些限制可帮助优化资源分配并提高整体性能。
连接问题：更正配置 YAML 中的网络设置可能会导致应用程序和数据库间的连接问题。确保存在正确的网络配置可以解决与连接和通信相关的问题。
数据存储和路径 ：配置 YAML 可能包含用于存储数据和日志的路径。如果路径配置错误或无法访问，数据库可能会在读取或写入数据时遇到错误，从而导致操作问题。
身份验证和安全性 ：配置 YAML 可能包含身份验证设置，包括用户名、密码和访问控制。验证这些设置对于维护数据库安全性并确保只有授权用户有权访问至关重要。
插件和扩展设置 ：一些数据库支持增强功能的扩展或插件。如果这些插件配置不正确或未正确加载，则可能会出现问题。检查配置 YAML 可帮助识别插件设置中的任何问题。
复制和高可用性设置：在集群或复制的数据库设置中，配置 YAML 可以定义复制设置和 高可用性配置。错误设置可能会导致数据不一致和系统不稳定。
备份和恢复选项 ：配置 YAML 可能包含备份和恢复选项，指定如何执行数据备份以及在失败时如何恢复数据。验证这些设置可确保数据安全性和成功恢复过程。

通过检查您的配置 YAML，Red Hat Quay 管理员可以在对应用程序或服务造成大量中断前检测和解决这些问题。

4.1. 获取 Red Hat Quay 的配置信息

可为所有类型的 Red Hat Quay 部署获取配置信息，包括独立、Operator 和异地复制部署。获取配置信息可帮助您解决与身份验证和授权、数据库、对象存储和存储库镜像相关的问题。获取必要的配置信息后，您可以更新 config.yaml 文件，搜索红帽知识库中的解决方案，或使用红帽支持团队提交支持问题单。

步骤

要获取 Red Hat Quay Operator 部署的配置信息，您可以使用 oc exec、oc cp 或 oc rsync。

要使用 oc exec 命令，请输入以下命令：
```
$ oc exec -it <quay_pod_name> -- cat /conf/stack/config.yaml
```
此命令将 config.yaml 文件直接返回到您的终端。
要使用 oc copy 命令，请输入以下命令：
```
$ oc cp <quay_pod_name>:/conf/stack/config.yaml /tmp/config.yaml
```
要在终端中显示此信息，请输入以下命令：
```
$ cat /tmp/config.yaml
```

要使用 oc rsync 命令，请输入以下命令：

oc rsync <quay_pod_name>:/conf/stack/ /tmp/local_directory/

要在终端中显示此信息，请输入以下命令：

$ cat /tmp/local_directory/config.yaml

输出示例

DISTRIBUTED_STORAGE_CONFIG:
local_us:
- RHOCSStorage
- access_key: redacted
  bucket_name: lht-quay-datastore-68fff7b8-1b5e-46aa-8110-c4b7ead781f5
  hostname: s3.openshift-storage.svc.cluster.local
  is_secure: true
  port: 443
  secret_key: redacted
  storage_path: /datastorage/registry
DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS:
- local_us
DISTRIBUTED_STORAGE_PREFERENCE:
- local_us

要获取独立 Red Hat Quay 部署的配置信息，您可以使用 podman cp 或 podman exec。

要使用 podman copy 命令，请输入以下命令：

$ podman cp <quay_container_id>:/conf/stack/config.yaml /tmp/local_directory/

要在终端中显示此信息，请输入以下命令：

$ cat /tmp/local_directory/config.yaml

要使用 podman exec，请输入以下命令：

$ podman exec -it <quay_container_id> cat /conf/stack/config.yaml

输出示例

BROWSER_API_CALLS_XHR_ONLY: false
ALLOWED_OCI_ARTIFACT_TYPES:
    application/vnd.oci.image.config.v1+json:
        - application/vnd.oci.image.layer.v1.tar+zstd
    application/vnd.sylabs.sif.config.v1+json:
        - application/vnd.sylabs.sif.layer.v1+tar
AUTHENTICATION_TYPE: Database
AVATAR_KIND: local
BUILDLOGS_REDIS:
    host: quay-server.example.com
    password: strongpassword
    port: 6379
DATABASE_SECRET_KEY: 05ee6382-24a6-43c0-b30f-849c8a0f7260
DB_CONNECTION_ARGS: {}
---

4.2. 获取数据库配置信息

您可以按照以下流程获取有关数据库的配置信息。

警告

与 PostgreSQL 数据库交互可能具有破坏性。强烈建议您通过 Red Hat Quay 支持专家执行以下步骤。

步骤

如果您在 OpenShift Container Platform 上使用 Red Hat Quay Operator，请输入以下命令：
```
$ oc exec -it <database_pod> -- cat /var/lib/pgsql/data/userdata/postgresql.conf
```

如果使用独立部署 Red Hat Quay，请输入以下命令：

$ podman exec -it <database_container> cat /var/lib/pgsql/data/userdata/postgresql.conf

第 5 章在 Red Hat Quay 部署中执行健康检查

健康检查机制旨在评估系统、服务或组件的健康状态和功能。健康检查有助于确保一切正常工作，并可用于在潜在问题成为关键问题前识别潜在的问题。通过监控系统的健康状况，Red Hat Quay 管理员可以处理异常或潜在的故障，如地理复制部署、Operator 部署、独立 Red Hat Quay 部署、对象存储问题等。执行健康检查还有助于降低遇到故障排除场景的可能性。

健康检查机制可以通过提供有关系统当前状态的宝贵信息来诊断问题的角色。通过将健康检查结果与预期基准或预定义的阈值进行比较，可以更快地识别或异常情况。

5.1. Red Hat Quay 健康检查端点

重要

这里包含的任何外部网站的链接仅为方便用户而提供。红帽没有审阅链接的内容，并不对其内容负责。包含任何指向外部网站的链接并不表示红帽认可网站或其实体、产品或服务。您同意红帽对因您使用（或依赖）外部网站或内容而导致的任何损失或费用不承担任何责任。

Red Hat Quay 有几个健康检查端点。下表显示了健康检查、描述、端点和示例输出。

表 5.1. 健康检查端点
健康检查	描述	端点	输出示例
`实例`	`实例` 端点获取特定 Red Hat Quay 实例的整个状态。为以下内容返回带有键值对的字典： `auth`、`database`、`disk_space`、`registry_gunicorn`、`service_key`、和 `web_gunicorn。` 返回一个数字，指示健康检查响应 `200`，这表示实例处于健康状态，即 `503`，这表示您的部署出现问题。	`https://{quay-ip-endpoint}/health/instance` 或 `https://{quay-ip-endpoint}/health`	`{"data":{"services":{"auth":true,"database":true,"disk_space":true,"registry_gunicorn":true,"service_key":true,"web_gunicorn":true}},"status_code":200}`
`endtoend`	`endtoend` 端点会对 Red Hat Quay 实例的所有服务进行检查。为以下内容返回带有键值对的字典： `auth`、`database`、`redis`、`存储`。返回一个数字，指示健康检查响应 `200`，这表示实例处于健康状态，即 `503`，这表示您的部署出现问题。	`https://{quay-ip-endpoint}/health/endtoend`	`{"data":{"services":{"auth":true,"database":true,"redis":true,"storage":true}},"status_code":200}`
`warning`	`警告` 端点会对警告进行检查。为以下内容返回带有键值对的字典： `disk_space_warning`。返回一个数字，指示健康检查响应 `200`，这表示实例处于健康状态，即 `503`，这表示您的部署出现问题。	`https://{quay-ip-endpoint}/health/warning`	`{"data":{"services":{"disk_space_warning":true}},"status_code":503}`

5.2. 导航到 Red Hat Quay 健康检查端点

使用以下步骤导航到 实例 端点。对于 endtoend 和 warning 端点，可以重复这个过程。

步骤

在您的 Web 浏览器中，导航到 https://{quay-ip-endpoint}/health/instance。
您要进入健康实例页面，它会返回类似如下的信息：
```
{"data":{"services":{"auth":true,"database":true,"disk_space":true,"registry_gunicorn":true,"service_key":true,"web_gunicorn":true}},"status_code":200}
```
对于 Red Hat Quay，"status_code": 200 表示实例是健康的。相反，如果您收到 "status_code": 503，则部署会出现问题。

第 6 章 Red Hat Quay 组件故障排除

本文档侧重于对 Red Hat Quay 中的特定组件进行故障排除，为解决可能出现的问题提供目标指导。此资源专为系统管理员、操作员和开发人员而设计，旨在帮助诊断和故障排除与 Red Hat Quay 各个组件相关的问题。

除了以下步骤外，Red Hat Quay 组件还可以通过以 debug 模式运行 Red Hat Quay、获取日志信息、获取配置信息，并对端点执行健康检查而出现问题。

通过使用以下流程，您可以对常见组件问题进行故障排除。之后，您可以在红帽知识库中搜索解决方案，或使用红帽支持团队提交支持问题单。

6.1. 对 Red Hat Quay 数据库进行故障排除

用于 Red Hat Quay 的 PostgreSQL 数据库存储各种与容器镜像及其管理相关的信息。PostgreSQL 数据库存储的一些关键信息包括：

镜像元数据.数据库存储与容器镜像关联的元数据，如镜像名称、版本、创建时间戳以及拥有该镜像的用户或机构。这些信息可轻松识别和组织注册表中的容器镜像。
镜像标签.Red Hat Quay 允许用户为容器镜像分配标签，从而方便标记和版本控制。PostgreSQL 数据库维护镜像标签和对应的镜像清单之间的映射，允许用户根据提供的标签检索容器镜像的特定版本。
镜像层.容器镜像由多个层组成，这些层存储为各个对象。数据库记录有关这些层的信息，包括其顺序、校验和和大小。这些数据对于高效存储和检索容器镜像至关重要。
用户和组织数据.Red Hat Quay 支持用户和机构管理，允许用户验证和管理对容器镜像的访问。PostgreSQL 数据库存储用户和组织信息，包括用户名、电子邮件地址、身份验证令牌和访问权限。
存储库信息.Red Hat Quay 将容器镜像组织到存储库中，作为对相关镜像进行分组的逻辑单元。数据库维护存储库数据，包括名称、描述、可见性设置和访问控制信息，使用户能够有效地管理和共享其存储库。
事件日志.Red Hat Quay 跟踪与镜像管理和存储库操作相关的各种事件和活动。这些事件日志（包括镜像推送、拉取、删除和存储库修改）存储在 PostgreSQL 数据库中，提供审计跟踪，并允许管理员监控和分析系统活动。

本节中的内容包括以下步骤：

检查部署类型 ：确定数据库是否作为容器部署到虚拟机上，还是作为 OpenShift Container Platform 上的 pod 部署。
检查容器或 pod 状态 ：使用基于部署类型的特定命令验证 数据库 pod 或容器的状态。
检查数据库容器或 pod 日志 ：访问并检查数据库 pod 或容器的日志，包括用于不同部署类型的命令。
检查 Red Hat Quay 和数据库 pod 之间的连接 ：使用相关命令检查 Red Hat Quay 和数据库 pod 之间的连接。
检查数据库配置 ：根据部署类型在不同的级别(OpenShift Container Platform 或 PostgreSQL 级别)中检查数据库配置。
检查资源分配 ：监控 Red Hat Quay 部署的资源分配，包括磁盘用量和其他资源使用量。
与 Red Hat Quay 数据库 交互：了解如何与 PostgreSQL 数据库交互，包括访问和查询数据库的命令。

6.1.1. Red Hat Quay 数据库问题故障排除

使用以下步骤对 PostgreSQL 数据库进行故障排除。

6.1.1.1. 与 Red Hat Quay 数据库交互

使用以下步骤与 PostgreSQL 数据库交互。

警告

与 PostgreSQL 数据库交互可能具有破坏性。强烈建议您通过 Red Hat Quay 支持专家执行以下步骤。

注意

与 PostgreSQL 数据库交互也可用于对授权和身份验证问题进行故障排除。

步骤

执行到 Red Hat Quay 数据库。
1. 输入以下命令在 OpenShift Container Platform 上的 Red Hat Quay 数据库 pod 中执行：
```
$ oc exec -it <quay_database_pod> -- psql
```
2. 输入以下命令在独立部署中执行 Red Hat Quay 数据库：
```
$ sudo podman exec -it <quay_container_name> /bin/bash
```
输入 PostgreSQL shell。
警告
与 PostgreSQL 数据库交互可能具有破坏性。强烈建议您通过 Red Hat Quay 支持专家执行以下步骤。
1. 如果使用 Red Hat Quay Operator，请输入以下命令输入 PostgreSQL shell：
```
$ oc rsh <quay_pod_name> psql -U your_username -d your_database_name
```
2. 如果您位于独立的 Red Hat Quay 部署中，请输入以下命令输入 PostgreSQL shell：
```
bash-4.4$ psql -U your_username -d your_database_name
```

6.1.1.2. crashloopbackoff 状态故障排除

使用以下步骤 troueblshoot crashloopbackoff 状态。

步骤

如果容器或 pod 处于 crashloopbackoff 状态，您可以输入以下命令。

输入以下命令缩减 Red Hat Quay Operator：

$ oc scale deployment/quay-operator.v3.8.z  --replicas=0

输出示例

deployment.apps/quay-operator.v3.8.z scaled

输入以下命令缩减 Red Hat Quay 数据库：

$ oc scale deployment/<quay_database> --replicas=0

输出示例

deployment.apps/<quay_database> scaled

输入以下命令来编辑 Red Hat Quay 数据库：

警告

与 PostgreSQL 数据库交互可能具有破坏性。强烈建议您通过 Red Hat Quay 支持专家执行以下步骤。

$ oc edit deployment <quay_database>

...
 template:
   metadata:
     creationTimestamp: null
     labels:
       quay-component: <quay_database>
       quay-operator/quayregistry: quay-operator.v3.8.z
   spec:
     containers:
     - env:
       - name: POSTGRESQL_USER
         value: postgres
       - name: POSTGRESQL_DATABASE
         value: postgres
       - name: POSTGRESQL_PASSWORD
         value: postgres
       - name: POSTGRESQL_ADMIN_PASSWORD
         value: postgres
       - name: POSTGRESQL_MAX_CONNECTIONS
         value: "1000"
       image: registry.redhat.io/rhel8/postgresql-10@sha256:a52ad402458ec8ef3f275972c6ebed05ad64398f884404b9bb8e3010c5c95291
       imagePullPolicy: IfNotPresent
       name: postgres
       command: ["/bin/bash", "-c", "sleep 86400"] 1
...

1: 在同一缩进中添加这一行。

输出示例

deployment.apps/<quay_database> edited

在 < quay_database> 中执行以下命令 ：

$ oc exec -it <quay_database> -- cat /var/lib/pgsql/data/userdata/postgresql/logs/* /path/to/desired_directory_on_host

6.1.1.3. 检查 Red Hat Quay 和数据库 pod 之间的连接

使用以下步骤检查 Red Hat Quay 和数据库 pod 之间的连接

步骤

检查 Red Hat Quay 和数据库 pod 之间的连接。
1. 如果您在 OpenShift Container Platform 上使用 Red Hat Quay Operator，请输入以下命令：
```
$ oc exec -it _quay_pod_name_ -- curl -v telnet://<database_pod_name>:5432
```
2. 如果使用独立部署 Red Hat Quay，请输入以下命令：
```
$ podman exec -it <quay_container_name >curl -v telnet://<database_container_name>:5432
```

6.1.1.4. 检查资源分配

使用以下步骤检查资源分配。

步骤

获取运行容器的列表。
监控 Red Hat Quay 部署的磁盘用量。
1. 如果您在 OpenShift Container Platform 上使用 Red Hat Quay Operator，请输入以下命令：
```
$ oc exec -it <quay_database_pod_name> -- df -ah
```
2. 如果使用独立部署 Red Hat Quay，请输入以下命令：
```
$ podman exec -it <quay_database_conatiner_name> df -ah
```
监控其他资源使用量。
1. 输入以下命令在 Red Hat Quay Operator 部署中检查资源分配：
```
$ oc adm top pods
```
2. 输入以下命令在 Red Hat Quay 的独立部署中检查特定 pod 的状态：
```
$ podman pod stats <pod_name>
```
3. 输入以下命令在 Red Hat Quay 的独立部署中检查特定容器的状态：
```
$ podman stats <container_name>
```
  返回以下信息：
  - CPU %。容器自上次测量以来的 CPU 使用量百分比。这个值代表了容器的可用 CPU 资源的共享。
  - MEM USAGE/ LIMIT。容器的当前内存用量及其内存限值。这些值以 current_usage / memory_limit 格式显示。例如，300.4MiB / 7.795GiB 表示容器目前使用 300.4MB 内存，其限值为 7.795GB。
  - MEM %.容器的内存使用量与内存限制有关。
  - 网络 I/O.容器的网络 I/O （输入/输出）统计信息。它显示容器通过网络传输和接收的数据量。这些值以以下格式显示： transport _bytes / received_bytes。
  - 块 I/O.容器的块 I/O （输入/输出）统计信息。它代表了从容器读取和写入到块设备（如磁盘）的数据量。这些值以 read_bytes / written_bytes 格式显示。

6.1.2. 在 Red Hat Quay 独立部署中重置超级用户密码

使用以下步骤重置超级用户的密码。

先决条件

您已创建了 Red Hat Quay 超级用户。
已安装 Python 3.9。
您已为 Python 安装 pip 软件包管理器。
您已为 pip 安装了 bcrypt 软件包。

步骤

输入以下命令，使用 Python 3.9 中的 bcrypt 软件包生成安全、哈希的密码：

$ python3.9 -c 'import bcrypt; print(bcrypt.hashpw(b"newpass1234", bcrypt.gensalt(12)).decode("utf-8"))'

输出示例

$2b$12$T8pkgtOoys3G5ut7FV1She6vXlYgU.6TeoGmbbAVQtN8X8ch4knKm

输入以下命令显示 Red Hat Quay 容器 registry 的容器 ID：

$ sudo podman ps -a

输出示例

CONTAINER ID  IMAGE                                       COMMAND         CREATED         STATUS             PORTS                   NAMES
70560beda7aa  registry.redhat.io/rhel8/redis-5:1         run-redis       2 hours ago     Up 2 hours ago     0.0.0.0:6379->6379/tcp                       redis
8012f4491d10  registry.redhat.io/quay/quay-rhel8:v3.8.2  registry        3 minutes ago   Up 8 seconds ago   0.0.0.0:80->8080/tcp, 0.0.0.0:443->8443/tcp  quay
8b35b493ac05  registry.redhat.io/rhel8/postgresql-10:1   run-postgresql  39 seconds ago  Up 39 seconds ago  0.0.0.0:5432->5432/tcp                       postgresql-quay

输入以下命令为 postgresql 容器镜像执行交互式 shell：
```
$ sudo podman exec -it 8b35b493ac05 /bin/bash
```
重新输入 quay PostgreSQL 数据库服务器，指定数据库、用户名和主机地址：
```
bash-4.4$ psql -d quay -U quayuser -h 192.168.1.28 -W
```

更新超级用户 admin 的 password_hash，其丢失了其密码：

quay=> UPDATE public.user SET password_hash = '$2b$12$T8pkgtOoys3G5ut7FV1She6vXlYgU.6TeoGmbbAVQtN8X8ch4knKm' where username = 'quayadmin';

输出示例

UPDATE 1

输入以下命令来确保 password_hash 已更新：

quay=> select * from public.user;

输出示例

id | uuid | username | password_hash | email | verified | stripe_id | organization | robot | invoice_email | invalid_login_attempts | last_invalid_login |removed_tag_expiration_s | enabled | invoice_email_address | company | family_name | given_name | location | maximum_queued_builds_count | creation_date | last_accessed
----+--------------------------------------+-----------+--------------------------------------------------------------+-----------------------+---
-------+-----------+--------------+-------+---------------+------------------------+----------------------------+--------------------------+------
---+-----------------------+---------+-------------+------------+----------+-----------------------------+----------------------------+-----------
1 | 73f04ef6-19ba-41d3-b14d-f2f1eed94a4a | quayadmin | $2b$12$T8pkgtOoys3G5ut7FV1She6vXlYgU.6TeoGmbbAVQtN8X8ch4knKm | quayadmin@example.com | t | | f | f | f | 0 | 2023-02-23 07:54:39.116485 | 1209600 | t | | | | | | | 2023-02-23 07:54:39.116492

使用新密码登录到 Red Hat Quay 部署：

$ sudo podman login -u quayadmin -p newpass1234 http://quay-server.example.com --tls-verify=false

输出示例

Login Succeeded!

其他资源

如需更多信息，请参阅为 Quay 重置超级用户密码。

6.1.3. 在 Red Hat Quay Operator 上重置超级用户密码

先决条件

您已创建了 Red Hat Quay 超级用户。
已安装 Python 3.9。
您已为 Python 安装 pip 软件包管理器。
您已为 pip 安装了 bcrypt 软件包。

步骤

登录到您的 Red Hat Quay 部署。
在 OpenShift Container Platform UI 中，进入到 Workloads → Secrets。
为您的 Red Hat Quay 部署选择命名空间，如 Project quay。
查找并存储 PostgreSQL 数据库凭据。

输入以下命令，使用 Python 3.9 中的 bcrypt 软件包生成安全、哈希的密码：

$ python3.9 -c 'import bcrypt; print(bcrypt.hashpw(b"newpass1234", bcrypt.gensalt(12)).decode("utf-8"))'

输出示例

$2b$12$zoilcTG6XQeAoVuDuIZH0..UpvQEZcKh3V6puksQJaUQupHgJ4.4y

在 CLI 中，登录到数据库，例如：

$ oc rsh quayuser-quay-quay-database-669c8998f-v9qsl

输入以下命令打开到 quay PostgreSQL 数据库服务器的连接，指定数据库、用户名和主机地址：
```
sh-4.4$ psql -U quayuser-quay-quay-database -d quayuser-quay-quay-database -W
```
输入以下命令连接到当前用户的默认数据库：
```
quay=> \c
```

更新超级用户 admin 的 password_hash，其丢失了其密码：

quay=> UPDATE public.user SET password_hash = '$2b$12$zoilcTG6XQeAoVuDuIZH0..UpvQEZcKh3V6puksQJaUQupHgJ4.4y' where username = 'quayadmin';

输入以下命令来确保 password_hash 已更新：

quay=> select * from public.user;

输出示例

id | uuid | username | password_hash | email | verified | stripe_id | organization | robot | invoice_email | invalid_login_attempts | last_invalid_login |removed_tag_expiration_s | enabled | invoice_email_address | company | family_name | given_name | location | maximum_queued_builds_count | creation_date | last_accessed
----+--------------------------------------+-----------+--------------------------------------------------------------+-----------------------+---
-------+-----------+--------------+-------+---------------+------------------------+----------------------------+--------------------------+------
---+-----------------------+---------+-------------+------------+----------+-----------------------------+----------------------------+-----------
1 | 73f04ef6-19ba-41d3-b14d-f2f1eed94a4a | quayadmin | $2b$12$zoilcTG6XQeAoVuDuIZH0..UpvQEZcKh3V6puksQJaUQupHgJ4.4y | quayadmin@example.com | t | | f | f | f | 0 | 2023-02-23 07:54:39.116485 | 1209600 | t | | | | | | | 2023-02-23 07:54:39.116492

进入到 OpenShift Container Platform 上的 Red Hat Quay UI，并使用新凭证登录。

6.2. Red Hat Quay 身份验证故障排除

身份验证和授权对于安全访问 Red Hat Quay 至关重要。它们一起保护敏感容器镜像、验证用户身份、强制访问控制、促进审计和责任，并启用与外部身份提供程序无缝集成。通过优先级身份验证，组织可以为其容器注册表环境带来整体安全性和完整性。

Red Hat Quay 支持以下验证方法：

用户名和密码。用户可以通过提供用户名和密码进行身份验证，这些用户名和密码针对 Red Hat Quay 中配置的用户数据库进行验证。这种传统方法要求用户输入其凭据以获取访问权限。
OAuth.Red Hat Quay 支持 OAuth 身份验证，允许用户使用来自 Google、GitHub 或 Keycloak 等第三方服务的凭证进行身份验证。OAuth 支持无缝的登录体验，消除了单独帐户创建和简化用户管理的需求。
OIDC.OpenID Connect 支持单点登录(SSO)功能，并与企业身份提供程序集成。通过 OpenID Connect，用户可以使用其现有的机构凭证进行身份验证，为不同的系统和应用程序提供统一的身份验证体验。
基于令牌的身份验证.用户可以获取唯一令牌，以授予 Red Hat Quay 中特定资源的访问权限。令牌可以通过各种方式获取，如 OAuth，或在 Red Hat Quay 用户界面中生成 API 令牌。基于令牌的身份验证通常用于自动或编程访问 registry。
外部身份提供程序。Red Hat Quay 可以和外部身份提供程序（如 LDAP 或 AzureAD）集成，以进行身份验证。这种集成允许组织使用现有的身份管理基础架构，启用集中用户身份验证并减少对单独用户数据库的需求。

6.2.1. 对特定用户的 Red Hat Quay 身份验证和授权问题进行故障排除

使用以下步骤对特定用户的身份验证和授权问题进行故障排除。

步骤

执行到 Red Hat Quay pod 或容器中。如需更多信息，请参阅"与 Red Hat Quay 数据库交互"。

输入以下命令显示用于外部身份验证的所有用户：

quay=# select * from federatedlogin;

输出示例

id | user_id | service_id |                service_ident                |               metadata_json
----+---------+------------+---------------------------------------------+-------------------------------------------
1 |       1 |          3 | testuser0                                   | {}
2 |       1 |          8 | PK7Zpg2Yu2AnfUKG15hKNXqOXirqUog6G-oE7OgzSWc | {"service_username": "live.com#testuser0"}
3 |       2 |          3 | testuser1                                    | {}
4 |       2 |          4 | 110875797246250333431                       | {"service_username": "testuser1"}
5 |       3 |          3 | testuser2                                    | {}
6 |       3 |          1 | 26310880                                    | {"service_username": "testuser2"}
(6 rows)

验证用户是否已插入到 user 表中：

quay=# select username, email from "user";

输出示例

username  |        email
-----------+----------------------
testuser0 | testuser0@outlook.com
testuser1  | testuser1@gmail.com
testuser2  | testuser2@redhat.com
(3 rows)

6.3. Red Hat Quay 对象存储故障排除

对象存储是一种数据存储架构，可将数据作为离散单元进行管理，称为 对象。与将数据组织到分层目录和文件的传统文件系统不同，对象存储将数据视为具有唯一标识符的独立实体。每个对象包含数据本身，以及描述对象的元数据，并启用高效的检索。

Red Hat Quay 使用对象存储作为存储和管理容器镜像的底层存储机制。它将容器镜像存储为单独的对象。每个容器镜像都被视为对象，具有自己的唯一标识符和相关元数据。

6.3.1. Red Hat Quay 对象存储问题故障排除

使用以下选项排除 Red Hat Quay 对象存储问题。

步骤

输入以下命令查看使用哪些对象存储：
```
$ oc get quayregistry quay-registry-name -o yaml
```
通过检查经过测试的集成页面，确保 Red Hat Quay 正式支持您使用的对象存储。
启用调试模式。如需更多信息，请参阅"以 debug 模式运行 Red Hat Quay"。
在 config.yaml 文件中检查对象存储配置。确保其准确，并与对象存储供应商提供的设置匹配。您可以检查访问凭证、端点 URL、存储桶和容器名称等信息，以及其他相关的配置参数。
确保 Red Hat Quay 与对象存储端点具有网络连接。检查网络配置，以确保不会限制阻止 Red Hat Quay 和对象存储端点之间的通信。

如果在 config.yaml 文件中启用了 FEATURE_STORAGE_PROXY，请检查是否可以访问它的下载 URL。这可在 Red Hat Quay 调试日志中找到。例如：

$ curl -vvv "https://QUAY_HOSTNAME/_storage_proxy/dhaWZKRjlyO......Kuhc=/https/quay.hostname.com/quay-test/datastorage/registry/sha256/0e/0e1d17a1687fa270ba4f52a85c0f0e7958e13d3ded5123c3851a8031a9e55681?AWSAccessKeyId=xxxx&Signature=xxxxxx4%3D&Expires=1676066703"

尝试访问 Red Hat Quay 之外的对象存储服务，以确定问题是否特定于您的部署，还是底层对象存储。您可以使用 aws、gsutil 或对象存储供应商提供的 s3cmd 等命令行工具执行基本操作，如列出存储桶、容器或上传和下载对象。这可帮助您隔离问题。

6.4. geo-replication

地理复制允许多个地理分散的 Red Hat Quay 部署，从客户端或用户的角度来看，作为单个 registry 工作。它显著提高了全局分布式 Red Hat Quay 设置中的推送和拉取性能。镜像数据会在后台异步复制，为客户端进行透明故障转移和重定向。

在独立和 Operator 部署中支持部署带有异地复制的 Red Hat Quay。

6.4.1. Red Hat Quay 的地理复制故障排除

使用以下部分对 Red Hat Quay 的 geo-replication 进行故障排除。

6.4.1.1. 检查后端存储桶中的数据复制

使用以下步骤来确保您的数据在所有后端存储桶中被正确复制。

先决条件

已安装 aws CLI。

步骤

输入以下命令来确保您的数据在所有后端存储桶中复制：

$ aws --profile quay_prod_s3 --endpoint=http://10.0.x.x:port s3 ls ocp-quay --recursive --human-readable --summarize

输出示例

Total Objects: 17996
Total Size: 514.4 GiB

6.4.1.2. 检查后端存储的状态

使用以下资源来检查后端存储的状态。

Amazon Web Service Storage (AWS).检查 AWS Service Health Dashboard 上的 AWS S3 服务健康状态。使用 aws CLI 或 SDK 列出已知存储桶中的对象来验证您对 S3 的访问。
Google Cloud Storage (GCS).检查 Google Cloud Status Dashboard，以查看 GCS 服务的状态。使用 Google Cloud SDK 或 GCS 客户端库列出已知存储桶中的对象，来验证您对 GCS 的访问。
NooBaa。检查 NooBaa 管理控制台或管理界面，是否有任何健康状态或状态指示器。确保 NooBaa 服务和相关组件正在运行并可以访问。使用 NooBaa CLI 或 SDK 列出已知存储桶中的对象来验证对 NooBaa 的访问。
Red Hat OpenShift Data Foundation.检查 OpenShift Container Platform 控制台或管理界面，以查看 Red Hat OpenShift Data Foundation 组件的状态。验证 Red Hat OpenShift Data Foundation S3 接口和服务是否可用。确保 Red Hat OpenShift Data Foundation 服务正在运行并可以访问。使用适当的 S3 兼容 SDK 或 CLI，验证对 Red Hat OpenShift Data Foundation S3 的访问。
Ceph.检查 Ceph 服务的状态，包括 Ceph 监视器、OSD 和 RGW。验证 Ceph 集群是否正常运行。使用适当的 Ceph 对象存储 API 或 CLI 列出已知存储桶中的对象，验证对 Ceph 对象存储的访问。
Azure Blob 存储.检查 Azure Status Dashboard，以查看 Azure Blob Storage 服务的健康状态。使用 Azure CLI 或 Azure SDK 列出容器或对象来验证您对 Azure Blob Storage 的访问。
OpenStack Swift.检查 OpenStack Status 页面，以验证 OpenStack Swift 服务的状态。确保 Swift 服务（如代理服务器、容器服务器、对象服务器）正在运行并可访问。使用适当的 Swift CLI 或 SDK 列出容器或对象，来验证您对 Swift 的访问。

检查后端存储的状态后，请确保所有 Red Hat Quay 实例都可以访问所有 s3 存储后端。

6.5. 仓库镜像

Red Hat Quay 存储库镜像可让您将外部容器 registry 中的镜像（或另一个本地 registry）镜像到 Red Hat Quay 集群中。使用存储库镜像，您可以根据存储库名称和标签将镜像同步到 Red Hat Quay。

在启用了存储库镜像的 Red Hat Quay 集群中，您可以执行以下操作：

从外部 registry 选择要镜像的存储库
添加用于访问外部 registry 的凭证
识别特定容器镜像存储库名称和要同步的标签
设置同步存储库的间隔
检查同步的当前状态

要使用镜像功能，您需要执行以下操作：

在 Red Hat Quay 配置文件中启用存储库镜像
运行存储库镜像 worker
创建已镜像的存储库

所有存储库镜像配置都可以使用配置工具 UI 或 Red Hat Quay API 执行。

6.5.1. 存储库镜像故障排除

使用以下部分对 Red Hat Quay 的存储库镜像进行故障排除。

6.5.1.1. 验证身份验证和权限

确保用于镜像的身份验证凭据在源和目标 Red Hat Quay 实例上都有必要的权限和访问权限。

在 Red Hat Quay UI 中，检查以下设置：

访问控制设置。确保执行镜像操作的用户或服务帐户具有所需的特权。
Red Hat Quay registry 上机器人帐户的权限。

6.6. Clair 安全扫描程序

6.6.1. Clair 问题故障排除

使用以下步骤对 Clair 进行故障排除。

6.6.1.1. 验证镜像兼容性

如果使用 Clair，请确保 Clair 支持尝试扫描的镜像。Clair 具有特定要求，不支持所有镜像格式或配置。

如需更多信息，请参阅 Clair 漏洞数据库。

6.6.1.2. 允许 Clair 更新器

如果您在代理配置后使用 Clair，则必须在代理或防火墙配置中列出更新程序。有关更新器 URL 的更多信息，请参阅 Clair 更新器 URL。

6.6.1.3. 更新 Clair 扫描程序及其依赖项

确保您使用最新版本的 Clair 安全扫描程序。过时的版本可能缺少对较新的镜像格式的支持，或者可能存在已知问题。

使用以下步骤检查您的 Clair 版本。

注意

也可以使用检查 Clair 日志来检查 Clair 日志中是否存在来自 updaters 微服务的错误。默认情况下，Clair 每 30 分钟更新漏洞数据库。

步骤

检查您的 Clair 版本。
1. 如果您在 OpenShift Container Platform 上的 Red Hat Quay 上运行 Clair，请输入以下命令：
```
$ oc logs clair-pod
```
2. 如果您正在运行 Red Hat Quay 的独立部署并使用 Clair 容器，请输入以下命令：
```
$ podman logs clair-container
```
  输出示例
```
"level":"info",
"component":"main",
"version":"v4.5.1",
```

6.6.1.4. 为 Clair 启用调试模式

默认情况下，Clair 的调试模式被禁用。您可以通过更新 clair-config.yaml 文件为 Clair 启用调试模式。

先决条件

对于 OpenShift Container Platform 部署上的 Red Hat Quay Clair，您必须使用受管 Clair 数据库运行自定义 Clair 配置。

使用以下步骤为 Clair 启用调试模式。

步骤

更新 clair-config.yaml 文件，使其包含 debug 选项。
1. 在独立 Red Hat Quay 部署中：
  1. 在您的 clair-config.yaml 文件中添加以下配置字段：
    log_level: debug
  2. 输入以下命令重启 Clair 部署：
    $ podman restart <clair_container_name>
2. 在 OpenShift Container Platform 部署的 Red Hat Quay 中：
  1. 在 OpenShift Container Platform web 控制台中，点 Operators → Installed Operators → Quay Registry。
  2. 单击 registry 的名称，如 示例 Registry。您将被重定向到 registry 的 Details 页面。
  3. 单击 Config Bundle Secret，如 example-registry-config-bundle-xncls。
  4. 通过在 secret 的 Details 页面的 Data 部分查找 clair-config.yaml 文件，确认您正在运行自定义 Clair 配置。
  5. 如果您有一个 clair-config.yaml 文件，请点击 Actions → Edit Secret。如果没有，请参阅"使用受管 Clair 数据库运行自定义 Clair 配置"。
  6. 更新 clair-config.yaml 文件，使其包含 log_level: debug 配置变量。例如：
    log_level: debug
  7. 点击 Save。
  8. 您可以点击 Workloads → Pods 来检查 Clair 部署的状态。clair-app pod 应该会在 Ready 类别下报告 1/1。
  9. 您可以点 Ready → Logs 的 clair-app pod 确认 Clair 正在返回调试信息。

6.6.1.5. 检查 Clair 配置

检查您的 Clair config.yaml 文件，以确保没有错误配置或可能导致问题不一致的问题。如需更多信息，请参阅 Clair 配置概述。

6.6.1.6. 检查镜像元数据

在某些情况下，您可能会收到 Unsupported 信息。这可能表示扫描程序无法从镜像中提取必要的元数据。检查镜像元数据是否已正确格式化并可以访问。

其他资源

如需更多信息，请参阅对 Clair 进行故障排除。

法律通告

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.

Red Hat Quay 故障排除