Il comando go get si blocca, va in timeout o restituisce dial tcp: i/o timeout — una situazione familiare per gli sviluppatori dietro un firewall aziendale, in una rete chiusa o quando si lavora con repository GitLab/GitHub privati. Nel 90% dei casi, la causa è una configurazione errata di GOPROXY, l'assenza di GOPRIVATE o il blocco dell'accesso diretto a proxy.golang.org da parte di un firewall. Analizziamo come risolvere correttamente il problema.
Perché i moduli Go non vengono scaricati
A partire dalla versione Go 1.13, il sistema dei moduli per impostazione predefinita si rivolge al proxy pubblico proxy.golang.org e al server di verifica delle somme sum.golang.org. Se entrambi i servizi sono bloccati a livello di rete (questo è tipico per la Russia, la Cina e segmenti aziendali con restrizioni), il comando go build o go mod tidy si bloccherà fino al timeout, per poi restituire un errore:
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
Ci sono tre scenari tipici che possono interrompere il download dei moduli:
- Blocco di rete — il provider o il firewall aziendale taglia l'accesso all'infrastruttura di Google, su cui si basano proxy.golang.org e sum.golang.org.
- Repository privati — il modulo si trova in un GitLab/Bitbucket interno, e il GOPROXY pubblico non può fisicamente raggiungerlo, mentre cerca anche di verificare il suo checksum su sum.golang.org, anche se non dovrebbe.
- Proxy server nella rete senza variabili d'ambiente configurate — il traffico verso l'esterno passa solo attraverso un proxy HTTP/SOCKS5, ma Go non lo sa, perché
go getutilizza il client net/http standard, che legge le variabili d'ambiente e non le impostazioni proxy di sistema dal browser.
Successivamente, analizzeremo ciascun caso con comandi specifici e file di configurazione.
Che cos'è GOPROXY e come funziona
GOPROXY è una variabile d'ambiente che indica alla toolchain di Go da dove scaricare i moduli. Per impostazione predefinita (a partire da Go 1.14) il suo valore è:
GOPROXY=https://proxy.golang.org,direct
Il valore separato da virgole è un elenco di fonti che Go esamina in ordine. direct significa "scaricare direttamente da VCS (git, svn, hg), se il proxy restituisce 404 o 410". Se il proxy non è fisicamente disponibile (timeout, non 404), Go non passa alla fonte successiva — si blocca semplicemente o va in timeout. Questo è un punto chiave che molti non comprendono: il meccanismo di fallback funziona solo per "modulo non trovato", non per "rete non disponibile".
Oltre a proxy.golang.org, ci sono mirror pubblici che possono essere utilizzati come alternativa:
| Server GOPROXY | URL | Caratteristica |
|---|---|---|
| Google ufficiale | proxy.golang.org | Spesso bloccato in reti chiuse |
| goproxy.cn | goproxy.cn | Mirror della comunità cinese, stabilmente accessibile |
| Astra (goproxy.io) | goproxy.io | Mirror globale alternativo |
| Athens (self-hosted) | server proprio | Controllo completo, adatto per la cache dei moduli aziendali |
Configurazione di GOPROXY: configurazioni funzionanti
Le variabili d'ambiente di Go possono essere impostate temporaneamente (per la sessione) o permanentemente tramite go env -w, che salva i valori in un file di configurazione di Go (di solito ~/.config/go/env su Linux/macOS e %APPDATA%\go\env su Windows).
Impostazione permanente (consigliata):
go env -w GOPROXY=https://goproxy.cn,direct go env -w GOSUMDB=sum.golang.org
Controllare il valore attuale:
go env GOPROXY
Se sono necessari più mirror con riserva:
go env -w GOPROXY=https://goproxy.cn,https://goproxy.io,https://proxy.golang.org,direct
Un aspetto importante: se il primo proxy nell'elenco risponde con un timeout, e non con un errore HTTP, il passaggio alla fonte successiva può richiedere fino a un minuto per ogni modulo — questo rallenta la velocità di build in CI. Pertanto, se la rete non riesce fisicamente a raggiungere il primo proxy, è meglio rimuoverlo immediatamente dall'elenco o configurare l'accesso di rete tramite un server proxy (vedi la sezione sottostante), piuttosto che fare affidamento sul fallback.
Se si desidera disabilitare completamente l'accesso a proxy esterni e lavorare solo dalla cache locale o direttamente da VCS:
go env -w GOPROXY=direct
GOPRIVATE, GONOSUMCHECK e GOSUMDB
Quando un modulo si trova in un repository Git interno (GitLab aziendale, Bitbucket Server, Gitea self-hosted), Go tenterà comunque di verificarlo tramite il GOPROXY pubblico e confrontare l'hash tramite GOSUMDB — il che è impossibile, poiché il codice privato non viene pubblicato all'esterno. Il risultato è un errore 410 Gone o verifying module: checksum mismatch.
La soluzione è la variabile GOPRIVATE, che dice a Go: "questi percorsi di moduli sono privati, non cercarli nel proxy pubblico e non verificare il checksum".
go env -w GOPRIVATE=gitlab.company.com/*,github.com/myorg/*
GOPRIVATE imposta automaticamente due flag: GONOSUMCHECK (disabilita il controllo dell'hash tramite GOSUMDB) e GOPROXY=direct per i percorsi specificati. Ma se è necessaria una configurazione più fine, è possibile impostarli separatamente:
go env -w GONOSUMCHECK=1 go env -w GOSUMDB=off go env -w GONOSUMDB=gitlab.company.com/*
Per i repository privati su GitHub, è necessario anche configurare git per utilizzare un token invece di SSH durante il cloning tramite HTTPS, poiché la toolchain di Go utilizza git sotto il cofano:
git config --global url."https://${GITHUB_TOKEN}@github.com/".insteadOf "https://github.com/"
Questo comando sostituisce tutte le richieste HTTPS a github.com con una richiesta contenente il token nell'URL, consentendo al client Go di scaricare moduli privati senza richiedere l'inserimento interattivo di nome utente/password.
Proxy HTTP/HTTPS per go get
Se l'ufficio o il server si trova dietro un proxy HTTP aziendale (ad esempio, Squid), Go non lo scoprirà automaticamente — legge solo le variabili d'ambiente HTTP_PROXY, HTTPS_PROXY e NO_PROXY, standard per il client Go net/http.
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
Per non doverlo scrivere ogni volta, aggiungi le righe a ~/.bashrc, ~/.zshrc o ~/.profile.
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"
Per salvare permanentemente su Windows, utilizzare setx:
setx HTTP_PROXY "http://user:password@proxy-host:3128" setx HTTPS_PROXY "http://user:password@proxy-host:3128"
È importante: NO_PROXY deve includere i domini interni (GitLab interno, server Athens locale), altrimenti le richieste a questi andranno anch'esse attraverso il proxy esterno e restituiranno un errore di accesso.
Se il GOPROXY pubblico non è accessibile non a causa di un firewall interno, ma a causa di un geoblocking di una specifica regione — una situazione che le squadre affrontano quando i loro server sono distribuiti in diversi paesi — invece di un proxy HTTP aziendale, è possibile creare un tunnel in uscita tramite un server proxy esterno con la geolocalizzazione desiderata. Per tali scenari, sono adatti proxy di data center — forniscono un canale veloce e stabile e una latenza prevedibile, il che è critico durante il caricamento massivo delle dipendenze in un pipeline CI.
Proxy SOCKS5 e bypass dei blocchi
Le variabili HTTP_PROXY/HTTPS_PROXY supportano non solo proxy HTTP(S), ma anche SOCKS5 — a partire da Go 1.10+, la libreria standard può lavorare tramite lo schema socks5://:
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
La variabile ALL_PROXY è universale, viene letta da molte utilità CLI, non solo da Go. Se hai già un tunnel SOCKS5 (ad esempio, tramite SSH: ssh -D 1080 user@remote-host), puoi instradare tutto il traffico go get attraverso di esso senza ulteriori configurazioni sul server.
Per testare la build da diverse regioni (ad esempio, per verificare come si comporta la pipeline CI quando richiede un mirror regionale dei pacchetti o come risponde un servizio esterno a richieste da un paese specifico) è spesso necessario un canale con un indirizzo IP reale, simile a quello di un utente normale, e non di un data center. In tali casi, si scelgono proxy residenziali — sono meno soggetti a restrizioni automatiche da parte dei server di distribuzione dei moduli o dei registri di pacchetti privati.
Puoi verificare che il proxy venga effettivamente utilizzato da Go con un semplice comando con output dettagliato:
GODEBUG=http2debug=1 go get -x github.com/gin-gonic/gin
Il flag -x stampa ogni comando eseguito, comprese le richieste di rete, il che aiuta a capire se go get sta passando attraverso il proxy o ignorando le variabili d'ambiente (questo accade se le variabili sono state esportate in un'altra sessione del terminale o non sono state propagate al sottoprocesso).
Proxy in CI/CD e Docker
Nei runner CI (GitHub Actions, GitLab CI, Jenkins), le variabili d'ambiente devono essere passate esplicitamente tramite le impostazioni del job, e non fare affidamento sul .bashrc locale, che non viene letto nel contenitore.
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 (build multi-stage):
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 .
Gli argomenti di build vengono passati quando si chiama docker build:
docker build --build-arg HTTP_PROXY=http://user:password@proxy-host:3128 \ --build-arg HTTPS_PROXY=http://user:password@proxy-host:3128 \ -t myapp .
Se la build avviene in parallelo su più runner e si desidera evitare il ban per IP da parte del mirror dei moduli a causa di un numero elevato di richieste simultanee (cosa che può accadere con un proxy Athens self-hosted sotto carico elevato), è utile distribuire le richieste in uscita tramite rotazione IP. Per una distribuzione uniforme del carico e per escludere il rate-limit da parte del server proxy del mirror dei moduli, si utilizzano spesso proxy di data center — forniscono una bassa latenza, il che è importante per CI, dove ogni secondo in più si moltiplica per il numero di job.
Errori comuni e le loro soluzioni
| Errore | Causa | Soluzione |
|---|---|---|
dial tcp: i/o timeout |
proxy.golang.org non è accessibile dalla rete | Cambia GOPROXY con un mirror o configura HTTP_PROXY |
410 Gone |
Il modulo privato non è accessibile al proxy pubblico | Configura GOPRIVATE per il percorso del modulo necessario |
checksum mismatch |
GOSUMDB sta cercando di verificare un modulo privato | Disabilita tramite GONOSUMDB o GOSUMDB=off |
x509: certificate signed by unknown authority |
Il proxy aziendale sostituisce il certificato TLS (MITM) | Aggiungi il certificato radice dell'azienda nel keystore di sistema |
repository not found |
Nessun token di accesso per il repository git privato | Configura git config url.insteadOf con il token |
| Le variabili proxy vengono ignorate | L'esportazione è stata effettuata in un'altra shell/sessione | Controlla tramite env | grep PROXY nella stessa sessione in cui viene eseguito go |
Vale la pena menzionare i proxy MITM (Squid/Zscaler aziendali con sostituzione dei certificati): se un tale proxy intercetta il traffico HTTPS per analisi, il client Go non si fida del suo certificato autofirmato, e questo porta a un errore x509. La soluzione è esportare il certificato radice dell'azienda in formato PEM e definirlo nella variabile:
export SSL_CERT_FILE=/etc/ssl/certs/company-root-ca.pem
Questa variabile viene letta dal runtime di Go durante il controllo della catena TLS e consente di lavorare attraverso un proxy MITM aziendale senza disabilitare completamente il controllo dei certificati (cosa che non si dovrebbe fare per motivi di sicurezza).
Conclusione
Se i moduli Go non vengono scaricati, nel 90% dei casi bastano tre passaggi: impostare un GOPROXY funzionante (un mirror pubblico al posto di proxy.golang.org bloccato), aggiungere GOPRIVATE per i repository interni e configurare HTTP_PROXY/HTTPS_PROXY se la rete esce verso l'esterno solo tramite un proxy aziendale. Per CI/CD, queste variabili devono essere passate esplicitamente tramite variabili d'ambiente del job o argomenti di build Docker, e non fare affidamento sulle configurazioni locali dello sviluppatore.
Se la causa dei fallimenti è il geoblocking del mirror dei moduli o il rate-limit da parte del server proxy durante la build parallela in CI, è consigliabile instradare il traffico in uscita attraverso un canale esterno stabile. Per tali compiti, i proxy di data center sono molto adatti — la bassa latenza e la larghezza di banda prevedibile sono critiche durante il caricamento massivo delle dipendenze. E se è necessario emulare il traffico di un utente normale durante il test della disponibilità di servizi esterni da diverse regioni, i proxy residenziali sono una buona scelta — sono meno soggetti a sospetti da parte dei sistemi di protezione sui server di distribuzione dei pacchetti.