Mimari ve barındırma

Bu sayfa, oyununuzu Open Play ile nasıl konumlandıracağınızı anlatır: yığının parçaları, tarayıcı oyunlarının Open Play’i doğrudan (CORS) ya da ters vekille nasıl çağıracağı, ortama alan adı bağlama ve çerez/TLS gereksinimleri. Bir tarayıcı ya da WebGL oyunu yayımlayacaksanız bu sayfayı baştan sona okuyun.

Neyin nerede çalıştığı

Referans dağıtım bir Docker Compose yığınıdır:

Oyuncu tarayıcısı ──HTTPS──▶ oyun.example.com ─┬─ /            ▶ oyununuzun statik dosyaları
                                               └─ /open-play/* ▶ Open Play public-gateway ▶ api
Oyun sunucunuz ───────HTTPS──────────────────────────────────▶ Open Play public-gateway ▶ api
Open Play worker ──imzalı webhook──────────────────────────────▶ sizin sunucunuz

Public TLS, bu yığının içinde sonlandırılmaz; Cloudflare, bir yük dengeleyici ya da bir Caddy/nginx girişi gerekir. Panel çerezi Secure olduğundan panel de HTTPS ister. Kurulum, kaynak bütçeleri ve ağ ayrıntıları için üretim dağıtımı rehberine (docs/production-and-adapters.tr.md) bakın.

Not

gRPC arayüzü oyun geliştiricisi için dışa açık bir kanal değildir; varsayılan olarak yalnız loopback’te dinler ve SDK’lar onu kullanmaz.

Tarayıcıdan çağrı: doğrudan CORS ya da ters vekil

Oyununuzun alan adı ortamın alan adı listesindeyse tarayıcı oyununuz Open Play’i doğrudan çağırabilir. Sunucu, kamusal API’de (panel ve kurulum uçları hariç) CORS (cross-origin resource sharing, çapraz kaynak paylaşımı) başlıkları gönderir. İzin kümesi, panelde Oyun ayarları › Ortamlar ve alan adları altında tüm ortamlara yazılmış alan adları ile operatörün genel izinli listesinin (CRX_AUTH_TRUSTED_ORIGINS) birleşimidir; oyuna özel bir ayar yoktur. Örneğin oyun https://oyun.example.com adresinde, Open Play https://open-play.example.com adresinde çalışıyorsa ve oyun.example.com bir ortamın alan adıysa, oyun baseUrl: "https://open-play.example.com/open-play" ile doğrudan konuşur.

Kurallar:

• İzinli origin tam olarak https://<alan adı> biçimindedir (yol yok, varsayılan olmayan port yok). Yanıt Access-Control-Allow-Origin olarak o origin’i aynen yansıtır ve Access-Control-Allow-Credentials: true ekler; * hiçbir zaman kullanılmaz, bilinmeyen origin’e başlık verilmez.
• Önkontrol (preflight, OPTIONS) izinli origin için 204, izinsiz için 403 döner; Access-Control-Max-Age 600 sn’dir.
• Üretim dışı ortamlarda (CRX_ENV development ya da test) listede localhost ya da 127.0.0.1 varsa http://localhost:<port> ve http://127.0.0.1:<port> de izinlidir.
• Panelde yeni eklenen alan adı en geç birkaç saniyede (sunucu anlık görüntüsü 5 sn’de bir yenilenir) geçerli olur.
• CORS yetki değildir. Origin/CSRF/ortam denetimleri aynen çalışır; CORS yalnız tarayıcının yanıtı okumasına izin verir. Panel yolu (/v1/panel/*) hiçbir koşulda CORS başlığı almaz. Gerçek zamanlı WebSocket el sıkışması değişmedi: Origin ortam başına denetlenir.

Uyarı

Oturum çerezi aynı site ister. Çerezler __Secure-, HttpOnly, SameSite=Lax ile yazılır. Oyun, Open Play’den farklı bir kayıtlı alan adındaysa (ör. oyun.example.com ve open-play.baska.dev) tarayıcı çapraz-site fetch isteklerine oturum çerezini eklemez; CORS başlıkları doğru olsa da oturum kurulamaz. Aynı kayıtlı alan adının alt alanları (ör. oyun.example.com ve open-play.example.com) aynı sitedir ve çalışır. Farklı sitede bu desteklenmez; bu durumda aşağıdaki ters vekili kullanın.

Ters vekil hâlâ bir seçenektir. Oyunu ve API’yi aynı origin’den sunmak istiyorsanız (ya da oyun farklı bir sitedeyse), oyunun kendi ağ geçidinde API yolunu Open Play’e yönlendiren bir ters vekil (reverse proxy) kurarsınız; bu durumda CORS devreye girmez. Örnek (Caddy):

oyun.example.com {
  # /open-play/ önekini sıyırıp Open Play public-gateway'e iletir.
  handle_path /open-play/* {
    reverse_proxy open-play-gateway:8080
  }
  # Geri kalan her şey oyununuzun statik dosyaları.
  handle {
    root * /srv/oyun
    try_files {path} /index.html
    file_server
  }
}

Ters vekil kurulumunda istemci tarafı ayarı şudur:

Ters vekilde dikkat edin:

• WebSocket yükseltmesi (Upgrade/Connection) geçmelidir; gerçek zamanlı bağlantı /v1/realtime/ws üzerindedir. Caddy reverse_proxy bunu kendiliğinden yapar; nginx’te proxy_http_version 1.1 ve Upgrade başlıklarını açıkça verin.
• Origin ve Cookie başlıkları olduğu gibi iletilmelidir.
• İstemci IP’si: X-Forwarded-For başlığını doğru yazın. Önde fazladan bir vekil varsa ve sunucuya güvenilen vekil adresleri tanıtılmadıysa bütün oyuncular tek IP kovasına düşer; belirtisi, farklı oyuncuların aynı anda 429 almasıdır. Bunu operatör ekibinizle çözün (bkz. Oran sınırları).
• Panel yolunu açmayın. /v1/panel/* yolu public-gateway’de 404’tür; oyun alan adınız üzerinden panele yol vermeyin.

Çerez davranışı

Secure çerezler HTTPS ister. Yerel geliştirmede SDK’lar yalnız loopback adreslerinde (localhost, 127.0.0.1, ::1) düz http’ye izin verir; tarayıcınızın localhost için Secure çerezleri kabul edip etmediğini denetleyin, kabul etmiyorsa yerelde de HTTPS kullanın.

Alan adları ve güvenilir origin

Tarayıcı, durum değiştiren (POST, PUT, PATCH, DELETE) isteklere Origin başlığı ekler. Sunucu bu origin’in ilgili ortama bağlı bir alan adı olup olmadığını denetler:

• Ortama bağlı alan adı: panelde Oyun ayarları › Ortamlar ve alan adları › Alan adları alanına yazdığınız adlardır. Her satır tam bir alan adıdır (örneğin oyun.example.com); joker karakter, IP ve port yoktur; ortam başına en çok 10 alan adı bağlanabilir. Aynı alan adı iki ortama bağlanamaz (409).
• Genel izinli liste: operatörün sunucu ayarıdır (CRX_AUTH_TRUSTED_ORIGINS: tam alan adı ya da *.alan). Ortamın kendi alan adı yoksa bu liste geçerlidir.
• Bir alan adı başka bir ortama bağlıysa o alan adından gelen tarayıcı, bu ortama yazamaz ve bu ortamı okuyamaz (403).
• Origin göndermeyen istemciler (oyun sunucunuz, curl gibi tarayıcı dışı istemciler) origin denetimine takılmaz; onları çerez kullanıyorlarsa CSRF çift gönderim koruması denetler.
• Sec-Fetch-Site: cross-site ile Sec-Fetch-Mode: navigate birlikte geliyorsa durum değiştiren istek reddedilir.

Gerçek zamanlı bilet de aynı origin kuralına bağlıdır: bilet tek kullanımlıktır ve alındığı origin’e bağlıdır.

Not

Unity yerel derlemeleri, bilet ve WebSocket isteklerinde yapılandırmadan türetilen sabit bir Origin gönderir (BaseUrl’in şeması, alan adı ve varsayılan olmayan portu; NativeOrigin ile değiştirilebilir). Bu origin’in ortamın alan adlarında ya da genel izinli listede bulunması gerekir. Bkz. Unity SDK.

Alan adı bağlama adımları: Ortamlar ve alan adları.

Oyun sunucunuzdan çağrı

Oyun sunucunuz sunucu anahtarıyla Open Play’e doğrudan (HTTPS) bağlanır. Ters vekil, CORS ya da alan adı bağlaması gerekmez (CORS yalnız tarayıcıyı ilgilendirir); ortam anahtardan çıkar. Anahtarı yalnız sunucu ortamında (ortam değişkeni ya da gizli yönetimi) tutun.

Oyuncunun kimliğini sunucunuzda doğrulamak için erişim JWT’sini çevrimdışı doğrulayabilirsiniz: Sunucuda doğrulama.

Webhook’lar (Open Play → sizin sunucunuz)

Worker, olayları imzalı HTTPS isteği olarak sizin adresinize gönderir. Adresiniz genel erişilebilir olmalı ve imzayı doğrulamalıdır. Bkz. Webhook’lar ve Güvenlik.

Yayın öncesi kontrol

Üretim kontrol listesi alan adı bağlama, anahtar yönetimi, TLS ve izleme maddelerini toplar.