← Kembali ke blog

Ollama melalui proxy: cara mengatur HTTP_PROXY dan memperbaiki kesalahan menarik model

Analisis mendetail tentang pengaturan Ollama melalui server proxy - dari variabel lingkungan hingga diagnosis kesalahan saat menarik model dan pemilihan jenis proxy yang sesuai.

📅16 November 2026

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 biasa
  • HTTPS_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.