极狐 GitLab Logo

配置极狐GitLab 软件包捆绑的 Puma 实例

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

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：

    ruby
    puma['per_worker_max_memory_mb'] = 1024 # 1GB

  2. 重新配置极狐GitLab：

    shell
    sudo gitlab-ctl reconfigure

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

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

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

监控工作进程重启#

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

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

json
1{
2  "severity": "WARN",
3  "time": "2023-01-04T09:45:16.173Z",
4  "correlation_id": null,
5  "pid": 2725,
6  "worker_id": "puma_0",
7  "memwd_handler_class": "Gitlab::Memory::Watchdog::PumaHandler",
8  "memwd_sleep_time_s": 5,
9  "memwd_rss_bytes": 1077682176,
10  "memwd_max_rss_bytes": 629145600,
11  "memwd_max_strikes": 5,
12  "memwd_cur_strikes": 6,
13  "message": "rss memory limit exceeded"
14}

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

更改工作进程超时时间#

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

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

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

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

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

  2. 重新配置极狐GitLab：

    shell
    sudo gitlab-ctl reconfigure

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

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

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

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

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

    ruby
    puma['worker_processes'] = 0

  2. 重新配置极狐GitLab：

    shell
    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。

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

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

    ruby
    1puma['ssl_listen'] = '127.0.0.1'
2puma['ssl_port'] = 9111
3puma['ssl_certificate'] = '<path_to_certificate>'
4puma['ssl_certificate_key'] = '<path_to_key>'
5
6# Disable UNIX socket
7puma['socket'] = ""

  2. 重新配置极狐GitLab：

    shell
    sudo gitlab-ctl reconfigure

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

使用加密的 SSL 密钥#

History
    • 引入于极狐GitLab 16.1。

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

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

    shell
    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 中创建一个基本脚本来回显密码：

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

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

    shell
    #!/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 进程有足够的权限来执行该脚本并读取加密密钥：

    shell
    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]：

    ruby
    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：

    shell
    sudo gitlab-ctl reconfigure

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

从 Unicorn 切换到 Puma#

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

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 的那些键，以及哪些没有对应的对应物。

    UnicornPuma
    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：

    shell
    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 窗口中输入：

    plaintext
    call (void) rb_backtrace()

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

    plaintext
    1from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:33:in `block in start'
2from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:33:in `loop'
3from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:36:in `block (2 levels) in start'
4from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:44:in `sample'
5from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:68:in `sample_objects'
6from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:68:in `each_with_object'
7from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:68:in `each'
8from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:69:in `block in sample_objects'
9from /opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/sampler.rb:69:in `name'

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

    plaintext
    thread apply all bt

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

    plaintext
    detach
exit

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

ruby
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 控制台中，运行：

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

    例如：

    ruby
    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 可能有助于隔离问题：

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

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

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

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

相关主题#