เริ่มต้นใช้งาน
Cap มีสองส่วน คือวิดเจ็ตซึ่งรันและแก้ challenge ในเบราว์เซอร์ของผู้เข้าชมแล้วส่ง token ให้คุณ กับเซิร์ฟเวอร์ (capd) ซึ่งออก challenge และตรวจสอบ token เหล่านั้น
1. ตั้งค่า capd
ขั้นแรก คุณต้องตั้งค่า capd ซึ่งรันเป็นเซิร์ฟเวอร์ที่โฮสต์เอง มาพร้อมแดชบอร์ด สถิติการใช้งาน กฎ และ API โดยเก็บคีย์และการตั้งค่าไว้ใน Valkey ก่อนเริ่ม คุณต้องตัดสินใจสองเรื่อง:
1. จะรัน capd ที่ไหน: คุณรันบนเซิร์ฟเวอร์ของคุณเองด้วย Docker ใช้ Railway หรือใช้แพลตฟอร์ม serverless อย่าง Workers ก็ได้ คู่มือนี้จะพาคุณใช้ Docker
2. จะเก็บสถิติไว้ที่ไหน: คุณใช้ DuckDB ซึ่งเบาและเหมาะกับเว็บไซต์ขนาดเล็ก หรือ ClickHouse ซึ่งขยายระบบได้ดีกว่าก็ได้ ทั้งสองตัวมีมาให้ในตัวและตั้งค่าได้ง่าย
curl -fsSLo docker-compose.yml https://raw.githubusercontent.com/tiagozip/cap/main/capd/docker-compose.duckdb.yml
echo "ADMIN_KEY=$(openssl rand -hex 24)" > .env
docker compose up -dcurl -fsSLo docker-compose.yml https://raw.githubusercontent.com/tiagozip/cap/main/capd/docker-compose.yml
echo "ADMIN_KEY=$(openssl rand -hex 24)" > .env
docker compose up -dเปิด http://localhost:3000 แล้วเข้าสู่ระบบด้วย ADMIN_KEY จาก .env ซึ่งก็คือรหัสผ่านแดชบอร์ด สร้าง site key แล้วคัดลอกทั้ง site key และ secret ของมันเก็บไว้
วิดเจ็ตจะติดต่อกับเซิร์ฟเวอร์นี้จากเบราว์เซอร์ของผู้เข้าชม ดังนั้นในระบบจริงเซิร์ฟเวอร์ต้องมี URL สาธารณะ เราแนะนำให้ใช้บริการอย่าง Tunnels แต่เอกสารของ capd ก็อธิบายกรณีอื่น ๆ ไว้เกือบทั้งหมด รวมถึง reverse proxy ด้วย
2. เพิ่มวิดเจ็ต
โหลดสคริปต์ โดยตรึงเวอร์ชันจากหน้ารีลีส:
<script src="https://cdn.jsdelivr.net/npm/cap-widget@<version>"></script>วางวิดเจ็ตไว้ในฟอร์มของคุณ:
<form action="/submit" method="POST">
<cap-widget data-cap-api-endpoint="https://cap.example.com/<site-key>/"></cap-widget>
<button type="submit">Submit</button>
</form>endpoint คือ https://<your-instance>/<site-key>/
เมื่อผู้เข้าชมแก้ challenge เสร็จ วิดเจ็ตจะเพิ่มฟิลด์ซ่อน cap-token ลงในฟอร์ม ถ้าไม่ได้อยู่ในฟอร์ม ให้ดักฟังเหตุการณ์ solve แทน:
document.querySelector("cap-widget").addEventListener("solve", (e) => {
const token = e.detail.token;
});หน้าวิดเจ็ตมีตัวอย่างโค้ดสำหรับ React, Vue, Svelte และเฟรมเวิร์กอื่น ๆ
3. ตรวจสอบ token
ก่อนจะเชื่อข้อมูลที่ส่งเข้ามา ให้ส่ง token ของมันจากเซิร์ฟเวอร์ของคุณไปที่ /siteverify:
const res = await fetch("https://cap.example.com/<site-key>/siteverify", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ secret: "<secret>", response: token }),
});
const { success } = await res.json();import requests
success = requests.post(
"https://cap.example.com/<site-key>/siteverify",
json={"secret": "<secret>", "response": token},
).json()["success"]$res = file_get_contents("https://cap.example.com/<site-key>/siteverify", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Content-Type: application/json",
"content" => json_encode(["secret" => "<secret>", "response" => $token]),
],
]));
$success = json_decode($res, true)["success"] ?? false;curl -X POST "https://cap.example.com/<site-key>/siteverify" \
-H "Content-Type: application/json" \
-d '{"secret": "<secret>", "response": "<token>"}'<secret> คือ secret ของ site key ไม่ใช่ ADMIN_KEY ของคุณ การสับสนสองอย่างนี้คือความผิดพลาดตอนตั้งค่าที่พบบ่อยที่สุด
ถ้าคุณย้ายมาจาก reCAPTCHA /siteverify รองรับรูปแบบคำขอเดียวกัน โค้ดตรวจสอบของคุณจึงแค่เปลี่ยนไปใช้ hostname ของเซิร์ฟเวอร์คุณเท่านั้น
token ที่ถูกต้องจะได้ผลลัพธ์เป็น { "success": true } token แต่ละอันใช้ได้ครั้งเดียว การตรวจสอบ token เดิมเป็นครั้งที่สองจึงล้มเหลว การส่งซ้ำสองครั้งจึงเป็นวิธีง่าย ๆ ในการเช็กว่าการตั้งค่าทำงานครบทุกขั้นตอน
ใช้ core library แทน
ถ้าคุณอยากออกและตรวจสอบ challenge ภายในแบ็กเอนด์ของคุณเอง core library คือแพ็กเกจ npm ขนาดเล็กที่ทำแค่งานนั้น คุณเก็บ token ไว้ในฐานข้อมูลของคุณเอง และจะไม่มีแดชบอร์ด สถิติการใช้งาน หรือการจำกัดอัตราคำขอ
ขั้นตอนถัดไป
- ปรับแต่งวิดเจ็ต ทั้งข้อความ ภาษา และสไตล์
- ตั้งค่า capd ทั้งพร็อกซี ไฟล์วิดเจ็ต และ API
- อ่านเอกสารอ้างอิงของ core library
- อ่านวิธีการทำงานของ Cap
