Gitaly developers guide · Gitlab 中文文檔

# Gitaly developers guide > 原文：[https://docs.gitlab.com/ee/development/gitaly.html](https://docs.gitlab.com/ee/development/gitaly.html) * [Deep Dive](#deep-dive) * [Beginner’s guide](#beginners-guide) * [Developing new Git features](#developing-new-git-features) * [`gitaly-ruby`](#gitaly-ruby) * [Gitaly-Related Test Failures](#gitaly-related-test-failures) * [Legacy Rugged code](#legacy-rugged-code) * [`TooManyInvocationsError` errors](#toomanyinvocationserror-errors) * [Request counts](#request-counts) * [Running tests with a locally modified version of Gitaly](#running-tests-with-a-locally-modified-version-of-gitaly) * [Use a locally modified version of Gitaly RPC client](#use-a-locally-modified-version-of-gitaly-rpc-client) * [Wrapping RPCs in Feature Flags](#wrapping-rpcs-in-feature-flags) * [Gitaly](#gitaly) * [GitLab Rails](#gitlab-rails) * [Testing with GDK](#testing-with-gdk) # Gitaly developers guide[](#gitaly-developers-guide "Permalink") [Gitaly](https://gitlab.com/gitlab-org/gitaly)是 GitLab Rails，Workhorse 和 GitLab Shell 使用的高級 Git RPC 服務. ## Deep Dive[](#deep-dive "Permalink") 在 2019 年 5 月，Bob Van Landuyt 主持了有關 GitLab 的[Gitaly 項目](https://gitlab.com/gitlab-org/gitaly)以及如何以 Ruby 的形式進行的 Deep Dive（僅限 GitLab 團隊成員： `https://gitlab.com/gitlab-org/create-stage/issues/1` : [//gitlab.com/gitlab-org/create-stage/issues/1](https://gitlab.com/gitlab-org/gitaly) ）開發人員，以便與將來可能在代碼庫這一部分工作的任何人共享他的特定領域知識. 您可以[在 YouTube 上](https://www.youtube.com/watch?v=BmlEWFS8ORo)找到[錄音](https://www.youtube.com/watch?v=BmlEWFS8ORo) ，在[Google 幻燈片](https://docs.google.com/presentation/d/1VgRbiYih9ODhcPnL8dS0W98EwFYpJ7GXMPpX-1TM6YE/edit)和[PDF 中](https://gitlab.com/gitlab-org/create-stage/uploads/a4fdb1026278bda5c1c5bb574379cf80/Create_Deep_Dive__Gitaly_for_Create_Ruby_Devs.pdf)找到[幻燈片](https://docs.google.com/presentation/d/1VgRbiYih9ODhcPnL8dS0W98EwFYpJ7GXMPpX-1TM6YE/edit) . 截至 GitLab 11.11 為止，本次深入介紹中涉及的所有內容都是準確的，盡管自那時以來特定細節可能有所更改，但它仍應作為一個很好的介紹. ## Beginner’s guide[](#beginners-guide "Permalink") 首先閱讀 Gitaly 存儲庫的[Gitaly 貢獻初學者指南](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/beginners_guide.md) . 它描述了如何設置 Gitaly，Gitaly 的各個組件以及它們的作用以及如何運行其測試套件. ## Developing new Git features[](#developing-new-git-features "Permalink") 要讀取或寫入 Git 數據，必須向 Gitaly 發出請求. 這意味著如果您要開發一項新功能，則需要`lib/gitlab/git`尚不可用的數據，則必須對 Gitaly 進行更改. > 這是一個尚未明確定義的新過程. 如果您想提供 Git 功能，但遇到困難，請與 Gitaly 團隊或`@jacobvosmaer-gitlab` . "新功能"是指`lib/gitlab/git`中從`lib/gitlab/git`外部調用的任何方法或類. 有關從`lib/gitlab/git`內部調用的新方法，請參見下面的"修改現有 Git 功能". 在`lib/gitlab/git`之外的任何地方，都不應有任何通過磁盤訪問（例如 Rugged， `git` ， `rm -rf` ）接觸 Git 存儲庫的新代碼. 添加新的 Gitaly 功能的過程是： * 探索/原型制作 * 在[`gitaly-proto`](https://gitlab.com/gitlab-org/gitaly-proto)設計和創建新的 Gitaly RPC * 發行新版本的`gitaly-proto` * 用 Go 或 Ruby [在 Gitaly 中](https://gitlab.com/gitlab-org/gitaly)編寫 RPC 的實現和測試 * release a new version of Gitaly * 在調用新 Gitaly RPC 的 GitLab CE / EE，GitLab Workhorse 或 GitLab Shell 中編寫客戶端代碼這些步驟經常重疊. 在測試和開發過程中，可以使用未發行的 Gitaly 和`gitaly-proto`版本. * 有關使用未發布的協議編寫服務器端代碼的說明，請參見[Gitaly 存儲庫](https://gitlab.com/gitlab-org/gitaly/blob/master/CONTRIBUTING.md#development-and-testing-with-a-custom-gitaly-proto) . * 有關使用修改后的 Gitaly 版本運行 GitLab CE 測試的說明，請參見[下文](#running-tests-with-a-locally-modified-version-of-gitaly) . * 在 GDK 中運行`gdk install`并重新啟動`gdk run` （或`gdk run app` ）以使用本地修改的 Gitaly 版本進行開發 ### `gitaly-ruby`[](#gitaly-ruby "Permalink") 可以在[`gitaly-ruby`](https://gitlab.com/gitlab-org/gitaly/tree/master/ruby)使用 Ruby 代碼在[`gitaly-ruby`](https://gitlab.com/gitlab-org/gitaly/tree/master/ruby)實現和測試 RPC. 這應該使對不喜歡編寫 Go 代碼的開發人員的貢獻更加容易. [Gitaly 存儲庫](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/ruby_endpoint.md)中提供[了](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/ruby_endpoint.md)有關此方法[的文檔](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/ruby_endpoint.md) . ## Gitaly-Related Test Failures[](#gitaly-related-test-failures "Permalink") 如果您的測試套件因 Gitaly 問題而失敗，請首先嘗試運行： ``` rm -rf tmp/tests/gitaly ``` 在 RSpec 測試期間，Gitaly 實例會將日志寫入`gitlab/log/gitaly-test.log` . ## Legacy Rugged code[](#legacy-rugged-code "Permalink") 盡管 Gitaly 可以處理所有 Git 訪問，但許多 GitLab 客戶仍在 NFS 上運行 Gitaly. 由于 N + 1 個 Gitaly 調用和其他原因，用于 Git 調用的傳統 Rugged 實現可能比 Gitaly RPC 更快. 有關更多詳細信息，請參見[問題](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/57317) . 在 GitLab 消除了大多數這些低效率問題或對 Git 數據停止使用 NFS 之前，可以通過功能標志啟用某些最常用 RPC 的 Rugged 實現： * `rugged_find_commit` * `rugged_get_tree_entries` * `rugged_tree_entry` * `rugged_commit_is_ancestor` * `rugged_commit_tree_entry` * `rugged_list_commits_by_oid` 方便的 Rake 任務可用于一起啟用或禁用這些標志. 啟用： ``` bundle exec rake gitlab:features:enable_rugged ``` 禁用： ``` bundle exec rake gitlab:features:disable_rugged ``` 此代碼大部分存在于`lib/gitlab/git/rugged_impl`目錄中. **注意：**除非與[Gitaly Team](https://gitlab.com/groups/gl-gitaly/group_members)明確討論，否則您無需添加或修改與 Rugged 相關的代碼. 此代碼不適用于 GitLab.com 或其他不使用 NFS 的 GitLab 實例. ## `TooManyInvocationsError` errors[](#toomanyinvocationserror-errors "Permalink") 在開發和測試過程中，您可能會遇到`Gitlab::GitalyClient::TooManyInvocationsError`故障. 該`GitalyClient`將試圖通過時 Gitaly 被稱為 30 倍以上在單個的 Rails 請求或 Sidekiq 執行提高此錯誤來阻止對潛在的 n + 1 點的問題. 作為臨時措施，導出`GITALY_DISABLE_REQUEST_LIMITS=1`以消除該錯誤. 這將在開發環境中禁用 n + 1 檢測. 請在 GitLab CE 或 EE 存儲庫中提出問題，以報告該問題. 包括標簽?Gitaly?性能?"技術債務". 請確保問題包含完整的堆棧跟蹤和`TooManyInvocationsError`錯誤消息. 如果可能，還包括任何已知的失敗測試. 找出 n + 1 問題的根源. 通常，這將是一個循環，導致對數組中的每個元素調用 Gitaly. 如果您無法找出問題所在，請與[Gitaly 小組](https://gitlab.com/groups/gl-gitaly/group_members)成員聯系以尋求幫助. 找到源之后，將其包裝在`allow_n_plus_1_calls`塊中，如下所示： ``` # n+1: link to n+1 issue Gitlab::GitalyClient.allow_n_plus_1_calls do # original code commits.each { |commit| ... } end ``` 一旦將代碼包裝在此塊中，將從 n + 1 檢測中排除此代碼路徑. ## Request counts[](#request-counts "Permalink") 提交和其他 Git 數據現在通過 Gitaly 獲取. 可以像數據庫一樣批處理這些提取. 這樣可以提高客戶端以及 Gitaly 本身以及用戶的性能. 為了保持性能穩定并防止性能下降，可以對 Gitaly 通話進行計數，并可以對通話計數進行測試. 這需要設置`:request_store`標志. ``` describe 'Gitaly Request count tests' do context 'when the request store is activated', :request_store do it 'correctly counts the gitaly requests made' do expect { subject }.to change { Gitlab::GitalyClient.get_request_count }.by(10) end end end ``` ## Running tests with a locally modified version of Gitaly[](#running-tests-with-a-locally-modified-version-of-gitaly "Permalink") 通常，GitLab CE / EE 測試在`tmp/tests/gitaly`使用 Gitaly 的本地克隆，固定在`GITALY_SERVER_VERSION`指定的版本上. `GITALY_SERVER_VERSION`文件還支持分支和 SHA，以在[https://gitlab.com/gitlab-org/gitaly 中](https://gitlab.com/gitlab-org/gitaly)使用自定義提交. **注：**通過引入自動部署 Gitaly 的，格式`GITALY_SERVER_VERSION`用總括的語法一致. 它不再支持`=revision` ，它將評估文件內容作為 Git 引用（分支或 SHA），僅當它與 semver 匹配時才在`v` . 如果要針對修改后的 Gitaly 版本在本地運行測試，則可以用符號鏈接替換`tmp/tests/gitaly` . 這要快得多，因為這樣可以避免每次運行`rspec`時都重新安裝 Gitaly. ``` rm -rf tmp/tests/gitaly ln -s /path/to/gitaly tmp/tests/gitaly ``` 在運行測試之前，請確保在本地 Gitaly 目錄中運行`make` . 否則，Gitaly 將無法啟動. 如果您在兩次測試之間更改了本地 Gitaly，則需要再次手動運行`make` . 請注意，CI 測試不會使用您本地修改的 Gitaly 版本. 要在 CI 中使用自定義 Gitaly 版本，您需要按照本段開頭所述更新 GITALY_SERVER_VERSION. 要使用其他 Gitaly 存儲庫（例如，如果您的更改出現在 fork 上），則可以在運行測試時指定`GITALY_REPO_URL`環境變量： ``` GITALY_REPO_URL=https://gitlab.com/nick.thomas/gitaly bundle exec rspec spec/lib/gitlab/git/repository_spec.rb ``` 如果您的 Gitaly 分支是私有的，則可以生成一個[Deploy Token](../user/project/deploy_tokens/index.html)并在 URL 中指定它： ``` GITALY_REPO_URL=https://gitlab+deploy-token-1000:token-here@gitlab.com/nick.thomas/gitaly bundle exec rspec spec/lib/gitlab/git/repository_spec.rb ``` 要在 CI 中使用自定義的 Gitaly 存儲庫，例如，如果您希望 GitLab 分支始終使用自己的 Gitaly 分支，請將`GITALY_REPO_URL`設置為[CI 環境變量](../ci/variables/README.html#gitlab-cicd-environment-variables) . ### Use a locally modified version of Gitaly RPC client[](#use-a-locally-modified-version-of-gitaly-rpc-client "Permalink") 如果要對 RPC 客戶端進行更改，例如添加新端點或向現有端點添加新參數，請遵循[Gitaly proto](https://gitlab.com/gitlab-org/gitaly/blob/master/proto/README.md)指南. 在推送具有更改的分支（例如`new-feature-branch` ）之后： 1. 將 Rails 的`Gemfile`的`gitaly`行更改為： ``` gem 'gitaly', git: 'https://gitlab.com/gitlab-org/gitaly.git', branch: 'new-feature-branch' ``` 2. 運行`bundle install`以使用修改后的 RPC 客戶端. * * * [Return to Development documentation](README.html) ## Wrapping RPCs in Feature Flags[](#wrapping-rpcs-in-feature-flags "Permalink") 以下是在功能標記后在 Gitaly 中選通新功能的步驟. ### Gitaly[](#gitaly "Permalink") 1. 創建一個包范圍的標志名： ``` var findAllTagsFeatureFlag = "go-find-all-tags" ``` 2. 使用`featureflag`包在代碼中創建一個開關： ``` if featureflag.IsEnabled(ctx, findAllTagsFeatureFlag) { // go implementation } else { // ruby implementation } ``` 3. 創建 Prometheus 指標： ``` var findAllTagsRequests = prometheus.NewCounterVec( prometheus.CounterOpts{ Name: "gitaly_find_all_tags_requests_total", Help: "Counter of go vs ruby implementation of FindAllTags", }, []string{"implementation"}, ) func init() { prometheus.Register(findAllTagsRequests) } if featureflag.IsEnabled(ctx, findAllTagsFeatureFlag) { findAllTagsRequests.WithLabelValues("go").Inc() // go implementation } else { findAllTagsRequests.WithLabelValues("ruby").Inc() // ruby implementation } ``` 4. Set headers in tests: ``` import ( "google.golang.org/grpc/metadata" "gitlab.com/gitlab-org/gitaly/internal/featureflag" ) //... md := metadata.New(map[string]string{featureflag.HeaderKey(findAllTagsFeatureFlag): "true"}) ctx = metadata.NewOutgoingContext(context.Background(), md) c, err = client.FindAllTags(ctx, rpcRequest) require.NoError(t, err) ``` ### GitLab Rails[](#gitlab-rails "Permalink") 1. 通過設置功能標記在 Rails 控制臺中進行測試： **注意：請**注意標志的名稱以及在 Rails 控制臺中使用的標志的名稱. 它們之間是有區別的（用下劃線代替短劃線，并且更改了名稱前綴）. 確保在所有標志`gitaly_`加上`gitaly_` . ``` Feature.enable('gitaly_go_find_all_tags') ``` ### Testing with GDK[](#testing-with-gdk "Permalink") 為確保正確設置該標志并將其放入 Gitaly 中，可以使用 GDK 檢查集成： 1. 標志的狀態必須是可觀察的. 要檢查它，您需要通過獲取 Prometheus 指標來啟用它： 1. 導航到 GDK 的根目錄. 2. 確保您已經為 Gitaly 簽出了正確的分支. 3. 使用`make gitaly-setup`重新編譯它，并使用`gdk restart gitaly`重新啟動服務. 4. 確保您的設置正在運行： `gdk status | grep praefect` `gdk status | grep praefect` . 5. 檢查使用了什么配置文件： `cat ./services/praefect/run | grep praefect` `-config`標志的`cat ./services/praefect/run | grep praefect`值 6. 在配置文件中取消注釋`prometheus_listen_addr`并運行`gdk restart gitaly` . 2. Make sure that the flag is not enabled yet: 1. 執行觸發更改所需的任何操作（項目創建，提交提交，觀察歷史記錄等）. 2. 檢查當前指標列表是否具有新的功能標記計數器： ``` curl --silent http://localhost:9236/metrics | grep go_find_all_tags ``` 3. 一旦觀察到新功能標志的度量標準并遞增，就可以啟用新功能： 1. 導航到 GDK 的根目錄. 2. 啟動一個 Rails 控制臺： ``` bundle install && bundle exec rails console ``` 3. 檢查功能標志列表： ``` Feature :: Gitaly . server_feature_flags ``` 應該禁用`"gitaly-feature-go-find-all-tags"=>"false"` . 4. 啟用它： ``` Feature . enable ( 'gitaly_go_find_all_tags' ) ``` 5. 退出 Rails 控制臺并執行觸發更改所需的任何操作（項目創建，提交提交，觀察歷史記錄等）. 6. 通過觀察該功能的度量來確認該功能已啟用： ``` curl --silent http://localhost:9236/metrics | grep go_find_all_tags ```