極狐GitLab 是 GitLab 在中國的發行版,關于中文參考文檔和資料有:
- 極狐GitLab 中文文檔
- 極狐GitLab 中文論壇
- 極狐GitLab 官網
恢復極狐GitLab (BASIC SELF)
極狐GitLab 提供了一個命令行界面來恢復整個安裝,足夠靈活以滿足您的需求。
恢復先決條件部分 包含關鍵信息。在嘗試在生產環境中執行之前,請務必至少閱讀和測試完整的恢復過程一次。
恢復先決條件
目標極狐GitLab 實例必須已經在工作
您需要有一個正在運行的極狐GitLab 安裝才能進行恢復。這是因為執行恢復操作的系統用戶(git)通常不被允許創建或刪除導入數據所需的 SQL 數據庫(gitlabhq_production)。所有現有數據要么被刪除(SQL),要么被移動到單獨的目錄(例如存儲庫和上傳)。恢復 SQL 數據跳過 PostgreSQL 擴展擁有的視圖。
目標極狐GitLab 實例必須具有完全相同的版本
您只能將備份恢復到創建它的極狐GitLab 的完全相同版本和類型(基礎版或企業版)。例如,基礎版 15.1.4。
如果您的備份版本與當前安裝版本不同,則必須在恢復備份之前降級或升級您的極狐GitLab 安裝。
極狐GitLab 密鑰必須恢復
要恢復備份,您還必須恢復極狐GitLab 密鑰。這些包括數據庫加密密鑰,CI/CD 變量,以及用于雙因素認證的變量。如果沒有這些密鑰,會發生多個問題,包括啟用雙因素認證的用戶無法訪問,以及極狐GitLab Runner 無法登錄。
恢復:
-
/etc/gitlab/gitlab-secrets.json(Linux 軟件包安裝)
-
/home/git/gitlab/.secret(自編譯安裝)
-
恢復密鑰(云原生極狐GitLab)
- 如果需要,極狐GitLab Helm chart 密鑰可以轉換為 Linux 軟件包格式。
某些極狐GitLab 配置必須與原始備份環境匹配
您可能還希望恢復之前的 /etc/gitlab/gitlab.rb(對于 Linux 軟件包安裝)或 /home/git/gitlab/config/gitlab.yml(對于自編譯安裝)以及任何 TLS 密鑰、證書(/etc/gitlab/ssl,/etc/gitlab/trusted-certs),或 SSH 主機密鑰。
某些配置與 PostgreSQL 中的數據相關。例如:
- 如果原始環境有三個存儲庫存儲(例如,default、my-storage-1 和 my-storage-2),那么目標環境也必須至少在配置中定義這些存儲名稱。
- 從使用本地存儲的環境恢復備份,即使目標環境使用對象存儲,仍會恢復到本地存儲。遷移到對象存儲必須在恢復之前或之后完成。
恢復作為掛載點的目錄
如果您要恢復到作為掛載點的目錄中,則必須確保這些目錄在嘗試恢復之前是空的。否則,極狐GitLab 會在恢復新數據之前嘗試移動這些目錄,從而導致錯誤。
關于配置 NFS 掛載的信息。
Linux 軟件包安裝的恢復
該過程假設:
- 您已安裝了極狐GitLab 的完全相同版本和類型(基礎版/企業版),備份就是使用該版本創建的。
- 您至少運行過一次 sudo gitlab-ctl reconfigure。
- 極狐GitLab 正在運行。如果沒有,請使用 sudo gitlab-ctl start 啟動它。
首先確保您的備份 tar 文件位于 gitlab.rb 配置中描述的備份目錄中 gitlab_rails[‘backup_path’]。默認路徑是 /var/opt/gitlab/backups。備份文件需要由 git 用戶擁有。
sudo cp 11493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar /var/opt/gitlab/backups/
sudo chown git:git /var/opt/gitlab/backups/11493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar
停止連接到數據庫的進程。讓極狐GitLab 的其他部分繼續運行:
sudo gitlab-ctl stop puma
sudo gitlab-ctl stop sidekiq
# 驗證
sudo gitlab-ctl status
接下來,確保您已完成 恢復先決條件 步驟,并在從原始安裝復制極狐GitLab 密鑰文件后運行 gitlab-ctl reconfigure。
接下來,恢復備份,指定您要恢復的備份的 ID:
WARNING:
以下命令會覆蓋您的極狐GitLab 數據庫的內容!
# NOTE: "_gitlab_backup.tar" 是省略的名稱
sudo gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce
如果您的備份 tar 文件和安裝的極狐GitLab 版本之間存在版本不匹配,恢復命令會以錯誤消息中止:
極狐GitLab 版本不匹配:您當前的極狐GitLab 版本(16.5.0-ee)與備份中的極狐GitLab 版本不同!請切換到以下版本并重試:version: 16.4.3-ee
安裝正確的極狐GitLab 版本,然后重試。
WARNING:
恢復命令需要附加參數,當您的安裝使用 PgBouncer 時,出于性能原因或與 Patroni 集群一起使用時。
接下來,重啟并檢查極狐GitLab:
sudo gitlab-ctl restart
sudo gitlab-rake gitlab:check SANITIZE=true
驗證數據庫值是否可以解密,特別是如果 /etc/gitlab/gitlab-secrets.json 已恢復,或如果不同的服務器是恢復目標。
sudo gitlab-rake gitlab:doctor:secrets
為增加保證,您可以對上傳文件執行完整性檢查:
sudo gitlab-rake gitlab:artifacts:check
sudo gitlab-rake gitlab:lfs:check
sudo gitlab-rake gitlab:uploads:check
恢復完成后,建議生成數據庫統計數據以提高數據庫性能并避免 UI 中的不一致:
1.進入數據庫控制臺。
2.運行以下命令:
SET STATEMENT_TIMEOUT=0 ; ANALYZE VERBOSE;
Docker 鏡像和極狐GitLab Helm chart 安裝的恢復
對于在 Kubernetes 集群上使用 Docker 鏡像或極狐GitLab Helm chart 的極狐GitLab 安裝,恢復任務期望恢復目錄是空的。然而,使用 Docker 和 Kubernetes 卷掛載時,可能會在卷根目錄創建一些系統級目錄,例如在 Linux 操作系統中發現的 lost+found 目錄。這些目錄通常由 root 擁有,這可能導致訪問權限錯誤,因為恢復 Rake 任務以 git 用戶身份運行。要恢復極狐GitLab 安裝,用戶必須確認恢復目標目錄是空的。
對于這兩種安裝類型,備份 tarball 必須可用于備份位置(默認位置是 /var/opt/gitlab/backups)。
Helm chart 安裝的恢復
極狐GitLab Helm chart 使用恢復極狐GitLab Helm chart 安裝中記錄的過程。
Docker 鏡像安裝的恢復
如果您使用 Docker Swarm,容器可能會在恢復過程中重啟,因為 Puma 被關閉,導致容器健康檢查失敗。為了解決這個問題,暫時禁用健康檢查機制。
1.編輯 docker-compose.yml:
healthcheck:
disable: true
2.部署堆棧:
docker stack deploy --compose-file docker-compose.yml mystack可以從主機運行恢復任務:# 停止連接到數據庫的進程
docker exec -it <name of container> gitlab-ctl stop puma
docker exec -it <name of container> gitlab-ctl stop sidekiq# 在繼續之前驗證所有進程都已關閉
docker exec -it <name of container> gitlab-ctl status# 運行恢復。NOTE: "_gitlab_backup.tar" 是省略的名稱
docker exec -it <name of container> gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce# 重啟極狐GitLab 容器
docker restart <name of container># 檢查極狐GitLab
docker exec -it <name of container> gitlab-rake gitlab:check SANITIZE=true
自編譯安裝的恢復
首先,確保您的備份 tar 文件位于 gitlab.yml 配置中描述的備份目錄中:
## 備份設置
backup:path: "tmp/backups" # 相對路徑相對于 Rails.root(默認:tmp/backups/)
默認路徑是 /home/git/gitlab/tmp/backups,并且需要由 git 用戶擁有。現在,您可以開始備份過程:
# 停止連接到數據庫的進程
sudo service gitlab stopsudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production
示例輸出:
解壓備份... [完成]
恢復數據庫表:
-- create_table("events", {:force=>true})-> 0.2231s
[...]
- 加載固定事件...[完成]
- 加載固定議題...[完成]
- 加載固定密鑰...[跳過]
- 加載固定合并請求...[完成]
- 加載固定里程碑...[完成]
- 加載固定命名空間...[完成]
- 加載固定備注...[完成]
- 加載固定項目...[完成]
- 加載固定受保護分支...[跳過]
- 加載固定 schema_migrations...[完成]
- 加載固定服務...[跳過]
- 加載固定代碼片段...[跳過]
- 加載固定標記...[跳過]
- 加載固定標簽...[跳過]
- 加載固定用戶...[完成]
- 加載固定用戶項目...[完成]
- 加載固定 web_hooks...[跳過]
- 加載固定 wiki...[跳過]
恢復存儲庫:
- 恢復存儲庫 abcd... [完成]
- 對象池 1 ...
刪除臨時目錄...[完成]
接下來,如果需要恢復 /home/git/gitlab/.secret,如前所述。
重啟極狐GitLab:
sudo service gitlab restart
從備份中僅恢復一個或幾個項目或組
雖然用于恢復極狐GitLab 實例的 Rake 任務不支持恢復單個項目或組,但您可以通過將備份恢復到單獨的臨時極狐GitLab 實例,然后從那里導出項目或組來使用一種解決方法:
1.安裝一個新的極狐GitLab 實例,版本與您要恢復的備份實例相同。
2.將備份恢復到這個新實例,然后導出您的項目或組。有關導出的內容和未導出的內容的更多信息,請參閱導出功能的文檔。
3.導出完成后,轉到舊實例,然后導入它。
4.完成您想要的項目或組導入后,您可以刪除新的臨時極狐GitLab 實例。
恢復增量存儲庫備份
每個備份檔案都包含一個完整的自包含備份,包括通過增量存儲庫備份過程創建的備份。要恢復增量存儲庫備份,請使用與恢復任何其他常規備份檔案相同的說明。
恢復選項
極狐GitLab 提供的命令行工具可以接受更多選項來從備份中恢復。
在存在多個備份時指定恢復的備份
備份文件使用以備份 ID 開頭的命名方案 starting with a backup ID。當存在多個備份時,您必須通過設置環境變量 BACKUP= 來指定要恢復的 _gitlab_backup.tar 文件。
在恢復期間禁用提示
在從備份恢復期間,恢復腳本會提示確認:
- 如果啟用了 Write to authorized_keys 設置,則在恢復腳本刪除并重建 authorized_keys 文件之前。
- 在恢復數據庫時,在恢復腳本刪除所有現有表之前。
- 在恢復數據庫后,如果恢復架構時出現錯誤,則在繼續之前,因為可能會出現進一步的問題。
要禁用這些提示,請將 GITLAB_ASSUME_YES 環境變量設置為 1。
- Linux 軟件包安裝:
sudo GITLAB_ASSUME_YES=1 gitlab-backup restore
- 自編譯安裝:
sudo -u git -H GITLAB_ASSUME_YES=1 bundle exec rake gitlab:backup:restore RAILS_ENV=production
force=yes 環境變量也會禁用這些提示。
在恢復時排除任務
您可以通過添加環境變量 SKIP 來排除恢復時的特定任務,其值是以下選項的逗號分隔列表:
-
db(數據庫)
-
uploads(附件)
-
builds(CI 作業輸出日志)
-
artifacts(CI 作業制品)
-
lfs(LFS 對象)
-
terraform_state(Terraform 狀態)
-
registry(容器注冊表鏡像)
-
pages(Pages 內容)
-
repositories(Git 存儲庫數據)
-
packages(軟件包)
要排除特定任務:
- Linux 軟件包安裝:
sudo gitlab-backup restore BACKUP=<backup-id> SKIP=db,uploads
- 自編譯安裝:
sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=<backup-id> SKIP=db,uploads RAILS_ENV=production
恢復特定存儲庫存儲
- 引入于極狐GitLab 15.0。
WARNING:
極狐GitLab 17.1 及更早版本受競爭條件影響,可能導致數據丟失。該問題影響了已被 fork 并使用極狐GitLab 對象池的存儲庫。為了避免數據丟失,僅使用極狐GitLab 17.2 或更高版本恢復備份。
當使用多個存儲庫存儲時,可以使用 REPOSITORIES_STORAGES 選項單獨恢復特定存儲庫存儲的存儲庫。該選項接受逗號分隔的存儲名稱列表。
例如:
- Linux 軟件包安裝:
sudo gitlab-backup restore BACKUP=<backup-id> REPOSITORIES_STORAGES=storage1,storage2
- 自編譯安裝:
sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=<backup-id> REPOSITORIES_STORAGES=storage1,storage2
恢復特定存儲庫
- 引入于極狐GitLab 15.1。
WARNING:
極狐GitLab 17.1 及更早版本受競爭條件影響,可能導致數據丟失。該問題影響了已被 fork 并使用極狐GitLab 對象池的存儲庫。為了避免數據丟失,僅使用極狐GitLab 17.2 或更高版本恢復備份。
您可以使用 REPOSITORIES_PATHS 和 SKIP_REPOSITORIES_PATHS 選項恢復特定存儲庫。這兩個選項都接受項目和組路徑的逗號分隔列表。如果您指定了組路徑,則所有項目中的所有存儲庫以及子組中的存儲庫都被包括在內或跳過,具體取決于您使用的選項。這些組和項目必須存在于指定的備份或目標實例中。
NOTE:
REPOSITORIES_PATHS 和 SKIP_REPOSITORIES_PATHS 選項僅適用于 Git 存儲庫。它們不適用于項目或組數據庫條目。如果您使用 SKIP=db 創建了存儲庫備份,單獨它不能用于將特定存儲庫恢復到新實例。
例如,要恢復 群組 A(group-a)中所有項目的所有存儲庫,群組 B 中 項目 C(group-b/project-c)的存儲庫,并跳過 群組 A 中的 項目 D(group-a/project-d):
- Linux 軟件包安裝:
sudo gitlab-backup restore BACKUP=<backup-id> REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d
- 自編譯安裝:
sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=<backup-id> REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d
恢復未打包的備份
如果發現未打包的備份(使用 SKIP=tar 創建),并且沒有使用 BACKUP= 選擇備份,則使用未打包的備份。
例如:
- Linux 軟件包安裝:
sudo gitlab-backup restore
- 自編譯安裝:
sudo -u git -H bundle exec rake gitlab:backup:restore
故障排除
以下是您可能遇到的問題以及潛在的解決方案。
使用 Linux 軟件包安裝時輸出警告恢復數據庫備份
如果您使用備份恢復程序,可能會遇到以下警告消息:
ERROR: 必須是擴展 pg_trgm 的所有者
ERROR: 必須是擴展 btree_gist 的所有者
ERROR: 必須是擴展 plpgsql 的所有者
WARNING: "public" 沒有權限可以撤銷(出現兩次)
WARNING: "public" 沒有權限被授予(出現兩次)
請注意,備份已成功恢復,盡管有這些警告消息。
Rake 任務以 gitlab 用戶身份運行,該用戶沒有數據庫的超級用戶訪問權限。當恢復啟動時,它也以 gitlab 用戶身份運行,但它也嘗試改變它沒有訪問權限的對象。這些對象對數據庫備份或恢復沒有影響,但顯示警告消息。
有關更多信息,請參閱:
-
PostgreSQL 問題跟蹤:
- 不是超級用戶。
- 具有不同所有者。
由于 Git 服務器鉤子導致恢復失敗
在備份恢復期間,如果以下條件為真,您可能會遇到錯誤:
- 使用極狐GitLab 版本 15.10 及更早版本的方法配置了 Git 服務器鉤子(custom_hook)
- 您的極狐GitLab 版本是版本 15.11 及更高版本
- 您創建了指向極狐GitLab 管理位置之外的目錄的符號鏈接
錯誤看起來像:
{"level":"fatal","msg":"restore: pipeline: 1 failures encountered:\n - @hashed/path/to/hashed_repository.git (path/to_project): manager: restore custom hooks, \"@hashed/path/to/hashed_repository/<BackupID>_<GitLabVersion>-ee/001.custom_hooks.tar\": rpc error: code = Internal desc = setting custom hooks: generating prepared vote: walking directory: copying file to hash: read /mnt/gitlab-app/git-data/repositories/+gitaly/tmp/default-repositories.old.<timestamp>.<temporaryfolder>/custom_hooks/compliance-triggers.d: is a directory\n","pid":3256017,"time":"2023-08-10T20:09:44.395Z"}
要解決此問題,可以更新極狐GitLab 版本 15.11 及更高版本的 Git 服務器鉤子,并創建新的備份。
使用 fapolicyd 時恢復成功但存儲庫顯示為空
使用 fapolicyd 增強安全性時,極狐GitLab 可以報告恢復成功,但存儲庫顯示為空。有關更多故障排除幫助,請參閱Gitaly 故障排除文檔。