← Bloga geri dön

Go modülleri indirilmedi: go get için GOPROXY, GOPRIVATE ve HTTP proxy ayarları

GOPROXY, GOPRIVATE ve go get için ağ proxy'sinin ayarlanmasına dair adım adım kılavuz — kurumsal güvenlik duvarı veya CI/CD altında Go modüllerinin indirilmediği durumlar için.

📅20 Kasım 2026

go get komutu takılıyor, zaman aşımına uğruyor veya dial tcp: i/o timeout hatası veriyor — bu, kurumsal güvenlik duvarı arkasında, kapalı bir ağda veya özel GitLab/GitHub depolarıyla çalışırken geliştiriciler için tanıdık bir durum. Durumların %90'ında sorun, yanlış yapılandırılmış GOPROXY, eksik GOPRIVATE veya proxy.golang.org'a doğrudan erişimin ağ güvenlik duvarı tarafından engellenmesidir. Bunu doğru bir şekilde nasıl düzelteceğimizi inceleyelim.

Neden Go modülleri indirilemiyor

Go 1.13 sürümünden itibaren, modüler sistem varsayılan olarak kamuya açık proxy proxy.golang.org ve kontrol sunucusu sum.golang.org ile iletişim kurar. Eğer her iki hizmet de ağ düzeyinde engellenmişse (bu, Rusya, Çin ve kısıtlamaların bulunduğu kurumsal segmentler için tipik bir durumdur), go build veya go mod tidy komutu zaman aşımına kadar takılacak ve ardından hata verecektir:

go: github.com/some/[email protected]: reading github.com/some/package/@v/v1.2.3.info: 
dial tcp 142.250.x.x:443: i/o timeout

Modüllerin indirilmesini bozan üç tipik senaryo vardır:

  • Ağ engeli — sağlayıcı veya kurumsal güvenlik duvarı, proxy.golang.org ve sum.golang.org üzerinde bulunan Google altyapısına erişimi kesiyor.
  • Özel depolar — modül, dahili bir GitLab/Bitbucket'ta yer alıyor ve kamuya açık GOPROXY fiziksel olarak ona ulaşamıyor, ayrıca sum.golang.org üzerinde kontrol etmek için checksum'ını kontrol etmeye çalışıyor, oysa bunu yapmamalı.
  • Proxy sunucusu ayarlanmamış ortam değişkenleri ile çalışıyor — dışarıya giden trafik yalnızca HTTP/SOCKS5 proxy üzerinden geçiyor, ancak Go bunun farkında değil, çünkü go get standart net/http istemcisini kullanıyor ve bu istemci ortam değişkenlerini okuyor, tarayıcıdan sistem proxy ayarlarını değil.

Şimdi her durumu belirli komutlar ve yapılandırma dosyaları ile inceleyeceğiz.

GOPROXY nedir ve nasıl çalışır

GOPROXY, Go araçlarına modülleri nereden indireceğini belirten bir ortam değişkenidir. Varsayılan olarak (Go 1.14'ten itibaren) değeri:

GOPROXY=https://proxy.golang.org,direct

Virgülle ayrılmış değerler, Go'nun sırayla denediği kaynakların listesidir. direct, "proxy 404 veya 410 dönerse VCS'den (git, svn, hg) doğrudan indirin" anlamına gelir. Eğer proxy fiziksel olarak erişilemezse (zaman aşımı, 404 değil), Go bir sonraki kaynağa geçmez — sadece takılır veya zaman aşımına uğrar. Bu, birçok kişinin anlamadığı önemli bir noktadır: geri dönüş mekanizması yalnızca "modül bulunamadı" için çalışır, "ağ erişilemez" için değil.

proxy.golang.org dışında, alternatif olarak kullanılabilecek kamuya açık aynalar da vardır:

GOPROXY sunucusu URL Özellik
Google resmi proxy.golang.org Kapalı ağlarda sıkça engellenir
goproxy.cn goproxy.cn Çin topluluğundan bir ayna, sürekli erişilebilir
Astra (goproxy.io) goproxy.io Alternatif küresel ayna
Athens (self-hosted) kendi sunucunuz Tam kontrol, kurumsal modül önbelleği için uygundur

GOPROXY ayarı: çalışan yapılandırmalar

Go ortam değişkenleri geçici (oturum için) veya kalıcı olarak go env -w ile ayarlanabilir, bu da değerleri Go yapılandırma dosyasına kaydeder (genellikle ~/.config/go/env Linux/macOS için ve %APPDATA%\go\env Windows için).

Kalıcı ayar (önerilir):

go env -w GOPROXY=https://goproxy.cn,direct
go env -w GOSUMDB=sum.golang.org

Mevcut değeri kontrol etmek için:

go env GOPROXY

Eğer birden fazla ayna ile yedekleme gerekiyorsa:

go env -w GOPROXY=https://goproxy.cn,https://goproxy.io,https://proxy.golang.org,direct

Önemli bir nokta: Eğer listedeki ilk proxy zaman aşımına uğrarsa, HTTP hatası değil, bir sonraki kaynağa geçmek bir modül için bir dakikaya kadar sürebilir — bu, CI'deki derleme hızını öldürür. Bu nedenle, eğer ağ fiziksel olarak ilk proxy'ye ulaşamıyorsa, onu listeden çıkarmak veya proxy sunucusu üzerinden ağ erişimini ayarlamak daha iyidir (aşağıdaki bölüme bakın), geri dönüşe güvenmek yerine.

Eğer dış proxy'lere erişimi tamamen devre dışı bırakmak ve yalnızca yerel önbellekten veya doğrudan VCS'den çalışmak istiyorsanız:

go env -w GOPROXY=direct

GOPRIVATE, GONOSUMCHECK ve GOSUMDB

Modül dahili bir Git deposunda (kurumsal GitLab, Bitbucket Server, kendi kendine barındırılan Gitea) yer alıyorsa, Go yine de varsayılan olarak bunu kamuya açık GOPROXY üzerinden kontrol etmeye çalışacak ve GOSUMDB üzerinden hash'ini kontrol edecektir — bu mümkün değildir çünkü özel kod dışarıya yayınlanmaz. Sonuç, 410 Gone veya verifying module: checksum mismatch hatasıdır.

Çözüm, Go'ya "bu modül yolları özel, kamuya açık proxy'ye gitme ve checksum'ı kontrol etme" diyen GOPRIVATE değişkenidir.

go env -w GOPRIVATE=gitlab.company.com/*,github.com/myorg/*

GOPRIVATE otomatik olarak iki bayrağı da ayarlar: GONOSUMCHECK (GOSUMDB üzerinden hash kontrolünü devre dışı bırakır) ve belirtilen yollar için GOPROXY=direct. Ancak daha ince ayar gerekiyorsa, bunları ayrı ayrı belirtebilirsiniz:

go env -w GONOSUMCHECK=1
go env -w GOSUMDB=off
go env -w GONOSUMDB=gitlab.company.com/*

GitHub'daki özel depolar için ayrıca, HTTPS üzerinden klonlama yaparken SSH yerine token kullanmak için git'i ayarlamak gerekir, çünkü Go araçları altında git kullanır:

git config --global url."https://${GITHUB_TOKEN}@github.com/".insteadOf "https://github.com/"

Bu komut, github.com'a yapılan tüm HTTPS isteklerini URL'de token ile değiştirilmiş bir istek haline getirir, bu da Go istemcisinin özel modülleri etkileşimli kullanıcı adı/şifre girişi olmadan indirmesine olanak tanır.

go get için HTTP/HTTPS proxy

Ofis veya sunucu kurumsal bir HTTP proxy arkasındaysa (örneğin, Squid), Go bunu otomatik olarak bilemez — yalnızca Go net/http istemcisi için standart olan ortam değişkenlerini HTTP_PROXY, HTTPS_PROXY ve NO_PROXY okur.

Linux / macOS (bash/zsh):

export HTTP_PROXY=http://user:password@proxy-host:3128
export HTTPS_PROXY=http://user:password@proxy-host:3128
export NO_PROXY=localhost,127.0.0.1,gitlab.company.com

Bunu her seferinde yazmamak için, satırları ~/.bashrc, ~/.zshrc veya ~/.profile dosyasına ekleyin.

Windows (PowerShell):

$env:HTTP_PROXY = "http://user:password@proxy-host:3128"
$env:HTTPS_PROXY = "http://user:password@proxy-host:3128"
$env:NO_PROXY = "localhost,127.0.0.1"

Windows'ta kalıcı olarak saklamak için setx kullanın:

setx HTTP_PROXY "http://user:password@proxy-host:3128"
setx HTTPS_PROXY "http://user:password@proxy-host:3128"

Önemli: NO_PROXY, dahili alanları (dahili GitLab, yerel Athens sunucusu) içermelidir, aksi takdirde bu alanlara yapılan istekler de dış proxy üzerinden gidecek ve erişim hatası verecektir.

Eğer kamuya açık GOPROXY, iç güvenlik duvarı nedeniyle değil, belirli bir bölgedeki coğrafi engelleme nedeniyle erişilemiyorsa — bu, sunucuları farklı ülkelerde bulunan ekiplerin karşılaştığı bir durumdur — kurumsal HTTP proxy yerine, gerekli coğrafi konumda bir dış proxy sunucusu üzerinden çıkış tüneli oluşturulabilir. Bu tür senaryolar için veri merkezi proxyleri uygundur — bunlar, bağımlılıkların toplu olarak yüklenmesi sırasında kritik olan kararlı hızlı bir kanal ve öngörülebilir gecikme sağlar.

SOCKS5 proxy ve engellerin aşılması

HTTP_PROXY/HTTPS_PROXY değişkenleri yalnızca HTTP(S) proxy'leri değil, aynı zamanda SOCKS5'i de destekler — Go 1.10+ sürümünden itibaren standart kütüphane socks5:// şemasını kullanarak çalışabilir:

export ALL_PROXY=socks5://user:password@proxy-host:1080
export HTTP_PROXY=socks5://user:password@proxy-host:1080
export HTTPS_PROXY=socks5://user:password@proxy-host:1080

ALL_PROXY değişkeni evrenseldir, birçok CLI aracı tarafından okunur, yalnızca Go değil. Eğer zaten bir SOCKS5 tüneliniz varsa (örneğin, SSH üzerinden: ssh -D 1080 user@remote-host), tüm go get trafiğini ek sunucu ayarları olmadan bu tünel üzerinden yönlendirebilirsiniz.

Farklı bölgelerden derleme testleri yapmak için (örneğin, CI'deki bir paket ayna isteği sırasında nasıl davrandığını kontrol etmek veya belirli bir ülkeden gelen istekler üzerine dış hizmetin nasıl tepki verdiğini görmek için) genellikle gerçek bir IP adresi ile bir kanal gereklidir, bu da sıradan bir kullanıcı gibi görünmelidir, veri merkezi gibi değil. Bu tür durumlarda rezidans proxyleri tercih edilir — bunlar, modül dağıtım sunucularında otomatik kısıtlamalara daha az maruz kalır.

Go'nun proxy'yi gerçekten kullanıp kullanmadığını kontrol etmek için basit bir komutla detaylı çıktı alabilirsiniz:

GODEBUG=http2debug=1 go get -x github.com/gin-gonic/gin

-x bayrağı, her yürütülen komutu, ağ istekleri dahil, yazdırır; bu, go get'in proxy üzerinden gidip gitmediğini veya ortam değişkenlerini görmezden gelip gelmediğini anlamanıza yardımcı olur (bu, değişkenlerin başka bir terminal oturumunda dışa aktarılması veya alt süreçte geçmemesi durumunda olur).

CI/CD ve Docker'da proxy

CI koşucularında (GitHub Actions, GitLab CI, Jenkins) ortam değişkenlerini açıkça iş tanımı ayarları üzerinden geçirmelisiniz, yerel .bashrc'ye güvenmemelisiniz, çünkü konteyner içinde okunmaz.

GitLab CI (.gitlab-ci.yml):

variables:
  GOPROXY: "https://goproxy.cn,direct"
  GOPRIVATE: "gitlab.company.com/*"
  HTTPS_PROXY: "http://user:password@proxy-host:3128"

build:
  script:
    - go mod download
    - go build ./...

Dockerfile (çok aşamalı derleme):

FROM golang:1.22 AS builder
ARG HTTP_PROXY
ARG HTTPS_PROXY
ENV HTTP_PROXY=${HTTP_PROXY}
ENV HTTPS_PROXY=${HTTPS_PROXY}
ENV GOPROXY=https://goproxy.cn,direct
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build -o app .

Derleme argümanları docker build çağrıldığında geçilir:

docker build --build-arg HTTP_PROXY=http://user:password@proxy-host:3128 \
  --build-arg HTTPS_PROXY=http://user:password@proxy-host:3128 \
  -t myapp .

Eğer derleme birden fazla koşucuda paralel olarak yapılıyorsa ve modül aynasından çok sayıda eşzamanlı istek nedeniyle IP'nin yasaklanmasını önlemek gerekiyorsa (bu, yüksek yük altında kendi kendine barındırılan Athens proxy ile olabilir), çıkış isteklerini IP rotasyonu ile dağıtmak faydalı olabilir. Yükü eşit bir şekilde dağıtmak ve proxy sunucusu tarafından rate-limit'i önlemek için genellikle veri merkezi proxyleri kullanılır — bunlar düşük gecikme sağlar, bu da CI için önemlidir, çünkü her fazla saniye iş sayısına çarpılır.

Sık karşılaşılan hatalar ve çözümleri

Hata Sebep Çözüm
dial tcp: i/o timeout proxy.golang.org ağdan erişilemiyor GOPROXY'yi bir ayna ile değiştirin veya HTTP_PROXY'yi ayarlayın
410 Gone Özel modül kamuya açık proxy'ye erişilemiyor GOPRIVATE'yi gerekli modül yolu için ayarlayın
checksum mismatch GOSUMDB özel modülü kontrol etmeye çalışıyor GONOSUMDB veya GOSUMDB=off ile devre dışı bırakın
x509: certificate signed by unknown authority Kurumsal proxy TLS sertifikasını değiştiriyor (MITM) Şirketin kök sertifikasını sistem deposuna ekleyin
repository not found Özel git deposu için erişim tokeni yok Token ile git config url.insteadOf'ı ayarlayın
Proxy değişkenleri yok sayılıyor Dışa aktarım başka bir kabuk/oturumda yapıldı Aynı oturumda env | grep PROXY ile kontrol edin, go'nun çalıştığı oturumda

MITM proxy'leri (kurumsal Squid/Zscaler ile sertifika değişimi) hakkında ayrıca bir şey söylemek gerekir: Eğer böyle bir proxy, HTTPS trafiğini analiz için yakalıyorsa, Go istemcisi kendi kendine imzalanmış sertifikasına güvenmez ve bu da x509 hatasına yol açar. Çözüm, şirketin kök sertifikasını PEM formatında dışa aktarmak ve bunu değişkene yazmaktır:

export SSL_CERT_FILE=/etc/ssl/certs/company-root-ca.pem

Bu değişken, TLS zincirini kontrol ederken Go çalışma zamanı tarafından okunur ve kurumsal MITM proxy üzerinden sertifika kontrolünü tamamen devre dışı bırakmadan çalışmaya olanak tanır (bu güvenlik nedenleriyle yapılmamalıdır).

Sonuç

Eğer Go modülleri indirilemiyorsa, %90 durumunda üç adım yeterlidir: çalışır bir GOPROXY ayarlamak (engellenmiş proxy.golang.org yerine kamuya açık bir ayna), dahili depolar için GOPRIVATE eklemek ve ağ sadece kurumsal proxy üzerinden çıkıyorsa HTTP_PROXY/HTTPS_PROXY'yi ayarlamak. CI/CD için bu değişkenlerin açıkça iş tanımı veya Docker yapılandırma argümanları üzerinden geçirilmesi gerekir, geliştirici yerel yapılandırmalarına güvenilmemelidir.

Eğer hataların nedeni modül aynasının coğrafi engellenmesi veya CI'de paralel derleme sırasında proxy sunucusu tarafından rate-limit ise, çıkış trafiğini kararlı bir dış kanaldan geçirmek iyi bir fikirdir. Bu tür görevler için veri merkezi proxyleri iyi bir seçimdir — düşük gecikme ve öngörülebilir bant genişliği, bağımlılıkların toplu olarak yüklenmesinde kritik öneme sahiptir. Eğer dış hizmetlerin erişilebilirliğini farklı bölgelerden test ederken sıradan kullanıcı trafiğini taklit etmek gerekiyorsa, rezidans proxyleri uygundur — bunlar, paket dağıtım sunucularında güvenlik sistemlerinin şüphelenmesini daha az tetikler.