• 减少内存使用
  • 监控工作进程重启
• 更改工作进程超时时间
• 在内存受限环境中禁用 Puma 集群模式
  • Puma 单一模式已知问题
• 配置 Puma 通过 SSL 监听
  • 使用加密的 SSL 密钥
• 从 Unicorn 切换到 Puma
• Puma 故障排除
  • Puma 在 100% CPU 负载下导致 502 网关超时
    • 不影响其他用户的故障排除
  • 极狐GitLab：API 不可访问
• 相关主题

{{< details >}}

• Tier: 基础版, 专业版, 旗舰版
• Offering: 私有化部署

{{< /details >}}

Puma 是一个快速、多线程和高并发的 HTTP 1.1 服务器，适用于 Ruby 应用程序。它运行核心 Rails 应用程序，提供极狐GitLab 的用户界面功能。

减少内存使用

为了减少内存使用，Puma 会派生工作进程。每次创建一个工作进程时，它会与主进程共享内存。只有当工作进程更改或添加其内存页面时才会使用额外的内存。随着工作进程处理更多的 Web 请求，Puma 的工作进程可能会随着时间的推移使用更多的物理内存。随着极狐GitLab 的使用量增加，内存使用量也会随之增加。极狐GitLab 用户使用的功能越多，预计内存使用量随时间的增加也越多。

为了阻止不受控制的内存增长，极狐GitLab Rails 应用程序运行一个监督线程，如果工作进程超过给定驻留集大小 (RSS) 阈值持续一段时间，就会自动重新启动工作进程。

极狐GitLab 将内存限制的默认值设置为 1200Mb。要覆盖默认值，请将 per_worker_max_memory_mb 设置为新的 RSS 限制（以 MB 为单位）：

1. 编辑 /etc/gitlab/gitlab.rb：

   puma['per_worker_max_memory_mb'] = 1024 # 1GB
   

2. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

当工作进程重新启动时，运行极狐GitLab 的容量会在短时间内减少。如果工作进程被替换过于频繁，请将 per_worker_max_memory_mb 设置为更高的值。

工作进程数根据 CPU 核心数计算。一个小型的极狐GitLab 部署，拥有 4-8 个工作进程，如果工作进程被过于频繁地重新启动（每分钟一次或更多），可能会遇到性能问题。

如果服务器有空闲内存，设置 1200 或更高的值可能会有益。

监控工作进程重启

极狐GitLab 会在由于高内存使用而重新启动工作进程时发出日志事件。

以下是在 /var/log/gitlab/gitlab-rails/application_json.log 中的这些日志事件的示例：

{
  "severity": "WARN",
  "time": "2023-01-04T09:45:16.173Z",
  "correlation_id": null,
  "pid": 2725,
  "worker_id": "puma_0",
  "memwd_handler_class": "Gitlab::Memory::Watchdog::PumaHandler",
  "memwd_sleep_time_s": 5,
  "memwd_rss_bytes": 1077682176,
  "memwd_max_rss_bytes": 629145600,
  "memwd_max_strikes": 5,
  "memwd_cur_strikes": 6,
  "message": "rss memory limit exceeded"
}

memwd_rss_bytes 是实际消耗的内存量，而 memwd_max_rss_bytes 是通过 per_worker_max_memory_mb 设置的 RSS 限制。

更改工作进程超时时间

默认的 Puma 超时时间为 60 秒。

{{< alert type=”note” >}}

puma['worker_timeout'] 设置不会设置最大请求持续时间。

{{< /alert >}}

要将工作进程超时更改为 600 秒：

1. 编辑 /etc/gitlab/gitlab.rb：

   gitlab_rails['env'] = {
      'GITLAB_RAILS_RACK_TIMEOUT' => 600
    }
   

2. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

在内存受限环境中禁用 Puma 集群模式

{{< alert type=”warning” >}}

此功能是一个实验，可能会在不通知的情况下更改。此功能尚未准备好用于生产环境。如果您想使用此功能，您应该先在生产环境之外进行测试。有关详细信息，请参阅已知问题。

{{< /alert >}}

在可用 RAM 少于 4 GB 的内存受限环境中，考虑禁用 Puma 集群模式。

将 workers 的数量设置为 0 可以减少数百 MB 的内存使用：

1. 编辑 /etc/gitlab/gitlab.rb：

   puma['worker_processes'] = 0
   

2. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

不像默认设置的集群模式，只有单个 Puma 进程将为应用程序提供服务。有关 Puma 工作进程和线程设置的详细信息，请参阅 Puma 要求。

在这种配置下运行 Puma 的缺点是吞吐量减少，这在内存受限环境中可以被视为一个公平的权衡。

请记住要有足够的交换空间可用，以避免内存不足 (OOM) 情况。查看 内存要求 获取详细信息。

Puma 单一模式已知问题

在单一模式下运行 Puma 时，某些功能不受支持：

• 分阶段重启
• 内存杀手

配置 Puma 通过 SSL 监听

当使用 Linux 软件包安装部署时，Puma 默认通过 Unix 套接字监听。要配置 Puma 通过 HTTPS 端口监听，请按照以下步骤操作：

1. 为 Puma 将要监听的地址生成一个 SSL 证书密钥对。对于以下示例，这是 127.0.0.1。

   {{< alert type=”note” >}}

   如果使用来自自定义证书颁发机构 (CA) 的自签名证书，请按照文档使其被其他极狐GitLab 组件信任。

   {{< /alert >}}

2. 编辑 /etc/gitlab/gitlab.rb：

   puma['ssl_listen'] = '127.0.0.1'
   puma['ssl_port'] = 9111
   puma['ssl_certificate'] = '<path_to_certificate>'
   puma['ssl_certificate_key'] = '<path_to_key>'
   
   # Disable UNIX socket
   puma['socket'] = ""
   

3. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

{{< alert type=”note” >}}

除了 Unix 套接字，Puma 还通过端口 8080 上的 HTTP 监听，为 Prometheus 提供可抓取的指标。因此，无法在不丢失 Prometheus 指标的情况下关闭此 HTTP 监听器。

{{< /alert >}}

使用加密的 SSL 密钥

{{< history >}}

• 引入于极狐GitLab 16.1。

{{< /history >}}

Puma 支持使用加密的私有 SSL 密钥，可以在运行时解密。以下说明展示了如何配置：

1. 如果密钥尚未加密，请使用密码加密：

   openssl rsa -aes256 -in /path/to/ssl-key.pem -out /path/to/encrypted-ssl-key.pem
   

   输入密码两次以写入加密文件。在此示例中，我们使用 some-password-here。

2. 创建一个打印密码的脚本或可执行文件。例如，在 /var/opt/gitlab/gitlab-rails/etc/puma-ssl-key-password 中创建一个基本脚本来回显密码：

   #!/bin/sh
   echo some-password-here
   

   避免将密码存储在磁盘上，并使用安全机制来检索密码，例如 Vault。例如，脚本可能看起来像：

   #!/bin/sh
   export VAULT_ADDR=http://vault-password-distribution-point:8200
   export VAULT_TOKEN=<some token>
   
   echo "$(vault kv get -mount=secret puma-ssl-password)"
   

3. 确保 Puma 进程有足够的权限来执行该脚本并读取加密密钥：

   chown git:git /var/opt/gitlab/gitlab-rails/etc/puma-ssl-key-password
   chmod 770 /var/opt/gitlab/gitlab-rails/etc/puma-ssl-key-password
   chmod 660 /path/to/encrypted-ssl-key.pem
   

4. 编辑 /etc/gitlab/gitlab.rb，用加密密钥替换 puma['ssl_certificate_key'] 并指定 puma['ssl_key_password_command]：

   puma['ssl_certificate_key'] = '/path/to/encrypted-ssl-key.pem'
   puma['ssl_key_password_command'] = '/var/opt/gitlab/gitlab-rails/etc/puma-ssl-key-password'
   

5. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

6. 如果极狐GitLab 成功启动，您应该可以删除存储在极狐GitLab 实例上的未加密 SSL 密钥。

从 Unicorn 切换到 Puma

{{< alert type=”note” >}}

对于基于 Helm 的部署，请参阅webservice 图表文档。

{{< /alert >}}

Puma 是默认的 Web 服务器，Unicorn 不再受支持。

Puma 具有多线程架构，比多进程应用服务器（如 Unicorn）使用更少的内存。在 JihuLab.com 上，我们看到内存消耗减少了 40%。大多数 Rails 应用程序请求通常包含一定比例的 I/O 等待时间。

在 I/O 等待时间期间，MRI Ruby 会将 GVL 释放给其他线程。因此，多线程的 Puma 仍然可以比单个进程服务更多请求。

当切换到 Puma 时，由于两个应用服务器之间的差异，任何 Unicorn 服务器配置都不会自动携带过来。

要从 Unicorn 切换到 Puma：

1. 确定合适的 Puma 工作进程和线程设置。

2. 将 /etc/gitlab/gitlab.rb 中的任何自定义 Unicorn 设置转换为 Puma。

   下表总结了在使用 Linux 软件包时 Unicorn 配置键对应于 Puma 的那些键，以及哪些没有对应的对应物。

   Unicorn	Puma
   unicorn['enable']	puma['enable']
   unicorn['worker_timeout']	puma['worker_timeout']
   unicorn['worker_processes']	puma['worker_processes']
   不适用	puma['ha']
   不适用	puma['min_threads']
   不适用	puma['max_threads']
   unicorn['listen']	puma['listen']
   unicorn['port']	puma['port']
   unicorn['socket']	puma['socket']
   unicorn['pidfile']	puma['pidfile']
   unicorn['tcp_nopush']	不适用
   unicorn['backlog_socket']	不适用
   unicorn['somaxconn']	puma['somaxconn']
   不适用	puma['state_path']
   unicorn['log_directory']	puma['log_directory']
   unicorn['worker_memory_limit_min']	不适用
   unicorn['worker_memory_limit_max']	puma['per_worker_max_memory_mb']
   unicorn['exporter_enabled']	puma['exporter_enabled']
   unicorn['exporter_address']	puma['exporter_address']
   unicorn['exporter_port']	puma['exporter_port']

3. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

4. 可选。对于多节点部署，配置负载均衡器以使用 就绪检查。

Puma 故障排除

Puma 在 100% CPU 负载下导致 502 网关超时

当 Web 服务器在没有收到 Puma 工作进程的响应后超时（默认：60 秒）时，会出现此错误。如果在此过程中 CPU 达到 100% 负载，可能有某些事情需要比预期更长的时间。

要解决此问题，我们首先需要弄清楚发生了什么。如果您不介意用户受到停机的影响，则仅推荐以下提示。否则，请跳至下一部分。

1. 加载问题 URL
2. 运行 sudo gdb -p <PID> 来附加到 Puma 进程。

3. 在 GDB 窗口中输入：

   call (void) rb_backtrace()
   

4. 这会强制进程生成一个 Ruby 回溯。检查 /var/log/gitlab/puma/puma_stderr.log 中的回溯。例如，您可能会看到：

   from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:33:in `block in start'
   from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:33:in `loop'
   from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:36:in `block (2 levels) in start'
   from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:44:in `sample'
   from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:68:in `sample_objects'
   from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:68:in `each_with_object'
   from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:68:in `each'
   from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:69:in `block in sample_objects'
   from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:69:in `name'
   

5. 要查看当前线程，请运行：

   thread apply all bt
   

6. 完成 gdb 调试后，确保从进程分离并退出：

   detach
   exit
   

如果 Puma 进程在您能够运行这些命令之前终止，GDB 会报告错误。为了争取更多时间，您可以始终提高 Puma 工作进程超时。对于 Linux 软件包安装用户，您可以编辑 /etc/gitlab/gitlab.rb 并将其从 60 秒增加到 600 秒：

gitlab_rails['env'] = {
        'GITLAB_RAILS_RACK_TIMEOUT' => 600
}

对于自编译安装，请设置环境变量。请参阅 Puma 工作进程超时。

重新配置 极狐GitLab 以使更改生效。

不影响其他用户的故障排除

上一节附加到了正在运行的 Puma 进程，这可能会对试图在此期间访问极狐GitLab 的用户产生不利影响。如果您担心在生产系统期间影响其他用户，您可以运行一个单独的 Rails 进程来调试问题：

1. 登录到您的极狐GitLab 账户。
2. 复制导致问题的 URL（例如，https://gitlab.com/ABC）。
3. 为您的用户创建一个个人访问令牌（用户设置 -> 访问令牌）。
4. 启动 极狐GitLab Rails 控制台。

5. 在 Rails 控制台中，运行：

   app.get '<URL FROM STEP 2>/?private_token=<TOKEN FROM STEP 3>'
   

   例如：

   app.get 'https://gitlab.com/gitlab-org/gitlab-foss/-/issues/1?private_token=123456'
   

6. 在新窗口中运行 top。它应该显示此 Ruby 进程使用 100% 的 CPU。记下 PID。
7. 按照上一节中使用 GDB 的步骤 2。

极狐GitLab：API 不可访问

当极狐GitLab Shell 尝试通过内部 API请求授权（例如，http://localhost:8080/api/v4/internal/allowed）时，通常会发生这种情况，并且检查中出现了一些问题。可能发生这种情况的原因有很多：

1. 连接到数据库（例如，PostgreSQL 或 Redis）超时
2. Git 钩子或推送规则中的错误
3. 访问存储库时出错（例如，陈旧的 NFS 句柄）

要诊断此问题，请尝试重现该问题，然后查看是否有 Puma 工作进程通过 top 旋转。尝试使用上述 gdb 技术。此外，使用 strace 可能有助于隔离问题：

strace -ttTfyyy -s 1024 -p <PID of puma worker> -o /tmp/puma.txt

如果无法隔离哪个 Puma 工作进程是问题，请尝试在所有 Puma 工作进程上运行 strace，以查看 /internal/allowed 端点在哪里卡住：

ps auwx | grep puma | awk '{ print " -p " $2}' | xargs  strace -ttTfyyy -s 1024 -o /tmp/puma.txt

/tmp/puma.txt 中的输出可能有助于诊断根本原因。

相关主题

• 使用专用的指标服务器导出 Web 指标