Geo (development) · Gitlab 中文文檔

# Geo (development) > 原文：[https://docs.gitlab.com/ee/development/geo.html](https://docs.gitlab.com/ee/development/geo.html) * [Replication layer](#replication-layer) * [Geo Log Cursor daemon](#geo-log-cursor-daemon) * [Database replication](#database-replication) * [Repository replication](#repository-replication) * [Project Registry](#project-registry) * [Repository Sync worker](#repository-sync-worker) * [Uploads replication](#uploads-replication) * [Upload Registry](#upload-registry) * [File Download Dispatch worker](#file-download-dispatch-worker) * [Authentication](#authentication) * [Git Push to Geo secondary](#git-push-to-geo-secondary) * [Using the Tracking Database](#using-the-tracking-database) * [Configuration](#configuration) * [Foreign Data Wrapper](#foreign-data-wrapper) * [Refreshing the Foreign Tables](#refreshing-the-foreign-tables) * [Accessing data from a Foreign Table](#accessing-data-from-a-foreign-table) * [Finders](#finders) * [Finders Performance](#finders-performance) * [Redis](#redis) * [Object Storage](#object-storage) * [Verification](#verification) * [Repository verification](#repository-verification) * [Glossary](#glossary) * [Primary node](#primary-node) * [Secondary node](#secondary-node) * [Streaming replication](#streaming-replication) * [Tracking database](#tracking-database) * [FDW](#fdw) * [Geo Event Log](#geo-event-log) * [Geo Log Cursor](#geo-log-cursor) * [Code features](#code-features) * [`Gitlab::Geo` utilities](#gitlabgeo-utilities) * [Current node](#current-node) * [Primary or secondary](#primary-or-secondary) * [Geo Database configured?](#geo-database-configured) * [Enablement](#enablement) * [Read-only](#read-only) * [Steps needed to replicate a new data type](#steps-needed-to-replicate-a-new-data-type) * [Geo self-service framework (alpha)](#geo-self-service-framework-alpha) * [History of communication channel](#history-of-communication-channel) * [Custom code (GitLab 8.6 and earlier)](#custom-code-gitlab-86-and-earlier) * [System hooks (GitLab 8.7 to 9.5)](#system-hooks-gitlab-87-to-95) * [Geo Log Cursor (GitLab 10.0 and up)](#geo-log-cursor-gitlab-100-and-up) * [Self-service framework](#self-service-framework) # Geo (development)[](#geo-development-premium-only "Permalink") Geo 將 GitLab 實例連接在一起. 一個 GitLab 實例被指定**為主**節點，并且可以與多個**輔助**節點一起運行. Geo 精心策劃了很多組件，這些組件可以在下圖中看到，并在本文檔中進行了更詳細的描述. [![Geo Architecture Diagram](https://img.kancloud.cn/df/46/df46f240bd1ee71d25036c347ec2b792_1059x1168.png)](../administration/geo/replication/img/geo_architecture.png) ## Replication layer[](#replication-layer "Permalink") Geo 處理不同組件的復制： * [數據庫](#database-replication) ：包括整個應用程序，緩存和作業除外. * [Git 存儲庫](#repository-replication) ：包括項目和 Wiki. * [上載的 Blob](#uploads-replication) ：包括從問題附帶的圖像到 CI 的原始日志和資產的所有內容. 除數據庫復制外，在*輔助*節點上，所有內容均由[Geo Log Cursor](#geo-log-cursor)協調. ### Geo Log Cursor daemon[](#geo-log-cursor-daemon "Permalink") [Geo Log Cursor 守護程序](#geo-log-cursor-daemon)是在每個**輔助**節點上運行的單獨進程. 它監視[地理事件日志中](#geo-event-log)是否有新事件，并為每種特定事件類型創建后臺作業. 例如，當更新存儲庫時，Geo **主**節點會創建一個帶有關聯的存儲庫更新事件的 Geo 事件. Geo Log Cursor 守護程序接收事件并安排一個`Geo::ProjectSyncWorker`作業，該作業將使用`Geo::RepositorySyncService`和`Geo::WikiSyncService`類分別更新存儲庫和 Wiki. Geo Log Cursor 守護程序可以自動在高可用性模式下運行. 守護程序將不時嘗試獲取鎖，一旦獲得鎖定，它將充當*活動*守護程序. 在同一節點上的所有其他正在運行的守護程序都將處于待機模式，如果*活動*守護程序釋放其鎖定，則可以恢復工作. We use the [`ExclusiveLease`](https://www.rubydoc.info/github/gitlabhq/gitlabhq/Gitlab/ExclusiveLease) lock type with a small TTL, that is renewed at every pooling cycle. That allows us to implement this global lock with a timeout. 在池化周期結束時，如果守護程序無法更新和/或重新獲得鎖定，它將切換到待機模式. ### Database replication[](#database-replication "Permalink") Geo 使用[流復制](#streaming-replication)將數據庫從**主**節點[復制](#streaming-replication)到**輔助**節點. 通過此復制， **輔助**節點可以訪問數據庫中保存的所有數據. 因此，用戶可以登錄**次級**和讀取所有的問題，合并請求等**輔助**節點上. ### Repository replication[](#repository-replication "Permalink") Geo 還復制存儲庫. 每個**輔助**節點都[跟蹤跟蹤數據庫](#tracking-database)中每個存儲庫的狀態. 存在以下幾種方式來復制存儲庫： * [Repository Sync worker](#repository-sync-worker). * [Geo Log Cursor](#geo-log-cursor). #### Project Registry[](#project-registry "Permalink") `Geo::ProjectRegistry`類定義用于跟蹤存儲庫復制狀態的模型. 對于主數據庫中的每個項目，在跟蹤數據庫中保留一個記錄. 它記錄有關存儲庫的以下內容： * 他們上次同步的時間. * 上一次成功同步它們. * 是否需要重新同步. * 重試的時間. * 重試次數. * 是否以及何時進行驗證. 它還將項目 Wiki 的這些屬性存儲在專用列中. #### Repository Sync worker[](#repository-sync-worker "Permalink") The `Geo::RepositorySyncWorker` class runs periodically in the background and it searches the `Geo::ProjectRegistry` model for projects that need updating. Those projects can be: * 未同步：從未在**輔助**節點上同步過的項目，因此尚不存在. * 最近更新：項目的`last_repository_updated_at`時間戳比`Geo::ProjectRegistry`模型中的`last_repository_successful_sync_at`時間戳更新. * 手動：管理員可以在[地理管理面板中](../user/admin_area/geo_nodes.html)手動標記存儲庫以重新同步. 當我們在次要`RETRIES_BEFORE_REDOWNLOAD`時間內無法獲取存儲庫時，Geo 會進行所謂的*重新下載* . 它將干凈地克隆到存儲根目錄中的`@geo-temporary`目錄中. 成功后，我們用新克隆的倉庫替換主倉庫. ### Uploads replication[](#uploads-replication "Permalink") 文件上傳也被復制到**輔助**節點. 為了跟蹤同步狀態，使用了`Geo::UploadRegistry`模型. #### Upload Registry[](#upload-registry "Permalink") 與[項目注冊表](#project-registry)類似，有一個`Geo::UploadRegistry`模型可以跟蹤同步的上傳. CI Job Artifacts and LFS objects are synced in a similar way as uploads, but they are tracked by `Geo::JobArtifactRegistry`, and `Geo::LfsObjectRegistry` models respectively. #### File Download Dispatch worker[](#file-download-dispatch-worker "Permalink") 還類似于[Repository Sync 工作器](#repository-sync-worker) ，有一個`Geo::FileDownloadDispatchWorker`類，該類定期運行以同步所有尚未同步到 Geo **輔助**節點的上載. 通過 HTTP 復制文件，并通過`/api/v4/geo/transfers/:type/:id`端點（例如`/api/v4/geo/transfers/lfs/123` . ## Authentication[](#authentication "Permalink") 為了驗證文件傳輸，每個`GeoNode`記錄都有兩個字段： * 公共訪問密鑰（ `access_key`字段）. * 秘密訪問密鑰（ `secret_access_key`字段）. **次要**節點通過[JWT 請求進行](https://jwt.io/)身份驗證. 當**輔助**節點希望下載文件時，它將發送帶有`Authorization`標頭的 HTTP 請求： ``` Authorization: GL-Geo <access_key>:<JWT payload> ``` **主**節點使用`access_key`字段查找相應的**輔助**節點并解密 JWT 有效負載，該負載包含用于標識文件請求的其他信息. 這樣可以確保**輔助**節點為正確的數據庫 ID 下載正確的文件. 例如，對于 LFS 對象，請求還必須包含文件的 SHA256 和. JWT 有效負載示例如下所示： ``` { "data": { sha256: "31806bb23580caab78040f8c45d329f5016b0115" }, iat: "1234567890" } ``` 如果請求的文件與請求的 SHA256 總和匹配，則 Geo **主**節點將通過[X-Sendfile](https://www.nginx.com/resources/wiki/start/topics/examples/xsendfile/)功能發送數據，這使 NGINX 可以處理文件傳輸而不會占用 Rails 或 Workhorse. **注意：** JWT 需要在所涉及的機器之間同步時鐘，否則它可能會因加密錯誤而失敗. ## Git Push to Geo secondary[](#git-push-to-geo-secondary "Permalink") Git Push Proxy 作為`gitlab-shell`組件內置的功能存在. 它僅在**輔助**節點上處于活動狀態. 它允許從輔助節點克隆存儲庫的用戶推送到相同的 URL. 定向到**次**節點的 Git `push`請求將發送到**主**節點，而`pull`請求將繼續由**次**節點服務，以實現最大效率. HTTPS 和 SSH 請求的處理方式不同： * 使用 HTTPS，我們將為用戶提供指向**主**節點上項目的`HTTP 302 Redirect` . Git 客戶端足夠聰明，可以理解該狀態碼并處理重定向. * 使用 SSH，因為沒有等效的方法來執行重定向，所以我們必須代理請求. 這是在[`gitlab-shell`](https://gitlab.com/gitlab-org/gitlab-shell)內部[`gitlab-shell`](https://gitlab.com/gitlab-org/gitlab-shell) ，方法是先將請求轉換為 HTTP 協議，然后將其代理到**主**節點. [`gitlab-shell`](https://gitlab.com/gitlab-org/gitlab-shell)守護程序根據`/api/v4/allowed`的響應知道何時進行代理. 返回一個特殊的`HTTP 300`狀態代碼，我們執行在響應正文中指定的"自定義操作". 該響應包含允許代理`push`操作在**主**節點上發生的其他數據. ## Using the Tracking Database[](#using-the-tracking-database "Permalink") 除了要復制的主數據庫外，Geo **輔助**節點還具有自己的單獨的[跟蹤數據庫](#tracking-database) . 跟蹤數據庫包含**輔助**節點的狀態. 任何需要在升級過程中運行的數據庫遷移都需要應用于每個**輔助**節點上的跟蹤數據庫. ### Configuration[](#configuration "Permalink") 數據庫配置在[`config/database_geo.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/config/database_geo.yml.postgresql)設置. [`ee/db/geo`](https://gitlab.com/gitlab-org/gitlab/tree/master/ee/db/geo)目錄包含此數據庫的架構和遷移. 要為數據庫編寫遷移，請使用`GeoMigrationGenerator` ： ``` rails g geo_migration [args] [options] ``` 要遷移跟蹤數據庫，請運行： ``` bundle exec rake geo:db:migrate ``` ### Foreign Data Wrapper[](#foreign-data-wrapper "Permalink") 在 GitLab 10.1 中引入. [地理日志游標](#geo-log-cursor)使用了外部數據包裝器（ [FDW](#fdw) ），并提高了許多同步操作的性能. FDW 是 PostgreSQL 擴展（ [`postgres_fdw`](https://s0www0postgresql0org.icopy.site/docs/11/postgres-fdw.html) ），已在 Geo Tracking 數據庫中（在**輔助**節點上）啟用，它允許它連接到只讀數據庫副本并執行查詢和過濾來自兩個實例的數據. 該持久連接被配置為名為`gitlab_secondary`的 FDW 服務器. 此配置僅存在于數據庫的用戶上下文中. 要訪問`gitlab_secondary` ，GitLab 需要使用先前配置的同一數據庫用戶. 地理跟蹤數據庫以常規用戶身份通過??FDW 訪問只讀數據庫副本，受其自身限制的限制. 憑據被配置為與先前映射的`SERVER` （ `gitlab_secondary` ）相關聯的`USER MAPPING` . FDW 配置和憑據定義由 Omnibus GitLab `gitlab-ctl reconfigure`命令自動管理. #### Refreshing the Foreign Tables[](#refreshing-the-foreign-tables "Permalink") 每當在**主**節點上配置了新的地理節點或數據庫架構更改時，都必須通過運行以下命令來刷新**輔助**節點上的外部表： ``` bundle exec rake geo:db:refresh_foreign_tables ``` 否則，將阻止**輔助**節點正常運行. **輔助**節點將生成錯誤消息，如以下 PostgreSQL 錯誤所示： ``` ERROR: relation "gitlab_secondary.ci_job_artifacts" does not exist at character 323 STATEMENT: SELECT a.attname, format_type(a.atttypid, a.atttypmod), pg_get_expr(d.adbin, d.adrelid), a.attnotnull, a.atttypid, a.atttypmod FROM pg_attribute a LEFT JOIN pg_attrdef d ON a.attrelid = d.adrelid AND a.attnum = d.adnum WHERE a.attrelid = '"gitlab_secondary"."ci_job_artifacts"'::regclass AND a.attnum > 0 AND NOT a.attisdropped ORDER BY a.attnum ``` #### Accessing data from a Foreign Table[](#accessing-data-from-a-foreign-table "Permalink") 在 SQL 級別，您要做的就是從`gitlab_secondary.*` `SELECT`數據. 這是一個如何從地理跟蹤數據庫的 FDW 訪問所有項目的示例： ``` SELECT * FROM gitlab_secondary.projects; ``` 作為一個更真實的示例，這是在"跟蹤數據庫"中過濾未歸檔項目的方式： ``` SELECT project_registry.* FROM project_registry JOIN gitlab_secondary.projects ON (project_registry.project_id = gitlab_secondary.projects.id AND gitlab_secondary.projects.archived IS FALSE) ``` 在 ActiveRecord 級別，我們還有其他表示外部表的模型. 必須以稍微不同的方式映射它們，并且它們是只讀的. 檢查`ee/app/models/geo/fdw`現有的 FDW 模型以供參考. 從開發人員的角度來看，這與創建代表數據庫視圖的模型沒有什么不同. 通過上面的示例，您可以通過以下方式訪問項目： ``` Geo::Fdw::Project.all ``` 并通過未歸檔的項目訪問`ProjectRegistry`過濾： ``` # We have to use Arel here: project_registry_table = Geo::ProjectRegistry.arel_table fdw_project_table = Geo::Fdw::Project.arel_table project_registry_table.join(fdw_project_table) .on(project_registry_table[:project_id].eq(fdw_project_table[:id])) .where((fdw_project_table[:archived]).eq(true)) # if you append `.to_sql` you can check generated query ``` ## Finders[](#finders "Permalink") Geo 使用[Finders](https://gitlab.com/gitlab-org/gitlab/tree/master/app/finders) ，這是一些類，可以幫助您輕松查找項目/附件/等. 在跟蹤數據庫和主數據庫中. ### Finders Performance[](#finders-performance "Permalink") 查找者需要將主數據庫中的數據與跟蹤數據庫中的數據進行比較. 例如，計算已同步項目的數量通常涉及從一個數據庫中檢索項目 ID，并檢查它們在另一個數據庫中的狀態. 這很慢并且需要大量內存. 為了克服這個問題，查找器使用[FDW](#fdw)或外部數據包裝器. 這允許在主數據庫和跟蹤數據庫之間進行常規的`JOIN` . ## Redis[](#redis "Permalink") Redis 的**輔助**節點上的工作方式相同的**主**節點上. 它用于緩存，存儲會話和其他持久性數據. 不使用**主**節點和**輔助**節點之間的 Redis 數據復制，因此會話等不在節點之間共享. ## Object Storage[](#object-storage "Permalink") GitLab 可以選擇使用對象存儲來存儲否則將存儲在磁盤上的數據. 這些事情可以是： * LFS Objects * CI 工作工件 * Uploads Geo 不處理存儲在對象存儲中的對象. Geo 會忽略對象存儲中的項目. 要么： * 對象存儲層應注意其自身的地理復制. * 所有輔助節點應使用相同的存儲節點. ## Verification[](#verification "Permalink") ### Repository verification[](#repository-verification "Permalink") 存儲庫將通過校驗和進行驗證. **主**節點在存儲庫上計算校驗和. 它基本上將所有 Git 引用散列在一起，并將該散列存儲在數據庫的`project_repository_states`表中. **次**節點執行相同操作以計算其克隆的哈希，然后將哈希與**主**節點計算出的值進行比較. 如果存在不匹配，Geo 會將其標記為不匹配，管理員可以在[Geo 管理面板中](../user/admin_area/geo_nodes.html)看到此不匹配. ## Glossary[](#glossary "Permalink") ### Primary node[](#primary-node "Permalink") **主**節點是地理設置中具有讀寫功能的單個節點. 這是事實的唯一來源，Geo **次要**節點從那里復制數據. 在地理位置設置中，只能有一個**主**節點. 所有**輔助**節點都連接到該**主**節點. ### Secondary node[](#secondary-node "Permalink") **輔助**節點是在不同地理位置運行的**主要**節點的只讀副本. ### Streaming replication[](#streaming-replication "Permalink") Geo 取決于 PostgreSQL 的流復制功能. 它完全復制數據庫數據和數據庫模式. 數據庫副本是只讀副本. 流復制取決于預寫日志或 WAL. 這些日志將復制到副本并在此處重放. 由于流復制還可以復制架構，因此數據庫遷移不需要在輔助節點上運行. ### Tracking database[](#tracking-database "Permalink") 每個 Geo **輔助**節點上的數據庫，該數據庫保留其所在節點的狀態. 在[使用跟蹤數據庫中](#using-the-tracking-database)閱讀更多[信息](#using-the-tracking-database) . ### FDW[](#fdw "Permalink") 外部數據包裝程序（FDW）是 PostgreSQL 內置的功能. 它允許從不同的數據源查詢數據. 在 Geo 中，它用于查詢來自不同 PostgreSQL 實例的數據. ## Geo Event Log[](#geo-event-log "Permalink") Geo **主數據庫**將事件存儲在`geo_event_log`表中. 日志中的每個條目都包含特定類型的事件. 這些類型的事件包括： * 存儲庫已刪除事件 * 存儲庫重命名事件 * 存儲庫更改事件 * 存儲庫創建事件 * 哈希存儲遷移事件 * Lfs 對象已刪除事件 * 哈希存儲附件事件 * Job Artifact Deleted 事件 * 上載已刪除的活動 ### Geo Log Cursor[](#geo-log-cursor "Permalink") 在尋找新的`Geo::EventLog`行的**輔助**節點上運行的進程. ## Code features[](#code-features "Permalink") ### `Gitlab::Geo` utilities[](#gitlabgeo-utilities "Permalink") 與 Geo 相關的小型實用工具方法進入[`ee/lib/gitlab/geo.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/gitlab/geo.rb)文件. 其中許多方法都使用`RequestStore`類進行緩存，以減少在整個代碼庫中使用這些方法對性能的影響. #### Current node[](#current-node "Permalink") 類方法`.current_node`返回當前節點的`GeoNode`記錄. 我們使用`gitlab.yml`的`host` ， `port`和`relative_url_root`值，并在數據庫中搜索以標識我們所在的節點（請參見`GeoNode.current_node` ）. #### Primary or secondary[](#primary-or-secondary "Permalink") 要確定當前節點是**主**節點還是**輔助**節點，請使用`.primary?` 和`.secondary?` 類方法. 當未啟用節點時，這些方法都可能在節點上都返回`false` . 請參閱[啟用](#enablement) . #### Geo Database configured?[](#geo-database-configured "Permalink") 處理初始化期間發生的事情時，還有一個附加的陷阱. 在一些地方，我們使用`Gitlab::Geo.geo_database_configured?` 檢查節點是否具有跟蹤數據庫的方法，該數據庫僅存在于**輔助**節點上. 這克服了在引導新節點期間可能發生的競爭條件. #### Enablement[](#enablement "Permalink") 當用戶擁有包括功能的有效許可證，并且在"地理節點"屏幕上定義了至少一個節點時，我們認為地理功能已啟用. See `Gitlab::Geo.enabled?` and `Gitlab::Geo.license_allows?` methods. #### Read-only[](#read-only "Permalink") 所有地理**輔助**節點均為只讀. [只讀數據庫](verifying_database_capabilities.html#read-only-database)的一般原則適用于所有 Geo **輔助**節點. 那么`Gitlab::Database.read_only?` 方法將始終在**輔助**節點上返回`true` . 當由于節點是**輔助**節點而不允許某些寫操作時，請考慮添加`Gitlab::Database.read_only?` 還是`Gitlab::Database.read_write?` 后衛，而不是`Gitlab::Geo.secondary?` . 在復制的設置中，數據庫本身已經是只讀的，因此我們無需為此采取任何額外的步驟. ## Steps needed to replicate a new data type[](#steps-needed-to-replicate-a-new-data-type "Permalink") 隨著 GitLab 的發展，我們不斷需要向 Geo 復制系統添加新資源. 具體實現取決于資源的具體情況，但是需要注意以下幾點： * 主站點上的事件生成. 每當更改/更新新資源時，我們都需要為 Log Cursor 創建一個任務. * 事件處理. 日志游標需要為主站點生成的每種事件類型都有一個處理程序. * 派遣工人（臨時工）. 確保回填條件良好. * 同步工作者. * 注冊所有可能的狀態. * Verification. * 清潔器. 更改輔助站點的同步設置后，需要清理一些資源. * 地理節點狀態. 我們需要在 GitLab 管理區域中提供 API 端點以及一些演示. * 健康檢查. 如果我們可以執行一些預檢查并在出現問題時使節點不正常，則應該這樣做. `rake gitlab:geo:check`命令也必須更新. ### Geo self-service framework (alpha)[](#geo-self-service-framework-alpha "Permalink") 我們開始開發新的[Geo 自助服務框架（alpha）](geo/framework.html) ，這使添加新數據類型變得容易得多. ## History of communication channel[](#history-of-communication-channel "Permalink") 自從第一次迭代以來，溝通渠道已經發生了變化，您可以在此處查看歷史性決策以及我們為何遷移到新實現的原因. ### Custom code (GitLab 8.6 and earlier)[](#custom-code-gitlab-86-and-earlier "Permalink") 在 8.6 之前的 GitLab 版本中，自定義代碼用于處理 HTTP 請求從**主**節點到**輔助**節點的通知. ### System hooks (GitLab 8.7 to 9.5)[](#system-hooks-gitlab-87-to-95 "Permalink") 后來，決定放棄自定義代碼，開始使用系統掛鉤. 使用它們的人越來越多，因此許多人將從對該通信層進行的改進中受益. 我們的 API 代碼（Grape）中有一個特定的**內部**端點，該端點接收來自此系統掛鉤的所有請求： `/api/v4/geo/receive_events` . 我們通過`event_name`字段切換和過濾每個事件. ### Geo Log Cursor (GitLab 10.0 and up)[](#geo-log-cursor-gitlab-100-and-up "Permalink") 從 GitLab 10.0 開始，不再使用[系統 Webhooks](#system-hooks-gitlab-87-to-95) ， [而是](#system-hooks-gitlab-87-to-95)使用 Geo Log Cursor. 日志光標遍歷`Geo::EventLog`行以查看自上次檢查日志以來是否有更改，并將處理存儲庫更新，刪除，更改和重命名. 該表位于復制的數據庫中. 與舊方法相比，它具有兩個優點： * 復制是同步的，我們保留事件的順序. * 事件的復制與數據庫中的更改同時發生. ## Self-service framework[](#self-service-framework "Permalink") 如果您想為正在處理的資源添加簡單的地理復制，請查看我們的[自助服務框架](geo/framework.html) .