Ansible ile CaptchaAI Worker Dağıtımı ve Yönetimi

Tek bir sunucuda CAPTCHA çözen bir worker çalıştırmak kolaydır; aynı worker'ı on beş sunucuda aynı sürüm, aynı yapılandırma ve sıfır kesintiyle güncel tutmak ise elle yönetilebilecek bir iş değildir. Ansible bu tekrarı sizin yerinize üstlenir: worker'ı sunucu filonuza dağıtır, yapılandırma değişikliklerini tek komutla iter ve rolling update ile sürüm geçişini kesintiye uğratmadan yürütür.

Bu rehber, CaptchaAI çözme worker'larını üretimde çalıştırmak için eksiksiz bir Ansible yapısı sunar: yeniden kullanılabilir bir rol, ortam bazlı envanter dosyaları ve dağıtım, güncelleme ve sağlık kontrolü için üç ayrı playbook. İş bölümü nettir — altyapıyı (sunucular, ağlar) Terraform oluşturur, o sunucuların üzerine yazılımı kuran ve yapılandıran katman ise Ansible'dır. İkisi birlikte, elle SSH bağlanıp komut çalıştırma alışkanlığını tamamen ortadan kaldırır.

Serbest çalışan bir otomasyon geliştiricisiyseniz ve müşteri projelerini teslim tarihine yetiştirmeniz gerekiyorsa, filonuzun tamamını sürüm kontrolündeki tek bir kod tabanından yönetmek en büyük zaman kazancıdır. CaptchaAI'nin thread bazlı ve USD cinsinden sabit aylık fiyatlandırması da bu öngörülebilirliği tamamlar: TL'deki dalgalanmadan bağımsız olarak, aylık maliyetiniz thread sayınıza bağlı kalır.

Ön koşullar

Başlamadan önce elinizde şunların bulunması gerekir:

• Terraform ya da başka bir yöntemle sağlanmış, SSH ile erişilebilen sunucular
• Sunuculara anahtar tabanlı SSH erişimi (ssh-copy-id user@host)
• Panelinizden alınmış bir CaptchaAI API anahtarı
• Kontrol makinenizde kurulu Ansible 2.14 veya üzeri

Veri kazıma iş akışları için worker çalıştırıyorsanız, topladığınız kişisel verilerin KVKK kapsamına girebileceğini unutmayın; CaptchaAI'yi yalnızca yetkili QA ve veri toplama süreçlerinizde kullanın.

Dizin yapısı

Ansible projesini standart rol düzeniyle kurun. Rol, worker'ı kuran ve yapılandıran tüm mantığı taşır; playbook'lar bu rolü hangi sunuculara ve hangi sırayla uygulayacağınızı belirler. Bu ayrım, aynı rolü hem staging hem production ortamında yeniden kullanmanızı sağlar. Üç üst düzey dizin işi böler:

• inventory/ — ortam başına sunucular ve değişkenler
• roles/captcha-worker/ — kurulum ve yapılandırma mantığı
• playbooks/ — rolü sunuculara uygulayan iş akışları

ansible/
├── inventory/
│   ├── production.yml
│   └── staging.yml
├── roles/
│   └── captcha-worker/
│       ├── tasks/
│       │   └── main.yml
│       ├── templates/
│       │   ├── captcha-worker.service.j2
│       │   └── config.yaml.j2
│       ├── handlers/
│       │   └── main.yml
│       └── defaults/
│           └── main.yml
├── playbooks/
│   ├── deploy.yml
│   ├── rolling-update.yml
│   └── health-check.yml
└── ansible.cfg

Envanter: production ve staging ortamları

Envanter dosyaları, hangi sunucuların worker çalıştırdığını ve her ortamın kendine özgü değişkenlerini tanımlar. Production ortamında eşzamanlılığı yüksek (captchaai_concurrency: 20) ve log seviyesini düşük tutarken, staging'de tek bir sunucuda düşük eşzamanlılık ve debug log seviyesiyle çalışmak yaygın bir yaklaşımdır. Böylece yeni bir worker sürümünü önce staging'de doğrular, sonra production'a taşırsınız.

# inventory/production.yml
all:
  children:
    captcha_workers:
      hosts:
        worker-1:
          ansible_host: 10.0.1.10
        worker-2:
          ansible_host: 10.0.1.11
        worker-3:
          ansible_host: 10.0.1.12
      vars:
        captchaai_concurrency: 20
        captchaai_poll_interval: 3
        captchaai_log_level: warning
        worker_version: "1.3.0"

# inventory/staging.yml
all:
  children:
    captcha_workers:
      hosts:
        staging-worker-1:
          ansible_host: 10.0.2.10
      vars:
        captchaai_concurrency: 5
        captchaai_poll_interval: 5
        captchaai_log_level: debug
        worker_version: "1.4.0-rc1"

captcha-worker rolü

Rol, tekrar eden tüm kurulum adımlarını kapsüller: sistem kullanıcısı, Python sanal ortamı, bağımlılıklar, worker kodu, yapılandırma ve systemd servisi. Değişkenleri defaults/ altında tanımlayarak envanterden kolayca geçersiz kılabilirsiniz.

Varsayılan değişkenler

Bu değerler her ortam için makul bir başlangıç noktasıdır. captchaai_concurrency bir worker'ın aynı anda kaç CAPTCHA çözümü yürüteceğini belirler; captchaai_poll_interval ise sonucu sorgulama aralığıdır (saniye). Envanterde farklı değer vermezseniz rol bu varsayılanları kullanır.

# roles/captcha-worker/defaults/main.yml
captchaai_concurrency: 10
captchaai_poll_interval: 5
captchaai_log_level: info
captchaai_timeout: 300
captchaai_retries: 3
worker_version: "latest"
worker_user: captcha
worker_dir: /opt/captcha-worker
worker_venv: /opt/captcha-worker/venv

Görevler: kullanıcı, bağımlılıklar ve servis

Görev dosyası sırayla ilerler: ayrıcalıksız bir sistem kullanıcısı oluşturur, çalışma dizinini hazırlar, Python bağımlılıklarını sanal ortama kurar, worker uygulamasını ve yapılandırmayı kopyalar, ardından systemd servisini etkinleştirir. Yapılandırma ya da uygulama değiştiğinde notify ile handler tetiklenir; böylece servis yalnızca gerçekten gerektiğinde yeniden başlatılır.

# roles/captcha-worker/tasks/main.yml
---

- name: Create worker user
  ansible.builtin.user:
    name: "{{ worker_user }}"
    system: true
    shell: /usr/sbin/nologin
    home: "{{ worker_dir }}"

- name: Create worker directory
  ansible.builtin.file:
    path: "{{ worker_dir }}"
    state: directory
    owner: "{{ worker_user }}"
    mode: "0755"

- name: Install system dependencies
  ansible.builtin.apt:
    name:

      - python3
      - python3-venv
      - python3-pip
    state: present
    update_cache: true

- name: Create Python virtual environment
  ansible.builtin.command:
    cmd: python3 -m venv {{ worker_venv }}
    creates: "{{ worker_venv }}/bin/activate"

- name: Install Python dependencies
  ansible.builtin.pip:
    name:

      - requests>=2.31.0
      - pyyaml>=6.0
    virtualenv: "{{ worker_venv }}"

- name: Deploy worker application
  ansible.builtin.copy:
    src: captcha_worker.py
    dest: "{{ worker_dir }}/captcha_worker.py"
    owner: "{{ worker_user }}"
    mode: "0644"
  notify: restart captcha-worker

- name: Deploy configuration
  ansible.builtin.template:
    src: config.yaml.j2
    dest: "{{ worker_dir }}/config.yaml"
    owner: "{{ worker_user }}"
    mode: "0600"
  notify: restart captcha-worker

- name: Deploy systemd service
  ansible.builtin.template:
    src: captcha-worker.service.j2
    dest: /etc/systemd/system/captcha-worker.service
    mode: "0644"
  notify:

    - reload systemd
    - restart captcha-worker

- name: Enable and start service
  ansible.builtin.systemd:
    name: captcha-worker
    enabled: true
    state: started

Şablonlar: config ve systemd servisi

Jinja2 şablonları, envanterdeki değişkenleri her sunucuya özgü dosyalara dönüştürür. config.yaml.j2 worker'ın çalışma zamanı ayarlarını üretir; systemd servis şablonu ise API anahtarını ortam değişkeni olarak enjekte eder ve NoNewPrivileges ile ProtectSystem=strict gibi güvenlik sıkılaştırmalarını uygular.

# roles/captcha-worker/templates/config.yaml.j2
# CaptchaAI Worker Configuration
# Managed by Ansible — do not edit manually
concurrency: {{ captchaai_concurrency }}
poll_interval: {{ captchaai_poll_interval }}
timeout: {{ captchaai_timeout }}
retries: {{ captchaai_retries }}
log_level: {{ captchaai_log_level }}

# roles/captcha-worker/templates/captcha-worker.service.j2
[Unit]
Description=CaptchaAI CAPTCHA Solving Worker
After=network.target
Wants=network-online.target

[Service]
Type=simple
User={{ worker_user }}
WorkingDirectory={{ worker_dir }}
ExecStart={{ worker_venv }}/bin/python {{ worker_dir }}/captcha_worker.py
Environment=CAPTCHAAI_API_KEY={{ captchaai_api_key }}
Restart=always
RestartSec=10
TimeoutStopSec=30

# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ReadWritePaths={{ worker_dir }}

[Install]
WantedBy=multi-user.target

Handler'lar

Handler'lar yalnızca bir görev değişiklik bildirdiğinde çalışır. Burada iki handler var: systemd yapılandırmasını yeniden yükleyen reload systemd ve servisi yeniden başlatan restart captcha-worker. Bu sayede her playbook çalıştırmasında gereksiz yeniden başlatma yaşanmaz.

# roles/captcha-worker/handlers/main.yml
---

- name: reload systemd
  ansible.builtin.systemd:
    daemon_reload: true

- name: restart captcha-worker
  ansible.builtin.systemd:
    name: captcha-worker
    state: restarted

Playbook'lar

Üç playbook, worker yaşam döngüsünün üç aşamasını kapsar:

• deploy.yml — worker'ı ilk kez kurar ve başlatır
• rolling-update.yml — sürümü sıfır kesintiyle günceller
• health-check.yml — servis ve API durumunu düzenli olarak doğrular

Dağıtım playbook'u

Dağıtım playbook'u API anahtarını vars_prompt ile güvenli biçimde ister, bağlantıyı doğrular, rolü uygular ve worker'ın açıldığını doğrular. Anahtarı komut geçmişine düşürmeden çalışma anında girmenizi sağlar; kalıcı saklama için Ansible Vault'u tercih edin.

# playbooks/deploy.yml
---

- name: Deploy CaptchaAI Workers
  hosts: captcha_workers
  become: true
  vars_prompt:

    - name: captchaai_api_key
      prompt: "Enter CaptchaAI API key"
      private: true

  pre_tasks:

    - name: Verify connectivity
      ansible.builtin.ping:

  roles:

    - captcha-worker

  post_tasks:

    - name: Wait for worker to start
      ansible.builtin.wait_for:
        port: 8080
        timeout: 30
      ignore_errors: true

    - name: Check worker status
      ansible.builtin.systemd:
        name: captcha-worker
      register: worker_status

    - name: Report status
      ansible.builtin.debug:
        msg: "Worker {{ inventory_hostname }}: {{ worker_status.status.ActiveState }}"

Rolling update: sıfır kesinti

serial: 1 sayesinde güncelleme her seferinde tek bir sunucuda yürür; biri güncellenirken diğerleri istekleri karşılamaya devam eder. Her sunucu önce devam eden görevleri boşaltır (drain.py), sonra durur, yeni sürümü alır ve sağlık kontrolünden geçtikten sonra tekrar hizmete girer. max_fail_percentage: 0 ise bir sunucu başarısız olursa güncellemeyi durdurur.

İpucu: serial: 1 yerine serial: "50%" yazarak filonun yarısını aynı anda güncelleyebilirsiniz. Küçük filolarda tek tek, büyük filolarda yüzdesel güncelleme daha pratiktir.

# playbooks/rolling-update.yml
---

- name: Rolling Update CaptchaAI Workers
  hosts: captcha_workers
  become: true
  serial: 1   # Update one host at a time
  max_fail_percentage: 0

  tasks:

    - name: Drain current tasks
      ansible.builtin.command:
        cmd: "{{ worker_venv }}/bin/python {{ worker_dir }}/drain.py"
      timeout: 120
      ignore_errors: true

    - name: Stop worker
      ansible.builtin.systemd:
        name: captcha-worker
        state: stopped

    - name: Deploy new version
      ansible.builtin.copy:
        src: "captcha_worker.py"
        dest: "{{ worker_dir }}/captcha_worker.py"
        owner: "{{ worker_user }}"
        mode: "0644"

    - name: Update dependencies
      ansible.builtin.pip:
        requirements: "{{ worker_dir }}/requirements.txt"
        virtualenv: "{{ worker_venv }}"

    - name: Start worker
      ansible.builtin.systemd:
        name: captcha-worker
        state: started

    - name: Verify worker health
      ansible.builtin.uri:
        url: "http://localhost:8080/health"
        return_content: true
      register: health
      until: health.status == 200
      retries: 6
      delay: 10

    - name: Report update result
      ansible.builtin.debug:
        msg: "{{ inventory_hostname }} updated — {{ health.content }}"

Health-check ve bakiye sorgusu

Sağlık kontrolü playbook'u hem systemd servisinin durumunu hem de CaptchaAI API bağlantısını doğrular. getbalance çağrısı kalan bakiyenizi döndürür; bunu düzenli çalıştırarak worker'ların hem ayakta hem de API'ye erişebilir olduğundan emin olursunuz.

# playbooks/health-check.yml
---

- name: Check CaptchaAI Worker Health
  hosts: captcha_workers
  become: false
  gather_facts: false

  tasks:

    - name: Check systemd service
      ansible.builtin.systemd:
        name: captcha-worker
      register: service_status
      become: true

    - name: Check API connectivity
      ansible.builtin.uri:
        url: "https://ocr.captchaai.com/res.php?key={{ captchaai_api_key }}&action=getbalance&json=1"
        return_content: true
      register: api_check
      delegate_to: localhost
      run_once: true

    - name: Summary
      ansible.builtin.debug:
        msg: |
          Host: {{ inventory_hostname }}
          Service: {{ service_status.status.ActiveState }}
          API Balance: {{ (api_check.content | from_json).request }}

Çalıştırma komutları

Playbook'ları doğru envanterle eşleştirin. Önce staging'e dağıtın, doğrulayın, ardından production'da rolling update çalıştırın. --limit ile tek bir sunucuyu hedefleyebilirsiniz.

# Deploy to staging
ansible-playbook -i inventory/staging.yml playbooks/deploy.yml

# Rolling update in production
ansible-playbook -i inventory/production.yml playbooks/rolling-update.yml

# Health check
ansible-playbook -i inventory/production.yml playbooks/health-check.yml

# Limit to specific hosts
ansible-playbook -i inventory/production.yml playbooks/deploy.yml --limit worker-1

Sık karşılaşılan sorunlar

En sık rastlanan dört sorun ve çözümleri aşağıda. Çoğu, SSH erişimi ya da API anahtarı yapılandırmasıyla ilgilidir.

Sık sorulan sorular

Bir CaptchaAI planı kaç worker sunucusunu besler?

CaptchaAI planları worker ya da sunucu sayısına göre değil, eşzamanlı thread sayısına göre faturalandırılır — bir thread, aynı anda çözülen bir CAPTCHA demektir. Sınır, filonuzdaki tüm worker'ların toplam eşzamanlılığıdır. Örneğin production envanterindeki 3 worker × captchaai_concurrency: 20 = 60 eşzamanlı çözüm, PREMIUM ($170/ay, 100 thread) planına rahatça sığar. Thread başına çözüm sayısı sınırsızdır ve günlük tavan yoktur.

Rolling update sırasında devam eden çözümler kaybolur mu?

Hayır. Playbook, her sunucuyu durdurmadan önce drain.py ile devam eden görevleri boşaltır ve serial: 1 sayesinde aynı anda yalnızca bir sunucu güncellenir. Diğer worker'lar istekleri karşılamaya devam ettiği için filo genelinde kesinti oluşmaz.

API anahtarını Ansible Vault ile nasıl güvende tutarım?

Anahtarı düz metin olarak saklamayın. ansible-vault encrypt_string 'api-anahtariniz' --name 'captchaai_api_key' komutuyla şifreleyin ve şifreli değişkeni envanterinizde veya group_vars altında referanslayın. Playbook çalışırken Vault parolasını sorar; anahtar hiçbir zaman komut geçmişine veya günlüklere düşmez.

Staging ve production envanterini nasıl ayırırım?

İki ayrı envanter dosyası tutun. Staging tek bir sunucuda düşük eşzamanlılık (captchaai_concurrency: 5) ve debug log seviyesiyle çalışır; production ise yüksek eşzamanlılık ve warning seviyesiyle. Aynı rolü her iki ortama uygulayıp yalnızca envanter değişkenlerini değiştirdiğiniz için sürüm geçişleri öngörülebilir olur.

CaptchaAI, Ansible ile hangi CAPTCHA türlerini çözer?

Worker, CaptchaAI'nin desteklediği türleri çözer: reCAPTCHA v2 ve v3, Cloudflare Turnstile ve Cloudflare doğrulama akışı, GeeTest (v3) ile görüntü/OCR CAPTCHA'ları. hCaptcha ve FunCaptcha desteklenmez; GeeTest v4 ise yalnızca çok yakında kapsamındadır. CaptchaFox, Friendly Captcha ve Lemin ise beta olarak sunulur.

Sonraki adımlar

Worker filonuzu koda dönüştürün — CaptchaAI API anahtarınızı alın ve tek komutla üretime dağıtın.

İlgili rehberler:

• Terraform ile altyapıyı kod olarak yönetin
• Docker ile konteynerli CAPTCHA çözümü
• Üretimde yapılandırma yönetimi