← بازگشت به وبلاگ

دانلود نشدن ماژول‌های Go: تنظیم GOPROXY، GOPRIVATE و پروکسی HTTP برای go get

راهنمای گام به گام برای تنظیم GOPROXY، GOPRIVATE و پروکسی شبکه برای go get - برای کسانی که ماژول‌های Go را در پشت فایروال شرکتی یا در CI/CD دانلود نمی‌کنند.

📅۲۹ آبان ۱۴۰۵

فرمان go get متوقف می‌شود، با تایم‌اوت سقوط می‌کند یا خطای dial tcp: i/o timeout را نشان می‌دهد — این وضعیت برای توسعه‌دهندگان در پشت فایروال شرکتی، در شبکه‌های بسته یا هنگام کار با مخازن خصوصی GitLab/GitHub آشناست. در 90% موارد، دلیل این مشکل تنظیم نادرست GOPROXY، عدم وجود GOPRIVATE یا مسدود شدن دسترسی مستقیم به proxy.golang.org توسط فایروال شبکه است. بیایید بررسی کنیم که چگونه می‌توان این مشکل را به درستی حل کرد.

چرا ماژول‌های Go دانلود نمی‌شوند

از نسخه Go 1.13، سیستم ماژول به طور پیش‌فرض به پروکسی عمومی proxy.golang.org و سرور بررسی هش sum.golang.org مراجعه می‌کند. اگر هر دو سرویس در سطح شبکه مسدود شده باشند (این وضعیت معمولاً در روسیه، چین و بخش‌های شرکتی با محدودیت‌ها دیده می‌شود)، فرمان go build یا go mod tidy به تایم‌اوت می‌رسد و سپس خطا را نشان می‌دهد:

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

سه سناریوی معمول وجود دارد که باعث می‌شود دانلود ماژول‌ها شکست بخورد:

  • مسدودیت شبکه — ارائه‌دهنده یا فایروال شرکتی دسترسی به زیرساخت‌های Google که proxy.golang.org و sum.golang.org را نگه می‌دارد، قطع می‌کند.
  • مخازن خصوصی — ماژول در GitLab/Bitbucket داخلی قرار دارد و GOPROXY عمومی به طور فیزیکی نمی‌تواند به آن دسترسی پیدا کند و در عین حال سعی می‌کند هش آن را در sum.golang.org بررسی کند، در حالی که نباید این کار را انجام دهد.
  • سرور پروکسی در شبکه بدون تنظیم متغیرهای محیطی — ترافیک به بیرون فقط از طریق پروکسی HTTP/SOCKS5 می‌رود، اما Go از این موضوع بی‌خبر است زیرا go get از کلاینت استاندارد net/http استفاده می‌کند که متغیرهای محیطی را می‌خواند، نه تنظیمات سیستم پروکسی از مرورگر.

در ادامه هر مورد را با فرمان‌ها و فایل‌های پیکربندی مشخص بررسی خواهیم کرد.

GOPROXY چیست و چگونه کار می‌کند

GOPROXY یک متغیر محیطی است که به ابزار Go می‌گوید از کجا ماژول‌ها را دانلود کند. به طور پیش‌فرض (از Go 1.14 به بعد) مقدار آن:

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

مقدار با کاما جدا شده — لیستی از منابع است که Go به ترتیب آن‌ها را بررسی می‌کند. direct به معنای «به طور مستقیم از VCS (git، svn، hg) دانلود کن، اگر پروکسی 404 یا 410 را برگرداند». اگر پروکسی به طور فیزیکی در دسترس نباشد (تایم‌اوت، نه 404)، Go به منبع بعدی نمی‌رود — فقط متوقف می‌شود یا به تایم‌اوت می‌رسد. این نکته کلیدی است که بسیاری از افراد متوجه آن نمی‌شوند: مکانیزم fallback فقط برای «ماژول پیدا نشد» کار می‌کند، نه برای «شبکه در دسترس نیست».

علاوه بر proxy.golang.org، آینه‌های عمومی وجود دارند که می‌توان از آن‌ها به عنوان جایگزین استفاده کرد:

سرور GOPROXY URL ویژگی
Google رسمی proxy.golang.org معمولاً در شبکه‌های بسته مسدود است
goproxy.cn goproxy.cn آینه‌ای از جامعه چینی، به طور پایدار در دسترس است
Astra (goproxy.io) goproxy.io آینه جهانی جایگزین
Athens (self-hosted) سرور خود کنترل کامل، مناسب برای کش ماژول‌های شرکتی

تنظیم GOPROXY: پیکربندی‌های عملیاتی

متغیرهای محیطی Go را می‌توان به طور موقت (برای یک جلسه) یا دائمی از طریق go env -w تنظیم کرد، که مقادیر را در فایل پیکربندی Go ذخیره می‌کند (معمولاً ~/.config/go/env در Linux/macOS و %APPDATA%\go\env در Windows).

تنظیم دائمی (توصیه شده):

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

برای بررسی مقدار فعلی:

go env GOPROXY

اگر به چندین آینه با پشتیبانی نیاز دارید:

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

نکته مهم: اگر پروکسی اول در لیست به تایم‌اوت پاسخ دهد و نه خطای HTTP، انتقال به منبع بعدی ممکن است تا یک دقیقه برای هر ماژول طول بکشد — این سرعت ساخت را در CI کاهش می‌دهد. بنابراین اگر شبکه به طور فیزیکی به پروکسی اول دسترسی ندارد، بهتر است آن را از لیست حذف کنید یا دسترسی شبکه را از طریق سرور پروکسی تنظیم کنید (به بخش زیر مراجعه کنید)، نه اینکه به fallback تکیه کنید.

اگر می‌خواهید به طور کامل دسترسی به پروکسی‌های خارجی را غیرفعال کنید و فقط از کش محلی یا به طور مستقیم از VCS کار کنید:

go env -w GOPROXY=direct

GOPRIVATE، GONOSUMCHECK و GOSUMDB

وقتی ماژول در یک مخزن Git داخلی (GitLab شرکتی، Bitbucket Server، Gitea خود میزبانی) قرار دارد، Go به طور پیش‌فرض سعی می‌کند آن را از طریق GOPROXY عمومی بررسی کند و هش را از طریق GOSUMDB مقایسه کند — که این ممکن نیست زیرا کد خصوصی به بیرون منتشر نمی‌شود. نتیجه — خطای 410 Gone یا verifying module: checksum mismatch.

راه‌حل — متغیر GOPRIVATE است که به Go می‌گوید: «این مسیرهای ماژول خصوصی هستند، به پروکسی عمومی نرو و هش را بررسی نکن».

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

GOPRIVATE به طور خودکار دو پرچم را همزمان تنظیم می‌کند: GONOSUMCHECK (بررسی هش از طریق GOSUMDB را غیرفعال می‌کند) و GOPROXY=direct برای مسیرهای مشخص شده. اما اگر نیاز به تنظیم دقیق‌تری دارید، می‌توانید آن‌ها را به طور جداگانه تنظیم کنید:

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

برای مخازن خصوصی در GitHub، به طور اضافی باید git را برای استفاده از توکن به جای SSH هنگام کلون کردن از طریق HTTPS تنظیم کنید، زیرا ابزار Go از git در پس‌زمینه استفاده می‌کند:

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

این فرمان تمام درخواست‌های HTTPS به github.com را با درخواست توکن در URL جایگزین می‌کند، که به کلاینت Go اجازه می‌دهد ماژول‌های خصوصی را بدون وارد کردن نام کاربری/گذرواژه به صورت تعاملی دانلود کند.

پروکسی HTTP/HTTPS برای go get

اگر دفتر یا سرور در پشت پروکسی HTTP شرکتی (به عنوان مثال، Squid) قرار داشته باشد، Go به طور خودکار از این موضوع مطلع نمی‌شود — او فقط متغیرهای محیطی HTTP_PROXY، HTTPS_PROXY و NO_PROXY را می‌خواند، که برای کلاینت 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

برای اینکه هر بار این موارد را وارد نکنید، خطوط را به ~/.bashrc، ~/.zshrc یا ~/.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"

برای ذخیره دائمی در Windows از setx استفاده کنید:

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

مهم است: NO_PROXY باید شامل دامنه‌های داخلی (GitLab داخلی، سرور Athens محلی) باشد، در غیر این صورت درخواست‌ها به آن‌ها نیز از طریق پروکسی خارجی خواهد رفت و با خطای دسترسی سقوط می‌کند.

اگر GOPROXY عمومی به دلیل فایروال داخلی در دسترس نیست، بلکه به دلیل مسدودیت جغرافیایی در یک منطقه خاص — وضعیتی که تیم‌ها با آن مواجه هستند که سرورهایشان در کشورهای مختلف قرار دارند — به جای پروکسی HTTP شرکتی می‌توان یک تونل خروجی از طریق سرور پروکسی خارجی با موقعیت جغرافیایی مورد نیاز راه‌اندازی کرد. برای چنین سناریوهایی، پروکسی‌های دیتا سنتر مناسب هستند — آن‌ها یک کانال سریع و پایدار و تأخیر پیش‌بینی‌پذیر را فراهم می‌کنند که در زمان بارگذاری انبوه وابستگی‌ها در CI حیاتی است.

پروکسی SOCKS5 و دور زدن مسدودیت‌ها

متغیرهای HTTP_PROXY/HTTPS_PROXY نه تنها پروکسی‌های HTTP(S) را پشتیبانی می‌کنند، بلکه SOCKS5 را نیز پشتیبانی می‌کنند — از Go 1.10+ به بعد، کتابخانه استاندارد می‌تواند از طریق طرح 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

متغیر ALL_PROXY یک متغیر عمومی است که بسیاری از ابزارهای CLI، نه تنها Go، آن را می‌خوانند. اگر شما قبلاً یک تونل SOCKS5 دارید (به عنوان مثال، از طریق SSH: ssh -D 1080 user@remote-host)، می‌توانید تمام ترافیک go get را بدون تنظیمات اضافی بر روی سرور از طریق آن عبور دهید.

برای آزمایش ساخت از مناطق مختلف (به عنوان مثال، برای بررسی اینکه CI چگونه در برابر درخواست به آینه منطقه‌ای بسته‌ها رفتار می‌کند یا چگونه سرویس خارجی به درخواست‌ها از یک کشور خاص پاسخ می‌دهد) اغلب به یک کانال با آدرس IP واقعی نیاز است که شبیه به یک کاربر عادی باشد، نه یک دیتا سنتر. در چنین مواردی، پروکسی‌های مسکونی انتخاب می‌شوند — آن‌ها کمتر تحت محدودیت‌های خودکار از طرف سرورهای توزیع ماژول‌ها یا مخازن خصوصی قرار می‌گیرند.

برای بررسی اینکه آیا پروکسی واقعاً توسط Go استفاده می‌شود، می‌توان با یک فرمان ساده و خروجی دقیق این کار را انجام داد:

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

پرچم -x هر فرمانی که اجرا می‌شود را چاپ می‌کند، از جمله درخواست‌های شبکه، که کمک می‌کند تا بفهمید آیا go get از طریق پروکسی می‌رود یا متغیرهای محیطی را نادیده می‌گیرد (این اتفاق می‌افتد اگر متغیرها در یک جلسه ترمینال دیگر صادر شده باشند یا به زیر فرایند منتقل نشده باشند).

پروکسی در CI/CD و Docker

در رنجرهای CI (GitHub Actions، GitLab CI، Jenkins) متغیرهای محیطی باید به طور صریح از طریق تنظیمات job منتقل شوند، نه اینکه به .bashrc محلی تکیه کنید که در کانتینر خوانده نمی‌شود.

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 (ساخت چند مرحله‌ای):

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 .

آرگومان‌های ساخت هنگام فراخوانی 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 .

اگر ساخت به طور موازی در چندین رنجر انجام شود و نیاز به جلوگیری از مسدودیت IP از طرف آینه ماژول‌ها به دلیل تعداد زیادی درخواست همزمان (این اتفاق با پروکسی Athens خود میزبانی تحت بار بالا می‌افتد)، مفید است که درخواست‌های خروجی را از طریق چرخش IP تقسیم کنید. برای توزیع یکنواخت بار و جلوگیری از محدودیت نرخ از طرف سرور پروکسی آینه ماژول‌ها، معمولاً از پروکسی‌های دیتا سنتر استفاده می‌شود — آن‌ها تأخیر پایینی را فراهم می‌کنند که برای CI مهم است، جایی که هر ثانیه اضافی در تعداد job‌ها ضرب می‌شود.

خطاهای رایج و راه‌حل‌های آن‌ها

خطا دلیل راه‌حل
dial tcp: i/o timeout proxy.golang.org از شبکه در دسترس نیست GOPROXY را به آینه تغییر دهید یا HTTP_PROXY را تنظیم کنید
410 Gone ماژول خصوصی برای پروکسی عمومی در دسترس نیست GOPRIVATE را برای مسیر ماژول مورد نظر تنظیم کنید
checksum mismatch GOSUMDB سعی در بررسی ماژول خصوصی دارد از طریق GONOSUMDB یا GOSUMDB=off غیرفعال کنید
x509: certificate signed by unknown authority پروکسی شرکتی گواهی TLS را تغییر می‌دهد (MITM) گواهی ریشه شرکت را به مخزن سیستم اضافه کنید
repository not found هیچ توکن دسترسی برای مخزن git خصوصی وجود ندارد تنظیم git config url.insteadOf با توکن
متغیرهای پروکسی نادیده گرفته می‌شوند صادر کردن در یک شل/جلسه دیگر انجام شده است از طریق env | grep PROXY در همان جلسه‌ای که go اجرا می‌شود، بررسی کنید

به طور جداگانه باید در مورد پروکسی MITM (Squid/Zscaler شرکتی با تغییر گواهی‌ها) صحبت کرد: اگر چنین پروکسی ترافیک HTTPS را برای تجزیه و تحلیل متوقف کند، کلاینت Go به گواهی خودامضا شده آن اعتماد نمی‌کند و این منجر به خطای x509 می‌شود. راه‌حل — صادر کردن گواهی ریشه شرکت به فرمت PEM و نوشتن آن در متغیر:

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

این متغیر توسط زمان اجرای Go هنگام بررسی زنجیره TLS خوانده می‌شود و به کار کردن از طریق پروکسی MITM شرکتی بدون غیرفعال کردن کامل بررسی گواهی‌ها اجازه می‌دهد (که از نظر امنیتی کار درستی نیست).

نتیجه‌گیری

اگر ماژول‌های Go دانلود نمی‌شوند، در 90% موارد کافی است سه مرحله انجام شود: تنظیم یک GOPROXY عملیاتی (آینه عمومی به جای proxy.golang.org مسدود شده)، افزودن GOPRIVATE برای مخازن داخلی و نوشتن HTTP_PROXY/HTTPS_PROXY، اگر شبکه فقط از طریق پروکسی شرکتی به بیرون می‌رود. برای CI/CD، این متغیرها باید به طور صریح از طریق متغیرهای محیطی job یا آرگومان‌های ساخت Docker منتقل شوند و نباید به پیکربندی‌های محلی توسعه‌دهنده تکیه کرد.

اگر دلیل شکست‌ها مسدودیت جغرافیایی آینه ماژول‌ها یا محدودیت نرخ از طرف سرور پروکسی در هنگام ساخت موازی در CI باشد، بهتر است ترافیک خروجی را از طریق یک کانال پایدار خارجی عبور دهید. برای چنین کارهایی، پروکسی‌های دیتا سنتر بسیار مناسب هستند — تأخیر پایین و ظرفیت پیش‌بینی‌پذیر در زمان بارگذاری انبوه وابستگی‌ها حیاتی است. و اگر نیاز به شبیه‌سازی ترافیک کاربر عادی در هنگام آزمایش دسترسی به سرویس‌های خارجی از مناطق مختلف دارید، پروکسی‌های مسکونی مناسب هستند — آن‌ها کمتر تحت نظارت سیستم‌های حفاظت از طرف سرورهای توزیع بسته‌ها قرار می‌گیرند.