الأمر 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 لا ينتقل إلى المصدر التالي - بل يبقى معلقًا أو يسقط بسبب انتهاء المهلة. هذه نقطة رئيسية لا يفهمها الكثيرون: آلية التراجع تعمل فقط لـ "الوحدة غير موجودة"، وليس لـ "الشبكة غير متاحة".
بالإضافة إلى proxy.golang.org، هناك مرايا عامة يمكن استخدامها كبدائل:
| خادم GOPROXY | URL | ميزة |
|---|---|---|
| Google الرسمي | proxy.golang.org | غالبًا ما يتم حظره في الشبكات المغلقة |
| goproxy.cn | goproxy.cn | مرآة من المجتمع الصيني، متاحة بشكل مستقر |
| Astra (goproxy.io) | goproxy.io | مرآة عالمية بديلة |
| Athens (مستضاف ذاتيًا) | خادم خاص | تحكم كامل، مناسب للتخزين المؤسسي لوحدات التخزين |
إعداد 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. لذلك، إذا كانت الشبكة لا تصل فعليًا إلى الوكيل الأول، فمن الأفضل إزالته من القائمة على الفور أو إعداد الوصول الشبكي عبر خادم الوكيل (انظر القسم أدناه)، بدلاً من الاعتماد على التراجع.
إذا كنت ترغب في تعطيل الوصول إلى الوكلاء الخارجيين تمامًا والعمل فقط من التخزين المحلي أو مباشرة من 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)، يجب تمرير المتغيرات البيئية بوضوح عبر إعدادات الوظيفة، وعدم الاعتماد على .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، حيث يتم مضاعفة كل ثانية إضافية بعدد الوظائف.
الأخطاء الشائعة وحلولها
| الخطأ | السبب | الحل |
|---|---|---|
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، يجب تمرير هذه المتغيرات بوضوح عبر متغيرات البيئة للوظيفة أو وسائط البناء لـ Docker، وعدم الاعتماد على تكوينات المطور المحلية.
إذا كان سبب الفشل هو الحظر الجغرافي لمرآة الوحدات أو الحد من المعدل من جانب خادم الوكيل أثناء البناء المتوازي في CI، فمن الأفضل توجيه حركة المرور الصادرة عبر قناة خارجية مستقرة. لمثل هذه المهام، تعتبر وكلاء مراكز البيانات مناسبة - زمن الانتقال المنخفض وسعة المرور المتوقعة أمران حاسمان عند تحميل الاعتماديات بكميات كبيرة. وإذا كنت بحاجة إلى محاكاة حركة مرور المستخدم العادية عند اختبار توفر الخدمات الخارجية من مناطق مختلفة، فإن الوكلاء السكنيين هي الخيار المناسب - فهي نادرًا ما تثير الشكوك لدى أنظمة الحماية على جانب خوادم توزيع الحزم.