Geo 프록시

요약

보조 사이트는 거의 모든 HTTP 요청을 Workhorse를 통해 기본 사이트로 프록시합니다. GitLab UI 및 API HTTP 요청의 프록시는 gitlab-workhorse 구성 요소가 처리합니다. HTTP를 통한 Git 요청의 프록시는 gitlab-workhorse 구성 요소가 처리하지만, 프록시 여부는 Rails 애플리케이션이 요청이 push 인지 pull 인지와 요청 대상 Git 데이터가 최신인지를 고려해 결정합니다.

보조 사이트는 거의 모든 HTTP 요청을 Workhorse를 통해 기본 사이트로 프록시합니다. 그래서 보조 사이트로 접속한 사용자는 읽기·쓰기 UI를 보게 되며, 기본 사이트에서 할 수 있는 모든 작업을 수행할 수 있습니다.

상위 수준 구성 요소#

GitLab UI 및 API HTTP 요청의 프록시는 gitlab-workhorse 구성 요소가 처리합니다. 평소 Geo 보조 사이트의 Rails 애플리케이션으로 보내지는 트래픽은 대신 기본 Geo 사이트의 내부 URL로 프록시됩니다.

HTTP를 통한 Git 요청의 프록시는 gitlab-workhorse 구성 요소가 처리하지만, 프록시 여부는 Rails 애플리케이션이 요청이 push 인지 pull 인지와 요청 대상 Git 데이터가 최신인지를 고려해 결정합니다.

SSH를 통한 Git 트래픽의 프록시는 gitlab-shell 구성 요소가 처리하지만, 프록시 여부는 Rails 애플리케이션이 요청이 push 인지 pull 인지와 요청 대상 Git 데이터가 최신인지를 고려해 결정합니다.

요청 수명 주기#

최상위 개요#

프록시 동작은 다음 다이어그램으로 개괄할 수 있습니다.

Mermaid 다이어그램 (9줄)

소스 코드 보기

sequenceDiagram
actor client
participant secondary
participant primary
client->>secondary: GET /explore
secondary-->>primary: GET /explore (proxied)
primary-->>secondary: HTTP/1.1 200 OK [..]
secondary->>client: HTTP/1.1 200 OK [..]

프록시 탐지 메커니즘#

Workhorse는 기본 사이트로 요청을 프록시해야 하는지와 (데이터베이스에 저장된) 기본 사이트의 URL을 알기 위해, Geo가 활성화돼 있으면 내부 API를 폴링합니다. 프록시를 활성화해야 할 때 내부 API는 기본 사이트 URL과, 모든 요청마다 기본 사이트로 전달되는 JWT 서명 데이터를 응답합니다.

Mermaid 다이어그램 (7줄)

소스 코드 보기

sequenceDiagram
    participant W as Workhorse (secondary)
    participant API as Internal Rails API
    W->API: GET /api/v4/geo/proxy (internal)
    loop Poll every 10 seconds
        API-->W: {geo_proxy_primary_url, geo_proxy_extra_data}, update config
    end

상세 요청 흐름 및 로컬 데이터 가속과 프록시 비교#

구현 관점에서 보면, 요청을 받은 보조 사이트의 Workhorse가 데이터를 프록시할지 결정합니다. 해당 데이터 유형을 "가속" 할 수 있다면(즉, 왕복 요청을 줄이기 위해 로컬에서 제공할 수 있다면) 데이터를 즉시 반환합니다. 그렇지 않으면 트래픽은 기본 사이트의 내부 URL로 전송되고, 직접 요청과 똑같이 기본 사이트의 Workhorse가 응답합니다. 그 응답은 같은 연결에서 보조 사이트 Workhorse를 거쳐 사용자에게 다시 프록시됩니다.

Mermaid 다이어그램 (6줄)

소스 코드 보기

flowchart LR
  A[Client]--->W1["Workhorse (secondary)"]
  W1 --> W1C[Serve data locally?]
  W1C -- "Yes" ----> W1
  W1C -- "No (proxy)" ----> W2["Workhorse (primary)"]
  W2 --> W1 ----> A

로그인#

인가가 필요한 기본 사이트 프록시 요청#

Mermaid 다이어그램 (21줄)

소스 코드 보기

sequenceDiagram
autoNumber
participant Client
participant Secondary
participant Primary
Client->>Secondary: /group/project request
Secondary->>Primary: proxy /group/project
opt primary not signed in
Primary-->>Secondary: 302 redirect
Secondary-->>Client: proxy 302 redirect
Client->>Secondary: /users/sign_in
Secondary->>Primary: proxy /users/sign_in
Note right of Primary: authentication happens, POST to same URL etc
Primary-->>Secondary: 302 redirect
Secondary-->>Client: proxy 302 redirect
Client->>Secondary: /group/project
Secondary->>Primary: proxy /group/project
end
Primary-->>Secondary: /group/project logged in response (session on primary created)
Secondary-->>Client: proxy full response

Git pull#

Git pull 전달 경로는 GitLab 17.10에서 의미를 더 분명히 하기 위해 기존 이름 push_from_secondary에서 from_secondary로 변경됐습니다.

HTTP(s)를 통한 Git pull#

가속된 리포지터리#

리포지터리가 보조 사이트에 있고 기본 사이트와 최신 상태로 일치한다고 판단되면, 프록시하지 않고 보조 사이트에서 직접 제공합니다.

Mermaid 다이어그램 (20줄)

소스 코드 보기

sequenceDiagram
participant C as Git client
participant Wsec as "Workhorse (secondary)"
participant Rsec as "Rails (secondary)"
participant Gsec as "Gitaly (secondary)"
C->>Wsec: GET /foo/bar.git/info/refs/?service=git-upload-pack
Wsec->>Rsec: <internal API check>
note over Rsec: decide that the repo is synced and up to date
Rsec-->>Wsec: 401 Unauthorized
Wsec-->>C: <response>
C->>Wsec: GET /foo/bar.git/info/refs/?service=git-upload-pack
Wsec->>Rsec: <internal API check>
Rsec-->>Wsec: Render Workhorse OK
Wsec-->>C: 200 OK
C->>Wsec: POST /foo/bar.git/git-upload-pack
Wsec->>Rsec: GitHttpController#git_receive_pack
Rsec-->>Wsec: Render Workhorse OK
Wsec->>Gsec: Workhorse gets the connection details from Rails, connects to Gitaly: SmartHTTP Service, UploadPack RPC (check the proto for details)
Gsec-->>Wsec: Return a stream of Proto messages
Wsec-->>C: Pipe messages to the Git client

프록시된 리포지터리#

요청된 리포지터리가 동기화되지 않았거나 최신 상태가 아니라고 판단되면, 최신 변경 사항을 가져오기 위해 요청을 기본 사이트로 프록시합니다.

Mermaid 다이어그램 (33줄)

소스 코드 보기

sequenceDiagram
participant C as Git client
participant Wsec as "Workhorse (secondary)"
participant Rsec as "Rails (secondary)"
participant W as "Workhorse (primary)"
participant R as "Rails (primary)"
participant G as "Gitaly (primary)"
C->>Wsec: GET /foo/bar.git/info/refs/?service=git-upload-pack
Wsec->>Rsec: <response>
note over Rsec: decide that the repo is out of date
Rsec-->>Wsec: 302 Redirect to /-/from_secondary/2/foo/bar.git/info/refs?service=git-upload-pack
Wsec-->>C: <response>
C->>Wsec: GET /-/from_secondary/2/foo/bar.git/info/refs/?service=git-upload-pack
Wsec->>W: <proxied request>
W->>R: <data>
R-->>W: 401 Unauthorized
W-->>Wsec: <proxied response>
Wsec-->>C: <response>
C->>Wsec: GET /-/from_secondary/2/foo/bar.git/info/refs/?service=git-upload-pack
note over W: proxied
Wsec->>W: <proxied request>
W->>R: <data>
R-->>W: Render Workhorse OK
W-->>Wsec: <proxied response>
Wsec-->>C: <response>
C->>Wsec: POST /-/from_secondary/2/foo/bar.git/git-upload-pack
Wsec->>W: <proxied request>
W->>R: GitHttpController#git_receive_pack
R-->>W: Render Workhorse OK
W->>G: Workhorse gets the connection details from Rails, connects to Gitaly: SmartHTTP Service, UploadPack RPC (check the proto for details)
G-->>W: Return a stream of Proto messages
W-->>Wsec: Pipe messages to the Git client
Wsec-->>C: Return piped messages from Git

SSH를 통한 Git pull#

SSH 작업은 Workhorse가 아니라 GitLab Shell을 거치므로 Workhorse 요청에 쓰이는 메커니즘으로 프록시되지 않습니다. SSH 작업은 보조 사이트의 Rails 내부 API가 Git HTTP 요청 형태로 기본 사이트에 프록시합니다.

가속된 리포지터리#

리포지터리가 보조 사이트에 있고 기본 사이트와 최신 상태로 일치한다고 판단되면, 프록시하지 않고 보조 사이트에서 직접 제공합니다.

Mermaid 다이어그램 (15줄)

소스 코드 보기

sequenceDiagram
participant C as Git client
participant S as GitLab Shell (secondary)
participant I as Internal API (secondary Rails)
participant G as Gitaly (secondary)
C->>S: git pull
S->>I: SSH key validation (api/v4/internal/authorized_keys?key=..)
I-->>S: HTTP/1.1 200 OK
S->>G: InfoRefs:UploadPack RPC
G-->>S: stream Git response back
S-->>C: stream Git response back
C-->>S: stream Git data to push
S->>G: UploadPack RPC
G-->>S: stream Git response back
S-->>C: stream Git response back

프록시된 리포지터리#

요청된 리포지터리가 동기화되지 않았거나 최신 상태가 아니라고 판단되면, 최신 변경 사항을 가져오기 위해 요청을 기본 사이트로 프록시합니다.

Mermaid 다이어그램 (19줄)

소스 코드 보기

sequenceDiagram
participant C as Git client
participant S as GitLab Shell (secondary)
participant I as Internal API (secondary Rails)
participant P as Primary API
C->>S: git pull
S->>I: SSH key validation (api/v4/internal/authorized_keys?key=..)
I-->>S: HTTP/1.1 300 (custom action status) with {endpoint, msg, primary_repo}
S->>I: POST /api/v4/geo/proxy_git_ssh/info_refs_upload_pack
I->>P: POST $PRIMARY/foo/bar.git/info/refs/?service=git-upload-pack
P-->>I: HTTP/1.1 200 OK
I-->>S: <response>
S-->>C: return Git response from primary
C-->>S: stream Git data to push
S->>I: POST /api/v4/geo/proxy_git_ssh/upload_pack
I->>P: POST $PRIMARY/foo/bar.git/git-upload-pack
P-->>I: HTTP/1.1 200 OK
I-->>S: <response>
S-->>C: return Git response from primary

Git push#

SSH를 통한 Git push#

Mermaid 다이어그램 (19줄)

소스 코드 보기

sequenceDiagram
participant C as Git client
participant S as GitLab Shell (secondary)
participant I as Internal API (secondary Rails)
participant P as Primary API
C->>S: git push
S->>I: SSH key validation (api/v4/internal/authorized_keys?key=..)
I-->>S: HTTP/1.1 300 (custom action status) with {endpoint, msg, primary_repo}
S->>I: POST /api/v4/geo/proxy_git_ssh/info_refs_receive_pack
I->>P: POST $PRIMARY/foo/bar.git/info/refs/?service=git-receive-pack
P-->>I: HTTP/1.1 200 OK
I-->>S: <response>
S-->>C: return Git response from primary
C-->>S: stream Git data to push
S->>I: POST /api/v4/geo/proxy_git_ssh/receive_pack
I->>P: POST $PRIMARY/foo/bar.git/git-receive-pack
P-->>I: HTTP/1.1 200 OK
I-->>S: <response>
S-->>C: return Git response from primary

HTTP(S)를 통한 Git push#

요청된 리포지터리가 동기화되지 않았거나 최신 상태가 아니라고 판단되면 요청은 기본 사이트로 프록시됩니다. push는 /-/from_secondary/$SECONDARY_ID/* 형식의 로컬 경로로 리디렉션됩니다. 또한 이 경로를 통한 요청은 기본 사이트로 프록시되고, 기본 사이트가 push를 처리합니다.

Mermaid 다이어그램 (28줄)

소스 코드 보기

sequenceDiagram
participant C as Git client
participant Wsec as Workhorse (secondary)
participant W as Workhorse (primary)
participant R as Rails (primary)
participant G as Gitaly (primary)
C->>Wsec: GET /foo/bar.git/info/refs/?service=git-receive-pack
Wsec->>C: 302 Redirect to /-/from_secondary/2/foo/bar.git/info/refs?service=git-receive-pack
C->>Wsec: GET /-/from_secondary/2/foo/bar.git/info/refs/?service=git-receive-pack
Wsec->>W: <proxied request>
W->>R: <data>
R-->>W: 401 Unauthorized
W-->>Wsec: <proxied response>
Wsec-->>C: <response>
C->>Wsec: GET /-/from_secondary/2/foo/bar.git/info/refs/?service=git-receive-pack
Wsec->>W: <proxied request>
W->>R: <data>
R-->>W: Render Workhorse OK
W-->>Wsec: <proxied response>
Wsec-->>C: <response>
C->>Wsec: POST /-/from_secondary/2/foo/bar.git/git-receive-pack
Wsec->>W: <proxied request>
W->>R: GitHttpController:git_receive_pack
R-->>W: Render Workhorse OK
W->>G: Get connection details from Rails and connects to SmartHTTP Service, ReceivePack RPC
G-->>W: Return a stream of Proto messages
W-->>Wsec: Pipe messages to the Git client
Wsec-->>C: Return piped messages from Git

Geo 프록시

GitLab v19.4

원문 보기

번역일: 2026-09-18

요약

상위 수준 구성 요소#

요청 수명 주기#

최상위 개요#

프록시 동작은 다음 다이어그램으로 개괄할 수 있습니다.

Mermaid 다이어그램 (9줄)

소스 코드 보기

sequenceDiagram
actor client
participant secondary
participant primary
client->>secondary: GET /explore
secondary-->>primary: GET /explore (proxied)
primary-->>secondary: HTTP/1.1 200 OK [..]
secondary->>client: HTTP/1.1 200 OK [..]

프록시 탐지 메커니즘#

Mermaid 다이어그램 (7줄)

소스 코드 보기

sequenceDiagram
    participant W as Workhorse (secondary)
    participant API as Internal Rails API
    W->API: GET /api/v4/geo/proxy (internal)
    loop Poll every 10 seconds
        API-->W: {geo_proxy_primary_url, geo_proxy_extra_data}, update config
    end

상세 요청 흐름 및 로컬 데이터 가속과 프록시 비교#

Mermaid 다이어그램 (6줄)

소스 코드 보기

flowchart LR
  A[Client]--->W1["Workhorse (secondary)"]
  W1 --> W1C[Serve data locally?]
  W1C -- "Yes" ----> W1
  W1C -- "No (proxy)" ----> W2["Workhorse (primary)"]
  W2 --> W1 ----> A

로그인#

인가가 필요한 기본 사이트 프록시 요청#

Mermaid 다이어그램 (21줄)

소스 코드 보기

sequenceDiagram
autoNumber
participant Client
participant Secondary
participant Primary
Client->>Secondary: /group/project request
Secondary->>Primary: proxy /group/project
opt primary not signed in
Primary-->>Secondary: 302 redirect
Secondary-->>Client: proxy 302 redirect
Client->>Secondary: /users/sign_in
Secondary->>Primary: proxy /users/sign_in
Note right of Primary: authentication happens, POST to same URL etc
Primary-->>Secondary: 302 redirect
Secondary-->>Client: proxy 302 redirect
Client->>Secondary: /group/project
Secondary->>Primary: proxy /group/project
end
Primary-->>Secondary: /group/project logged in response (session on primary created)
Secondary-->>Client: proxy full response

Git pull#

Git pull 전달 경로는 GitLab 17.10에서 의미를 더 분명히 하기 위해 기존 이름 push_from_secondary에서 from_secondary로 변경됐습니다.

HTTP(s)를 통한 Git pull#

가속된 리포지터리#

리포지터리가 보조 사이트에 있고 기본 사이트와 최신 상태로 일치한다고 판단되면, 프록시하지 않고 보조 사이트에서 직접 제공합니다.

Mermaid 다이어그램 (20줄)

소스 코드 보기

sequenceDiagram
participant C as Git client
participant Wsec as "Workhorse (secondary)"
participant Rsec as "Rails (secondary)"
participant Gsec as "Gitaly (secondary)"
C->>Wsec: GET /foo/bar.git/info/refs/?service=git-upload-pack
Wsec->>Rsec: <internal API check>
note over Rsec: decide that the repo is synced and up to date
Rsec-->>Wsec: 401 Unauthorized
Wsec-->>C: <response>
C->>Wsec: GET /foo/bar.git/info/refs/?service=git-upload-pack
Wsec->>Rsec: <internal API check>
Rsec-->>Wsec: Render Workhorse OK
Wsec-->>C: 200 OK
C->>Wsec: POST /foo/bar.git/git-upload-pack
Wsec->>Rsec: GitHttpController#git_receive_pack
Rsec-->>Wsec: Render Workhorse OK
Wsec->>Gsec: Workhorse gets the connection details from Rails, connects to Gitaly: SmartHTTP Service, UploadPack RPC (check the proto for details)
Gsec-->>Wsec: Return a stream of Proto messages
Wsec-->>C: Pipe messages to the Git client

프록시된 리포지터리#

요청된 리포지터리가 동기화되지 않았거나 최신 상태가 아니라고 판단되면, 최신 변경 사항을 가져오기 위해 요청을 기본 사이트로 프록시합니다.

Mermaid 다이어그램 (33줄)

소스 코드 보기

sequenceDiagram
participant C as Git client
participant Wsec as "Workhorse (secondary)"
participant Rsec as "Rails (secondary)"
participant W as "Workhorse (primary)"
participant R as "Rails (primary)"
participant G as "Gitaly (primary)"
C->>Wsec: GET /foo/bar.git/info/refs/?service=git-upload-pack
Wsec->>Rsec: <response>
note over Rsec: decide that the repo is out of date
Rsec-->>Wsec: 302 Redirect to /-/from_secondary/2/foo/bar.git/info/refs?service=git-upload-pack
Wsec-->>C: <response>
C->>Wsec: GET /-/from_secondary/2/foo/bar.git/info/refs/?service=git-upload-pack
Wsec->>W: <proxied request>
W->>R: <data>
R-->>W: 401 Unauthorized
W-->>Wsec: <proxied response>
Wsec-->>C: <response>
C->>Wsec: GET /-/from_secondary/2/foo/bar.git/info/refs/?service=git-upload-pack
note over W: proxied
Wsec->>W: <proxied request>
W->>R: <data>
R-->>W: Render Workhorse OK
W-->>Wsec: <proxied response>
Wsec-->>C: <response>
C->>Wsec: POST /-/from_secondary/2/foo/bar.git/git-upload-pack
Wsec->>W: <proxied request>
W->>R: GitHttpController#git_receive_pack
R-->>W: Render Workhorse OK
W->>G: Workhorse gets the connection details from Rails, connects to Gitaly: SmartHTTP Service, UploadPack RPC (check the proto for details)
G-->>W: Return a stream of Proto messages
W-->>Wsec: Pipe messages to the Git client
Wsec-->>C: Return piped messages from Git

SSH를 통한 Git pull#

가속된 리포지터리#

리포지터리가 보조 사이트에 있고 기본 사이트와 최신 상태로 일치한다고 판단되면, 프록시하지 않고 보조 사이트에서 직접 제공합니다.

Mermaid 다이어그램 (15줄)

소스 코드 보기

sequenceDiagram
participant C as Git client
participant S as GitLab Shell (secondary)
participant I as Internal API (secondary Rails)
participant G as Gitaly (secondary)
C->>S: git pull
S->>I: SSH key validation (api/v4/internal/authorized_keys?key=..)
I-->>S: HTTP/1.1 200 OK
S->>G: InfoRefs:UploadPack RPC
G-->>S: stream Git response back
S-->>C: stream Git response back
C-->>S: stream Git data to push
S->>G: UploadPack RPC
G-->>S: stream Git response back
S-->>C: stream Git response back

프록시된 리포지터리#

요청된 리포지터리가 동기화되지 않았거나 최신 상태가 아니라고 판단되면, 최신 변경 사항을 가져오기 위해 요청을 기본 사이트로 프록시합니다.

Mermaid 다이어그램 (19줄)

소스 코드 보기

sequenceDiagram
participant C as Git client
participant S as GitLab Shell (secondary)
participant I as Internal API (secondary Rails)
participant P as Primary API
C->>S: git pull
S->>I: SSH key validation (api/v4/internal/authorized_keys?key=..)
I-->>S: HTTP/1.1 300 (custom action status) with {endpoint, msg, primary_repo}
S->>I: POST /api/v4/geo/proxy_git_ssh/info_refs_upload_pack
I->>P: POST $PRIMARY/foo/bar.git/info/refs/?service=git-upload-pack
P-->>I: HTTP/1.1 200 OK
I-->>S: <response>
S-->>C: return Git response from primary
C-->>S: stream Git data to push
S->>I: POST /api/v4/geo/proxy_git_ssh/upload_pack
I->>P: POST $PRIMARY/foo/bar.git/git-upload-pack
P-->>I: HTTP/1.1 200 OK
I-->>S: <response>
S-->>C: return Git response from primary

Git push#

SSH를 통한 Git push#

Mermaid 다이어그램 (19줄)

소스 코드 보기

sequenceDiagram
participant C as Git client
participant S as GitLab Shell (secondary)
participant I as Internal API (secondary Rails)
participant P as Primary API
C->>S: git push
S->>I: SSH key validation (api/v4/internal/authorized_keys?key=..)
I-->>S: HTTP/1.1 300 (custom action status) with {endpoint, msg, primary_repo}
S->>I: POST /api/v4/geo/proxy_git_ssh/info_refs_receive_pack
I->>P: POST $PRIMARY/foo/bar.git/info/refs/?service=git-receive-pack
P-->>I: HTTP/1.1 200 OK
I-->>S: <response>
S-->>C: return Git response from primary
C-->>S: stream Git data to push
S->>I: POST /api/v4/geo/proxy_git_ssh/receive_pack
I->>P: POST $PRIMARY/foo/bar.git/git-receive-pack
P-->>I: HTTP/1.1 200 OK
I-->>S: <response>
S-->>C: return Git response from primary

HTTP(S)를 통한 Git push#

Mermaid 다이어그램 (28줄)

소스 코드 보기

sequenceDiagram
participant C as Git client
participant Wsec as Workhorse (secondary)
participant W as Workhorse (primary)
participant R as Rails (primary)
participant G as Gitaly (primary)
C->>Wsec: GET /foo/bar.git/info/refs/?service=git-receive-pack
Wsec->>C: 302 Redirect to /-/from_secondary/2/foo/bar.git/info/refs?service=git-receive-pack
C->>Wsec: GET /-/from_secondary/2/foo/bar.git/info/refs/?service=git-receive-pack
Wsec->>W: <proxied request>
W->>R: <data>
R-->>W: 401 Unauthorized
W-->>Wsec: <proxied response>
Wsec-->>C: <response>
C->>Wsec: GET /-/from_secondary/2/foo/bar.git/info/refs/?service=git-receive-pack
Wsec->>W: <proxied request>
W->>R: <data>
R-->>W: Render Workhorse OK
W-->>Wsec: <proxied response>
Wsec-->>C: <response>
C->>Wsec: POST /-/from_secondary/2/foo/bar.git/git-receive-pack
Wsec->>W: <proxied request>
W->>R: GitHttpController:git_receive_pack
R-->>W: Render Workhorse OK
W->>G: Get connection details from Rails and connects to SmartHTTP Service, ReceivePack RPC
G-->>W: Return a stream of Proto messages
W-->>Wsec: Pipe messages to the Git client
Wsec-->>C: Return piped messages from Git