配置 Gitlab 和 Elasticsearch/Zoekt 并使用 Docker Metadata 數據庫、Camo 代理服務

本文章首發于：連接 Gitlab 和 Elasticsearch/Zoekt 并使用 Docker Metadata 數據庫、Camo 代理服務 - Ayaka 的小站

為確保更好閱讀格式和閱讀體驗，更建議前往個人博客閱讀 ~，另外本文章部分內部 Issue 鏈接為個人 Gitlab，不保證鏈接可用性。

一、簡介

1）前提

大家好啊我是?Musicminion。今天這期博客來點小眾一點話題——把 Gitlab 接入 ElasticSearch 還有 Zoekt 搜索引擎，以及把 Docker 鏡像倉庫的 Metadata 遷移到 PostgreSQL 數據庫里面。

如果你想要學習 Gitlab 部署，網上還是有不少文章的，這篇文章可能對你不是很適用，因為這個算是比較進階的內容，前提是需要有一個你部署好的?Gitlab EE (企業版)?實例。關于獲取企業版許可證，請參考?Activate GitLab Enterprise Edition (EE) | GitLab Docs。

我知道大部分人部署?Gitlab?可能純純的當做內部協作的代碼倉庫來使用的，但是其實對于熱愛折騰朋友來說，探索應該不止于此。Gitlab 作為一個非常優秀的代碼存儲工具，功能經過數年的迭代還是非常全的，幾乎可以當做一個 All in One 的開發工具，比如下面的內容，網上已經有不少教程：

Gitlab Pages：個人靜態網站部署工具
Gitlab Docker Registry：容器鏡像庫
配置 Github 集成的單點登錄
CI/CD：流水線和 Runner 的配置
其他一些 Bug 的修復等

但是有些比較小眾的功能，比如搜索等，這些功能中文教程很少。得對著說明文檔一點一點的配置。因此這篇文章介紹一下 Gitlab 的小眾功能。

2）搜索功能簡介

Gitlab 的高級搜索還有精確代碼搜索都是付費功能，需要企業版許可證。

Gitlab 支持不同類型的 Gitlab 搜索，比如搜索代碼，搜索 Issue、項目名字，這些功能統稱搜索。

社區 CE 版搜索：只支持最基本的搜索：項目名字等
Gitlab 高級搜索：可以搜索具體代碼、評論、Issue 內容、里程碑
Zoekt 精確代碼：高級搜索的代碼不一定準確，Zoekt 可以更精準的搜索到代碼（beta 版）

因為我平時個人搜索代碼還是很頻繁的，你要說為什么不本地 vscode 里面直接搜，那肯定是最快的嘛，但是有時候開發很可能就是想起來了，在瀏覽器里面順手一搜索的事，能簡化肯定是希望更簡化的。

這是不同搜索支持的功能，看完之后是不是很心動：

基本搜索 (Basic search)				高級搜索 (Advanced search)				精確代碼搜索 (Exact code search)
范圍	全局	群組	項目	范圍	全局	群組	項目	范圍	全局	群組	項目
Code	No	No	Yes	Code	Yes	Yes	Yes	Code	No	Yes	Yes
Comments	No	No	Yes	Comments	Yes	Yes	Yes	Comments	No? ??
Commits	No	No	Yes	Commits	Yes	Yes	Yes	Commits
Epics	No	Yes	No	Epics	Yes	Yes	No	Epics
Issues	Yes	Yes	Yes	Issues	Yes	Yes	Yes	Issues
Merge requests	Yes	Yes	Yes	Merge requests	Yes	Yes	Yes	Merge requests
Milestones	Yes	Yes	Yes	Milestones	Yes	Yes	Yes	Milestones
Projects	Yes	Yes	No	Projects	Yes	Yes	No	Projects
Users	Yes	Yes	Yes	Users	Yes	Yes	Yes	Users
Wikis	No	No	Yes	Wikis	Yes	Yes	Yes	Wikis

這個是部署好后的效果：

精確搜索：僅適用于代碼搜索，并且會在搜索框里面顯示：精確代碼搜索（由 Zoekt 提供支持）已啟用。如果你用過高級搜索，你會發現高級搜索代碼經常可能會搜出來一堆無關緊要的東西，精確搜索可以保證搜到的所見即所

GitLab 精確搜索

GitLab 精確搜索?

高級搜索：可以搜索 Wiki、Commit 記錄等，會提示：高級搜索?已啟用

GitLab 高級搜索

GitLab 高級搜索?

3）容器鏡像庫 Metadata

如果你已經運營了一段時間的 Gitlab 的容器鏡像庫，就會發現你的 Gitlab 數據越來越大，經過排查我發現是 Gitlab 的容器鏡像庫默認情況不會自動做垃圾回收（GC）。（即使你通過 Web 界面刪除了一個 Docker Image，容器鏡像依然存儲在你的 Gitlab 中）

有關垃圾回收的教程，請參考?Running the garbage collection on schedule | GitLab Docs，具體就是運行下面這個命令：

sudo gitlab-ctl stop  # 停止 gitlab
sudo gitlab-ctl registry-garbage-collect # 運行垃圾回收
sudo gitlab-ctl start # 重啟 gitlab

注意，Gitlab 的垃圾回收需要停止 Gitlab 服務的運行，不能支持在線回收。那要做到支持在線回收，必須遷移使用 metadata database，也就是把容器的元數據存儲到數據庫里面。這里推測 Gitlab 之前可能采用了 Docker 官方的 Registry 的方案，后面發現存在種種限制，因此又做了一些數據的遷移工作。

You can run garbage collection in the background without the need to schedule it or require read-only mode, if you migrate to the?metadata database.

開啟了 metadata database 后，就可以愉快的統計容器鏡像庫

鏡像容量統計

鏡像容量統計?

4）Camo 代理服務

不知道有沒有小伙伴仔細看過 Github 里面引用的一些外鏈圖片的鏈接。如果你檢查過就會發現，所有 Github Readme 引用的外部圖片鏈接，全部變成了?https://camo.githubusercontent.com/?

官方解釋：為托管圖像，GitHub 使用開源項目 Camo。 Camo 為每個文件生成匿名 URL 代理，以隱藏您的瀏覽器詳細信息和來自其他用戶的相關信息。 URL 以?https://<subdomain>.githubusercontent.com/? 開頭，子域不同，具體取決于圖像的上傳方式。

這樣的好處就是，假如有人為了惡意統計用戶的訪問 IP，然后引用于一個自己服務器的圖片，這樣每次用戶打開這個 Readme 的時候，瀏覽器就會順著這個圖片的 URL，去抓取對應的圖片，這樣就可能導致隱私泄露的問題。

此外，因為國內的一些網絡環境不好，一些引用的外網的圖片，也可能全部變成了詭異的加載失敗，如果能搭建一個自己的圖片代理，就會好很多力！

Gitlab 的官方文檔其實也是支持?Proxying assets | GitLab Docs，只不過可能很少有朋友關注到了這一點。部署好后的效果如下，可以看到所有的圖片全都經過了我的個人 Camo 服務，成功加載：

Camo 效果演示

Camo 效果演示?

二、部署具體功能

廢話不多說，首先介紹一下我自己是使用 Docker-Compose 的?yml??文件來部署的 Gitlab，我喜歡所有的配置文件集中管理，這樣可以很好的遷移。關于 Docker 部署 Gitlab 教程已經爛大街我這里就不需要額外介紹了。

我們三個功能由易到難依次介紹：

1）Camo 代理服務

內部 Issue 鏈接：2025.08 Week 2: 給自建 Gitlab 增加 Camo 服務圖片代理 (#5) · Issue · Musicminion/personal-plan

Github 上有一個開源項目?cactus/go-camo: A secure image proxy server，采用 Go 語言編寫，同時具有輕量還有高效的特點，并且還提供了 Docker 的部署方式。

我這里是在一臺自己的海外服務器上運行的，這是?docker-compose.yml?：

services:go-camo:image: ghcr.io/cactus/go-camo:latestrestart: unless-stoppedports:- "52380:8080"command: ["-k", "somekey"]

注意，你應該生成一個自己的密鑰，然后用來代替上面的?somekey?，這個 key 后面會用來簽名使用。然后就是 Nginx 的配置這個也是老生常談了的：

server {listen 80;server_name camo.example.com;# 強制跳轉到 HTTPSreturn 301 https://$host$request_uri;
}server {listen 443 ssl http2;server_name camo.ayaka.space;ssl_certificate /path/to/fullchain.cer;ssl_certificate_key /path/to/*.example.com.key;# 建議加上一些現代 TLS 配置ssl_protocols TLSv1.2 TLSv1.3;ssl_ciphers HIGH:!aNULL:!MD5;ssl_prefer_server_ciphers on;location / {proxy_pass http://localhost:52380;   # 這里是 docker-compose 里的服務名:端口proxy_set_header Host $host;proxy_set_header X-Real-IP $remote_addr;proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;proxy_set_header X-Forwarded-Proto $scheme;proxy_hide_header Cache-Control;proxy_hide_header Expires;add_header Cache-Control "public, max-age=3600" always;}
}

然后需要自己去你的 Gitlab 的個人設置里面，生成一個 PRIVATE-TOKEN 個人訪問令牌，權限你可以暫時全部選上，或者勾選 sudo 也行。

Gitlab 個人訪問令牌設置界面

Gitlab 個人訪問令牌設置界面?

然后使用命令行，記得把?<my_private_token>??替換為你的個人訪問令牌：

curl --request "PUT" "https://gitlab.example.com/api/v4/application/settings?\
asset_proxy_enabled=true&\
asset_proxy_url=https://camo.example.com&\
asset_proxy_secret_key=somekey" \
--header 'PRIVATE-TOKEN: <my_private_token>'

之后重啟 GitLab，你應該就可以看到圖片是不是走的你的代理服務器加載的了。

Camo 服務啟用后的效果

Camo 服務啟用后的效果?

順便提一嘴，其實這里還可以個性化的配置緩存過期的時間，具體可以參考 Nginx 的緩存時間配置。

2）ElasticSearch 搜索配置

ElasticSearch 是一個 Java 寫的全文搜索工具，說實話非常吃性能，沒有 16G 的大內存基本很難跑。而且這個東西的 Docker 部署小有復雜。

首先給你的 Gitlab 的 Docker compose 的文件里面加上以下內容：

  elasticsearch:image: docker.elastic.co/elasticsearch/elasticsearch:8.10.2container_name: elasticsearchrestart: alwaysenvironment:- discovery.type=single-node- TZ=Asia/Shanghai- xpack.security.enabled=false- http.max_content_length=1024mbvolumes:- ./elasticsearch/data:/usr/share/elasticsearch/data- ./elasticsearch/config:/usr/share/elasticsearch/config- ./elasticsearch/logs:/usr/share/elasticsearch/logs- ./elasticsearch/plugins:/usr/share/elasticsearch/pluginsports:- '9200:9200'- '9300:9300'mem_limit: 16gcpus: '8'

然后不要著急，先把容器里面的文件數據偷出來：

# 啟動一個臨時容器（不運行服務）
docker run --name temp_elasticsearch -d docker.elastic.co/elasticsearch/elasticsearch:8.10.2 tail -f /dev/null# 拷貝數據
docker cp temp_elasticsearch:/usr/share/elasticsearch/data ./elasticsearch/data
docker cp temp_elasticsearch:/usr/share/elasticsearch/config ./elasticsearch/config
docker cp temp_elasticsearch:/usr/share/elasticsearch/logs ./elasticsearch/logs
docker cp temp_elasticsearch:/usr/share/elasticsearch/plugins ./elasticsearch/plugins# 刪除臨時容器
docker rm -f temp_elasticsearch

因為其實是這樣的，我們稍后會把這些目錄掛載出來，但是實際上這些目錄里面本身又有文件了，所以我們必須先把配置偷出來，然后才能運行，特別是像那些插件目錄，我們必須掛出來。記得啟動后檢查一下 ES 的日志，如果發現有問題可能還需要對應的解決。

然后就是熟悉的改配置：

services:gitlab:image: gitlab/gitlab-ee:18.3.0-ee.0container_name: gitlabrestart: alwaysshm_size: '4g'extra_hosts:- "host.docker.internal:host-gateway"environment:GITLAB_OMNIBUS_CONFIG: | # Add any other gitlab.rb configuration here, each on its own line# ... 已有的配置gitlab_rails['elasticsearch_enabled'] = truegitlab_rails['elasticsearch_url'] = ['http://elasticsearch:9200']gitlab_rails['elasticsearch_indexer_enabled'] = truegitlab_rails['elasticsearch_aws'] = false

然后就是進入管理頁面配置了：

勾選開啟 ElasticSearch 索引
然后注意 URL 必須配置為從 Gitlab 容器里面可以訪問到的搜索的 URL，為了安全起見可以考慮配置一下密碼之類的，我這里僅僅是內部訪問，就直接忽略了。
配置完成后點?索引實例?，然后靜候佳音

高級搜索設置面板

高級搜索設置面板?

另外據說還有一個中文的分詞器可以考慮一下，方法是進入 Elasticsearch 容器里面執行：

sudo bin/elasticsearch-plugin install analysis-smartcn

至于 Elasticsearch 不停機重建索引，這個一般適用于更新了 Gitlab 之后，發現搜索搜不了了，或者出現故障的時候，需要重建索引，就點一下，不要點的太頻繁。

等所有的項目索引完成，就可以快樂的搜索了！注意，一般開始索引實例之后，上圖里面暫停 ElasticSearch 索引的選項會自動打開，如果你發現索引好了，可以取消勾選然后保存。

3）Zoekt 精確代碼搜索

內部 Issue 鏈接：2025.08 Week 3: 給個人 Gitlab 新增代碼精確搜索功能 (#8) · Issue · Musicminion/personal-plan

先簡要介紹一下 Zoekt 的架構，Gitlab 和 Zoekt 是怎么配合的？Zoekt 會運行一個 indexer，負責構建索引。Zoekt indexer 啟動之后，會去找 Gitlab 一直拉取自己的作業需求，比如知道我現在要索引?/root??下面的所有倉庫，然后他就會通過 Gitaly 的 socket 接口去拉取這個對應的數據。這就會導致兩個問題：

Zoekt indexer 需要和 Gitlab 共享數據目錄（socket 通信目錄等）
需要解決權限問題，UID/GID 需要手動配置

此外，Zoekt 會把自己的 URL 通過心跳包的形式發送給 Gitlab，當用戶搜索的時候，Gitlab 通過心跳包里面獲得的 URL，然后發送給 Zoekt web server。web server 搜索然后返回結果理論是這樣。

Gitlab 的 Zoekt 容器的版本和 Gitlab 基本算配套發布的。

關于 Docker compose 部署 Zoekt 的流程，參考這里：example/docker-compose · main · GitLab.org / Gitlab Zoekt · GitLab，但是其實這個有些問題，有個環境變量沒寫會導致一直啟動失敗。

配置文件里面的幾個問題：

你需要找到 gitaly 目錄，然后?ls -ln? 看一下權限，一般 docker 部署的權限號碼應該是 998
?gitlab_shell_secret??這個文件可能需要你手動去找一下 gitlab 的這個文件的位置，find /??一下理論有，我這里也記不清楚，但是你最好拷貝一份放給 zoekt 專門用
?git.example.com??就是你的 Gitlab 的 URL
最重要的一個事情：Gitlab 主容器里面的?/var/opt/gitlab??這個掛載到宿主機出后，你需要把掛出來的這個目錄，重新掛載到 zoekt 里面去！這樣才能保證里面可以通過 socket 文件訪問 gitaly，因為需要拉取倉庫數據。

   gitlab:# 其他配置volumes:- './gitlab/config:/etc/gitlab'- './gitlab/logs:/var/log/gitlab'- './gitlab/data:/var/opt/gitlab' # 注意觀察 /var/opt/gitlab 的掛載點# registry.gitlab.com/gitlab-org/build/cng/gitlab-zoekt:v18.2.4-fipszoekt_webserver:image: registry.gitlab.com/gitlab-org/build/cng/gitlab-zoekt:v18.3.0container_name: zoekt_webserverrestart: always# 998 is the UID for ./gitlab/data/git-data/repositories/+gitaly# use ls -ln to checkuser: "998:998"ports:- 6070:6070environment:GITLAB_ZOEKT_MODE: webserverWEBSERVER_PORT: 6070GITLAB_URL: https://git.example.comGITLAB_ZOEKT_SELF_URL: "http://zoekt_webserver:6070"GITLAB_ZOEKT_VERSION: "v18.3.0"GITLAB_ZOEKT_SECRET_PATH: /.gitlab_shell_secretZOEKT_ENABLE_DEBUG_LOGGING: truevolumes:- ./zoekt/zoekt_index_data:/data/index- ./zoekt/.gitlab_shell_secret:/.gitlab_shell_secret- ./gitlab/data:/var/opt/gitlab # 注意模擬掛載到 /var/opt/gitlabdepends_on:- git.ayaka.spacezoekt_indexer:image: registry.gitlab.com/gitlab-org/build/cng/gitlab-zoekt:v18.3.0container_name: zoekt_indexerrestart: always# 998 is the UID for ./gitlab/data/git-data/repositories/+gitaly# use ls -ln to checkuser: "998:998"ports:- "6065:6065"environment:GITLAB_ZOEKT_MODE: indexerSERVICE_URL: http://zoekt_indexer:6065WEBSERVER_PORT: 6070GITLAB_URL: https://git.example.comGITLAB_ZOEKT_SELF_URL: "http://zoekt_webserver:6070"GITLAB_ZOEKT_VERSION: "v18.2.4"GITLAB_ZOEKT_SECRET_PATH: /.gitlab_shell_secretZOEKT_ENABLE_DEBUG_LOGGING: truevolumes:- ./zoekt/zoekt_index_data:/data/index- ./zoekt/.gitlab_shell_secret:/.gitlab_shell_secret- ./gitlab/data:/var/opt/gitlab # 注意模擬掛載到 /var/opt/gitlabdepends_on:- git.ayaka.spacemem_limit: 8gcpus: '4'

這些工作做完之后，你就可以啟動 zoekt，先看容器是否是正常啟動的。然后你先可以進入 Web 界面開啟：

精確代碼搜索設置面板

精確代碼搜索設置面板?

在默認情況 Gitlab 18.2.4 之前，他默認只會給新的 Group 或者用戶開啟這個搜索，不會開啟之前舊的名字空間的索引作業的，需要手動指定。比如?<top-level-group-to-index>??改成你的?root?，就可以索引當前 root 用戶下面的項目。

參考鏈接：Zoekt chart | GitLab Docs

# 需要進入 gitlab 容器然后執行下面的命令
gitlab-rails console
node = ::Search::Zoekt::Node.online.last
namespace = Namespace.find_by_full_path('<top-level-group-to-index>')
enabled_namespace = Search::Zoekt::EnabledNamespace.find_or_create_by(namespace: namespace)
replica = enabled_namespace.replicas.find_or_create_by(namespace_id: enabled_namespace.root_namespace_id)
node.indices.create!(zoekt_enabled_namespace_id: enabled_namespace.id, namespace_id: namespace.id, zoekt_replica_id: replica.id)

處理好后你應該可以看到索引已經重新建立，然后可以在 Web 界面愉快的搜索了。

4）Docker Registery Metadata

a）遷移教程

內部 Issue 鏈接：2025.08 Week 3: 給個人 Gitlab Registry 遷移到新的 metadata DB (#9) · Issue · Musicminion/personal-plan

首先，Gitlab 18.3 其實默認會運行一個遷移腳本，把容器鏡像倉庫遷移到新的 Meadata 數據庫中，所以最推薦的做法是直接升級到 18.3。

對于舊版本的 Gitlab，如果不想升級，并且又需要開啟容器鏡像倉庫的元數據數據庫，需要參考論壇的鏈接：論壇教程鏈接

首先需要創建數據庫專用用戶（友情提示：建議看完 b 部分我寫的遷移導致的問題在運行腳本）：

gitlab-psql -c "CREATE USER registry WITH PASSWORD 'registrypassword'"
gitlab-psql -c "CREATE DATABASE registry_database WITH OWNER registry"

需要指定數據庫的位置、允許外部用戶鏈接：

registry['database'] = {'enabled' => false, # Must be false!'host' => '/var/opt/gitlab/postgresql/','user' => 'registry','password' => 'registrypassword','dbname' => 'registry_database','sslmode' => 'disable'
}postgresql['custom_pg_hba_entries'] = {registry_db: [{type: 'local',database: 'registry_database',user: 'registry',method: 'md5'}]
}

然后配置好之后，參考教程：Gitlab Docs | 開啟容器鏡像倉庫元數據數據庫。

# 注意這里 storage 的配置，因為我用的本地存儲，所以要指定目錄：
registry['storage'] = {'filesystem' => {'rootdirectory' => '/var/opt/gitlab/gitlab-rails/shared/registry'} 'maintenance' => {'readonly' => {'enabled' => true # Must be set to true.}}
}

然后運行遷移腳本：

sudo -u registry gitlab-ctl registry-database migrate up
sudo -u registry gitlab-ctl registry-database import --log-to-stdout

因為在 Docker 里面 sudo 是不可用的，直接可以刪掉?sudo -u registry? 這一部分的，如果不是 Docker 部署，直接在物理機器運行就可以。

遷移完成后，原來的用 false 就可以關閉了，此外?'maintenance'? 那一欄目也需要刪掉，這樣用戶可以讀寫了。

registry['database'] = {'enabled' => true,'host' => '/var/opt/gitlab/postgresql/','user' => 'registry','password' => 'registrypassword','dbname' => 'registry_database','sslmode' => 'disable'
}

遷移完成后，容器鏡像倉庫是可以自動做垃圾回收 GC 的了，理論來說磁盤空間可以節省不少。

發現容器的數據統計不對，需要參考 Gitlab 的教程：Gitlab Issue | 容器鏡像倉庫 size 為 0 的原因修復，意思就是這個容器鏡像占用的空間是靜態更新的，或者通過 notifer，配置 notifer 教程在這?配置 Notifer 的官方文檔。所以需要再 Gitlab 的配置文件里面添加：

registry['notifications'] = [{'name' => '<test_endpoint>','url' => 'https://<gitlab.example.com>/api/v4/container_registry_event/events','timeout' => '500ms','threshold' => 5, # DEPRECATED: use `maxretries` instead.'maxretries' => 5,'backoff' => '1s','headers' => {"Authorization" => ["<AUTHORIZATION_EXAMPLE_TOKEN>"]}}
]gitlab_rails['registry_notification_secret'] = '<AUTHORIZATION_EXAMPLE_TOKEN>' # Must match the auth token in registry['notifications']

這個 notifer 本質是一個 webhook，當用戶推送 docker 鏡像之后，就會觸發一個作業 worker 的請求，重新統計當前倉庫的 Docker 鏡像大小。

其中?<AUTHORIZATION_EXAMPLE_TOKEN>? 需要隨機生成的 32 位字符，生成命令如下：

< /dev/urandom tr -dc _A-Z-a-z-0-9 | head -c 32 | sed "s/^[0-9]*//"; echo

配置好之后，當你推送鏡像，就會觸發這個重新計算的操作，并不是立刻顯示數據，時延大概是 5 min。效果如下所示，可以看到你用的用量占用了多少 size 了。

使用量配額效果圖

使用量配額效果圖?

b）遷移導致的問題

補充：如果你已經做了遷移，在更新到 18.3 的時候，注意一個小問題。就是 18.3 的遷移腳本會默認創建一個新的用戶。更新之后我發現自己 gitlab 容器鏡像數據 30 多 G 全丟，然后排查了很久。

其實按照我前面的遷移教程我已經做了一次了，但是 18.3 啟動腳本里面又做了一次遷移。按照我之前的配置，遷移腳本告訴我數據庫密碼不對。所以啟動失敗。我首先直接偷懶，把之前配置的數據庫用戶名密碼的部分全都刪了，然后發現遷移腳本啟動成功了就沒管。晚上發現數據都不在了（

然后一看數據庫里面有兩個 registry 的數據庫（一個叫registry?，一個叫registry_database?），顯然registry_database ?是新創的，但是巧妙的是，新創的默認 db 的用戶名是和我之前做遷移的時候用戶完全一樣的，所以推測啟動遷移腳本可能創建了一個用戶，然后正好把這個密碼給改掉了，導致遷移腳本告訴我數據庫密碼不對。所以啟動失敗。所以我就把用戶名密碼都刪除了。

Gitlab 的數據庫的示意圖如下：

GitLab 數據庫列表