İçeriğe atla
ColliePWA

17/Documentation

Dağıtım varyantları B–E

Varsayılan dışındaki giriş kapıları: kimlik algılayıcı proxy, Tailscale içermeyen bir ters proxy, sunucu dışı bir ingress, tek bir sunucuda birden fazla Collie (kullanıcı başına bir tane veya tek bir kullanıcı için birden fazla örnek) ve bir crew'un yedek kapısı

Köprü 127.0.0.1 adresine bağlanır. Dağıtımlar, giriş ve kimlik doğrulama yöntemlerine göre farklılık gösterir. Varyant A (yalın tailscale serve) README içindedir. docs/security.md içindeki güvenlik gereksinimleri tüm biçimler için geçerlidir.

Münferit cihazlar, eşleme üzerinden bir proxy olmadan da yetkilendirilebilir.

---

Varyant B: kimlik algılayıcı proxy + cihaz başına yetkilendirme

Collie, COLLIE_DEVICE_HEADER üzerinden opakt bir cihaz kimliği okur ve COLLIE_DEVICE_ALLOWLIST kontrolü yapar. İzin verilen kimlikler yazma erişimi alır; eksik veya listede olmayan kimlikler salt okunur erişim alır (terminal girişi, yüklemeler ve bölme eylemleri engellenir). Eşleme ikinci bir güvenlik kapısıdır ve her zaman açıktır: her cihazın, okumalar dahil her /api çağrısı için bir pairing token değerine de ihtiyacı vardır.

Collie yapılandırması (.env):

COLLIE_HOST=127.0.0.1                       # keep loopback (default)
COLLIE_DEVICE_HEADER=X-Device-Id            # the header your proxy injects
# ids allowed to drive agents; others → read-only
COLLIE_DEVICE_ALLOWLIST=my-phone,my-laptop
# only if the proxy does NOT forward the public Host
# COLLIE_ALLOWED_ORIGINS=https://collie.example.com
# REQUIRED unless the proxy forwards a Host Collie already knows: loopback, a
# discovered Tailscale host, or an allowed origin's host
# COLLIE_PUBLIC_HOSTS=collie.example.com
# opt out of Host validation entirely (re-opens DNS rebinding)
# COLLIE_ALLOW_ANY_HOST=1
# COLLIE_TRUSTED_USER still composes on top if your ingress also injects
# Tailscale-User-Login
# accept a request carrying no Tailscale-User-Login at all
# COLLIE_TRUSTED_USER_OPTIONAL=1

Proxy gereksinimleri:

  1. Cihazı doğrulayın (mTLS, SSO, forward-auth).
  2. İstemci sahteciliğini önlemek için yukarı akışa giden her istekte Cihaz başlığını geçersiz kılın.
  3. Loopback'e proxy yapın (127.0.0.1:$COLLIE_PORT).
  4. Genel Host değerini değiştirmeden iletin veya aynı kaynak denetimini geçmek için genel kaynağı COLLIE_ALLOWED_ORIGINS içinde listeleyin.

Örnek Nginx yapılandırması:

location / {
    proxy_set_header X-Device-Id $device_id;
    proxy_set_header Host        $host;
    proxy_pass http://127.0.0.1:8787;
}

Harici bir cihazdan başlık eklemeyi ve üzerine yazmayı doğrulayın. /api/health ve /api/pair dışındaki her /api çağrısı bir eşleme belirteci gerektirir; bu nedenle önce bir terminal eşleyin. Ana makinede collie pair çalıştırın. 8 karakterlik bir kod yazdırır. Kodu test ettiğiniz cihazdan talep edin. Origin başlığı genel URL ile eşleşmelidir. Yanıt belirteci içerir. Bunu bir kabuk değişkeninde tutun ve asla bir dosyaya yapıştırmayın:

$ collie pair                                   # on the host; note the code it prints
$ TOKEN=$(curl -s -X POST https://collie.example.com/api/pair \
    -H 'Content-Type: application/json' -H 'Origin: https://collie.example.com' \
    -d '{"code":"ABCD1234","label":"header-check"}' | jq -r .token)

Ardından belirteç ile başlık kontrolünü çalıştırın:

$ curl -s -H "Authorization: Bearer $TOKEN" https://collie.example.com/api/snapshot | jq -c .device
{"enforced":true,"device":"header-check","authorized":true}

$ curl -s -H "Authorization: Bearer $TOKEN" -H 'X-Device-Id: not-listed' https://collie.example.com/api/snapshot | jq -c .device
{"enforced":true,"device":"header-check","authorized":true}

Bir belirteç ile, device başlık değerini değil, eşlenen etiketi (header-check) adlandırır. Artık hiçbir alan ham başlık değerini döndürmez; bu yüzden authorized değerini okuyun: yalnızca köprünün gördüğü başlık COLLIE_DEVICE_ALLOWLIST üzerinde olduğunda ve belirteç geçerli olduğunda true olur. İkinci kontrol "authorized":false döndürürse, proxy istemcinin başlığını geçersiz kılmak yerine sonuna ekliyordur. İşiniz bittiğinde collie devices revoke header-check ile test cihazını kaldırın.

Operasyonel notlar:

  • Doğrudan loopback erişimi (http://127.0.0.1:$COLLIE_PORT) hiçbir başlık göndermez ve salt okunurdur; ayrıca yine bir eşleme belirteci gerektirir.
  • Komutları curl ile yerel olarak yürütmek için belirteci ve başlığı loopback'e açıkça iletin: curl -H "Authorization: Bearer $TOKEN" -H 'X-Device-Id: my-laptop' http://127.0.0.1:$COLLIE_PORT/api/...
  • Kimliği COLLIE_DEVICE_ALLOWLIST dosyasından kaldırarak ve yeniden başlatarak erişimi iptal edin (Standalone: bin/collie restart; Herdr: herdr plugin action invoke restart --plugin herdr.collie).
  • Yalın tailscale serve üzerinde COLLIE_DEVICE_HEADER seçeneğini etkinleştirmeyin; başlıkları geçersiz kılmaz.
  • Proxy başka bir ana bilgisayarda çalışıyorsa D Varyantı bölümüne bakın.

---

Varyant C: tek ön kapı olarak ters proxy (Tailscale yok)

Tailscale dışında veya özel bir TLS/SSO proxy'si arkasında çalışırken bunu kullanın. COLLIE_SKIP_SERVE=1, Collie'nin tailscale serve yönetimini engeller.

B Varyantı altındaki dört proxy gereksinimi geçerlidir.

Örnek Caddy yapılandırması:

collie.example.com {
    reverse_proxy 127.0.0.1:8787 {
        header_up X-Device-Id {your_device_id}
        header_up Host {host}
    }
}

Collie yapılandırması (.env):

# proxy is ingress; never run tailscale serve
COLLIE_SKIP_SERVE=1
# REQUIRED — Host validation fails closed, and `collie start` discovers no
# tailnet name here
COLLIE_PUBLIC_HOSTS=collie.example.com
# opt out of Host validation (re-opens DNS rebinding)
# COLLIE_ALLOW_ANY_HOST=1
# exact public origin for the same-origin gate
COLLIE_ALLOWED_ORIGINS=https://collie.example.com
COLLIE_DEVICE_HEADER=X-Device-Id                    # the header your proxy injects…
# …and the ids allowed to drive; others → read-only
COLLIE_DEVICE_ALLOWLIST=my-phone,my-laptop
# optional — status banner, `collie qr`, and the address a lead hands
# joining machines (crew)
# COLLIE_PUBLIC_URL=https://collie.example.com

COLLIE_TRUSTED_USER ayarının Tailscale olmadan hiçbir etkisi yoktur. Cihaz başına başlıklar veya proxy'nin kendi kimlik doğrulaması erişim kapısı görevi görür.

/auth/ yönlendirme ve önbelleğe alma

  • /sw.js ve index.html isteklerini Cache-Control kaynağı ile iletin (no-cache). Kimliği doğrulanmamış istemcilere statik varlıkları engellemeyin, aksi takdirde service worker'lar güncellenemez.
  • Kimlik doğrulama akışlarını /auth/* (veya Cloudflare Access için /cdn-cgi/access/) altına yönlendirin. Service worker'lar /auth/* için önbelleğe almayı atlar.
  • API isteklerindeki forward-auth yönlendirmeleri, giriş arayüzünü göstermek için 401 olarak değerlendirilir. Authentik kurulumları /auth/ adresini /outpost.goauthentik.io/start adresine yönlendirmelidir.
  • /auth/ üzerinde bir proxy olmadan Collie orada 404 yanıtını verir. Sayfa artık eşleşmemiş bir cihaza collie pair komutunu çalıştırmasını ve kodu Settings bölümüne girmesini söyler. Yol proxy'nize ait olduğu için hiçbir zaman yeniden yönlendirme yapmaz.
collie.example.com {
    handle /auth/* {
        reverse_proxy 127.0.0.1:9091
    }
    handle {
        forward_auth 127.0.0.1:9091 { ... }
        reverse_proxy 127.0.0.1:8787 { ... }
    }
}

Uç noktayı ve önbelleğe alma kurallarını doğrulayın. $TOKEN bir eşleme belirtecidir ve B Varyantı içindeki gibi talep edilir; authorized, başlığınız izin verilenler listesinde olduğunda true değerini alır:

$ curl -s -H "Authorization: Bearer $TOKEN" https://collie.example.com/api/snapshot | jq -c .device
{"enforced":true,"device":"header-check","authorized":true}

$ curl -sI https://collie.example.com/sw.js | grep -i '^cache-control'
cache-control: no-cache

---

Varyant D: tailnet üzerinden sunucu dışı kimlik proxy'si

Trafiği merkezi bir Tailscale giriş düğümü üzerinden yönlendirirken bunu kullanın.

Bir ingress düğümü, tailnet sınırında telefonun kimliğini doğrular ve Collie'nin kendisi yalnızca loopback üzerinde yanıt verir.phoneingress nodeagent hostCollie127.0.0.1:8787httpsTLS + forward-auth,sets the device headerhttp, tailnet only —WireGuard already encrypts ittailscale serve, tailnet-onlyloopback
Bir ingress düğümü, tailnet sınırında telefonun kimliğini doğrular ve Collie'nin kendisi yalnızca loopback üzerinde yanıt verir.

Proxy'nin geri döngü yerine ana bilgisayarın Tailscale HTTP uç noktasını hedeflemesi dışında, B Varyantı içindeki gereksinimler geçerlidir.

Tailscale ACL'leri (Zorunlu)

tailscale serve istemci başlıklarını değiştirmeden ilettiğinden, Tailscale ACL'leri doğrudan bağlantı noktası erişimini yalnızca giriş düğümüyle sınırlandırmalıdır.

Tailscale / Headscale ≥ 0.29:

"grants": [
  { "src": ["tag:ingress"], "dst": ["tag:agent-host"], "ip": ["tcp:8787"] },
]

Headscale ≤ 0.28:

acls:
  - action: accept
    src: ["ingress-node"]
    dst: ["agent-host:8787"]
  - action: accept
    src: ["my-phone", "my-laptop"]
    dst: ["agent-host:1-8786", "agent-host:8788-65535"]

Collie yapılandırması (.env):

# proxy terminates TLS; this hop is tailnet-internal
COLLIE_SERVE_MODE=http
COLLIE_HOST=127.0.0.1                                 # keep loopback (default)
# header your forward-auth injects — REQUIRED here
COLLIE_DEVICE_HEADER=X-Tailnet-Device
# ids allowed to drive; others + header-less → read-only
COLLIE_DEVICE_ALLOWLIST=my-phone,my-laptop
# REQUIRED — the Host the proxy forwards. COLLIE_TAILSCALE_HOSTS carries the bare
# tailnet name `collie start` found; a rewritten Host is yours to list.
# COLLIE_ALLOW_ANY_HOST=1 opts out.
COLLIE_PUBLIC_HOSTS=host:8787,host.your-tailnet.ts.net:8787
# the public origin the browser actually uses
COLLIE_ALLOWED_ORIGINS=https://collie.example.com

COLLIE_TRUSTED_USER, arkasındaki son kullanıcıyı değil, giriş düğümünün kimliğini eşler.

Doğrulama:

Giriş (ingress) olmayan bir tailnet eşinden. $TOKEN bir eşleme belirtecidir ve B Varyantı içindeki gibi talep edilir:

$ curl -s -H "Authorization: Bearer $TOKEN" https://collie.example.com/api/snapshot | jq -c .device
{"enforced":true,"device":"header-check","authorized":true}

$ curl -s --max-time 10 -H 'X-Tailnet-Device: my-phone' http://host.your-tailnet.ts.net:8787/api/snapshot
curl: (28) Connection timed out

Ajanın bulunduğu ana makinede bir istek başlık göndermez; bu nedenle geçerli bir belirteç olsa bile authorized false olur:

$ curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8787/api/snapshot | jq -c .device
{"enforced":true,"device":"header-check","authorized":false}

---

Varyant E: diğer herhangi bir mesh veya tünel (NetBird, ZeroTier, Cloudflare Tunnel)

Tüneli/proxy'yi 127.0.0.1:$COLLIE_PORT adresine yönlendirin.

Collie yapılandırması (.env):

COLLIE_SKIP_SERVE=1                                 # never run tailscale serve
# REQUIRED — exact public host; Host validation fails closed and finds no
# tailnet name here
COLLIE_PUBLIC_HOSTS=collie.example.com
# exact public origin for the same-origin gate
COLLIE_ALLOWED_ORIGINS=https://collie.example.com

Kurallar:

  1. B Varyantı proxy kurallarını uygulayın.
  2. COLLIE_TRUSTED_USER, Tailscale olmadan devre dışıdır. COLLIE_DEVICE_HEADER veya tünelin kimlik doğrulamasını kullanın.
  3. PWA önbelleğe almanın ve COLLIE_PUBLIC_HOSTS ayarının geçerli kalması için statik bir ana bilgisayar adı kullanın.

---

Ön kapılar, her seferinde bir ürün

Sıkça sorulan ön kapılar için kaba kurulumlar. Her biri aynı noktada biter: sabit bir ana makine adında HTTPS, bu ana makinedeki 127.0.0.1:$COLLIE_PORT adresine yönlendirilir.

Not. Web Push, mikrofon ve ana ekrana yükleme özellikleri, telefonun güvendiği bir sertifikaya sahip HTTPS gerektirir. Düz HTTP üzerinden Collie bir tarayıcı sekmesinde okumaya ve yanıt vermeye devam eder, ancak bu üç özellik kapalı kalır (Ses girişi ve Web Push).

Tailscale dışındaki her ön kapı, Collie'nin .env dosyasında aynı üç satırı kullanır, ardından bir yeniden başlatma gerekir:

COLLIE_SKIP_SERVE=1                                 # you own the door, not Collie
COLLIE_PUBLIC_HOSTS=collie.example.com              # the hostname the phone opens
COLLIE_ALLOWED_ORIGINS=https://collie.example.com   # the same, as an origin

Proxy'yi veya tüneli Collie ile aynı ana makinede çalıştırın. Collie geridöngüden gelmeyen bağlantıları reddeder; bu nedenle başka bir makinedeki bir proxy bunun yerine D Varyantı gerektirir.

Ardından telefonu collie pair ile eşleyin. Bu kapıların hiçbiri hangi cihazın yazabileceğini bilmez; bunu eşleme belirler (Bir cihazı eşleyin).

KapıVarsayılan olarak gizliHTTPS sertifikasıEk adım
Tailscaleevet, yalnızca tailnetTailscale düzenlerHTTPS sertifikalarını bir kez etkinleştirin
Cloudflare Tunnelhayır, genelCloudflare düzenlerönde Cloudflare Access girişi
Nginx Proxy Managerana makineye bağlıdırLet's Encryptkapsayıcı için ana makine ağ iletişimi
NetBirdevet, yalnızca meshkendisine ait yokana makinede bir proxy, DNS sınaması
Caddyana makineye bağlıdırLet's Encrypt, otomatiközel bir ad için bir DNS eklentisi

Tailscale

Varsayılan ve Collie'nin bizzat yönettiği tek kapı: collie start, MagicDNS adınız üzerinde tailscale serve çalıştırır.

  1. Tailscale yönetim konsolunda DNS açın, MagicDNS'i etkinleştirin, ardından HTTPS'i etkinleştirin.
  2. Kendisini tailnet üzerinde yayımlayan Collie'yi başlatın.
    collie start
  1. .env dosyasında COLLIE_TRUSTED_USER değerini tailnet oturum açma adınıza ayarlayın, ardından yeniden başlatın.
    collie restart

Kalanını Varyant A halleder. Bu kapı için COLLIE_SKIP_SERVE ayarlamayın.

tailscale funnel Asla kullanın. Funnel, bağlantı noktasını herkese açık internete açar.

Cloudflare Tunnel

cloudflared Cloudflare'e doğru giden bağlantı kurar, bu sayede yönlendiricinizde hiçbir bağlantı noktası açılmaz. Ana makine adı herkese açıktır, dolayısıyla önünde bir oturum açma mekanizması bulunmalıdır.

  1. Oturum açın, bir tünel oluşturun ve bir ana makine adını bu tünele yönlendirin.
    cloudflared tunnel login
cloudflared tunnel create collie
cloudflared tunnel route dns collie collie.example.com
  1. create çıktısındaki tünel kimliği ile ~/.cloudflared/config.yml dosyasını yazın.
    tunnel: <tunnel-id>
credentials-file: /home/you/.cloudflared/<tunnel-id>.json
ingress:
  - hostname: collie.example.com
    service: http://127.0.0.1:8787
  - service: http_status:404
  1. Yeniden başlatmalardan sonra da çalışması için bu yapılandırma ile bir servis olarak yükleyin.
    sudo cloudflared --config ~/.cloudflared/config.yml service install
  1. Cloudflare Zero Trust'ta collie.example.com için yalnızca sizin e-postanıza izin veren bir ilke ile kendi sunucunuzda barındırılan uygulama ekleyin.

Zero Trust kontrol panelinde oluşturulan bir tünel de çalışır: genel ana makine adı servisini http://127.0.0.1:8787 olarak ayarlayın. cloudflared, genel ana makine adını Host olarak iletir; bu da COLLIE_PUBLIC_HOSTS tarafından beklenendir.

Uyarı. 4. adım olmadan, ana makine adını bulan herkes makinenizde bir kabuk elde eder. Cloudflare Access kapının kilididir; ardından eşleştirme hangi cihazın komut yazabileceğini belirler.
  1. Collie'nin kilidi denetlemesini sağlayın. Access uygulamasında Uygulama Hedef Kitlesi (AUD) etiketi değerini kopyalayın. Bunu ve takım adınızı .env dosyasına ekleyin, ardından yeniden başlatın.
    COLLIE_ACCESS_TEAM=myteam          # from myteam.cloudflareaccess.com
COLLIE_ACCESS_AUD=<the AUD tag>

    Tünel üzerinden gelen her istek artık Cloudflare tarafından bu uygulama için imzalanmış bir belirteç taşımalıdır. Access uygulaması silinirse, bir atlama kuralı alırsa veya henüz her uç noktaya ulaşmadıysa, Collie bölmeleri göstermek yerine isteği reddeder. Hedef kitle denetimi önemlidir: bir takımdaki her Access uygulaması aynı anahtarla imzalar, bu nedenle başka bir uygulama için olan belirteç de reddedilir.

    Collie, takımın genel anahtarlarını başlangıçta ve her saat başı alır. İlk alma işlemi başarılı olana kadar her uzak istek 503 alır. Daha sonraki bir alma işlemi başarısız olursa Collie elindeki anahtarları saklar. Her iki satırı da ayarlayın veya hiçbirini ayarlamayın: tek başına biri her uzak isteği reddeder. Her iki durumda da köprü günlüğü sorunu tek satırda belirtir, bu nedenle yeniden başlatmanın ardından günlüğü kontrol edin.

    Belirteci yalnızca bu makinedeki bir işlem atlar: Cf-* ve iletme üstbilgisi (X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Proto, Forwarded, X-Real-Ip) taşımayan, 127.0.0.1 veya localhost hedefine yönelik bir istek. Yazmak için yine de eşleştirme gerekir. /api/health ve mürettebat bağlantıları da belirteç gerektirmez. collie doctor bu tür bir yerel çağırıcıdır, bu nedenle yeşil bir doctor, anahtarların yüklendiğini veya bir belirtecin doğrulandığını göstermez. Bunu kontrol etmek için ana bilgisayar adını telefondan açın. Gerekçeler ADR 0081 içindedir.

    Geçit açıkken şu kuralları koruyun:

    - Aynı anda tek bir ön kapı. Access etkinken tailscale serve, Caddy veya Traefik üzerinden gelen bir istek de belirteç gerektirir; çünkü bunlar varsayılan olarak bir yönlendirme başlığı ekler. Hem bir tünel hem de bir tailnet adı (tailscale serve) sunan bir makine, tarayıcılar için tailnet kapısını kaybeder: bu istekler Access belirteci taşımaz ve 401 alır. - cloudflared ile Collie arasında istekleri yerel gösteren ikinci bir proxy olmamalıdır. Host değerini 127.0.0.1 veya localhost olarak yeniden yazan ve Cf-* ile yönlendirme başlıklarını kaldıran bir yapılandırma bunu kasten yapar. Yalın bir nginx proxy_pass http://127.0.0.1:8787 bunu varsayılan olarak yapar: Host: 127.0.0.1:8787 gönderir ve siz yapılandırmadıkça yönlendirme başlığı eklemez. Bu istekler belirteci atlar. cloudflared adresini doğrudan Collie tarafına yönlendirin. - Collie yolları için Access atlama kuralları eklemeyin; manifest, service worker veya simgeler için değil. Access, geçişine izin verdiği her isteğe belirteci ekler. Atlanan bir yol belirteç taşımaz, bu nedenle Collie 401 yanıtı verir.

Access, oturum açmak için /cdn-cgi/access/ adresine yönlendirir. /auth/ yönlendirme ve önbelleğe alma belirtildiği gibi, sw.js ve index.html önbelleğe alınmamış olarak tutun.

Nginx Proxy Manager

Dahili bir web arayüzü ve Let's Encrypt içeren bir ters proxy. Docker içinde çalışır ve bir kapsayıcının içinde 127.0.0.1, ana makineniz değil, kapsayıcının kendisidir.

  1. Loopback üzerinden Collie'ye erişebilmesi için kapsayıcıya ana makinenin ağını verin.
    services:
  npm:
    image: jc21/nginx-proxy-manager:latest
    network_mode: host
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt
  1. Web arayüzünü 81 numaralı bağlantı noktasında açın ve bir Proxy Host ekleyin: alan adı collie.example.com, şema http, yönlendirme 127.0.0.1, bağlantı noktası 8787.
  2. SSL sekmesinde bir Let's Encrypt sertifikası talep edin ve SSL'i zorunlu kılın ayarını açın.

Service worker'ın güncellenebilmesi için Varlıkları Önbelleğe Al ayarını kapalı bırakın. Collie düz HTTP üzerinden sorgu yapar, bu nedenle Websockets Desteği anahtarı fark etmez.

Yalnızca ağınızın içinde çözümlenen bir ad için, SSL sekmesinde Bir DNS Challenge Kullanın seçeneğini belirleyin. Let's Encrypt özel bir ana bilgisayara HTTP üzerinden erişemez.

host-gateway ile Uyarı. host.docker.internal burada çalışmaz. Docker köprü adresine ulaşır ve Collie yalnızca 127.0.0.1 üzerinde dinler.

Proxy internete açıksa, proxy ana bilgisayarına bir Erişim Listesi ekleyin veya yönlendiricide 80 ve 443 numaralı bağlantı noktalarını kapalı tutup ana bilgisayara bir VPN üzerinden erişin.

NetBird

NetBird, tailnet benzeri bir WireGuard ağıdır. Trafiği taşır ve ana bilgisayardaki bir ters proxy HTTPS ekler.

  1. Ana bilgisayarı ve telefonu aynı NetBird ağına dahil edin.
    netbird up
  1. collie.example.com için bir DNS kaydını ana bilgisayarın NetBird adresine (100.x.y.z) yönlendirin.
  2. Ana bilgisayarda, bu adrese bağlı ve bir DNS challenge sertifikasına sahip Caddy çalıştırın.
    collie.example.com {
    bind 100.x.y.z
    tls {
        dns cloudflare {env.CF_API_TOKEN}
    }
    reverse_proxy 127.0.0.1:8787
}

DNS challenge, Let's Encrypt ana bilgisayara erişmeden etki alanının sahibi olduğunuzu kanıtlar; böylece ad özel bir adresi gösterebilir. Caddy, sağlayıcınız için DNS eklentisine ihtiyaç duyar, örneğin xcaddy build --with github.com/caddy-dns/cloudflare.

host.netbird.cloud gibi bir NetBird eş adı herkese açık olarak güvenilen bir sertifikaya sahip değildir, bu nedenle sahibi olduğunuz bir etki alanını kullanın. Aynı yöntem ZeroTier veya başka herhangi bir ağ için de geçerlidir.

Caddy

Caddy kendi sertifikasını alır ve yeniler. 80 ve 443 numaralı bağlantı noktalarından erişilebilen bir ana bilgisayarda yapılandırmanın tamamı şudur:

collie.example.com {
    reverse_proxy 127.0.0.1:8787
}

Özel bir ad için, yukarıdaki NetBird bölümünden tls { dns … } bloğunu ekleyin. Herkese açık bir ana bilgisayarın önünde, Varyant C içinde olduğu gibi bir oturum açma mekanizması da gerekir.

---

Collie'yi bir yol altında sunma

Tek bir sürüm derlemesi herhangi bir bağlama noktasına hizmet verir. Yolu .env örneğinde (veya config.toml içindeki [serve] base_path değerinde) ayarlayın, yeniden başlatın; köprü uygulamayı, varlıklarını ve /api/* öğesini bu yol altında sunar:

# https://<your-node>/collie/ — leading and trailing slash both optional; the bridge adds them
COLLIE_BASE_PATH=/collie

Kabul edilen: /collie, collie/, /apps/collie/. Reddedilen (günlükte tek bir satırla ve yerine kök kullanılarak): bir . veya .. bölümü, boşluk karakteri, ?, #. collie doctor, bağlama noktasını front-door satırında yazdırır.

Varsayılan ön kapı ile, collie serve (ve her collie start), kök yerine tailscale serve --set-path=/collie/ yayınlar; böylece başka bir uygulama aynı düğümde / tutabilir. Tailscale proxy uygulamadan önce bağlama noktasını ayıklar ve köprü bu yolu taşımaya devam eden bir isteği de kabul eder; bu sayede ters proxy her iki şekilde de çalışır. Sizinkini kontrol etmek için:

curl -s https://<your-node>/collie/api/health   # JSON, not HTML, means the mount is right

Kendi proxy'nizin arkasında (Varyant C), köprüyü aynı yola bağlayın. Caddy: handle_path /collie/* { reverse_proxy 127.0.0.1:8787 }. Nginx: location /collie/ { proxy_pass http://127.0.0.1:8787/; }. COLLIE_PUBLIC_URL ayarlarsanız yolu dahil edin: https://collie.example.com/collie/.

Bağlama noktası değişikliği, telefonda yeni bir uygulama demektir. Yüklü PWA'nın kapsamı ve kimliği, yüklendiği yoldur. COLLIE_BASE_PATH değerini değiştirdikten veya köke geri döndükten sonra, ana ekran simgesini kaldırın ve yeni adresten tekrar ekleyin; eski simge, köprünün artık hizmet vermediği bir yolu göstermeye devam eder. Köprünün kendisi yalnızca bir yeniden başlatmaya ihtiyaç duyar ve collie serve kapıyı kendi başına taşır: yeni kaydı yayınlamadan önce kaydının adlandırdığı eşlemeyi kaldırır.

---

Tek bir ana makinede birden fazla Collie

Paylaşılan bir sistemde kullanıcı başına bağımsız örnekler barındırmak için (ADR 0001):

# ~/.config/herdr/plugins/config/herdr.collie/.env — one per Unix user
# this user's loopback bridge port — unique per user
COLLIE_PORT=8801
# this user's tailnet https listener — unique per user
COLLIE_SERVE_PORT=8443
COLLIE_TRUSTED_USER=dev-a@example.com  # only this tailnet login may drive these agents

Bağımsız ikili URL kontrolü: bin/collie url. Herdr eklentisi URL kontrolü: herdr plugin action invoke url --plugin herdr.collie.

Gereksinimler:

  • Farklı Unix kullanıcıları ve ayrı herdr/Collie örnekleri çalıştırın.
  • Bağlantı noktası başına erişimi kısıtlamak için her zaman COLLIE_TRUSTED_USER ayarlayın.
  • İlk Tailscale bağlamaları operatör kurulumu gerektirir: bin/collie serve (veya Herdr eşdeğeri) komutunu operatör ayrıcalıklarıyla çalıştırın.

COLLIE_SERVE_PORT, bir örneğin giriş bağlantı noktasını ayarlar. COLLIE_INSTANCE, aynı ana bilgisayarda kendi servis birimi ve yapılandırması olan yalıtılmış bir örnek oluşturur (Tek bir konakta birden fazla Collie örneği).

---

Tek bir konakta birden fazla Collie örneği

Aynı makinede ikinci ve farklı bir Collie çalıştırmak için bu kurulumu kullanın. Kararlı bir sürümü çalışan bir kopyanın yanında çalıştırmak veya Herdr tarafından yönetilen varsayılanın yanında ikinci bir çoklayıcı (tmux/zellij) çalıştırmak buna örnektir. Her örnek özel bir bağlantı noktası, yapılandırma, durum dizini ve servis birimi alır. Bu, Unix kullanıcısı başına bir örnek ayıran Tek bir ana makinede birden fazla Collie yönteminden farklıdır. Burada tek bir kullanıcı birden fazla örnek çalıştırır.

İkinci örneği oluşturun

Örneği adlandırmak için COLLIE_INSTANCE=<name> ayarlayın. Ad [a-z0-9-]{1,16} ile eşleşmelidir. Adlandırılmış bir örnek ayrıca açık bir COLLIE_PORT gerektirir. Bu bağlantı noktası eksikse CLI bir hatayla çıkar; hiçbir varsayılan değer çıkarımı yapmaz.

~/.config/herdr/plugins/config/herdr.collie-<name>/.env oluşturun:

COLLIE_INSTANCE=<name>        # required — [a-z0-9-], max 16 chars
COLLIE_PORT=8788              # required for a named instance — no default is inferred
# Unset, this defaults to ~/.local/state/collie, with no instance suffix
COLLIE_STATE_DIR=/home/you/.local/state/collie-<name>

COLLIE_INSTANCE, COLLIE_PORT ve COLLIE_STATE_DIR değerlerinin tümü bu .env dosyasında bulunabilir. Birleştirilen ortam örneği çözer. HERDR_PLUGIN_CONFIG_DIR, CLI'nın yapılandırmayı aradığı dizini geçersiz kılar.

Örnek başına bir servis birimi çalıştırın

collie start, ortam örneği belirlediğinde birimi yazar. Operatör bunu elle yazmaz. macOS üzerinde bunun yerine ~/Library/LaunchAgents/ altına bir launchd plist yazar. Birim COLLIE_PORT, COLLIE_INSTANCE, COLLIE_PLUGIN_ROOT, HERDR_PLUGIN_CONFIG_DIR ve EnvironmentFile=-<config dir>/.env değerlerini ayarlar. ExecStart üzerindeki --instance <name>, yalnızca tek bir ikili dosyayı paylaşan iki örneğin kendi köprülerini ayırt edebilmesi için mevcuttur (cli/unit.ts systemdUnit()):

ExecStart=<root>/bin/collie _exec-bridge --instance <name>
Environment=COLLIE_PORT=8788
Environment=COLLIE_INSTANCE=<name>
Environment=COLLIE_PLUGIN_ROOT=<root>
Environment=HERDR_PLUGIN_CONFIG_DIR=<config dir>
EnvironmentFile=-<config dir>/.env

CLI, örnek başına bir tailscale serve işleyici dosyası tutar; bu sayede bir örnek üzerinde unserve çalıştırmak başka bir örneğin eşlemesini silmez.

CLI'dan adlandırılmış bir örneği hedefleyin

Her CLI fiili (pair, devices, url, qr, crew …, logs, push-test, …) hedef örneğini süreç ortamından çözer. Fiili çağırmadan önce COLLIE_INSTANCE değerini ayarlayın:

COLLIE_INSTANCE=next bin/collie pair
COLLIE_INSTANCE=next bin/collie devices list

COLLIE_INSTANCE olmadan CLI, Herdr'ı sorgular. Herdr yalnızca soneksiz eklentiyi izler, bu nedenle komut ilk örneğe karşı yürütülür. Yanlış örneği değiştirmeyi önlemek için tek bir ana bilgisayarda birden fazla örnek çalıştırırken COLLIE_INSTANCE değerini her zaman açıkça ayarlayın.

Reddetme kuralı

COLLIE_INSTANCE ayarlanmışsa ancak herdr.collie-<name>/.env eksikse CLI bir hata vererek çıkar. Başka bir örneğin yapılandırmasına geri dönmez.

Eşleştirme örnek başınadır

collie pair, ilgili örneğin durum dizinine bir eşleştirme kodu yazar. Yazdırdığı QR kodu bu örneğin kendi URL'sini kodlar; çünkü her örneğin kendi durum dizini ve COLLIE_PUBLIC_URL veya kendi bağlantı noktası üzerinden kendi giriş kapısı vardır. Telefonda ilgili örneğin özel URL'sini açın ve Ayarlar → Sistem → Eşleştirilmiş cihazlar altından kodu girin. Bir örnek için üretilen kod, bir cihazı başka bir örnekle eşleştiremez (Bir cihazı eşleyin).

---

Yedek kapı: bir ekibin yük devretme yolu

crew dağıtımları içindir. Lider erişilemez hale gelirse görevi devralması için önceden yetkilendirilmiş bir deputy yapılandırır (ADR 0027, ADR 0028, CREW_PROTOCOL.md §18).

Deputy ve lider ayarları:

AnahtarVarsayılanİşlevi
COLLIE_STANDBY_PORT(ayarlanmamış)Bekleme dinleyicisinin bağlantı noktası. Ayarlanmaması bekleme kapısını devre dışı bırakır. Lider ve deputy üzerinde eşleşmelidir.
COLLIE_STANDBY_HOST127.0.0.1Bağlanma adresi (yerel vekiller için 127.0.0.1, uzak için örtü ağı IP'si).
COLLIE_STANDBY_ARM_MSmax(30000, 2.5 × COLLIE_POLL_IDLE_MS)Devreye girmeden önce gereken lider sessizlik süresi.

Hem lider hem de deputy üzerinde COLLIE_STANDBY_PORT değerini aynı ve kullanılmayan bir bağlantı noktasına ayarlayın.

Ön koşul: bir ana bilgisayar adı, iki arka uç

PWA kaydını ve cihaz kimlik bilgilerini paylaşmak için lider ve deputy aynı kaynaktan sunulmalıdır. Birleşik giriş noktası olmayan bağımsız bir ekip bin/collie promote aracılığıyla kurtarılır (veya Herdr: herdr plugin action invoke promote --plugin herdr.collie; CREW_PROTOCOL §14.4).

Örnek Traefik yapılandırması:

http:
  routers:
    collie:
      rule: "Host(`collie.example.com`)"
      service: collie-crew
      tls: {}

  services:
    collie-crew:
      failover:
        service: collie-lead
        fallback: collie-deputy

    collie-lead:
      loadBalancer:
        servers:
          - url: "http://lead.internal:8787"
        healthCheck:
          path: /standby/health
          interval: 5s
          timeout: 2s

    collie-deputy:
      loadBalancer:
        servers:
          - url: "http://deputy.internal:8788"   # COLLIE_STANDBY_PORT
        healthCheck:
          path: /standby/health
          interval: 5s
          timeout: 2s

Sistem durumu denetimi yanıtları: lider 200 döndürür (görevden alındığında 200 harici); deputy devreye girene kadar 503, ardından 200 döndürür.

Her şey sağlıklıyken bir kez kurun

Lider üzerinde bağımsız kurulum:

bin/collie pair
bin/collie crew deputy nas
bin/collie crew status

Lider üzerinde Herdr kurulumu:

herdr plugin action invoke pair --plugin herdr.collie
herdr plugin action invoke crew --plugin herdr.collie deputy nas
herdr plugin action invoke crew --plugin herdr.collie status

Deputy üzerinde COLLIE_STANDBY_PORT=8788 yapılandırın ve yeniden başlatın. Deputy warrant dosyasını yüklemek için tüm eşlerin yeniden başlatıldığından emin olun. https://collie.example.com/standby adresinde doğrulayın.

⚠️ deputy denetlenmelidir

Devralma sırasında deputy durumu yazar ve süreç yeniden başlatmasını (bridge/index.ts) tetiklemek için 75 (EX_TEMPFAIL) durum koduyla çıkar.

Denetleyicinin sıfır dışı çıkış kodlarında yeniden başladığından emin olun (systemd: Restart=always veya Restart=on-failure).

Kötü gün: Çalışma kitabı

  1. https://collie.example.com adresini açın.
  2. lead sağlıksız olduğunda proxy /standby adresine yönlendirir.
  3. deputy bekleme durumunu inceleyin.
  4. Devral seçeneğini belirleyin.
  5. deputy eş konsensüsünü doğrular, warrant uygular ve 75 koduyla çıkar.
  6. Denetleyici süreci yeniden başlatır; PWA yeni lead olarak yeniden yüklenir.

Kurtarma sonrası:

  • Önceki lead, yeniden bağlandığında kendini görevden alır (CREW_PROTOCOL.md §8.4).
  • Görevden alınan düğümün eş adresini güncelleyin: Bağımsız bin/collie crew set-address <member> <host:port> veya Herdr herdr plugin action invoke crew --plugin herdr.collie set-address <member> <host:port>.
  • Yeni bir deputy atayın: Bağımsız bin/collie crew deputy <member> veya Herdr herdr plugin action invoke crew --plugin herdr.collie deputy <member>.
  • Tüm üyeler yeniden bağlanana kadar crew rotate çalıştırmayın.

Bu sayfayı GitHub üzerinde düzenleyin

The rest of the documentation