Üretimde CaptchaAI: Yapılandırma Yönetimi Kılavuzu

CaptchaAI'yi üretimde doğru yapılandırmanın özü tek bir kuralda toplanır: ayarlar koda gömülmez, katmanlı bir hiyerarşiden okunur. En üstte ortam değişkenleri, altında sürüm kontrolündeki yapılandırma dosyası, en altta da kodun içindeki varsayılanlar bulunur. API anahtarı gibi gizli diziler ise hiçbir zaman depoya girmez.

Bu referans, CaptchaAI worker'larınızı yeniden konuşlandırmadan yönetmek için gereken parametreleri, yükleyici kodunu ve gizli dizi yaklaşımlarını bir araya getirir. Freelance bir otomasyon işini teslime yetiştirirken de, ölçeklenen bir veri kazıma hattını işletirken de aynı yapı işinizi görür.

Yapılandırma önceliği: üç katmanlı hiyerarşi

Etkin yapılandırma tek bir yerden değil, öncelik sırasına göre üç katmandan çözülür. Operatöre en yakın katman kazanır:

• Ortam değişkenleri — dağıtıma özel geçersiz kılmalar; en yüksek öncelik.
• Yapılandırma dosyası (YAML/JSON) — sürüm kontrolündeki varsayılanlar.
• Uygulama varsayılanları — kodun içine gömülü son çare değerleri.

Priority (highest → lowest):

1. Environment variables     ← deployment-specific overrides
2. Config file (YAML/JSON)   ← version-controlled defaults
3. Application defaults      ← fallback values in code

Ortam değişkenleri yapılandırma dosyasını, dosya da kodun içindeki varsayılanları geçersiz kılar. Servisiniz destekliyorsa ortam değişkenlerinin üstüne bir komut satırı (CLI) bayrak katmanı da ekleyebilirsiniz; mantık aynı kalır.

Tüm yapılandırma parametreleri

Aşağıdaki tablo, bir CaptchaAI worker'ının okuduğu her ayarı, ilgili ortam değişkenini ve varsayılan değerini listeler. Ortam değişkeni adlarını olduğu gibi kullanın.

CAPTCHAAI_CONCURRENCY, aynı anda kaç CAPTCHA görevinin uçtuğunu belirler ve doğrudan planınızın thread sayısıyla sınırlıdır. CaptchaAI thread bazlı faturalandırır ve her thread'de sınırsız çözüm sunar: BASIC ($15/ay, 5 thread), STANDARD ($30/ay, 15 thread), ADVANCE ($90/ay, 50 thread). BASIC planında eşzamanlılığı 20'ye çıkarmak ek hız getirmez — fazla görevler beklemede kalır. Eşzamanlılığı thread sayınızın üstüne çıkarmayın.

Yapılandırmayı yükleyen kod

Yükleyici üç katmanı şu sırayla birleştirir:

1. Kod içindeki varsayılanları yükler.
2. Varsa yapılandırma dosyasını üzerine uygular.
3. Ortam değişkenlerini en son okuyarak her şeyi geçersiz kılar.

Ardından değerleri doğru tipe dönüştürür ve başlangıçta doğrulama yapar; böylece eksik API anahtarı gibi hatalar üretime değil, açılış anında ortaya çıkar.

Python

import os
import yaml
from dataclasses import dataclass, field
from pathlib import Path


@dataclass
class CaptchaAIConfig:
    api_key: str = ""
    submit_url: str = "https://ocr.captchaai.com/in.php"
    poll_url: str = "https://ocr.captchaai.com/res.php"
    poll_interval: int = 5
    max_polls: int = 60
    concurrency: int = 10
    timeout: int = 300
    proxy: str = ""
    callback_url: str = ""
    retries: int = 3
    log_level: str = "info"

    @classmethod
    def load(cls, config_path=None):
        """Load config: env vars override file, which overrides defaults."""
        config = cls()

        # Layer 2: Config file
        if config_path and Path(config_path).exists():
            with open(config_path) as f:
                file_config = yaml.safe_load(f) or {}
            for key, value in file_config.items():
                if hasattr(config, key):
                    setattr(config, key, value)

        # Layer 1: Environment variables (highest priority)
        env_map = {
            "CAPTCHAAI_API_KEY": "api_key",
            "CAPTCHAAI_SUBMIT_URL": "submit_url",
            "CAPTCHAAI_POLL_URL": "poll_url",
            "CAPTCHAAI_POLL_INTERVAL": "poll_interval",
            "CAPTCHAAI_MAX_POLLS": "max_polls",
            "CAPTCHAAI_CONCURRENCY": "concurrency",
            "CAPTCHAAI_TIMEOUT": "timeout",
            "CAPTCHAAI_PROXY": "proxy",
            "CAPTCHAAI_CALLBACK_URL": "callback_url",
            "CAPTCHAAI_RETRIES": "retries",
            "CAPTCHAAI_LOG_LEVEL": "log_level",
        }

        for env_key, attr_name in env_map.items():
            value = os.environ.get(env_key)
            if value is not None:
                # Cast to correct type
                current = getattr(config, attr_name)
                if isinstance(current, int):
                    value = int(value)
                setattr(config, attr_name, value)

        config.validate()
        return config

    def validate(self):
        if not self.api_key:
            raise ValueError("CAPTCHAAI_API_KEY is required")
        if self.poll_interval < 1:
            raise ValueError("poll_interval must be >= 1")
        if self.concurrency < 1:
            raise ValueError("concurrency must be >= 1")


# Usage
config = CaptchaAIConfig.load("config/captchaai.yaml")
print(f"Concurrency: {config.concurrency}, Timeout: {config.timeout}s")

JavaScript

const fs = require("fs");
const yaml = require("js-yaml");
const path = require("path");

class CaptchaAIConfig {
  static defaults = {
    apiKey: "",
    submitUrl: "https://ocr.captchaai.com/in.php",
    pollUrl: "https://ocr.captchaai.com/res.php",
    pollInterval: 5,
    maxPolls: 60,
    concurrency: 10,
    timeout: 300,
    proxy: "",
    callbackUrl: "",
    retries: 3,
    logLevel: "info",
  };

  static envMap = {
    CAPTCHAAI_API_KEY: "apiKey",
    CAPTCHAAI_SUBMIT_URL: "submitUrl",
    CAPTCHAAI_POLL_URL: "pollUrl",
    CAPTCHAAI_POLL_INTERVAL: { key: "pollInterval", type: "int" },
    CAPTCHAAI_MAX_POLLS: { key: "maxPolls", type: "int" },
    CAPTCHAAI_CONCURRENCY: { key: "concurrency", type: "int" },
    CAPTCHAAI_TIMEOUT: { key: "timeout", type: "int" },
    CAPTCHAAI_PROXY: "proxy",
    CAPTCHAAI_CALLBACK_URL: "callbackUrl",
    CAPTCHAAI_RETRIES: { key: "retries", type: "int" },
    CAPTCHAAI_LOG_LEVEL: "logLevel",
  };

  static load(configPath = null) {
    let config = { ...CaptchaAIConfig.defaults };

    // Layer 2: Config file
    if (configPath && fs.existsSync(configPath)) {
      const ext = path.extname(configPath);
      const raw = fs.readFileSync(configPath, "utf8");
      const fileConfig = ext === ".json" ? JSON.parse(raw) : yaml.load(raw);
      config = { ...config, ...fileConfig };
    }

    // Layer 1: Environment variables
    for (const [envKey, mapping] of Object.entries(CaptchaAIConfig.envMap)) {
      const value = process.env[envKey];
      if (value !== undefined) {
        const attrKey = typeof mapping === "string" ? mapping : mapping.key;
        const type = typeof mapping === "string" ? "string" : mapping.type;
        config[attrKey] = type === "int" ? parseInt(value, 10) : value;
      }
    }

    CaptchaAIConfig.validate(config);
    return config;
  }

  static validate(config) {
    if (!config.apiKey) throw new Error("CAPTCHAAI_API_KEY is required");
    if (config.pollInterval < 1) throw new Error("pollInterval must be >= 1");
    if (config.concurrency < 1) throw new Error("concurrency must be >= 1");
  }
}

// Usage
const config = CaptchaAIConfig.load("config/captchaai.yaml");
console.log(`Concurrency: ${config.concurrency}, Timeout: ${config.timeout}s`);

Ortama göre yapılandırma dosyaları

Ortak ayarları bir temel dosyada tutun, ortamlar arasında değişenleri ayrı dosyalara ayırın:

• Temel (base) — api_key alanı boş; ortak varsayılanlar burada.
• Üretim (production) — yüksek eşzamanlılık, düşük sorgulama aralığı, warning loglama.
• Staging — düşük eşzamanlılık, ayrıntılı debug günlükleri.

API anahtarı hiçbir dosyaya yazılmaz; her ortamda ortam değişkeninden gelir.

# config/captchaai.yaml — base
api_key: ""  # Always set via env var
concurrency: 5
poll_interval: 5
retries: 3
log_level: info

# config/captchaai.production.yaml
concurrency: 20
poll_interval: 3
timeout: 180
log_level: warning

# config/captchaai.staging.yaml
concurrency: 3
poll_interval: 5
timeout: 300
log_level: debug

Gizli dizi (secret) yönetimi

API anahtarlarını asla yapılandırma dosyalarında veya sürüm kontrolünde saklamayın. Bir kez depoya giren anahtar, geçmişte kalıcı olur ve depoya erişen herkese açık hale gelir. Anahtarı yalnızca ortam değişkeninden ya da bir gizli dizi yöneticisinden okuyun.

KVKK kapsamındaki kişisel verilerle çalışan ekipler için bu ayrım yalnızca güvenlik değil, denetim meselesidir de: yetkili bir gizli dizi yöneticisi, anahtara kimin ne zaman eriştiğini izlenebilir kılar.

Docker Compose örneği

services:
  captcha-worker:
    image: captcha-worker:latest
    environment:

      - CAPTCHAAI_API_KEY=${CAPTCHAAI_API_KEY}
      - CAPTCHAAI_CONCURRENCY=15
      - CAPTCHAAI_LOG_LEVEL=warning
    env_file:

      - .env.production

Sık karşılaşılan sorunlar ve çözümleri

Üretimde en çok görülen yapılandırma hataları ve hızlı çözümleri:

Özellik bayrakları (feature flags)

Yeniden konuşlandırma yapmadan yetenekleri açıp kapatın. Bayrakları ortam değişkenlerinden okuyarak callback kullanımını, proxy'yi veya eşzamanlılık tavanını çalışma anında değiştirebilirsiniz.

class FeatureFlags:
    def __init__(self):
        self.flags = {
            "use_callback": os.environ.get("FF_USE_CALLBACK", "false") == "true",
            "enable_proxy": os.environ.get("FF_ENABLE_PROXY", "true") == "true",
            "max_concurrent": int(os.environ.get("FF_MAX_CONCURRENT", "10")),
        }

    def is_enabled(self, flag):
        return self.flags.get(flag, False)

    def get(self, flag, default=None):
        return self.flags.get(flag, default)

Sık sorulan sorular

Eşzamanlılığı planımdaki thread sayısına göre nasıl seçmeliyim?

CAPTCHAAI_CONCURRENCY değerini planınızın thread sayısını aşacak şekilde ayarlamayın; fazlası beklemede kalır. CaptchaAI thread bazlı faturalandırır ve her thread'de sınırsız çözüm sunar, dolayısıyla BASIC ($15/ay, 5 thread) planında 5, ADVANCE ($90/ay, 50 thread) planında 50 civarı eşzamanlılık mantıklıdır.

API anahtarımı ne sıklıkla döndürmeliyim?

Anahtar sızdıysa hemen döndürün. Rutin uyumluluk için 90 günde bir rotasyon planlayın ve otomatik rotasyonu destekleyen bir gizli dizi yöneticisi kullanın.

Yapılandırma dosyalarını neden kaynak koduna koymamalıyım?

Gizli diziler depoya girerse commit geçmişinde kalıcı olur ve depoya erişen herkes görebilir. api_key alanını temel dosyada boş bırakın, anahtarı yalnızca ortam değişkeninden veya gizli dizi yöneticisinden okuyun.

Üretim, yanlış ortam ayarlarını kullanıyorsa ne yapmalıyım?

Önce katman önceliğini kontrol edin: ortam değişkenleri dosyayı, dosya da varsayılanları geçersiz kılar. NODE_ENV / APP_ENV değerinin doğru ortamı gösterdiğini ve üretim yapılandırma dosyasının gerçekten yüklendiğini doğrulayın.

Aynı yapılandırma tüm CAPTCHA türleri için geçerli mi?

Evet, bu yapılandırma türden bağımsızdır. CaptchaAI reCAPTCHA v2/v3, Cloudflare Turnstile ve Challenge, GeeTest v3, görüntü/OCR, grid ve BLS türlerini çözer; CaptchaFox (beta), Friendly Captcha (beta) ve Lemin (beta) beta aşamasındadır. hCaptcha ve FunCaptcha desteklenmez, GeeTest v4 ise çok yakında.

İlgili makaleler

• SOCKS5 proxy ile CaptchaAI kurulum yapılandırması
• Ekipler için çoklu kullanıcı API anahtarı yönetimi
• CaptchaAI proxy yapılandırma rehberi

Sonraki adımlar

Yapılandırmanızı üretime hazır hale getirin: yukarıdaki şablonları temel alın ve gizli dizileri ortam değişkenlerine taşıyın. CaptchaAI API anahtarınızı alın ve ilk worker'ınızı kurun.

İlgili kılavuzlar:

• API anahtarı güvenliği ve IP beyaz listesi
• Docker ile konteynerli CAPTCHA çözümü
• Çok bölgeli çözüm mimarisi