# Gitaly reference

> 原文：[https://docs.gitlab.com/ee/administration/gitaly/reference.html](https://docs.gitlab.com/ee/administration/gitaly/reference.html)

*   [Format](#format)
    *   [Authentication](#authentication)
    *   [TLS](#tls)
    *   [Storage](#storage)
    *   [Git](#git)
        *   [`cat-file` cache](#cat-file-cache)
    *   [`gitaly-ruby`](#gitaly-ruby)
    *   [GitLab Shell](#gitlab-shell)
    *   [Prometheus](#prometheus)
    *   [Logging](#logging)
*   [Concurrency](#concurrency)

# Gitaly reference[](#gitaly-reference "Permalink")

通过[TOML](https://github.com/toml-lang/toml)配置文件配置 Gitaly. 与源安装不同，在 Omnibus GitLab 中，您不会直接编辑此文件.

配置文件作为参数传递给`gitaly`可执行文件. 通常由 Omnibus GitLab 或您的[init](https://en.wikipedia.org/wiki/Init)脚本完成.

可以在 Gitaly 项目中找到[示例配置文件](https://gitlab.com/gitlab-org/gitaly/blob/master/config.toml.example) .

## Format[](#format "Permalink")

在顶层， `config.toml`定义下表中描述的项目.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `socket_path` | string | 是（如果未设置`listen_addr` ） | Gitaly 应该打开 Unix 套接字的路径. |
| `listen_addr` | string | 是（如果未设置`socket_path` ） | Gitaly 侦听的 TCP 地址. |
| `tls_listen_addr` | string | no | TCP over TLS 地址供 Gitaly 侦听. |
| `bin_dir` | string | yes | 包含 Gitaly 可执行文件的目录. |
| `prometheus_listen_addr` | string | no | Prometheus 指标的 TCP 侦听地址. 如果未设置，则不会启动 Prometheus 侦听器. |

例如：

```
socket_path = "/home/git/gitlab/tmp/sockets/private/gitaly.socket"
listen_addr = "localhost:9999"
tls_listen_addr = "localhost:8888"
bin_dir = "/home/git/gitaly"
prometheus_listen_addr = "localhost:9236" 
```

### Authentication[](#authentication "Permalink")

可以将 Gitaly 配置为拒绝标头中不包含特定承载令牌的请求. 这是通过 TCP 服务请求时要使用的一种安全措施：

```
[auth]
# A non-empty token enables authentication.
token = "the secret token" 
```

当`config.toml`的令牌设置不存在或为空字符串时，将禁用身份验证.

可以使用`transitioning`设置暂时禁用身份验证. 这使您可以监视所有客户端是否都在正确认证，而不会导致尚未正确配置的客户端的服务中断：

```
[auth]
token = "the secret token"
transitioning = true 
```

**警告：**完成更改令牌设置后，切记禁用`transitioning` .

所有身份验证尝试均以`gitaly_authentications_total`指标在 Prometheus 中进行计数.

### TLS[](#tls "Permalink")

Gitaly 支持 TLS 加密. 您将需要携带自己的证书，因为该证书不会自动提供.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `certificate_path` | string | no | 证书的路径. |
| `key_path` | string | no | 密钥的路径. |

```
tls_listen_addr = "localhost:8888"

[tls]
certificate_path = '/home/git/cert.cert'
key_path = '/home/git/key.pem' 
```

在 Gitaly 中[了解](index.html#enable-tls-support)有关 TLS 的[更多](index.html#enable-tls-support)信息.

### Storage[](#storage "Permalink")

GitLab 存储库被分组到称为"存储"的目录中（例如`/home/git/repositories` ），其中包含由 GitLab 管理的裸存储库，其名称（例如`default` ）.

这些名称和路径也在 GitLab 的`gitlab.yml`配置文件中定义. 当你在同一台机器 GitLab，这是默认和推荐的配置上运行 Gitaly，在 Gitaly 的定义存储路径`config.toml`必须与在`gitlab.yml` .

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `storage` | array | yes | 一组存储分片. |
| `path` | string | yes | 存储分片的路径. |
| `name` | string | yes | 存储分片的名称. |

例如：

```
[[storage]]
path = "/path/to/storage/repositories"
name = "my_shard"

[[storage]]
path = "/path/to/other/repositories"
name = "other_storage" 
```

### Git[](#git "Permalink")

可以在配置文件的`[git]`部分中设置以下值.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `bin_path` | string | no | Git 二进制文件的路径. 如果未设置，将使用`PATH`进行解析. |
| `catfile_cache_size` | integer | no | 缓存的[cat 文件进程的](#cat-file-cache)最大数量. 默认值为`100` . |

#### `cat-file` cache[](#cat-file-cache "Permalink")

许多 Gitaly RPC 需要从存储库中查找 Git 对象. 大多数时候，我们使用`git cat-file --batch`进程. 为了获得更好的性能，Gitaly 可以在 RPC 调用之间重用这些`git cat-file`过程. 先前使用的进程保留在[" Git cat-file 缓存"中](https://about.gitlab.com/blog/2019/07/08/git-performance-on-nfs/#enter-cat-file-cache) . 为了控制其使用多少系统资源，我们拥有可进入高速缓存的 cat 文件进程的最大数量.

默认限制是 100 个`cat-file` ，它们构成了一对`git cat-file --batch`和`git cat-file --batch-check`进程. 如果您看到抱怨"打开的文件太多"或无法创建新进程的错误，则可以降低此限制.

理想情况下，该数量应该足够大以处理正常流量. 如果提高该限制，则应在前后测量缓存命中率. 如果命中率没有提高，则上限可能不会产生有意义的变化. 这是一个 Prometheus 查询示例，用于查看命中率：

```
sum(rate(gitaly_catfile_cache_total{type="hit"}[5m])) / sum(rate(gitaly_catfile_cache_total{type=~"(hit)|(miss)"}[5m])) 
```

### `gitaly-ruby`[](#gitaly-ruby "Permalink")

一个 Gitaly 进程使用一个或多个`gitaly-ruby`帮助程序进程来执行在 Ruby 中而非 Go 中实现的 RPC. 配置文件的`[gitaly-ruby]`部分包含这些帮助程序的设置.

已知这些进程有时会遭受内存泄漏. 当其内存超过`max_rss`限制时，Gitaly 将重新启动其`gitaly-ruby`帮助`max_rss` .

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `dir` | string | yes | 安装`gitaly-ruby`路径（需要引导该进程）. |
| `max_rss` | integer | no | 触发`gitaly-ruby`重新启动的驻留集大小限制（以字节为单位）. 默认值为`200000000` （200MB）. |
| `graceful_restart_timeout` | string | no | 超出`max_rss`后，强制执行`gitaly-ruby`进程之前的`max_rss` . 默认值为`10m` （10 分钟）. |
| `restart_delay` | string | no | 重新启动之前， `gitaly-ruby`内存必须保持高电平的时间. 默认值为`5m` （5 分钟）. |
| `num_workers` | integer | no | Number of `gitaly-ruby` worker processes. Try increasing this number in case of `ResourceExhausted` errors. Default is `2`, minimum is `2`. |
| `linguist_languages_path` | string | no | 动态`languages.json` .json 发现的替代. 默认为空字符串（使用动态发现）. |

Example:

```
[gitaly-ruby]
dir = "/home/git/gitaly/ruby"
max_rss = 200000000
graceful_restart_timeout = "10m"
restart_delay = "5m"
num_workers = 2 
```

### GitLab Shell[](#gitlab-shell "Permalink")

出于历史原因， [GitLab Shell](https://gitlab.com/gitlab-org/gitlab-shell)包含 Git 挂钩，这些挂钩允许 GitLab 验证并响应 Git 推送. 由于 Gitaly 拥有 Git 推送，因此必须在 Gitaly 旁边安装 GitLab Shell. 将来会[简化](https://gitlab.com/gitlab-org/gitaly/-/issues/1226) .

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `dir` | string | yes | 安装 GitLab Shell 的目录. |

Example:

```
[gitlab-shell]
dir = "/home/git/gitlab-shell" 
```

### Prometheus[](#prometheus "Permalink")

您可以选择配置 Gitaly 以记录 Prometheus 中 GRPC 方法调用的直方图延迟.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `grpc_latency_buckets` | array | no | Prometheus 将每个观察值存储在一个存储桶中，这意味着您将获得延迟的近似值. 优化铲斗可更好地控制逼近精度. |

Example:

```
prometheus_listen_addr = "localhost:9236"

[prometheus]
grpc_latency_buckets = [0.001, 0.005, 0.025, 0.1, 0.5, 1.0, 10.0, 30.0, 60.0, 300.0, 1500.0] 
```

### Logging[](#logging "Permalink")

以下值在`[logging]`部分下的 Gitaly 中配置日志`[logging]` .

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `format` | string | no | 日志格式： `text`或`json` . 默认值： `text` . |
| `level` | string | no | 日志级别： `debug` ， `info` ， `warn` ， `error` ， `fatal`或`panic` . 默认值： `info` . |
| `sentry_dsn` | string | no | Sentry DSN 用于异常监视. |
| `sentry_environment` | string | no | [Sentry Environment](https://docs.sentry.io/enriching-error-data/environments/)用于异常监视. |
| `ruby_sentry_dsn` | string | no | Sentry DSN 用于`gitaly-ruby`异常监视. |

While the main Gitaly application logs go to `stdout`, there are some extra log files that go to a configured directory, like the GitLab Shell logs. GitLab Shell does not support `panic` or `trace` level logs. `panic` will fall back to `error`, while `trace` will fall back to `debug`. Any other invalid log levels will default to `info`.

Example:

```
[logging]
level = "warn"
dir = "/home/gitaly/logs"
format = "json"
sentry_dsn = "https://<key>:<secret>@sentry.io/<project>"
ruby_sentry_dsn = "https://<key>:<secret>@sentry.io/<project>" 
```

## Concurrency[](#concurrency "Permalink")

您可以调整每个 RPC 端点的`concurrency`性.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `concurrency` | array | yes | RPC 端点数组. |
| `rpc` | string | no | RPC 端点的名称（ `/gitaly.RepositoryService/GarbageCollect` ）. |
| `max_per_repo` | integer | no | 每个存储库的每个 RPC 的并发性. |

Example:

```
[[concurrency]]
rpc = "/gitaly.RepositoryService/GarbageCollect"
max_per_repo = 1 
```