Ana içeriğe geç

API Portal — Docker

Bu rehber Apinizer API Portal'ın Docker konteyneri olarak nasıl çalıştırılacağını anlatır. Portal geliştirici-yüzlü UI'dır: API'leri listeler, abonelikleri yönetir, dokümantasyonu sunar. Veriyi Apinizer Manager REST API'sinden alır — Portal'dan doğrudan MongoDB bağlantısı yoktur.

bilgi

Portal stateless'tır: her konteyner restart'ı güvenlidir, yatay ölçeklendirme için bir load balancer arkasında birden fazla replika çalıştırılabilir.

Gereksinimler​

  • Docker Engine 24+ kurulu bir Linux x86-64 host
  • Erişilebilir bir Apinizer Manager ve geçerli bir Manager API key
  • Boş bir TCP port (varsayılan 8080; Manager ile aynı host'taysa 8081'e remap edin)

1. İmajı çekin​

VERSION=<APINIZER_VERSION>
docker pull apinizercloud/apiportal:${VERSION}

2. Portal'ı Manager'a kaydedin​

Konteyneri başlatmadan önce Manager UI'da Portal'ı bir kez kaydedin:

  1. Manager UI'da Portal → Portals → Create. Üretilen Portal ID'yi not edin.
  2. Portal → API Keys → Generate ile API key oluşturun (sadece bir kez gösterilir).
  3. Bu API key için ayrı bir Manager kullanıcısı kullanın ve ona yalnız Portal Developer rolünü verin. Her Portal çağrısı için bir portal rolü gerekir. Portal Ayarları → Güvenlik → Management API Anahtarı Kullanıcıları listesinde kayıt varsa kullanıcıyı bu listeye de ekleyin. Liste boşsa rol yeterlidir. Aksi halde Manager Portal'ın tüm çağrılarını 403 ile reddeder. Bkz. Portal'ın Management API Anahtarı.

3. Yapılandırma​

Zorunlu:

DeğişkenAçıklama
API_PORTAL_ID2. adımdan gelen Portal kimliği
API_PORTAL_MANAGEMENT_API_BASE_URLManager REST API base URL (örn. https://manager.example.com)
API_PORTAL_MANAGEMENT_API_KEY2. adımdan gelen API key

Opsiyonel:

DeğişkenVarsayılanAçıklama
SERVER_PORT8080Konteyner içi HTTP portu
SPRING_PROFILES_ACTIVEprodÜretimde böyle kalsın
SSL_ENABLEDfalsetrue yapılırsa konteyner içinde TLS sonlandırılır
JAVA_OPTSboşEk JVM bayrakları

4. Konteyneri çalıştır​

docker run -d \
--name apinizer-apiportal \
-p 8081:8080 \
--memory=2g \
-e API_PORTAL_ID='portal-prod-01' \
-e API_PORTAL_MANAGEMENT_API_BASE_URL='https://manager.example.com' \
-e API_PORTAL_MANAGEMENT_API_KEY='<api-key>' \
-e SPRING_PROFILES_ACTIVE=prod \
--restart unless-stopped \
apinizercloud/apiportal:${VERSION}
ipucu

API Manager zaten host 8080'i kullanıyorsa konteynerin 8080'ini host 8081'e map edin.

5. docker-compose​

services:
apiportal:
image: apinizercloud/apiportal:<APINIZER_VERSION>
container_name: apinizer-apiportal
restart: unless-stopped
mem_limit: 2g
ports:
- "8081:8080"
environment:
API_PORTAL_ID: portal-prod-01
API_PORTAL_MANAGEMENT_API_BASE_URL: https://manager.example.com
SPRING_PROFILES_ACTIVE: prod
env_file:
- ./secrets/apiportal.env # API_PORTAL_MANAGEMENT_API_KEY=… içerir
healthcheck:
test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:8080/apinizer/management/health | grep -q OK || exit 1"]
interval: 30s
timeout: 5s
retries: 5
start_period: 60s

6. Doğrulama​

curl -fsS http://127.0.0.1:8081/apinizer/management/health

Tarayıcıda http://<host>:8081/ açın. İlk sayfa yüklemesi katalogu Manager'dan çeker — Manager URL veya API key yanlışsa 502/timeout banner görünür.

7. Operasyon​

EylemKomut
Durumdocker ps --filter name=apinizer-apiportal
Logdocker logs -f apinizer-apiportal
Yeniden başlatdocker restart apinizer-apiportal
Durdurdocker stop apinizer-apiportal

İmajlar logları konteyner konsoluna yazar; log volume'u gerekmez. Logları docker logs ile okuyun. Spring Boot ayrıca Manager ve Portal konteynerlerinde /tmp/spring.log adlı dönen bir dosyaya yazar; bu dosya kalıcı değildir.

8. TLS sonlandırma​

İki yaygın yaklaşım:

  1. Önünde reverse proxy (önerilen): nginx, Traefik veya bir LB üzerinde TLS sonlandır; konteynerde SSL_ENABLED=false kalsın.

  2. Konteyner içi TLS: PKCS#12 keystore mount edin:

    environment:
    SSL_ENABLED: "true"
    SSL_KEY_STORE: /run/keystore/portal.p12
    SSL_KEY_STORE_TYPE: PKCS12
    SSL_KEY_STORE_PASSWORD: <password>
    SSL_KEY_ALIAS: apinizer
    SSL_PROTOCOLS: TLSv1.2,TLSv1.3
    volumes:
    - ./secrets/portal.p12:/run/keystore/portal.p12:ro

9. Çoklu replika​

Portal stateless. Çoklu replika için:

  • Her replikaya aynı API_PORTAL_ID'yi verin.
  • Önüne bir LB koyun.
  • Sticky session gerekmez.

Sorun Giderme​

Konteyner sürekli restart, log'da Required configuration is missing​

Portal başlarken üç değişkeni denetler ve eksik olanları log mesajında yazar. Üçünü de verin: API_PORTAL_ID, API_PORTAL_MANAGEMENT_API_BASE_URL, API_PORTAL_MANAGEMENT_API_KEY.

Ana sayfa 502 Bad Gateway dönüyor​

Portal Manager REST API'ye erişemiyor. Konteyner içinden kontrol:

docker exec apinizer-apiportal sh -lc \
"wget --header='Authorization: $API_PORTAL_MANAGEMENT_API_KEY' \
-qO- $API_PORTAL_MANAGEMENT_API_BASE_URL/apiportal/management/hello"