Lệnh go get bị treo, bị lỗi thời gian hoặc báo lỗi dial tcp: i/o timeout - tình huống quen thuộc với các nhà phát triển trong môi trường doanh nghiệp, trong mạng kín hoặc khi làm việc với các kho GitLab/GitHub riêng tư. Trong 90% trường hợp, nguyên nhân là do cấu hình GOPROXY không chính xác, thiếu GOPRIVATE hoặc bị chặn truy cập trực tiếp đến proxy.golang.org bởi tường lửa. Hãy cùng tìm hiểu cách khắc phục đúng cách.
Tại sao các mô-đun Go không tải xuống
Kể từ phiên bản Go 1.13, hệ thống mô-đun mặc định truy cập vào proxy công khai proxy.golang.org và máy chủ kiểm tra checksum sum.golang.org. Nếu cả hai dịch vụ đều bị chặn ở cấp độ mạng (điều này thường xảy ra ở Nga, Trung Quốc và các phân khúc doanh nghiệp có hạn chế), lệnh go build hoặc go mod tidy sẽ treo cho đến khi hết thời gian, và sau đó sẽ báo lỗi:
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
Có ba kịch bản điển hình dẫn đến việc tải xuống mô-đun bị hỏng:
- Chặn mạng - nhà cung cấp hoặc tường lửa doanh nghiệp chặn truy cập vào cơ sở hạ tầng Google, nơi lưu trữ proxy.golang.org và sum.golang.org.
- Kho riêng tư - mô-đun nằm trong GitLab/Bitbucket nội bộ, và GOPROXY công khai không thể truy cập vào nó, đồng thời cố gắng kiểm tra checksum của nó trên sum.golang.org, mặc dù không nên.
- Máy chủ proxy trong mạng mà không có biến môi trường được cấu hình - lưu lượng truy cập ra ngoài chỉ đi qua HTTP/SOCKS5-proxy, nhưng Go không biết điều này, vì
go getsử dụng khách net/http tiêu chuẩn, đọc các biến môi trường, chứ không phải cài đặt proxy hệ thống từ trình duyệt.
Tiếp theo, chúng ta sẽ xem xét từng trường hợp với các lệnh cụ thể và tệp cấu hình.
GOPROXY là gì và nó hoạt động như thế nào
GOPROXY là một biến môi trường chỉ định cho công cụ Go biết từ đâu để tải xuống các mô-đun. Mặc định (bắt đầu từ Go 1.14), giá trị của nó là:
GOPROXY=https://proxy.golang.org,direct
Giá trị phân tách bằng dấu phẩy là danh sách các nguồn mà Go sẽ lần lượt kiểm tra. direct có nghĩa là "tải xuống trực tiếp từ VCS (git, svn, hg), nếu proxy trả về 404 hoặc 410". Nếu proxy không khả dụng về mặt vật lý (hết thời gian, không phải 404), Go sẽ không chuyển sang nguồn tiếp theo - nó chỉ treo hoặc bị lỗi do hết thời gian. Đây là điểm quan trọng mà nhiều người không hiểu: cơ chế fallback chỉ hoạt động cho "mô-đun không tìm thấy", chứ không phải cho "mạng không khả dụng".
Ngoài proxy.golang.org, còn có các gương công khai mà bạn có thể sử dụng như một sự thay thế:
| Máy chủ GOPROXY | URL | Đặc điểm |
|---|---|---|
| Google chính thức | proxy.golang.org | Thường bị chặn trong các mạng kín |
| goproxy.cn | goproxy.cn | Gương từ cộng đồng Trung Quốc, ổn định và có sẵn |
| Astra (goproxy.io) | goproxy.io | Gương toàn cầu thay thế |
| Athens (tự host) | máy chủ riêng | Kiểm soát hoàn toàn, phù hợp cho bộ nhớ cache mô-đun trong doanh nghiệp |
Cấu hình GOPROXY: các cấu hình hoạt động
Các biến môi trường của Go có thể được đặt tạm thời (trong phiên) hoặc vĩnh viễn thông qua go env -w, điều này sẽ lưu trữ giá trị vào tệp cấu hình Go (thường là ~/.config/go/env trên Linux/macOS và %APPDATA%\go\env trên Windows).
Cấu hình vĩnh viễn (được khuyến nghị):
go env -w GOPROXY=https://goproxy.cn,direct go env -w GOSUMDB=sum.golang.org
Kiểm tra giá trị hiện tại:
go env GOPROXY
Nếu cần nhiều gương dự phòng:
go env -w GOPROXY=https://goproxy.cn,https://goproxy.io,https://proxy.golang.org,direct
Một điểm quan trọng: nếu proxy đầu tiên trong danh sách phản hồi bằng thời gian chờ, thay vì lỗi HTTP, việc chuyển sang nguồn tiếp theo có thể mất đến một phút cho mỗi mô-đun - điều này làm giảm tốc độ xây dựng trong CI. Vì vậy, nếu mạng không thể truy cập vào proxy đầu tiên, tốt hơn là loại bỏ nó khỏi danh sách hoặc cấu hình truy cập mạng qua máy chủ proxy (xem phần dưới đây), thay vì dựa vào fallback.
Nếu muốn hoàn toàn tắt truy cập vào các proxy bên ngoài và chỉ làm việc từ bộ nhớ cache cục bộ hoặc trực tiếp từ VCS:
go env -w GOPROXY=direct
GOPRIVATE, GONOSUMCHECK và GOSUMDB
Khi mô-đun nằm trong kho Git nội bộ (GitLab doanh nghiệp, Bitbucket Server, Gitea tự host), Go vẫn sẽ cố gắng kiểm tra nó qua GOPROXY công khai và đối chiếu hash qua GOSUMDB - điều này không thể thực hiện được, vì mã nguồn riêng tư không được công khai. Kết quả là lỗi 410 Gone hoặc verifying module: checksum mismatch.
Giải pháp là biến GOPRIVATE, cho Go biết: "các đường dẫn mô-đun này là riêng tư, không truy cập vào proxy công khai và không kiểm tra checksum".
go env -w GOPRIVATE=gitlab.company.com/*,github.com/myorg/*
GOPRIVATE tự động thiết lập hai cờ ngay lập tức: GONOSUMCHECK (tắt kiểm tra hash qua GOSUMDB) và GOPROXY=direct cho các đường dẫn đã chỉ định. Nhưng nếu cần cấu hình tinh vi hơn, bạn có thể thiết lập chúng riêng biệt:
go env -w GONOSUMCHECK=1 go env -w GOSUMDB=off go env -w GONOSUMDB=gitlab.company.com/*
Đối với các kho riêng tư trên GitHub, cần cấu hình git để sử dụng token thay vì SSH khi sao chép qua HTTPS, vì công cụ Go sử dụng git bên trong:
git config --global url."https://${GITHUB_TOKEN}@github.com/".insteadOf "https://github.com/"
Lệnh này thay thế tất cả các yêu cầu HTTPS đến github.com bằng yêu cầu có token trong URL, cho phép khách hàng Go tải xuống các mô-đun riêng tư mà không cần nhập tên đăng nhập/mật khẩu một cách tương tác.
HTTP/HTTPS-proxy cho go get
Nếu văn phòng hoặc máy chủ nằm sau một HTTP-proxy doanh nghiệp (ví dụ: Squid), Go sẽ không tự động nhận biết điều này - nó chỉ đọc các biến môi trường HTTP_PROXY, HTTPS_PROXY và NO_PROXY, tiêu chuẩn cho khách hàng 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
Để không cần nhập lại mỗi lần, hãy thêm các dòng vào ~/.bashrc, ~/.zshrc hoặc ~/.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"
Để lưu vĩnh viễn trên Windows, hãy sử dụng setx:
setx HTTP_PROXY "http://user:password@proxy-host:3128" setx HTTPS_PROXY "http://user:password@proxy-host:3128"
Quan trọng: NO_PROXY phải bao gồm các miền nội bộ (GitLab nội bộ, máy chủ Athens cục bộ), nếu không, các yêu cầu đến chúng cũng sẽ đi qua proxy bên ngoài và sẽ gặp lỗi truy cập.
Nếu GOPROXY công khai không khả dụng không phải do tường lửa nội bộ, mà do geo-blocking của một khu vực cụ thể - tình huống mà các nhóm gặp phải khi máy chủ của họ phân tán ở nhiều quốc gia - thay vì proxy HTTP doanh nghiệp, bạn có thể thiết lập một đường hầm đầu ra qua máy chủ proxy bên ngoài với vị trí địa lý phù hợp. Đối với các kịch bản như vậy, các proxy trung tâm dữ liệu là lựa chọn tốt - chúng cung cấp kênh ổn định và độ trễ dự đoán, điều này rất quan trọng khi tải hàng loạt phụ thuộc trong pipeline CI.
SOCKS5-proxy và cách vượt qua các chặn
Các biến HTTP_PROXY/HTTPS_PROXY không chỉ hỗ trợ proxy HTTP(S), mà còn hỗ trợ SOCKS5 - bắt đầu từ Go 1.10+, thư viện tiêu chuẩn có thể hoạt động qua sơ đồ 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
Biến ALL_PROXY là đa năng, được nhiều công cụ CLI đọc, không chỉ Go. Nếu bạn đã có một đường hầm SOCKS5 (ví dụ: qua SSH: ssh -D 1080 user@remote-host), bạn có thể cho phép toàn bộ lưu lượng go get đi qua nó mà không cần cấu hình thêm trên máy chủ.
Để kiểm tra việc xây dựng từ các khu vực khác nhau (ví dụ: để kiểm tra cách pipeline CI hoạt động khi yêu cầu đến gương khu vực của các gói hoặc cách dịch vụ bên ngoài phản ứng với các yêu cầu từ một quốc gia cụ thể), thường cần một kênh với địa chỉ IP thực tế, giống như một người dùng bình thường, chứ không phải từ trung tâm dữ liệu. Trong những trường hợp như vậy, các proxy cư dân được chọn - chúng ít khi bị phát hiện bởi các hạn chế tự động từ phía máy chủ phân phối mô-đun hoặc các kho gói riêng tư.
Để kiểm tra xem proxy có thực sự được Go sử dụng hay không, bạn có thể sử dụng lệnh đơn giản với đầu ra chi tiết:
GODEBUG=http2debug=1 go get -x github.com/gin-gonic/gin
Cờ -x in ra mỗi lệnh được thực hiện, bao gồm các yêu cầu mạng, giúp hiểu xem go get có thực sự đi qua proxy hay không hoặc có bỏ qua các biến môi trường (điều này xảy ra nếu các biến được xuất trong một phiên terminal khác hoặc không được truyền vào subprocess).
Proxy trong CI/CD và Docker
Trong các runner CI (GitHub Actions, GitLab CI, Jenkins), các biến môi trường cần được truyền rõ ràng qua cài đặt job, thay vì dựa vào .bashrc cục bộ, mà không được đọc trong container.
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 (xây dựng đa giai đoạn):
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 .
Các tham số xây dựng được truyền khi gọi 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 .
Nếu việc xây dựng diễn ra song song trên nhiều runner và cần tránh bị cấm IP từ phía gương mô-đun do số lượng yêu cầu đồng thời lớn (điều này xảy ra với Athens-proxy tự host dưới tải cao), việc phân phối các yêu cầu đầu ra qua xoay vòng IP là hữu ích. Để phân phối đều tải và loại trừ rate-limit từ phía máy chủ proxy gương mô-đun, thường sử dụng các proxy trung tâm dữ liệu - chúng cung cấp độ trễ thấp, điều này rất quan trọng cho CI, nơi mỗi giây thừa sẽ nhân lên với số lượng job.
Các lỗi thường gặp và cách giải quyết
| Lỗi | Nguyên nhân | Giải pháp |
|---|---|---|
dial tcp: i/o timeout |
proxy.golang.org không khả dụng từ mạng | Thay đổi GOPROXY thành gương hoặc cấu hình HTTP_PROXY |
410 Gone |
Mô-đun riêng tư không khả dụng cho proxy công khai | Cấu hình GOPRIVATE cho đường dẫn mô-đun cần thiết |
checksum mismatch |
GOSUMDB cố gắng kiểm tra mô-đun riêng tư | Tắt thông qua GONOSUMDB hoặc GOSUMDB=off |
x509: certificate signed by unknown authority |
Proxy doanh nghiệp thay đổi chứng chỉ TLS (MITM) | Thêm chứng chỉ gốc của công ty vào kho lưu trữ hệ thống |
repository not found |
Không có token truy cập cho kho git riêng tư | Cấu hình git config url.insteadOf với token |
| Các biến proxy bị bỏ qua | Xuất được thực hiện trong một shell/session khác | Kiểm tra qua env | grep PROXY trong cùng một phiên mà go được chạy |
Cần nói riêng về proxy MITM (Squid/Zscaler doanh nghiệp với việc thay thế chứng chỉ): nếu proxy như vậy chặn lưu lượng HTTPS để phân tích, khách hàng Go sẽ không tin tưởng vào chứng chỉ tự ký của nó, và điều này dẫn đến lỗi x509. Giải pháp là xuất chứng chỉ gốc của công ty ở định dạng PEM và chỉ định nó trong biến:
export SSL_CERT_FILE=/etc/ssl/certs/company-root-ca.pem
Biến này được Go runtime đọc khi kiểm tra chuỗi TLS và cho phép làm việc qua proxy MITM doanh nghiệp mà không tắt hoàn toàn việc kiểm tra chứng chỉ (điều này không nên làm vì lý do bảo mật).
Kết luận
Nếu các mô-đun Go không tải xuống, trong 90% trường hợp chỉ cần ba bước: thiết lập GOPROXY hoạt động (gương công khai thay vì proxy.golang.org bị chặn), thêm GOPRIVATE cho các kho nội bộ và chỉ định HTTP_PROXY/HTTPS_PROXY nếu mạng chỉ ra ngoài qua proxy doanh nghiệp. Đối với CI/CD, các biến này cần được truyền rõ ràng qua các biến môi trường job hoặc các tham số build của Docker, thay vì dựa vào các cấu hình cục bộ của nhà phát triển.
Nếu nguyên nhân của các sự cố là geo-blocking của gương mô-đun hoặc rate-limit từ phía máy chủ proxy khi xây dựng song song trong CI, nên cho phép lưu lượng đầu ra đi qua một kênh bên ngoài ổn định. Đối với những nhiệm vụ như vậy, các proxy trung tâm dữ liệu là lựa chọn tốt - độ trễ thấp và băng thông dự đoán là rất quan trọng khi tải hàng loạt phụ thuộc. Và nếu cần mô phỏng lưu lượng người dùng bình thường khi kiểm tra khả năng truy cập của các dịch vụ bên ngoài từ các khu vực khác nhau, các proxy cư dân là lựa chọn phù hợp - chúng ít khi gây nghi ngờ cho các hệ thống bảo vệ ở phía máy chủ phân phối gói.