Jika Anda mencoba mengunduh model melalui ollama pull
dari jaringan perusahaan, melalui VPN atau melalui server proxy eksternal, Anda pasti sudah mengalami kesalahan seperti
dial tcp: lookup registry.ollama.ai atau
context deadline exceeded.
Ollama secara default tidak selalu menangkap pengaturan proxy sistem dengan benar, dan ukuran model yang besar (dari 2 hingga 70+ GB) memperburuk masalah —
koneksi terputus di tengah pengunduhan. Dalam artikel ini, kita akan membahas cara yang benar untuk menetapkan variabel lingkungan, mengatur proxy di Docker dan systemd,
serta menganalisis kesalahan pull yang paling umum dan cara mengatasinya.
Bagaimana Ollama bekerja dengan jaringan dan proxy
Ollama adalah aplikasi klien-server: server lokal (ollama serve)
menerima perintah dari CLI dan melakukan permintaan jaringan ke registri model registry.ollama.ai dan ke CDN, di mana lapisan (layers) model disimpan.
Perintah ollama pull llama3 sebenarnya melakukan serangkaian permintaan HTTPS,
mirip dengan Docker pull: pertama, manifest model diminta, kemudian lapisan biner (file GGUF bobot) diunduh secara berurutan atau paralel.
Nuansa penting: permintaan jaringan dilakukan oleh proses server Ollama, bukan perintah CLI. Ini berarti bahwa variabel lingkungan
dengan pengaturan proxy harus ditetapkan di tempat proses ollama serve
dijalankan, bukan di terminal tempat Anda memanggil ollama pull.
Jika layanan dijalankan sebagai unit systemd atau dalam kontainer Docker, ekspor variabel dalam sesi bash biasa tidak akan mempengaruhi —
ini adalah alasan paling umum mengapa "proxy tampaknya sudah diatur, tetapi pull tetap tidak berfungsi".
Variabel lingkungan HTTP_PROXY, HTTPS_PROXY, NO_PROXY
Ollama ditulis dalam Go, dan pustaka HTTP standar Go membaca pengaturan proxy dari variabel lingkungan klasik:
HTTP_PROXY— proxy untuk permintaan HTTP biasaHTTPS_PROXY— proxy untuk permintaan HTTPS (ini yang diperlukan untuk mengunduh model, karena registri berfungsi melalui TLS)NO_PROXY— daftar host yang harus dikecualikan dari pemrosesan proxy (misalnya, API lokal Ollama di 127.0.0.1:11434)
Format nilai: http://user:password@host:port untuk proxy dengan otorisasi
atau socks5://host:port untuk SOCKS5. Go mendukung kedua opsi,
tetapi untuk SOCKS5 penting agar biner Ollama dibangun dengan dukungan untuk proxy ini — dalam sebagian besar build terkini ini berlaku, tetapi jika ada kesalahan, sebaiknya
uji terlebih dahulu dengan proxy HTTP/HTTPS untuk mengecualikan variabel ini.
Penting: tentukan variabel dalam huruf kecil dan huruf besar
(http_proxy dan HTTP_PROXY).
Beberapa distribusi Linux hanya membaca huruf kecil, sementara aplikasi Go kadang-kadang mengharapkan huruf besar — lebih baik menetapkan kedua opsi untuk menghindari kebingungan.
Pengaturan di Linux dan macOS
Jika Anda menjalankan Ollama langsung dari terminal (tidak sebagai layanan sistem), cukup ekspor variabel sebelum menjalankan server:
export HTTP_PROXY="http://user:[email protected]:8000"
export HTTPS_PROXY="http://user:[email protected]:8000"
export http_proxy="http://user:[email protected]:8000"
export https_proxy="http://user:[email protected]:8000"
export NO_PROXY="localhost,127.0.0.1"
ollama serve &
ollama pull llama3
Agar pengaturan disimpan antara sesi, tambahkan baris ini ke ~/.bashrc,
~/.zshrc atau ~/.profile
tergantung pada shell yang digunakan. Setelah mengedit, jalankan source ~/.bashrc
dan restart proses Ollama — variabel lingkungan hanya dibaca saat proses dimulai, tidak ada hot reload yang disediakan.
Di macOS, jika Ollama diinstal sebagai aplikasi (bukan melalui Homebrew), variabel lingkungan dari terminal mungkin tidak sampai ke proses,
yang dijalankan melalui GUI. Dalam hal ini, lebih andal untuk menetapkan variabel melalui launchctl setenv:
launchctl setenv HTTPS_PROXY "http://user:[email protected]:8000"
launchctl setenv HTTP_PROXY "http://user:[email protected]:8000"
# Setelah itu, restart aplikasi Ollama sepenuhnya (keluar dari tray, bukan hanya menutup jendela)
Pengaturan di Windows
Di PowerShell, variabel ditetapkan untuk sesi saat ini dengan perintah:
$env:HTTP_PROXY="http://user:[email protected]:8000"
$env:HTTPS_PROXY="http://user:[email protected]:8000"
$env:NO_PROXY="localhost,127.0.0.1"
ollama pull mistral
Jika Ollama dijalankan sebagai layanan latar belakang (ikon di tray sistem), variabel sesi tidak cukup — layanan dimulai saat login
sebelum Anda membuka PowerShell. Anda perlu menetapkan variabel di tingkat pengguna atau sistem melalui
"Pengaturan → Sistem → Tentang → Pengaturan tambahan sistem → Variabel lingkungan", setelah itu sepenuhnya akhiri proses
ollama.exe melalui Task Manager dan restart aplikasi.
Proxy untuk Ollama di Docker
Jika Ollama dijalankan dalam kontainer (kasus umum untuk penyebaran server), variabel lingkungan host tidak otomatis masuk ke dalam kontainer —
mereka perlu diteruskan secara eksplisit melalui -e atau bagian environment
di docker-compose:
docker run -d \
-e HTTP_PROXY="http://user:[email protected]:8000" \
-e HTTPS_PROXY="http://user:[email protected]:8000" \
-e NO_PROXY="localhost,127.0.0.1" \
-v ollama:/root/.ollama \
-p 11434:11434 \
--name ollama ollama/ollama
Begitu juga dalam docker-compose.yml:
version: "3.8"
services:
ollama:
image: ollama/ollama
environment:
- HTTP_PROXY=http://user:[email protected]:8000
- HTTPS_PROXY=http://user:[email protected]:8000
- NO_PROXY=localhost,127.0.0.1
volumes:
- ollama:/root/.ollama
ports:
- "11434:11434"
volumes:
ollama:
Setelah mengubah variabel, kontainer perlu dibuat ulang (docker compose up -d --force-recreate),
restart sederhana tidak cukup, karena variabel lingkungan ditetapkan saat kontainer dibuat.
Proxy untuk layanan systemd Ollama
Di server Linux, Ollama sering diinstal sebagai layanan systemd melalui skrip instalasi resmi. Dalam hal ini, variabel lingkungan
ditetapkan melalui file override, bukan melalui export di terminal:
sudo systemctl edit ollama.service
Di editor yang terbuka, tambahkan:
[Service]
Environment="HTTP_PROXY=http://user:[email protected]:8000"
Environment="HTTPS_PROXY=http://user:[email protected]:8000"
Environment="NO_PROXY=localhost,127.0.0.1"
Kemudian terapkan perubahan:
sudo systemctl daemon-reload
sudo systemctl restart ollama
systemctl show ollama --property Environment
Perintah terakhir akan menunjukkan variabel apa yang benar-benar dilihat oleh proses — cara yang nyaman untuk memastikan bahwa konfigurasi diterapkan, sebelum mencoba lagi untuk melakukan pull.
Analisis kesalahan pull dan solusinya
Mari kita analisis pesan kesalahan yang paling umum saat mengunduh model melalui proxy dan apa yang harus dilakukan dengan mereka.
dial tcp: lookup registry.ollama.ai: no such host
DNS-resolving tidak berfungsi melalui proxy — biasanya ini berarti bahwa permintaan mencoba untuk pergi langsung, melewati server proxy, atau tidak ada akses
ke DNS di mesin (jaringan perusahaan tertutup). Solusi: pastikan bahwa HTTPS_PROXY
benar-benar ditangkap oleh proses (lihat perintah systemctl show di atas),
dan bahwa server proxy itu sendiri mampu meresolusi domain eksternal (proxy SOCKS5 meresolusi DNS di sisi mereka, proxy HTTP juga, tetapi beberapa proxy lokal tidak melakukannya).
proxyconnect tcp: dial tcp: connection refused
Ollama mencoba terhubung ke proxy, tetapi ditolak. Periksa port dan host untuk kesalahan ketik, pastikan bahwa server proxy benar-benar mendengarkan port yang ditentukan dari luar (bukan hanya di localhost), dan bahwa firewall tidak memblokir koneksi keluar ke port proxy.
407 Proxy Authentication Required
Proxy memerlukan login dan kata sandi, tetapi mereka tidak diberikan atau diberikan dengan salah. Pastikan bahwa di variabel lingkungan login dan kata sandi disematkan dalam URL
dalam format http://user:password@host:port, dan karakter khusus dalam kata sandi
(misalnya, @ atau :)
dikodekan melalui URL-encoding (%40, %3A).
x509: certificate signed by unknown authority
Ini adalah tanda proxy perusahaan dengan inspeksi TLS (MITM), yang mengganti sertifikat SSL dengan sertifikat root mereka. Klien Go Ollama tidak mempercayai
sertifikat ini. Solusi — tambahkan sertifikat root perusahaan ke penyimpanan sistem pusat sertifikasi yang tepercaya
(di Linux biasanya melalui update-ca-certificates setelah menyalin file .crt ke
/usr/local/share/ca-certificates/). Menonaktifkan pemeriksaan sertifikat secara global tidak disarankan — ini membuka jalan untuk penyadapan lalu lintas.
context deadline exceeded / i/o timeout saat mengunduh layer
Koneksi terputus di tengah pengunduhan layer besar model (seringkali ini adalah file 4-40 GB). Kesalahan semacam ini hampir selalu menunjukkan ketidakstabilan atau bandwidth rendah dari server proxy, bukan dari Ollama itu sendiri. Proxy publik gratis atau yang terlalu banyak beban memutus sesi TCP yang lama, terutama jika pengunduhan memakan waktu lebih dari beberapa menit. Dalam kasus seperti itu, beralih ke saluran yang lebih stabil membantu — misalnya, proxy data center, yang menyediakan kecepatan tinggi dan koneksi stabil untuk mengunduh file besar tanpa terputus.
Jenis proxy apa yang harus dipilih untuk Ollama
Pemilihan jenis proxy tergantung pada alasan mengapa Anda memerlukan proxy untuk Ollama. Jika tujuannya hanya untuk menghindari batasan firewall perusahaan di dalam jaringan Anda sendiri, hampir semua proxy HTTP(S) yang stabil akan cocok. Namun, jika tujuannya adalah untuk menghindari geo-blocking registri model atau menyembunyikan bahwa permintaan berasal dari data center (beberapa CDN membatasi kecepatan untuk rentang IP penyedia cloud yang dikenal), pemilihan jenis proxy menjadi sangat penting.
| Jenis Proxy | Kecepatan | Kapan digunakan untuk Ollama |
|---|---|---|
| Data Center | Tinggi | Mengunduh layer besar model (4-40+ GB) tanpa terputus, pengujian dari berbagai lokasi DC |
| Residential | Sedang | Menghindari geo-restriction registri, ketika IP data center terkena regional rate-limit |
| Mobile | Bervariasi | Kasus ekstrem ketika ada pemblokiran total berdasarkan rentang IP penyedia, kurang efektif untuk pengunduhan besar karena fluktuasi kecepatan |
Untuk sebagian besar skenario dengan Ollama — ketika Anda hanya perlu mengunduh model seberat puluhan gigabyte dengan stabil — pilihan optimal tetap proxy data center: mereka memberikan bandwidth maksimum dan latensi minimum, yang sangat penting saat mengunduh layer biner besar. IP residential sebaiknya hanya digunakan jika alamat data center benar-benar terkena batasan di sisi registri model.
Diagnostik koneksi
Sebelum menghabiskan waktu untuk debug Ollama itu sendiri, periksa proxy secara langsung melalui curl — ini akan mengecualikan kebingungan antara masalah di aplikasi dan masalah di server proxy itu sendiri:
# Memeriksa ketersediaan registri melalui proxy
curl -v -x http://user:[email protected]:8000 https://registry.ollama.ai/v2/
# Mengukur kecepatan pengunduhan melalui proxy
curl -x http://user:[email protected]:8000 -o /dev/null -w "%{speed_download}\n" https://registry.ollama.ai/v2/
# Menjalankan ollama serve dengan log detail
OLLAMA_DEBUG=1 ollama serve
Jika curl berhasil mendapatkan respons, tetapi ollama pull tetap gagal —
masalah hampir pasti karena variabel lingkungan tidak sampai ke proses server (layanan dijalankan dengan pengguna yang berbeda, dari shell yang berbeda
atau sebagai unit systemd tanpa override). Kembali ke bagian tentang systemd dan periksa output systemctl show ollama --property Environment.
Namun, jika curl juga terputus saat mengunduh file besar atau menunjukkan kecepatan yang tidak stabil — penyebabnya ada di server proxy, dan Anda harus mempertimbangkan untuk mengganti penyedia proxy dengan opsi yang lebih stabil, yang dirancang untuk mentransfer volume data besar.
Kesimpulan
Pengaturan Ollama melalui proxy berfokus pada tiga poin kunci: variabel lingkungan harus ditetapkan khusus untuk proses
ollama serve, bukan untuk terminal tempat Anda memanggil pull;
format URL proxy harus mencakup login dan kata sandi yang dikodekan dengan benar; dan saat terjadi kesalahan sertifikat, Anda perlu menambahkan sertifikat root perusahaan
ke penyimpanan tepercaya, bukan menonaktifkan pemeriksaan TLS. Sebagian besar kesalahan pull bukanlah bug dari Ollama itu sendiri,
tetapi akibat dari pengaturan jaringan yang tidak diterapkan pada proses yang tepat atau server proxy tidak mampu menangani transfer file besar yang berkepanjangan.
Jika tugas utama Anda adalah mengunduh model seberat puluhan gigabyte dengan stabil dan cepat tanpa terputus, kami merekomendasikan untuk mencoba proxy data center — mereka memberikan bandwidth tinggi, yang diperlukan untuk mengunduh layer besar model. Dan jika alasan penggunaan proxy adalah untuk menghindari geo-restriction registri model, perhatikan proxy residential, yang jarang terkena batasan regional yang diterapkan pada rentang IP penyedia cloud.