مستندات کپچی
کپتچی را به سرور، وردپرس یا اپلیکیشن وصل کنید. هر پاسخ را در سرور خودتان با Siteverify تأیید کنید.
شروع راهاندازیآمادهسازی در پنل
- در پنل مشتریان یک سایت بسازید و نام میزبان فرم را ثبت کنید.
- برای فرم یک اقدام فعال مثل
contact_formتعریف کنید. همان نام را در مرورگر و سرور بهکار ببرید. - کلید سایت را در تنظیمات ویجت بگذارید و کلید محرمانه را فقط در محیط سرور، مثلاً در
CAPTCHI_SECRET_KEY، نگه دارید.
نصب SDK در مرورگر
پوشهٔ خروجی SDK را روی وبسایت خود میزبانی کنید و ساختار captchi.js، captchi.css و chunks/ را حفظ کنید. در نسخهٔ خودمیزبان کپچی، مسیر خروجی این فایلها از ریشهٔ پروژه apps/com_captchi_core/theme/default/assets/captchi/ است. اگر پوشهٔ خروجی در کپی سورس وجود ندارد، در ریشهٔ پروژه دستورهای زیر را اجرا کنید.
npm --prefix apps/com_captchi_core/sdk ci
npm --prefix apps/com_captchi_core/sdk run build
مسیر فایلها، آدرس فرم و کلید سایت را در نمونه جایگزین کنید. ویجت توکن یکبارمصرف ct_resp_… را همراه فرم به سرور خودتان میفرستد.
<link rel="stylesheet" href="/vendor/captchi/captchi.css">
<form id="contact" action="/contact" method="post">
<!-- Keep your existing fields and CSRF input here. -->
<input type="hidden" name="response">
<div id="captchi-widget"></div>
<button type="submit">ارسال فرم</button>
<p id="captchi-message" role="status"></p>
</form>
<script type="module">
import { Captchi } from '/vendor/captchi/captchi.js';
const form = document.querySelector('#contact');
const button = form.querySelector('button');
const message = document.querySelector('#captchi-message');
const widget = Captchi.render('#captchi-widget', {
siteKey: 'REPLACE_WITH_SITE_KEY',
action: 'contact_form',
apiBaseUrl: 'https://api.captchi.ir',
});
form.addEventListener('submit', async event => {
event.preventDefault();
button.disabled = true;
message.textContent = '';
try {
form.elements.namedItem('response').value = await widget.execute();
HTMLFormElement.prototype.submit.call(form);
} catch {
widget.reset();
message.textContent = 'بررسی انجام نشد. دوباره تلاش کنید.';
button.disabled = false;
}
});
</script>
تأیید در سرور با Siteverify
در مسیر پردازش فرم، توکن را با POST /api/v1/siteverify بررسی کنید. نام اقدام، نام میزبان و کلید سایت را از تنظیمات مورد اعتماد سرور بردارید. نمونهٔ PHP به افزونهٔ cURL نیاز دارد.
<?php
// Call this from your POST handler before processing the form.
function verifyCaptchi(string $response): bool
{
$secret = getenv('CAPTCHI_SECRET_KEY');
if ($secret === false || $secret === '' || $response === '') {
return false;
}
$request = curl_init('https://api.captchi.ir/api/v1/siteverify');
curl_setopt_array($request, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 3,
CURLOPT_TIMEOUT => 8,
CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Accept: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'secret' => $secret,
'response' => $response,
'site_key' => 'REPLACE_WITH_SITE_KEY',
'action' => 'contact_form',
'hostname' => 'example.com',
], JSON_THROW_ON_ERROR),
]);
$body = curl_exec($request);
$status = curl_getinfo($request, CURLINFO_RESPONSE_CODE);
curl_close($request);
if (!is_string($body) || $status !== 200) {
return false;
}
$result = json_decode($body, true);
return ($result['success'] ?? false) === true
&& ($result['data']['success'] ?? false) === true;
}
فرم را فقط وقتی پردازش کنید که هر دو مقدار success و data.success برابر true باشند. بررسی CSRF و اعتبارسنجی فیلدهای فرم همچنان در مسیر سرور انجام میشود.
افزونهٔ وردپرس کپتچی
افزونهٔ رسمی وردپرس SDK را بارگذاری میکند، توکن را هنگام ارسال فرم میگیرد و Siteverify را سمت سرور اجرا میکند. دانلود افزونهٔ WordPress
- فایل ZIP را از پیشخوان WordPress در بخش «افزونهها ← افزودن ← بارگذاری افزونه» نصب و فعال کنید. افزونه به WordPress 6.0 و PHP 7.4 یا جدیدتر نیاز دارد.
- در تنظیمات ← Captchi، کلید عمومی و کلید محرمانه را وارد کنید. کلید محرمانه هنگام نمایش فرم پنهان میماند و فقط از backend فرستاده میشود.
- hostname و action فرم را در پنل کپچی ثبت کنید؛ hostname باید همان دامنهای باشد که WordPress از آن سرویس میدهد.
- در Contact Form 7 از form-tag کپچی استفاده کنید؛ افزونه اعتبارسنجی سروری را خودکار به ارسال CF7 وصل میکند.
- برای سایر فرمسازها، shortcode را داخل فرم بگذارید و helper تأیید را در hook پردازش همان فرم اجرا کنید.
[captchi captchi_response action:contact_form]
در Contact Form 7 نام فیلد باید captchi_response باشد. action را با مقدار فعال در پنل جایگزین کنید؛ افزونه از hook wpcf7_validate_captchi برای Siteverify سمت سرور استفاده میکند و در خطای شبکه یا رد پاسخ، ارسال فرم را متوقف میسازد.
[captchi action="contact_form" language="fa" theme="auto"]
ویژگیهای shortcode: action شناسهٔ فعال پنل، language یکی از fa/en و theme یکی از auto/light/dark است. ویجت باید داخل فرم قرار بگیرد.
// Call this inside your existing form handler after checking its WordPress nonce.
if (!captchi_verify_submission('contact_form')) {
wp_die('بررسی امنیتی انجام نشد. فرم را دوباره ارسال کنید.');
}
helper بهصورت پیشفرض توکن را از POST میخواند، hostname را از home_url() میگیرد و در خطای شبکه یا رد Siteverify مقدار false میدهد. nonce وردپرس و اعتبارسنجی فیلدهای فرم را همچنان اجرا کنید. اتصال خودکار این نسخه برای Contact Form 7 است؛ برای سایر فرمسازها تابع را در hook اعتبارسنجی سمت سرور همان فرم صدا بزنید.
برای سیاست score_only بهجای تابع boolean، Captchi_WordPress::verify_submission('checkout') را فراخوانی کنید؛ در پاسخ موفق، آرایهٔ risk_score را در اختیار backend قرار میدهد.
اپلیکیشنها و برنامههای تکصفحهای
SDK فعلی کپتچی برای مرورگر است. در React، Vue یا برنامهٔ وب تکصفحهای آن را در کامپوننت کلاینت راهاندازی و هنگام unmount با widget.remove() پاک کنید. نتیجهٔ widget.execute() را به API خودتان بفرستید؛ اپلیکیشن موبایل نباید Siteverify را مستقیم فراخوانی کند.
import { Captchi } from '/vendor/captchi/captchi.js';
const widget = Captchi.render('#captchi-widget', {
siteKey: 'REPLACE_WITH_SITE_KEY',
action: 'sign_in',
apiBaseUrl: 'https://api.captchi.ir',
language: 'fa',
theme: 'auto',
});
// On submit, await widget.execute() and send the returned response
// to your authenticated application server for Siteverify.
برای iOS و Android از صفحهٔ وب امن داخل WebView استفاده کنید که hostname آن در پنل ثبت شده است، یا flow تأیید را در وبسرور خودتان میزبانی کنید. SDK بومی Swift، Kotlin و React Native در مخزن موجود نیست. کلید محرمانه و منطق پذیرش باید روی backend برنامه باقی بمانند.
در SPA هنگام unmount کردن کامپوننت، widget.remove() را صدا بزنید. پس از خطای ارسال، widget.reset() را فراخوانی کنید تا برای تلاش بعدی توکن تازه گرفته شود.
تنظیمات سایت و حالتهای تأیید
تنظیمات هر سایت
- Hostname دامنهای که ویجت در آن اجرا میشود. مقدار را از ورودی کاربر دریافت نکنید و هنگام Siteverify hostname مورد انتظار خود را بفرستید.
- Action شناسهٔ کاری کوتاه مانند
sign_in،checkoutیاcontact_form. حروف کوچک، عدد، خط تیره و زیرخط مجازند و شناسه باید با حرف آغاز شود. - Site Key کلید عمومی برای SDK مرورگر.
- Secret Key برای Siteverify سمت سرور. در پنل فقط هنگام ایجاد یا چرخش کلید نمایش داده میشود؛ آن را بهصورت secret در سرور نگه دارید.
- Verification mode سیاست تصمیمگیری برای سایت. تغییرش از تنظیمات همان سایت در پنل انجام میشود.
حالتهای تأیید
auto- تصمیم سرور بر پایهٔ تنظیمات و ارزیابی ریسک، عبور یا نمایش چالش را تعیین میکند.
invisible- درخواست واجد شرایط میتواند بدون تعامل چالش عبور کند؛ تصمیم همچنان در سرور است.
managed- سرور بر پایهٔ سیاست ریسک خودش تعیین میکند چه زمانی چالش لازم است.
always- برای درخواستهای پذیرفتهشده چالش تعاملی درخواست میشود.
score_only- ارزیابی ریسک در پاسخ Siteverify سمت سرور ارائه میشود. امتیاز را فقط در backend و همراه با قاعدهٔ تصمیم خودتان مصرف کنید.
تنظیمات نصب خودمیزبان
این متغیرها برای اپلیکیشن سرور کپتچی هستند، نه برای نصبکنندههای SDK. نمونهٔ کامل و مقادیر پیشفرض در .env.example مخزن است. مقادیر حساس را با secret manager محیط خود جایگزین کنید.
# Provider and short-lived runtime state
CAPTCHI_CHALLENGE_PROVIDER=altcha
CAPTCHI_RUNTIME_STATE_DRIVER=auto
# Generate unique, private values for this deployment
CAPTCHI_ALTCHA_HMAC_SECRET=REPLACE_WITH_RANDOM_SECRET
CAPTCHI_SECRET_KEY_PEPPER=REPLACE_WITH_RANDOM_SECRET
CAPTCHI_RESPONSE_TOKEN_PEPPER=REPLACE_WITH_RANDOM_SECRET
CAPTCHI_PRIVACY_PEPPER=REPLACE_WITH_RANDOM_SECRET
# Set the environment explicitly
CAPTCHI_ENV=production
CAPTCHI_CHALLENGE_PROVIDERازaltchaیاfirst-partyپشتیبانی میکند.CAPTCHI_RUNTIME_STATE_DRIVERیکی ازauto،redisیاmysqlاست. حالتautoRedis را در صورت دسترسی انتخاب میکند و به MySQL بازمیگردد.- اتصال MySQL منبع پایدار تنظیمات و داده است. Redis فقط وضعیت موقت را نگه میدارد و اختیاری است.
- کلیدهای
CAPTCHI_*_PEPPERو HMAC باید منحصربهفرد، با entropy مناسب و خارج از مخزن باشند. چرخاندن آنها نیازمند برنامهٔ عملیاتی جداگانه است. - کلیدهای نمونهٔ
ct_test_*فقط برای محیطlocalوtestingهستند و در production یا staging پذیرفته نمیشوند.
متغیرهای تکمیلی سرور
برای نصب خودمیزبان، APP_ENV و CAPTCHI_ENV را متناسب با محیط تنظیم کنید. محیط production یا staging، کلیدهای تست را غیرفعال میکند. CAPTCHI_PUBLIC_BASE_URL نشانی عمومی پنل برای لینکهای ایمیل است. محدودیتهای نرخ و نگهداری رویدادها در .env.example مستند شدهاند؛ مقدار آنها را با ظرفیت و ترافیک واقعی تنظیم کنید.
شناسهٔ Site و Action، hostnameهای مجاز، verification mode، دامنهها و چرخش کلیدها از پنل همان سایت مدیریت میشوند، نه از تنظیمات JavaScript. secretهای سرور مانند pepperها فقط در محیط سرور قرار میگیرند.
مرجع متغیرهای سرور Captchi
این متغیرها را فقط در محیط سرور یا تنظیمات امن Pinoox قرار دهید. مقادیر زیر پیشفرض کد هستند؛ متغیرهای بدون پیشفرض باید صریح تنظیم شوند. پس از تغییر تنظیمات، سرویس PHP را طبق روش استقرار خود reload کنید.
محیط، دامنهها و ارائهدهنده
APP_ENVوCAPTCHI_ENV- نام محیط؛ برای سرور زنده
productionبگذارید. اگرCAPTCHI_ENVخالی باشد، سیاست کلید تست ازAPP_ENVپیروی میکند؛ کلیدهای آزمایشی فقط درlocal،testوtestingمجازند. CAPTCHI_API_DOMAIN،CAPTCHI_PANEL_DOMAIN- نام میزبان API و پنل؛ پیشفرض بهترتیب
api.captchi.irوpanel.captchi.irاست. فقط وقتی دامنهٔ سفارشی دارید تغییرشان دهید. CAPTCHI_ADMIN_DOMAIN- نام میزبان اختیاری کنسول اپراتور؛ در حالت خالی، کنسول روی hostname جداگانه route نمیشود. DNS و TLS آن باید پیش از فعالسازی آماده باشد.
CAPTCHI_CHALLENGE_PROVIDER- نوع ارائهدهنده:
altcha(پیشفرض) یاfirst-party. گزینهٔ دوم چالشهای تعاملی کپچی را فعال میکند. CAPTCHI_RUNTIME_STATE_DRIVER- محل وضعیت موقت:
auto(پیشفرض؛ Redis در دسترس و در غیر این صورت MySQL)،redisیاmysql. CAPTCHI_ADMIN_JWT_SECRET- کلید امضای نشست کنسول اپراتور؛ مقدار تصادفی یکتا با حداقل ۳۲ بایت بسازید و مستقل از
PINOOX_JWT_SECRETنگه دارید. برای دسترسی کنسول لازم است.
کلیدهای محرمانهٔ سرویس
CAPTCHI_SECRET_KEY_PEPPER- pepper برای هش کلیدهای محرمانهٔ سایت.
CAPTCHI_RESPONSE_TOKEN_PEPPER- pepper برای پاسخهای یکبارمصرف Captchi.
CAPTCHI_PRIVACY_PEPPER- pepper برای دادههای حریم خصوصی و شناسههای رویداد.
CAPTCHI_ALTCHA_HMAC_SECRET- کلید HMAC ارائهدهندهٔ ALTCHA؛ در صورت انتخاب
altchaلازم است. CAPTCHI_IDENTITY_MAIL_ENCRYPTION_KEY- کلید رمزنگاری outbox ایمیل هویت؛ باید Base64URL بدون padding با ۶۴ نویسه باشد.
برای ساخت امن secretهای گمشده اجرا کنید: php pinoox captchi:configure --generate-missing. مقدار کلیدها در خروجی چاپ نمیشود و در تنظیمات سمتسرور Pinoox ذخیره میشود. مقدارهای replace-locally نمونهاند و در سرور قابل استفاده نیستند؛ secret موجود را با تغییر اتفاقی عوض نکنید.
محدودیت درخواست و نگهداری داده
CAPTCHI_UNKNOWN_TARGET_GLOBAL_LIMIT_PER_MINUTE- حد درخواست برای site key ناشناخته؛ پیشفرض ۳۶۰۰ در دقیقه، بازهٔ پذیرفتهشده ۱۰۰ تا ۱۰۰۰۰۰.
CAPTCHI_RUNTIME_TARGET_LOOKUP_IP_LIMIT_PER_MINUTE- حد جستوجوی target برای هر IP؛ پیشفرض ۳۶۰۰ در دقیقه، بازهٔ ۱۰۰ تا ۱۰۰۰۰۰.
CAPTCHI_SITE_CHALLENGE_CREATE_LIMIT_PER_MINUTE- حد ساخت چالش برای هر سایت؛ پیشفرض ۱۲۰ در دقیقه، بازهٔ ۱۰۰ تا ۱۰۰۰۰۰.
CAPTCHI_SITEVERIFY_PREAUTH_IP_LIMIT_PER_MINUTE- سقف پیشبررسی Siteverify برای هر IP؛ پیشفرض ۳۶۰۰ در دقیقه، بازهٔ ۱۰۰ تا ۱۰۰۰۰۰.
CAPTCHI_SITEVERIFY_UNKNOWN_CREDENTIAL_LIMIT_PER_MINUTE- حد اعتبارنامهٔ ناشناخته؛ پیشفرض ۳۶۰۰ در دقیقه، بازهٔ ۱۰۰ تا ۱۰۰۰۰۰.
CAPTCHI_SITEVERIFY_SITE_LIMIT_PER_MINUTE- حد کلی Siteverify برای هر سایت؛ پیشفرض ۳۶۰۰ در دقیقه، بازهٔ ۱۰۰ تا ۱۰۰۰۰۰. حد Siteverify برای هر IP در کد ثابت و برابر ۶۰ در دقیقه است.
CAPTCHI_VERIFICATION_EVENT_RETENTION_DAYS- مدت نگهداری رویدادهای تأیید؛ پیشفرض ۷ روز، بازهٔ ۱ تا ۹۰ روز.
CAPTCHI_HEALTH_SNAPSHOT_RETENTION_DAYSوCAPTCHI_HEALTH_RESOLVED_ALERT_RETENTION_DAYS- مدت نگهداری snapshot سلامت و هشدارهای رفعشده؛ پیشفرض بهترتیب ۳۰ و ۹۰ روز، بازهٔ هرکدام ۱ تا ۳۶۵ روز.
ایمیل، هشدار و دموی سرور
CAPTCHI_MAILER_DSN- آدرس حملونقل SMTP یا SMTPS برای ایمیلهای پنل؛ نمونهٔ توسعه
smtp://mailpit:1025است. برای production از SMTPS و اعتبارنامهٔ مدیریتشده استفاده کنید. CAPTCHI_MAIL_FROM- نشانی فرستندهٔ ایمیل پنل، به قالب mailbox معتبر.
CAPTCHI_PUBLIC_BASE_URL- نشانی HTTPS عمومی پنل با مسیر
/panel؛ لینک ایمیلها از آن ساخته میشود. HTTP فقط برای loopback در محیط local/testing مجاز است. CAPTCHI_HEALTH_ALERT_MAIL_ENABLED- ارسال هشدار ایمیلی خاموش است (
0)؛ برای روشنکردن مقدار1بگذارید. CAPTCHI_HEALTH_ALERT_MAIL_DSN،CAPTCHI_HEALTH_ALERT_MAIL_RECIPIENT،CAPTCHI_HEALTH_ALERT_MAIL_SENDER- تنظیمات SMTP و mailbox گیرنده/فرستندهٔ هشدار. مقادیر Mailpit و
example.testفقط برای local/test هستند؛ production به SMTPS روی پورت ۴۶۵ و دو mailbox واقعی مدیریتشده نیاز دارد. CAPTCHI_DEMO_ENABLED- دموی زنده بهطور پیشفرض خاموش است (
0)؛ فقط با مقدار1فعال میشود. CAPTCHI_DEMO_HOSTNAME،CAPTCHI_DEMO_SITE_KEY،CAPTCHI_DEMO_SECRET_KEY- hostname و کلیدهای اختصاصی سایت آزمایشی. کلید محرمانه فقط در backend بماند و از کلیدهای سایت واقعی استفاده نکنید.
CAPTCHI_DEMO_TRUSTED_REMOTE_ADDRESS- آدرس peer اختیاری برای proxy محلی؛ فقط وقتی ingress به loopback محدود است تنظیم شود.
CAPTCHI_LOCAL_SAMPLE_ADMIN،CAPTCHI_LOCAL_SAMPLE_SITEوCAPTCHI_LOCAL_BASE_URL- تنظیمات seed برای حساب/سایت نمونهٔ محلی؛ فقط در توسعه و تست استفاده شوند، نه production.
CAPTCHI_LOCAL_BASE_URLآدرس نصب محلی را مشخص میکند و پیشفرض آنhttp://127.0.0.1:8099است.
ظاهر SDK
گزینهٔ language بهطور پیشفرض fa و گزینهٔ theme یکی از auto، light یا dark است. این گزینهها ظاهر ویجت را تغییر میدهند، نه سیاست امنیتی سایت.
تست اتصال
API عمومی روی https://api.captchi.ir/api/v1 قرار دارد. SDK برای دریافت تصمیم از GET /runtime-config و برای چالش از POST /challenges و POST /challenges/complete استفاده میکند. Siteverify فقط از سرور برنامه فراخوانی میشود.
پاسخ موفق چالش یک توکن ct_resp_… با عمر ۱۲۰ ثانیه میدهد. توکن یکبارمصرف است و باید در همان hostname و action تأیید شود. هنگام پاسخ ناموفق یا timeout، دادهٔ فرم را نپذیرید و برای تلاش تازه ویجت را reset کنید.
- روی محیط توسعه، فرم را با کلید و دامنهٔ همان محیط ارسال کنید و پذیرش فرم پس از تأیید سرور را بررسی کنید. از کلیدهای fixture فقط در local یا testing استفاده کنید.
- در تست سمت سرور، درخواست بدون توکن را بررسی کنید. پردازش فرم باید متوقف شود.
- قطع ارتباط با API را در محیط توسعه شبیهسازی کنید. فرم باید پیام تلاش دوباره بدهد و دادهٔ آن پردازش نشود.
- برای هر تلاش تازه توکن جدید بگیرید. در فرم تکصفحهای پس از پایان تلاش،
widget.reset()را فراخوانی کنید.
نمونههای آموزشی روشهای کپچا را در صفحهٔ پیشنمایش ببینید.
رفع خطا
invalid_secret- کلید محرمانهٔ فعال و تعلق آن به سایت را در تنظیمات سرور بررسی کنید.
hostname_mismatch/action_mismatch- نام میزبان و نام اقدام را با تنظیمات پنل و مقدار مورد انتظار سرور تطبیق دهید.
invalid_token/token_replay- بررسی را دوباره آغاز کنید تا توکن تازه صادر شود.
service_unavailable/rate_limited- پردازش فرم را متوقف کنید و امکان تلاش دوباره را پس از مدتی فراهم کنید.
کد خطا در data.error_code یا error.code قرار میگیرد. برای پیگیری، request_id را همراه کد خطا ثبت کنید و توکن یا کلید محرمانه را در گزارش نیاورید.