Yayına almak28 dk okuma
Deployment
Binary'yi build edin, bir container'da ya da systemd altında çalıştırın, production'ın ihtiyaç duyduklarını ayarlayın ve TLS'in arkasına koyun.
Bir collage sitesi bir Go programıdır. Bu yüzden deploy ettiğiniz şey derlenmiş bir binary'dir. Template'ler ve static dosyalar binary'nin içine gömülüdür. Binary, yanına hiçbir şey kopyalamadan herhangi bir dizinden çalışır. Tek istisna, plugin'leri yapılandırıyorsanız plugins-config.json dosyasıdır; aşağıya bakın.
Bu sayfa o binary'yi bir sunucuda çalıştırmayı anlatır. Hiç sunucusu olmayan bir site için Static export sayfasına bakın.
Host'u ve X-Forwarded-For ile X-Forwarded-Proto header'larıyla iletir; binary'nin bunlara inanıp inanmayacağına Server.TrustedProxies karar verir. Binary HOST:PORT'u dinler; ikisi de ayarlı değilse bu localhost:6060'dır. collage build -i'ın yazdığı image dosyası, 0.0.0.0:8080'i ayarlar; servis unit'i ise 127.0.0.1:8080'i. İhtiyaç duyduğu diğer her şey binary'nin içindedir. Dışında kalanlar yalnızca ortamı, bir de çalışma dizinine göre konumlanan page cache ile plugins-config.json'dır.Build: collage build
collage build
./bin/mysite
collage build, normalde aklınızda tutmanız gereken go build komutunu sizin yerinize çalıştırır:
CGO_ENABLED=0 GOOS=<os> GOARCH=<arch> go build -trimpath -ldflags="-s -w" -o bin/mysite .
- CGO kapalıdır, çünkü ne collage ne de standart kütüphane C'ye ihtiyaç duyar. Static bir binary, içinde başka hiçbir şey olmayan bir image'a konabilir.
-trimpathsayesinde binary, kendisini build eden makinenin path'lerini taşımaz.-s -wdebug tablolarını atar. Boyutun büyük kısmı bu tablolardır.- Varsayılan hedef bu makinedir. Mac için build edilmiş bir binary Linux container'ında çalışmaz. O yüzden sunucu için hedefi belirtin:
collage build -os linux -arch amd64.
| Flag | Varsayılan | Anlamı |
|---|---|---|
-o path | bin/<module name> | Binary'nin yazılacağı yer. |
-os name | bu makineninki | Hedef işletim sistemi. Çoğu sunucu için linux. |
-arch name | bu makineninki | Hedef mimari: amd64, Graviton ya da Ampere makineler için arm64. |
-i | kapalı | Binary'nin yanına bir Dockerfile ve bir systemd unit'i yazmayı önerir. |
Binary dist/'e değil, bin/'e yazılır. dist/ dizini collage export'a aittir ve export'un -clean seçeneği orada duran bir binary'yi silerdi.
collage start diye bir komut yoktur. Derlenmiş bir binary'yi çalıştırmak için hiçbir şeyi aklınızda tutmanız gerekmez. Bir start komutu olsaydı yapabileceği tek şey go run . çalıştırmak olurdu. Bu da Go toolchain'ini production image'ınıza koyar ve her açılışta yeniden derleme yapar.
Go 1.26.11 ya da sonrasıyla build edin. Bir binary, build edildiği standart kütüphaneyi içinde taşır. Go 1.26.11 (ya da 1.27.4), http.MaxBytesReader'daki, bir HTTP/1 sunucusunu çökertebilen ve collage'ın body limitinin üzerine kurulu olduğu bir race'i düzeltir (GO-2026-6859). go.mod ve scaffold 1.26.11 ister; böylece varsayılan GOTOOLCHAIN=auto ile go komutu, kurulu Go'nun daha eski olduğu yerde onu indirir. Bir build image'ı GOTOOLCHAIN=local ayarlar ve sürümü kendisi taşımalıdır: aşağıdaki Dockerfile'ın kullandığı golang:1.26 tag'i en son patch release'i izler. Bir binary'yi go version -m ile kontrol edin.
collage build -i: bir Dockerfile ve bir systemd unit'i
-i verildiğinde collage build, binary'nin yanına bir Dockerfile ve bir systemd unit'i yazıp yazmayacağını sorar:
$ collage build -i -os linux -arch amd64
Building mysite for linux/amd64.
Write a Dockerfile? [y/N]: y
Write a systemd unit? [y/N]: y
✓ bin/mysite
linux/amd64 · 9.3 MB
wrote bin/Dockerfile docker build -f bin/Dockerfile .
wrote bin/mysite.service
9.3 MB · linux/amd64 · 4.1s
Bu dosyalar üretildikleri için bin/'e yazılır. Proje kökü sizin yazdığınız dosyalar içindir. Var olan bir dosyanın üzerine asla yazılmaz, çünkü bunlar düzenlemeniz beklenen dosyalardır. Scaffold edilen bir projenin .gitignore'u yalnızca binary'yi yok sayar. Bu dosyaları da diğer dosyalar gibi commit edersiniz.
Dockerfile iki stage'den oluşur. Önce Go image'ında build eder, sonra distroless bir base image üzerinde yalnızca binary'yi taşır (üretilen dosyadaki yorumlar burada yoktur ve plugins-config.json satırı yalnızca bu dosyası olan projeler için yazılır):
# Built by "collage build -i".
FROM golang:1.26 AS build
WORKDIR /src
COPY go.mod go.sum* ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /mysite .
FROM gcr.io/distroless/static-debian12
WORKDIR /srv
COPY --from=build /mysite /usr/local/bin/mysite
COPY --from=build /src/plugins-config.json /srv/plugins-config.json
ENV HOST=0.0.0.0 PORT=8080
# Set this to at least 32 random bytes, kept with your other secrets. Without
# it a key is generated per process, and every form submitted before a restart
# is refused after it.
# ENV COLLAGE_CSRF_KEY=
EXPOSE 8080
ENTRYPOINT ["/usr/local/bin/mysite"]
Image'ı proje kökünden docker build -f bin/Dockerfile . ile build edin. Template'ler ya da static dosyalar için bir COPY satırı yoktur, çünkü onlar binary'nin içindedir. Son stage binary'yi ve, Dockerfile yazıldığı sırada projede varsa, plugins-config.json'ı kopyalar; Plugin config'i bölümüne bakın. WORKDIR, page cache ve bu dosya için önemlidir; ayrıntıları aşağıda bulabilirsiniz. COLLAGE_CSRF_KEY'i dosyanın içinde değil, platformunuzun secret'larından ayarlayın.
systemd unit'i binary'yi /usr/local/bin'den, /srv/<name> dizininde ve aynı adı taşıyan bir kullanıcıyla çalıştırır. Binary, önüne konacak bir reverse proxy için 127.0.0.1:8080'i dinler. Unit'i /etc/systemd/system/<name>.service konumuna kurmadan önce kullanıcıyı, dizini ve path'i kendinize göre düzenleyin:
systemctl daemon-reload && systemctl enable --now mysite
Ortam değişkenleri
Scaffold edilen main.go beş değişken okur. Bunları binary nerede çalışıyorsa orada ya da çalışma dizinindeki bir .env dosyasında ayarlayın. Scaffold edilen main'in çağırdığı collage.Main, bu dosyayı newApp çalışmadan önce yükler. Sunucunun environment'ında zaten tanımlı olan değer dosyadakinden önceliklidir. Dosyanın olmaması hata değildir, hatalı bir satır ise programı dosya adı ve satır numarasıyla birlikte durdurur. COLLAGE_CSRF_KEY gibi secret'ları commit ettiğiniz bir dosyaya koymayın; .gitignore bu nedenle .env'i yok sayar.
Bir değişkeni daha main.go değil, framework'ün kendisi okur: bir development sunucusunun cevap vereceği ek host'ları adlandıran COLLAGE_DEV_HOST. Production'da ayarlamayın. Bkz. Development modu bu makinede kalır.
| Değişken | Varsayılan | Değeri |
|---|---|---|
HOST | localhost | Container'da 0.0.0.0. localhost makinenin dışından gelen hiçbir bağlantıyı kabul etmez. Bu, yerel bir reverse proxy'nin arkasında doğrudur, başka her yerde yanlıştır. |
PORT | 6060 | Platformunuz hangi port'u atıyorsa o. Binary'nin -port flag'i bu değeri ezer. |
BASE_URL | ayarlı değil | Sitenin herkese açık origin'i, https://example.com. Canonical link'in, og:url'in ya da sitemap'in bir path'in önüne koyduğu değerdir. Path içermeyen yalın bir origin olmalıdır; collage.New başka bir şeyi ErrInvalidOrigin ile reddeder. |
COLLAGE_CSRF_KEY | üretilir | En az 32 rastgele byte. Bunu mutlaka ayarlayın. |
COLLAGE_DEV | ayarlı değil | Hiçbir şey; ayarlamadan bırakın.collage dev bu değişkeni 1 yapar ve development mode'u açar. Bu modda template'ler ve static dosyalar diskten okunur, cache bellekte tutulur ama hiç okunmaz, error page'lerde hata zincirinin tamamı gösterilir. Bu değişkenle çalışan bir sunucu bir development sunucusudur. |
Key'i şu komutla üretin:
openssl rand -hex 32
Key verilmezse collage her process için bir key üretir ve açılışta uyarı verir. Bu kendi makinenizde sorun değildir. Bir sunucuda ise iki nedenle yanlıştır:
- Form'lar restart'lar ve instance'lar arasında bozulur. Deploy'dan önce render edilmiş bir form, deploy'dan sonra gönderildiğinde reddedilir. Bir instance da başka bir instance'ın verdiği token'ı reddeder. Key'i her instance'ta aynı tutun ve restart'lar arasında değiştirmeyin.
- Form içeren cache'lenmiş page'ler her açılıştan sonra yeniden render edilir. Cache'lenmiş bir page'deki forgery token placeholder'ı key'den türetilir. Bu yüzden önceki process'in key'iyle saklanmış bir page miss sayılır ve baştan render edilir. Form içermeyen page'ler bundan etkilenmez. Disk cache'inin geri kalanı her durumda restart'tan sağ çıkar. Caching sayfasına bakın.
Key'i değiştirmek güvenlidir ama bedelsiz değildir. Değişiklikten önce render edilmiş form'lar reddedilir ve form içeren cache'lenmiş page'ler birer kez yeniden render edilir.
Gömülü template'ler ve static dosyalar
Scaffold edilen bir proje ikisini de, plugin ayarlarıyla birlikte, tek bir dosya sistemi olarak embed eder:
//go:embed all:templates all:static plugins-config.json
var files embed.FS
Template'ler collage'a Template.FS olarak verilir. Static dosyalar ise env.Static(files, "static") üzerinden mount edilir. Development mode'da diskteki dizinler önceliklidir. Böylece bir template'i düzenlediğinizde değişiklik bir sonraki request'te görünür. Production'da yalnızca gömülü kopya okunur. Böylece process nerede başlatılırsa başlatılsın, çalışan şey test ettiğiniz şeydir.
Page'lerinizin runtime'da okuduğu içerikleri, örneğin Markdown dosyalarını ya da bir JSON kataloğunu, aynı şekilde gömmek size kalmıştır. collage-docs da tam bu nedenle kendi content/ dizinini gömer ve development'ta bu dizini diskten okur. Böyle bir dizini Config.DevWatch içinde belirtirseniz içindeki bir dosyayı düzenlediğinizde tarayıcı da yenilenir.
Plugin config'i
Scaffold edilen newApp, plugins-config.json dosyasını env.PluginConfig(files) ile okur. Çalışma dizininde dosya varsa onu okur, böylece bir deployment bir ayarı yeniden build etmeden değiştirebilir. Yoksa binary'nin embed ettiği kopyayı okur. Dosya olmadan deploy edilen bir binary, build edildiği andaki ayarları korur.
Daha önce scaffold edilmiş bir proje dosyayı collage.LoadPluginConfig("plugins-config.json") ile okur. Bu path binary'ye göre değil, çalışma dizinine göredir ve dosya binary'ye gömülmez. Dosyanın bulunmaması bir hata değildir. Bu durumda her plugin sessizce kendi varsayılanlarıyla çalışır. Yani dosyanın olmadığı bir yerde başlatılan sunucu, plugin ayarlarınızı hiçbir uyarı vermeden yok sayar. env.PluginConfig'e geçin ya da dosyayı process'in başladığı yere kopyalayın. collage build -i'nin yazdığı Dockerfile, yazıldığı sırada projede bu dosya varsa onu da kopyalar. Dosyayı sonradan oluşturursanız satırı kendiniz ekleyin, çünkü collage build -i var olan bir Dockerfile'ın üzerine asla yazmaz. Dosyayı process'in başladığı WORKDIR'e koyun:
WORKDIR /srv
COPY --from=build /mysite /usr/local/bin/mysite
COPY --from=build /src/plugins-config.json /srv/plugins-config.json
systemd kullanıyorsanız dosyayı unit'in WorkingDirectory'sinde tutun.
Graceful shutdown ve drain
app.ListenAndServe, SIGINT ve SIGTERM sinyallerini yakalar ve ikisinden birinde graceful shutdown yapar. app.Shutdown(ctx)'i kendiniz çağırdığınızda da aynısı olur. Sıra sabittir:
- Drain.
ListenAndServe'ünServeHookplugin'lerineOnServe'de verdiği ctx iptal edilir. Böylece bir scheduler yeni iş başlatmaz.DrainHook'u implement eden her plugin'e bir kez haber verilir. Bir health plugin'i readiness check'ini burada false'a çevirir. Keep-alive'lar kapatılır: boşta bekleyen keep-alive bağlantıları hemen, meşgul olanlar ise o anki response'larından sonra kapanır. Bu bağlantıların client'ları load balancer üzerinden yeniden bağlanır. Port açık kalır ve request'lereServer.DrainDelayboyunca normal şekilde cevap verilir. - Stream'ler. Development reload stream'leri ve plugin stream'leri kapatılır. Bunlar kendiliğinden hiç bitmez.
- Sunucu. Port kapanır. Devam eden request'lerin bitmesi için en fazla
Server.ShutdownTimeoutkadar (varsayılan 10 saniye) beklenir. - Plugin'ler. Her plugin'in
Shutdown'ı çalışır veListenAndServenildöner. Bundan önce, bir invalidation'dan sonra hâlihazırda çalışan warm render'lar beklenir (kuyrukta bekleyenler atılır). Data cache'in yenilemeleri ve disk yazımları da beklenir. Bu bekleme, 3. adımla aynı deadline'a tabidir.
DrainDelay kadar, hizmet vermeye devam eder. Bu değer varsayılan olarak 0'dır ve development modunda yok sayılır. ShutdownTimeout ancak drain bittiğinde başlar ve ondan sonraki her şeyi sınırlar, bu yüzden bir durdurma DrainDelay + ShutdownTimeout kadar sürebilir. app.Shutdown(ctx)'i kendiniz çağırdığınızda aynı adımlar çalışır ve drain dahil hepsini sizin ctx'iniz sınırlar.DrainDelay varsayılan olarak 0'dır, yani hiç beklenmez. nginx, Caddy ya da Cloudflare arkasındaki tek bir instance hemen durur. Port kapanmadan önce bir load balancer'ın instance'ın ayrıldığını fark etmesi gerekiyorsa bu değeri ayarlayın. Değer, load balancer'ın readiness check'inin başarısız olması için geçen süreden birkaç saniye uzun olmalıdır:
app, err := collage.New(&collage.Config{
Server: collage.ServerConfig{
DrainDelay: 10 * time.Second,
ShutdownTimeout: 10 * time.Second,
},
})
İki süre toplanır. Bir sinyalde ShutdownTimeout drain bittiğinde başlar. Bu yüzden bir durdurma DrainDelay + ShutdownTimeout kadar sürebilir. app.Shutdown(ctx)'i kendiniz çağırdığınızda tek bir ctx hem drain'i hem de devam eden request'lerin beklenmesini sınırlar, ShutdownTimeout ise kullanılmaz. Bu ctx'e en az DrainDelay artı request'lerinizin ihtiyaç duyduğu süre kadar bir deadline verin. Aksi halde drain, request'lere kalacak süreyi tüketir.
Bir plugin'in Shutdown'ı bu deadline'ı biraz aşabilir: elagoht/jobs, ctx'ini dinlemeyen bir job için bir saniye daha bekler. Bu yüzden onunla bir durdurma DrainDelay + ShutdownTimeout + 1s kadar sürebilir.
Bekleme erken de bitebilir. İkinci bir SIGINT ya da SIGTERM (Ctrl-C'ye iki kez basmak) beklemeyi hemen bitirir ve doğrudan sunucunun durdurulmasına geçer. Bitmiş bir Shutdown ctx'i de aynısını yapar.
Development modunda DrainDelay yok sayılır, böylece restart'lar anında olur. OnDrain ise yine çağrılır. Henüz hiçbir şey hizmet vermezken yapılan bir Shutdown beklemez, çünkü drain edilecek trafik yoktur; hiçbir plugin'e de haber vermez, çünkü hiçbiri başlamamıştır.
Process'i durduran şey, onu öldürmeden önce bu toplamdan daha uzun beklemelidir:
- systemd:
TimeoutStopSec,DrainDelay + ShutdownTimeout'tan büyük olmalıdır. elagoht/jobs varsa buna bir saniye eklenir.collage build -i'ın yazdığı unitTimeoutStopSec=30ayarlar. Bu, varsayılan değerleri karşılar.DrainDelay'i artırdığınızda bunu da artırın. - Kubernetes:
terminationGracePeriodSecondsbu toplamdan büyük olmalıdır. Readiness probe'unu/readyz'ye, liveness probe'unu/healthz'ye yönlendirin. Bu iki endpoint'e elagoht/health cevap verir. Böylece readiness drain başlar başlamaz başarısız olur ve pod, portu kapanmadan önce Service'ten çıkarılır:
spec:
terminationGracePeriodSeconds: 30 # > DrainDelay + ShutdownTimeout (+ 1s with elagoht/jobs)
containers:
- name: app
readinessProbe:
httpGet: { path: /readyz, port: 8080 }
periodSeconds: 2
failureThreshold: 1
livenessProbe:
httpGet: { path: /healthz, port: 8080 }
periodSeconds: 10
failureThreshold: 3
Bu readiness probe'uyla 5 saniyelik bir DrainDelay, probe'un iki saniyelik periyodunu rahatça karşılar.
Sunucunun beklemesi için süre yetmezse, yani ShutdownTimeout dolduğunda hâlâ açık bir request varsa, plugin'ler yine de kapatılır. ListenAndServe de bunu bildiren bir hata döner (collage: server shutdown: context deadline exceeded). Shutdown'ı başarısız olan bir plugin için de aynı şekilde hata döner. Scaffold'daki main.go'nun çağırdığı collage.Main bu hatayı log'lar ve process 0 yerine 1 status koduyla çıkar. Durdurma sırasında sıfırdan farklı bir exit kodunu crash olarak gören bir platform bunu crash olarak raporlar.
DrainDelay'i ya da ShutdownTimeout'u artırırsanız platformunuzun grace period'unu da onunla birlikte artırın.
Kendi sunucunuzla hizmet vermek
OnServe'ü yalnızca ListenAndServe çağırır. app.Handler() üzerinde kendi http.Server'ını çalıştıran bir uygulama OnServe almaz. Bu yüzden bu tür plugin'leri kendisi başlatmalı ve durmaya başladığında ctx'lerini iptal etmelidir. elagoht/jobs için sunucu dinlemeye başlar başlamaz onun Start(ctx)'ini çağırın. Uygulama, sunucusu durduktan sonra app.Shutdown(ctx)'i de çağırmalıdır. Plugin'lerin Shutdown'ını çalıştıran bu çağrıdır. O olmadan bir queue'da bekleyen item'lar loglanmadan bile kaybolur.
// Init first, and its error: app.Handler() would only log it and answer 503,
// and the jobs plugin's Start panics before its Init has run.
if err := app.Start(); err != nil {
return err
}
ln, err := net.Listen("tcp", ":8080")
if err != nil {
return err
}
srv := &http.Server{Handler: app.Handler()}
go srv.Serve(ln)
ctx, stopJobs := context.WithCancel(context.Background())
j.Start(ctx) // the port is bound: start the jobs
// On shutdown:
stopJobs() // the drain: no more triggers; Enqueue still accepts
srv.Shutdown(shutdownCtx) // requests in flight finish
app.Shutdown(shutdownCtx) // the plugins stop; jobs finishes its queues and refuses more
app.Shutdown, DrainHook plugin'lerine haber verir ama DrainDelay kadar beklemez, çünkü App hizmet vermeye devam edecek bir sunucunuzdan haberdar değildir. Onu çağırmadan önce sunucunuzu durdurun.
Health check'ler
Liveness ve readiness, elagoht/health plugin'inden gelir. /healthz, process request'lere cevap verdiği sürece 200 döner. /readyz ise sizin check'lerinizden biri başarısız olana ya da bir drain başlayana kadar 200 döner, sonra 503 dönmeye başlar. Her platformu bu iki path'e yönlendirin: yukarıdaki Kubernetes probe'larını ya da bir systemd unit'inin önündeki load balancer'ın /readyz'deki health check'ini. Böylece readiness, drain başlar başlamaz başarısız olur. Plugin'i, bir request'i reddedebilen ya da ona cevap verebilen her plugin'den önce listeleyin. Nedenini plugin'in bölümünde bulabilirsiniz.
collage new --template demo ile scaffold edilen proje, bir /healthzdocument'ı ile gelir: documents/health.go. elagoht/health eklendiğinde /healthz'ye önce plugin'in middleware'i cevap verir ve document'a hiç ulaşılmaz. Startup bunu yakalamaz, çünkü plugin document'ları değil page'leri kontrol eder. Document'ı silin ya da plugin'in liveness endpoint'ini livePath ile başka bir path'e taşıyın.
Plugin'i kullanmayan bir proje de probe'larına kendi document'larıyla cevap verebilir. Bunlar yalnızca byte'lar ve bir content type'tır, template içermez. Bu yüzden bir template bozuldu diye bir check başarısız olmaya başlamaz. Bunları dynamic tutun: cache'ten sunulan bir health check, ok artık doğru olmaktan çıktıktan çok sonra da ok cevabını verirdi. Liveness için demo'daki documents/health.go kopyalanabilecek bir örnektir. Ancak böyle bir readiness document'ı drain'den haberdar değildir, bu yüzden port kapanana kadar 200 dönmeye devam eder. Minimal projede, yani --template demo olmadan collage new ile oluşturulan projede hiç /healthz yoktur.
Production'da page cache
Scaffold bir disk cache'i yapılandırır:
Cache: collage.CacheConfig{
Enabled: true,
Type: "disk",
Dir: env.CacheDir, // ".cache"
DefaultTTL: 5 * time.Minute,
},
Bu cache her static ve incremental page'i tutar. Strateji tanımlamayan bir page de, render ettiği hiçbir şeyin data handler'ı yoksa static'tir; bkz. Caching. Render edilmiş page'ler restart'tan sağ çıkar. Böylece aynı build'i yeniden deploy ettiğinizde site boş bir cache'e baştan render edilmez. Yeni bir build'in ne bulacağı, neyin değiştiğine bağlıdır:
- Cache, binary'nin hash'iyle namespace'lenir. Yeni bir build farklı bir dizini,
.cache/<hash>'i okur. Bu yüzden önceki build'in render ettiği page'leri asla sunmaz. Doğruluk için de, yer için de hiçbir şeyi temizlemeniz gerekmez: açılışta disk cache,Cache.Diriçinde diğer build'lerin bıraktığı dizinleri, içlerine bir saattir hiçbir şey yazılmadıysa siler. Yalnızca kendi verdiği adlara dokunur;data/'ya ya da orada tuttuğunuz başka bir şeye asla. Bir saat, önceki build'in yenisinin yanında hâlâ hizmet verdiği rolling deploy için bırakılan paydır. Page'lerin nasıl görüneceğini binary dışındaki bir şey belirliyorsaCache.Version'ı bir commit ya da release tag'i ile ayarlayın. - Dizin, çalışma dizinine göredir. Scaffold edilen bir projede nerede başlatıldığına bağlı olan tek şey budur. Container'da
WORKDIR'i ya da unit'teWorkingDirectory'yi ayarlayın veyaDir'e mutlak bir path verin. Process'in oraya yazabildiğinden de emin olun. - Hasarlı bir entry bir miss'tir. Bir entry okunurken kendi ETag'ine karşı kontrol edilir; bu yüzden dolu bir disk ya da bir çökme yüzünden yarım kalan bir dosya sunulmaz, yeniden render edilir. Entry'ler yerine yeniden adlandırılmadan önce diske flush edilir ve başarısız bir disk yazması memory'de de tutulmaz; page, disk düzelene kadar yeniden render edilir.
- Cache'in yazamaması bir hata değildir. Açılışta dizin oluşturulamazsa collage başlamayı reddetmez; bir uyarı verip in-memory cache'e geçer (uyarı:
collage: cannot use the disk cache directory, using an in-memory cache instead). Buna read-only bir dosya sistemi ya da process'in yazma izni olmayan bir çalışma dizini yol açabilir. Çalışırken başarısız olan bir yazma log'lanır, page cache'lenmeden sunulur ve bir sonraki request onu yeniden render eder. Sonuç yavaştır ama bozuk değildir. Bu uyarıyı takip edin ve deploy'dan sonra dizinin dolduğunu kontrol edin. - Her instance'ın kendi cache'i vardır. Container'da dizin container'ın içindedir. Bu yüzden her instance kendi cache'ini doldurur. Her page, her instance'ta bir kez render edilir. Bunu böyle bırakın: bir dizini paylaşan instance'lar bir cache'i paylaşmaz. Birindeki invalidation diski ve kendi memory'sini işaretler. Diğer her instance kendi memory'sindeki kopyayı expire olana kadar taze bir
HITolarak sunmaya devam eder. BirStaticpage için bu, bir restart'a ya da bir eviction'a kadar sürer. Bu arada page'i yeniden çeken bir CDN eski kopyayı tekrar alabilir. Tek bir cache'i paylaşması gereken bir filo bunun yerine paylaşılan bir store kullanır. - Önünde memory vardır ve restart'tan sonra boş başlamaz. Bir hit, memory katmanından sunulur. Bu katman açılışta dizinden, en yeni page'lerden başlanarak doldurulur. Böylece restart edilen bir instance son page'lerini hemen memory'den sunar. Katman process'in belleğinden en fazla 256 MiB kullanır.
MaxBytesbundan küçükse en fazlaMaxByteskadar kullanır. Aşağıya bakın. - Invalidate edilen bir page tutulur. Yeniden render'ı başarısız ya da degraded olursa
STALEolarak sunulur. Bkz. Caching. Invalidation'ın hemen ardından arka planda yeniden de render edilir. Bu, kısa bir süre CPU harcar. Bkz. warming. Bir action'ın redirect'i page'inin warm edilmesini bekleyebilsin diyeServer.WriteTimeout'u 5 saniyenin üzerinde tutun.
Öndeki bir CDN kendi kopyalarını tutar. elagoht/cdnpurge, collage bir page'i invalidate ettiğinde bu kopyaları purge eder. elagoht/compress ise response'ları Brotli ve gzip ile, okuyucu başına değil cache'lenen page başına bir kez sıkıştırır.
Memory cache ve container'ın bellek sınırı
"memory" cache MaxBytes ile sınırlıdır. Siz ayarlamadıkça bu sınır saklanan page'ler için 256 MiB'tır ve gerçekten işler: cache dolduğunda canlı heap büyümeyi bırakır. Ama process orada durmaz. Go'nun garbage collector'ı yeniden çalışmadan önce heap'in, son toplamadan sonra canlı kalan miktarın yaklaşık iki katına çıkmasına izin verir. Bu yüzden dolu bir 256 MiB'lık cache, 512 MiB'ı epey aşan bir process demek olabilir. Yaklaşık 14 KB'lık bir page 30.000 farklı URL ile istendiğinde process yaklaşık 720 MB'ta dengelendi. Bu, bütün ayarlar varsayılan değerinde bırakıldığında 512 MiB'lık bir container'ın öldürülmesine yeter.
Runtime'a ne kadar belleği olduğunu GOMEMLIMIT ile, container'ın sınırının biraz altında bir değerle söyleyin. Böylece runtime sınıra yaklaştıkça öldürülmek yerine belleği daha sıkı toplar:
# In a 512 MiB container.
ENV GOMEMLIMIT=400MiB
Aynı ölçüm GOMEMLIMIT=320MiB ile yaklaşık 430 MB'ta kaldı. Bu sınır yumuşaktır: runtime'ın hedeflediği bir değerdir, zorla uyguladığı bir tavan değildir. Bu yüzden MaxBytes'ı bunun epey altında tutun. Cache'in tuttuğu her şey canlıdır ve runtime ne kadar uğraşırsa uğraşsın toplanamaz. Boyutu sınırın üçte biri ile yarısı arasında olan bir cache, render'ların kendisine de yer bırakır. 512 MiB'lık bir container'da MaxBytes'ı varsayılanından 128–192 MiB'a indirin. Scaffold'un disk cache'i page'leri diskte tutar. Ama önlerinde bir memory katmanı vardır ve bu ayar ona da uygulanır. Katman en fazla 256 MiB tutar, MaxBytes bundan küçükse de MaxBytes kadar tutar. GOMEMLIMIT'i ayarlayın. Katmanın daha azını tutması gerekiyorsa MaxBytes'ı ya da MaxEntries'i düşürün.
Birden fazla instance ile invalidation
app.InvalidateTags, içinde çalıştığı process'in cache'indeki entry'leri invalidate eder. Tek instance varken, bir yazının tag'ini invalidate eden bir CMS webhook'u siteyi günceller. Birden fazla instance varsa yalnızca webhook'un ulaştığı instance güncellenir. Diğerleri eski page'i TTL'i dolana kadar sunmaya devam eder.
Üç çözümden birini seçin. Değişen page'lere Incremental(ttl) verin, böylece stale kopya kendiliğinden expire olur. Ya da webhook'u her instance'a gönderin. Ya da filonun tamamında tek bir cache'i paylaşın. Dir'ini instance'ların paylaştığı bir "disk" cache bu değildir: her instance'ın memory katmanı elindekini sunmaya devam eder. Caching sayfasına bakın.
Cache.Store'daki, collage.SharedCache'i implement eden bir store, örneğin collage-redis, üçüncü çözümdür ve cache'i gerçekten paylaşan tek çözümdür: birbirinin invalidation'larını görmesi gereken bir filo buna ihtiyaç duyar. Page'ler de collage.Cached değerleri de onda tutulur ve önünde instance başına bir kopya yoktur. Bu yüzden A instance'ına ulaşan bir webhook, B'nin bir sonraki okumasına da ulaşır. B'nin, A'nın invalidate etmekte olduğu veriden başlattığı bir render da taze değil, stale olarak saklanır. Invalidation'ın ulaştığı page'ler, hangi instance yazmış olursa olsun, A'nın plugin'lerine CacheInvalidateEvent.Entries içinde bildirilir (bir CDN purge'ünün üzerinde çalıştığı şey budur) ve A onları kendi WarmLimit'i içinde warm eder. Redis'in kapalı olması bir miss'tir, asla başarısız bir request değildir: site cache'siz render eder.
collage-redis ile deploy günü iki şey değişir. Her yeni binary boş bir namespace ile başlar, yani bir deploy cache boşken başlar. MaxAge (yedi gün) de stale bir kopyanın başarısız bir render'ın yerine ne kadar süre geçebileceğini sınırlar. Bkz. Bir filonun paylaştığı cache.
Yalnızca collage.TaggedCache ve collage.StaleCache'i implement eden paylaşılan bir store veriyi değil, page'leri tutar. collage.Cached ile tutulan değerler bu durumda her process'in kendi memory'sinde yaşar ve bir invalidation yalnızca içinde çalıştığı instance'a ulaşır. Webhook A instance'ına ulaştıktan sonra, paylaşılan store page'i invalidate ettiği için B instance'ı page'i yeniden render eder. Ama bunu hâlâ elinde tuttuğu eski değerle yapar. Bu değerlere katlanabileceğiniz kadar kısa bir TTL verin ya da invalidation'ı her instance'a gönderin.
TLS, bir proxy'nin arkasında
collage düz HTTP sunar ve ListenAndServeTLS sağlamaz. TLS'i düzgün terminate etmek sertifikalar, yenileme, HTTP/2, HSTS ve 80 numaralı port'tan redirect demektir. collage'ın çalıştığı her platform bunu zaten bir framework flag'inin yapabileceğinden daha iyi yapar: load balancer, reverse proxy, Cloudflare, Fly, Render.
Binary'yi bunlardan birinin arkasına koyun ve proxy'nin X-Forwarded-Proto: https gönderdiğinden emin olun. collage bu header'a bakarak forgery token cookie'sini Secure olarak işaretler. Böylece HTTPS üzerinden sunulan bir site bu cookie'yi asla düz HTTP üzerinden göndermez.
Header'ı değiştirmek yerine sonuna ekleyen bir proxy bir liste gönderir: https, http. Geçerli olan, okuyucunun kendi bağlantısını gösteren ilk entry'dir.
Tarayıcının gönderdiği Host'u da iletin. Forgery kontrolü eski bir tarayıcının Origin'ini onunla karşılaştırır ve Host page cache'in key'inin bir parçasıdır. Sertifikayı da kendisi alan minimal bir Caddy config'i şöyledir:
example.com {
reverse_proxy 127.0.0.1:8080
}
nginx'te location bloğuna eklenen proxy_set_header X-Forwarded-Proto $scheme; aynı işi görür. Güvenlik header'larının kendileri, yani HSTS, bir Content-Security-Policy ve diğerleri, elagoht/secure plugin'iyle binary'den de gelebilir. elagoht/ratelimit tek bir istemcinin form'ları ne kadar hızlı gönderebileceğini sınırlar. elagoht/basicauth ise bir staging deploy'unun önüne bir parola koyar.
TLS'i binary'nin kendisinin terminate etmesini istiyorsanız, app.Handler() sıradan bir http.Handler'dır:
srv := &http.Server{
Addr: ":443",
Handler: app.Handler(),
ReadHeaderTimeout: 15 * time.Second,
}
log.Fatal(srv.ListenAndServeTLS(certFile, keyFile))
Bu durumda ListenAndServe'ün sizin yerinize hallettiği timeout'lar ve signal handling artık sizin sorumluluğunuzdadır. Önce app.Start()'ı çağırırsınız, ServeHook plugin'lerini kendiniz başlatırsınız ve plugin'lerin kapanması için sunucunuz durduktan sonra app.Shutdown(ctx)'i çağırırsınız. Bkz. Kendi sunucunuzla hizmet vermek.
Bir proxy'nin arkasında: TrustedProxies
Bir proxy'nin arkasında her request'in RemoteAddr'i proxy'ninkidir. Gerçek istemciyi proxy X-Forwarded-For'da bildirir, ama bunu başkası da yapabilir: kendi X-Forwarded-For'unu gönderen bir istemciye inanılmaz. Server.TrustedProxies kimin söylediğine inanılacağını belirler:
Server: collage.ServerConfig{
TrustedProxies: []string{"10.0.0.0/8", "127.0.0.1"},
},
Her girdi bir adres ya da CIDR aralığıdır; ikisinden de olmayan bir girdi collage.New'ı başarısız kılar.
collage.ClientIP(r) bundan sonra istemcinin kim olduğunu söyler: RemoteAddr'in host'u; ta ki o güvenilen bir proxy olana kadar. Öyleyse header sağdan okunur, güvenilen adresler atlanır ve güvenilmeyen ilk adres istemcidir (hepsi güvenilense en soldaki). Boşken, yani varsayılanda, hiçbir header'a güvenilmez ve ClientIP her zaman RemoteAddr'dir.
Header'daki bir girdi, bazı proxy'lerin yazdığı gibi port (9.9.9.9:4567, [2001:db8::1]:443) ya da köşeli parantez ([2001:db8::1]) taşıyabilir; adres olarak okunur. Yine de adres olmayan bir girdi, örneğin bazı proxy'lerin gönderdiği unknown, okumayı bitirir. Ondan önce güvenilmeyen bir adres bulunmadıysa istemci bilinmez ve ClientIP sıfır netip.Addr'dir: asla proxy değil, çünkü o her ziyaretçiyi aynı istemci yapardı. İstemciye göre iş yapan bir plugin böyle bir request'i atlar.
İstemciyle sunucu arasındaki her hop'u yazın: kendi proxy'lerinizi ve bir CDN'in arkasındaysanız CDN'in yayımladığı aralıkları da. Unutulan bir hop istemci sanılır ve onun üzerinden gelen her ziyaretçi tek bir istemci olur.
Yalnızca kendi işlettiğiniz proxy'leri ya da platformunuzun belgelediği aralıkları yazın: istemcinin request gönderebildiği bir aralığa güvenmek, o istemcinin istediği adresi kendine vermesine izin vermektir. Sıfır bitlik bir girdi (0.0.0.0/0, ::/0) herkese güvenir; collage.New onu kabul eder ama bunu söyleyen bir Warn log'lar.
Aynı liste, hangi proxy'nin X-Forwarded-Proto'suna inanılacağını da belirler. Forgery cookie'si, request TLS üzerinden geldiğinde Secure olur. TLS'i terminate eden bir proxy'nin arkasında bunu proxy o header ile söyler.
TrustedProxies set edilmişse RemoteAddr'ı listedeki bir proxy olmayan bir request bu header'ı set edemez. Port'a düz http ile doğrudan ulaşan bir client, düz http üzerinden geri gönderebileceği bir cookie alır. Liste boşsa header herkesten kabul edilir. Liste var olmadan önce de böyleydi ve yalnızca proxy'nizden başka hiçbir şeyin sunucuya ulaşamadığı durumda doğrudur.
Bu karar tek bir fonksiyondur: collage.IsHTTPS(r). Forgery guard'ın cookie'si de, Secure cookie koyan ya da HSTS gönderen plugin'ler de — elagoht/session, flash, secure ve diğerleri — ona sorar. Böylece liste onların cookie'lerini ve header'larını da korur: proxy'nizi listeleyin, bir client sahip olmadığı TLS bağlantısını iddia edemesin.
Timeout'lar
ListenAndServe, Config.Server içindeki timeout'ları uygular:
| Alan | Varsayılan | Neyi sınırlar |
|---|---|---|
ReadTimeout | 15s | Header'lar dahil request'in okunmasını. Header'ları yavaş gönderen bir client bağlantıyı açık tutamaz. |
ReadHeaderTimeout | 0 | Yalnızca request header'larının okunmasını. Böylece header'ları bir byte'ta bir gönderen bir client erken düşürülür, büyük bir body ise ReadTimeout'un tamamını alır. Sıfır, ReadTimeout'u kullanır. |
WriteTimeout | 30s | Response'un yazılmasını. Request'in header'ları okunduğunda başlar, bu yüzden bir upload'un body'sini de sınırlar. Verisi bundan uzun süren bir page yarıda kesilir. |
IdleTimeout | 60s | Bir sonraki request'ini bekleyen keep-alive bağlantısını. |
DrainDelay | 0 | Bir SIGTERM'den sonra, keep-alive'lar kapalı olarak hizmet vermeye devam edilen süreyi; böylece load balancer trafik göndermeyi bırakabilir. |
ShutdownTimeout | 10s | Drain'den sonra, port kapandığında devam eden request'lerin bitmesini. |
MaxBodyBytes | 4 MiB | Bir action'ın request body'sini, action kendi sınırını belirlemediyse. Negatif değer sınırsız demektir. |
Server: collage.ServerConfig{
Host: env.Host,
Port: env.Port,
WriteTimeout: time.Minute,
},
collage dev'in proxy'si yalnızca development'ta geçerli, sabit 10 saniyelik kendi header timeout'unu kullanır. Bunlardan herhangi birindeki negatif değer collage.ErrNegativeDuration'dır.
Upload'lar için yalnızca ReadTimeout'u artırmak bir tuzaktır. WriteTimeout'tan uzun süren bir upload okunur ve handler onu kaydeder, ama cevap yarıda kesilir. Client bağlantının kapandığını görür ve yeniden dener.
İkisini birden bütün sunucu için artırmak ise yavaş her client'ın her endpoint'i o kadar süre tutmasına izin verir. Bunun yerine upload action'ına WithBodyTimeout ile kendi deadline'ını verin. Upload'lar bölümüne bakın.
Bir data handler'ın ne kadar sürebileceği ayrı bir ayardır. Bunu her fragment'in WithTimeout'u belirler. Timeout belirtmeyen fragment'ler ve document'lar için Template.Timeout (5 saniye) geçerlidir. Bu süreyi WriteTimeout'un epey altında tutun. Böylece yavaş bir upstream, page'in ortasında kapanan bir bağlantıya değil, fragment'in fallback'ine dönüşür. Config sayfasına bakın.
Upload'lar
Bir upload (Streaming body'ler bölümüne bakın), tarayıcı ile handler arasındaki her limitle karşılaşır. Bu limitlerin çoğunun varsayılanları form'lara göre boyutlanmıştır.
Sunucunun deadline'ları. Yukarıdaki varsayılanlar her upload'u 15 saniyelik okumadan sonra bitirir. Upload action'ındaki WithBodyTimeout(d), iki deadline'ı da yalnızca o action için şimdi artı d ile değiştirir. Bunu page'in guard'larından sonra (streaming bir action'da ise forgery kontrolünden de sonra) yapar. d'yi en az MaxBodyBytes bölü hizmet verdiğiniz en yavaş bağlantı artı cevap verme süresi kadar tutun. Client'ı gitmiş ya da süresi dolmuş bir upload sunucu hatası olarak değil, 400 ya da 408 olarak kaydedilir ve debug seviyesinde log'lanır. Giden bir client hiçbir şey almaz. WithBodyTimeout altında süresi dolan client da almaz, çünkü write deadline'ı read deadline'ı ile birlikte geçmiştir.
nginx, client_max_body_size'ı (varsayılan 1 MiB) aşan her şeye collage onu görmeden kendi 413'ü ile cevap verir. Varsayılan olarak ayrıca request body'sinin tamamını, bir kısmını bile iletmeden önce kendi diskine buffer'lar. Stream, kötü bir dosyanın erkenden reddedilmesi ve upload'un ilerleyişi kaybolur. Dolan da nginx'in temp dizini olur. Upload location'ı için:
location /upload {
client_max_body_size 2g; # MaxBodyBytes, or a little more
proxy_request_buffering off; # stream the body through
proxy_send_timeout 30m; # between two writes to collage
proxy_read_timeout 30m; # waiting for collage's answer
proxy_pass http://127.0.0.1:8080;
}
Caddy request body'lerini stream eder. Limiti, ayarlandığında, request_body { max_size 2GB }'dir.
Cloudflare ve diğer CDN'ler request body'sini plana göre sınırlar (bu yazı yazıldığında Free ve Pro planlarında 100 MB'tı; kendi planınız için Cloudflare'in dokümantasyonuna bakın) ve daha büyüğüne kendileri cevap verir. Load balancer'ların da kendi sınırları ve idle timeout'ları vardır. Daha büyük dosyalar için CDN'i atlayan bir hostname ya da parça parça devam ettirilebilen upload'lar gerekir. collage ikincisini yapmaz.
elagoht/health'in maxInFlight'ı, upload'lar dahil hizmet verilen her request'i sürdüğü boyunca sayar. Bunu aynı anda beklediğiniz upload'lara göre boyutlandırın. Aksi halde yavaş upload'lar slot'ları tutar ve sitenin geri kalanına 503 ile cevap verilir.
Loglar
Config.Logger verilmezse collage, slog'un varsayılan handler'ına log yazar. Terminalde çalışıyorsa insanların okuması için formatlanmış bir handler kullanır. Bir sunucuda loglar bir makine tarafından okunur. Orada bir JSON handler verin:
Logger: slog.New(slog.NewJSONHandler(os.Stdout, nil)),
collage her request'i değil, ters giden şeyleri log'lar. elagoht/accesslog aynı logger üzerinden her request için request id'li bir satır yazar. elagoht/prometheus framework'ün metric'lerini /metrics'te sunar. elagoht/otel ise span'lerini OpenTelemetry trace'lerine dönüştürür.
Development modu bu makinede kalır
DevMode, production'ın sunmaması gereken şeyleri sunar: stack'li ve kaynak kodlu hata sayfaları, reload stream'i, bir development toolbar'ı. Bunları burada tutan iki koruma vardır:
- Yabancı bir
Hostreddedilir. Development'ta sunucu,Host'u localhost (ya da.localhostaltındaki bir ad), bir IP adresi, ayrılmış bir ad,Server.HostveyaCOLLAGE_DEV_HOSTiçindeki bir ad olmayan request'lere403ile cevap verir. Ayrılmış adlarexample.com,example.net,example.orgve bunların altındaki adlar ile.example,.testve.invalidaltındaki adlardır. Bu kural uygulama doğrudan çalıştırıldığında da geçerlidir, yalnızcacollage devaltında değil. Başka bir sitedeki bir page kendi adının127.0.0.1'e çözümlenmesini sağlayabilir (DNS rebinding) ve böylece development sunucusuyla same-origin olur, ama gönderdiğiHostyine kendi adıdır. Ayrılmış adlara izin verilir, çünkü hiç kimse onlardan birini size yönlendirmek için register edemez. Test'lerin kullandığı adlar da bunlardır (httptest'in request'leriexample.comiçindir). Bir static build'in capture'ları kontrol edilmez. - Erişilebilir bir adres için uyarı verilir. Development'ta
ListenAndServeloopback dışında bir adrese (0.0.0.0,::, bir LAN adresi) bağlandığında, development sayfalarının uygulamanın iç yapısını açığa çıkardığını söyleyen bir Warn log'lar.collage devde kendi proxy'si öyle bağlandığında aynısını log'lar.
Yükseltme: ayrılmış adların dışında özel bir Host kullanan bir DevMode test'i ya da request'i, örneğin bir tenant domain'i, artık 403 alır. Adı Server.Host olarak set edin, COLLAGE_DEV_HOST içine yazın ya da tenant.test gibi ayrılmış bir ad kullanın.
Development'a başka bir adla erişmek
COLLAGE_DEV_HOST, bir development sunucusunun cevap vereceği ek adların virgülle ayrılmış listesidir. Şu durumlarda set edin:
- bir docker-compose servis adı, yani başka bir container'dan
http://app:6060; - ayrılmış adların dışında,
/etc/hostsiçindeki bir ad; - tek bir development sunucusunda birkaç tenant host'u (ya da hiçbir ayar gerektirmeyen
*.localhostadlarını kullanın); 0.0.0.0'a bağlı bir sunucuya telefondan makinenin LAN adıyla erişmek. IP adresiyle erişmek için hiçbir şey gerekmez.
COLLAGE_DEV_HOST=app,mybox.lan
Development modundaki bir uygulama bunu kendi process ortamından okur. Doğrudan çalıştırıyorsanız shell'de ya da process'in ortamını aldığı yerde set edin. collage dev onu shell'den ya da .env.development'tan okur, kendi proxy'sine uygular ve programa listeyi kendi HOST'uyla birlikte verir. Program loopback'te dinler ama tarayıcının Host'unu görür. Reddedilen bir request'in 403'ü Host'u alıntılar ve ayarın adını verir. ngrok gibi bir tünel, adını listeye yazmadıkça reddedilir. Bu bilerek böyledir, çünkü development sayfalarını internete açar.
İki koruma da production'da geçerli değildir. Orada DevMode kapalıdır ve Host, DNS'inizin gönderdiği ne ise odur.
Örnek: bir ekibin iş listesini deploy etmek
Bir ekibin iş listesi (her üye giriş yapar; bir admin ekibin her görevini, bir üye ise yalnızca kendi görevlerini değiştirebilir) bir load balancer'ın arkasındaki iki sunucuyla production'a çıkar. Load balancer TLS'i bitirir ve her request'i iki sunucudan birine gönderir.
İki sunucu olmasının sebebi, bir instance'ı restart etmenin onun port'unu kapatmasıdır. Tek sunucuyla her restart bir kesintidir; iki sunucuyla biri restart olurken diğeri hizmet verir. Session'lar uygulamanın kendi sid cookie'sidir ve uygulamanın kendi veri katmanından okunur. Bu yüzden iki sunucu da bir session'ı okuyabilir. Bu deploy, bir değişiklikten sonra gösterilen mesajlar için elagoht/flash plugin'ini ekler. Bu plugin cookie'sini kendine ait bir key ile imzalar.
| Neye ihtiyacı var | Nereden gelir |
|---|---|
| İki sunucuda da aynı forgery key'i | Unit'in okuduğu secret dosyasındaki COLLAGE_CSRF_KEY |
| İki sunucuda da aynı flash key'i | KeyEnv başka bir değişken adı vermedikçe elagoht/flash'ın okuduğu FLASH_KEY |
| Yazabildiği bir page cache | Unit'in WorkingDirectory'sinde .cache/<hash>, her sunucuda bir tane |
| Okuyucunun adresi ve scheme'i | Load balancer'ı listeleyen Server.TrustedProxies |
| Load balancer'ın fark ettiği bir drain | Plugin listesinde ilk sıradaki elagoht/health ve Server.DrainDelay |
Config
Scaffold'daki newApp, load balancer, drain ve iki plugin eklenmiş hâliyle:
h := health.New(health.Options{})
h.Check("db", func(ctx context.Context) error { return db.PingContext(ctx) })
app, err := collage.New(&collage.Config{
Server: collage.ServerConfig{
Host: env.Host,
Port: env.Port,
// The load balancer's private address: only its X-Forwarded-For
// and X-Forwarded-Proto are believed.
TrustedProxies: []string{"10.0.1.10"},
// The load balancer checks /readyz every 2 seconds and takes a
// server out after one failure: keep serving until it has.
DrainDelay: 5 * time.Second,
},
Cache: collage.CacheConfig{
Enabled: true,
Type: "disk",
Dir: env.CacheDir, // ".cache", under the unit's WorkingDirectory
DefaultTTL: 5 * time.Minute,
},
Plugins: []collage.Plugin{
h, // first, so a probe always reaches it
flash.New(flash.Options{}), // key'i FLASH_KEY'den
},
Security: collage.SecurityConfig{
CSRFKey: []byte(os.Getenv("COLLAGE_CSRF_KEY")),
},
// Template and the rest as scaffolded.
})
Load balancer listelendiğinde collage.ClientIP, load balancer'ın değil, okuyucunun adresidir. Bir sunucunun port'una başka bir yoldan ulaşan bir request de kendi X-Forwarded-Proto'suyla HTTPS iddia edemez. Load balancer'ın health check'ini /readyz'ye yönlendirin: veritabanı check'i başarısız olduğu sürece ve bir drain başladığı andan itibaren 503 döner.
Unit ve secret'lar
collage build -i -os linux -arch amd64, bin/tasks.service'i yazar. Her sunucuda bu dosyanın [Service] bölümü iki yerde değişir:
WorkingDirectory=/srv/tasks
ExecStart=/usr/local/bin/tasks
Environment=HOST=10.0.1.11
Environment=PORT=8080
EnvironmentFile=/etc/tasks/secrets.env
HOSTsunucunun private adresidir. Unit'teki127.0.0.1, başka bir makinedeki load balancer'dan gelen hiçbir şeyi kabul etmezdi.PORT=8080unit'in ayarladığı değerdir; o olmasa collage 6060'ı dinlerdi.- Secret'lar kendi dosyalarındadır; repository'nin ve unit'in dışında tutulur:
# 32 random bytes, hex
COLLAGE_CSRF_KEY=…
# 32 random bytes, hex, another one
FLASH_KEY=…
İki sunucu da aynı dosyayı alır. Böylece bir sunucunun render ettiği form diğerinde kabul edilir, birinin set ettiği flash cookie'si diğerinde okunur. Her birinin kendi key'i olsaydı ikisi de diğerinin verdiğini kabul etmezdi.
Page cache /srv/tasks/.cache/<hash> altına yazılır. Bu yüzden unit'in kullanıcısı tasks, /srv/tasks'a yazabilmelidir. Her sunucu kendi cache'ini doldurur.
Invalidation'ın ulaşmadığı sunucu
İş listesinin data handler'ı ekibin listesini collage.Cached ile ve sıfır bir ttl ile tutar: liste, tag'i invalidate edilene kadar taze kalır. API bu tag'i, request'in ulaştığı sunucuda invalidate eder. Diğer sunucu bundan hiç haberdar olmaz ve elindeki listeyi sunmaya devam eder.
Listeye bunun yerine bir TTL verin:
list, err := collage.Cached(rc, teamTasksKey.With(user.TeamID), 30*time.Second,
[]string{"team:" + user.TeamID + ":tasks"},
func(ctx context.Context) ([]Task, error) { return tasks.ByTeam(ctx, user.TeamID) })
Artık iki sunucu da aynı şekilde güncellenir. API çağrısının ulaştığı sunucuda listeyi, eskisi gibi, invalidation stale yapar; diğer sunucuda ise bunu 30 saniyenin dolması yapar. İki durumda da bir sonraki render'a eski liste sunulur. Bu sırada listeyi arka planda tek bir çekme işlemi yeniler ve ondan sonraki bir request değişikliği görür. Başka bir çözüm, invalidation'ı iki sunucuya da göndermektir. Üçüncüsü ise iki sunucunun da kullandığı, collage-redis gibi paylaşılan bir cache'tir. Ayrıntılar için Birden fazla instance ile invalidation bölümüne bakın.
Kesintisiz bir restart
Yeni bir build sunuculara birer birer gider:
- Yeni binary'yi
/usr/local/bin/taskskonumuna koyun ve servisi yeniden başlatın. - Drain. Servis yöneticisi
SIGTERMgönderir./readyz503 drainingdöner, keep-alive'lar kapatılır ve sunucuDrainDelayboyunca hizmet vermeye devam eder. Load balancer'ın check'i 2 saniye içinde başarısız olur ve load balancer her şeyi diğer sunucuya gönderir. - Durdurma. Port kapanır ve devam eden request'lere en fazla
ShutdownTimeout, yani 10 saniye verilir. Unit'inTimeoutStopSec=30'u, bunun sürebileceği 15 saniyeden uzundur. - Yeni binary. Servis yöneticisi onu başlatır. Yeni binary yeni bir
.cache/<hash>dizinini okur, bu yüzden önceki build'in render ettiği bir page'i asla sunmaz. /readyz'nin200dönmesini ve load balancer'ın sunucuyu geri almasını bekleyin, sonra aynısını diğer sunucuda yapın.
Okuyucular hiçbir şey fark etmez: restart'tan önce render edilen bir form, restart'tan sonra da kabul edilir, çünkü key değişmemiştir. İki sunucu da yeni build'i çalıştırdığında, önceki build'lerin /srv/tasks/.cache içinde bıraktığı dizinleri silin.
Kontrol listesi
COLLAGE_CSRF_KEYayarlı; her instance'ta ve restart'lar arasında aynı. Aksi hâlde form'lar her restart'ta ve instance'lar arasında bozulur.- Container'da
HOST=0.0.0.0,PORTplatformdan geliyor. .cacheiçin yazılabilir bir çalışma dizini var; disk cache, diğer build'lerin dizinlerini bir saat boşta kaldıklarında siler.- Birden fazla instance varsa ve birbirinin invalidation'larını görmeleri gerekiyorsa
Cache.Store'da bircollage.SharedCachestore'u var. - Build image'ında Go 1.26.11 ya da sonrası var.
- Plugin'leri yapılandırıyorsanız
plugins-config.jsonçalışma dizininde duruyor ya da gömülü. COLLAGE_DEVayarlı değil.- TLS proxy'de terminate ediliyor;
X-Forwarded-Protove tarayıcınınHost'u iletiliyor veServer.TrustedProxiesproxy'yi listeliyor. - Form'ları buraya post eden diğer her origin (örneğin bir admin subdomain'i)
Security.CSRFTrustedOrigins'te belirtilmiş. - Upload action'ının kendi
WithMaxBodyBytes'ı veWithBodyTimeout'u var, öndeki proxy de o boyuta izin veriyor ve body'yi stream ederek iletiyor. Upload'lar bölümüne bakın. - Platformun stop grace period'u
Server.DrainDelay + Server.ShutdownTimeout'tan uzun. elagoht/jobs varsa bir saniye daha uzun. - elagoht/health ile liveness check
/healthz'ye, readiness check/readyz'ye bakıyor. - Build'den önce CI'da
go test ./...çalışıyor. Test yazmak sayfasına bakın.