การตั้งค่า

การตั้งค่าส่วนใหญ่อยู่ในแดชบอร์ด ทั้งการตั้งค่าทั้งเซิร์ฟเวอร์ที่ Instance settings และการตั้งค่าในหน้า Settings ของแต่ละ site key

ตัวแปรสภาพแวดล้อม

ตัวแปร	หน้าที่
`ADMIN_KEY`	รหัสผ่านแดชบอร์ด ยาวอย่างน้อย 12 ตัวอักษร ต้องระบุ
`VALKEY_URL`	สตริงเชื่อมต่อ Valkey ค่าเริ่มต้นคือ `redis://localhost:6379` ใช้ Redis แทนก็ได้
`VALKEY_TLS_CA`	พาธไปยังใบรับรอง CA แบบ PEM ที่ Cap จะเชื่อถือเมื่อเชื่อมต่อ Valkey ผ่าน TLS เช่นเซิร์ฟเวอร์ที่ใช้ใบรับรองแบบ self-signed ให้ใช้ URL แบบ `rediss://` ส่วน `VALKEY_TLS_CERT` และ `VALKEY_TLS_KEY` ใช้ส่งใบรับรองฝั่งไคลเอนต์เมื่อเซิร์ฟเวอร์ต้องการ
`CLICKHOUSE_URL`	เก็บเหตุการณ์ใน ClickHouse แทน DuckDB เช่น `http://cap:password@clickhouse:8123/cap` เขียนรหัสผ่านตามจริงโดยไม่ต้องเข้ารหัส URL
`WEBHOOK_ALLOW_PRIVATE`	ตั้งเป็น `true` เพื่อให้ webhook ส่งคำขอไปยังที่อยู่ส่วนตัวและ loopback ได้ เช่น n8n ที่อยู่บน LAN ของคุณ
`DUCKDB_MEMORY_LIMIT`, `DUCKDB_THREADS`	ขีดจำกัดของ DuckDB ค่าเริ่มต้นคือ `256MB` และ `2`

IP ของไคลเอนต์เมื่ออยู่หลังพร็อกซี

Cap จำกัดอัตราคำขอ challenge ตาม IP ของไคลเอนต์ ค่าเริ่มต้นคือ 30 คำขอทุก 5 วินาที โดยใช้ที่อยู่ของซ็อกเก็ตและไม่สนใจเฮดเดอร์ส่งต่อ จนกว่าคุณจะเลือกพร็อกซีที่ Instance settings > Visitor location > Your proxy or CDN หากอยู่หลัง Cloudflare ให้เลือก Cloudflare สำหรับ X-Forwarded-For นั้น Cap อ่านรายการสุดท้าย ซึ่งเป็นรายการที่พร็อกซีของคุณเพิ่มเข้าไป

สำหรับ nginx ให้ส่งต่อที่อยู่แบบนี้:

nginx

location / {
    proxy_pass http://localhost:3000;
    proxy_set_header X-Forwarded-For $remote_addr;
}

ถ้าไม่ได้ตั้งค่าพร็อกซี ผู้เข้าชมทุกคนจะใช้โควตาจำกัดอัตราเดียวกับพร็อกซี เมื่อตั้งเฮดเดอร์แล้วอย่าเปิดพอร์ต 3000 ให้เข้าถึงได้โดยตรง ไม่เช่นนั้นไคลเอนต์จะส่ง IP อะไรมาก็ได้

ถ้าแดชบอร์ดอยู่หลัง Authentik, Authelia, oauth2-proxy หรือพร็อกซีลงชื่อเข้าใช้ตัวอื่น Cap จะให้ทุกคนที่พร็อกซีปล่อยผ่านเข้าใช้ได้เลย โดยไม่ต้องลงชื่อเข้าใช้ด้วย ADMIN_KEY อีกรอบ ไปที่ Instance settings > Proxy sign-in เพื่อสร้างรหัสลับ แล้วตั้งให้พร็อกซีใส่รหัสนี้ในเฮดเดอร์ X-Cap-Proxy-Secret บนคำขอที่ลงชื่อเข้าใช้แล้ว ถ้าใช้ Caddy ก็เพิ่มบรรทัดเดียวในบล็อก reverse_proxy ที่อยู่หลัง forward auth

txt

reverse_proxy localhost:3000 {
    header_up X-Cap-Proxy-Secret {env.CAP_PROXY_SECRET}
}

ถ้าใช้ nginx ให้ใส่ proxy_set_header X-Cap-Proxy-Secret $cap_proxy_secret; ใน location ที่ป้องกันไว้ ส่วนเส้นทางของวิดเจ็ตคือ /assets/*, /<siteKey>/challenge, /<siteKey>/redeem, /<siteKey>/siteverify และ /health อยู่นอกพร็อกซีลงชื่อเข้าใช้และไม่ต้องใช้เฮดเดอร์นี้

Proxy or admin key จะลงชื่อเข้าใช้ให้อัตโนมัติเมื่อมีเฮดเดอร์ และยังให้คนอื่นลงชื่อเข้าใช้ด้วยคีย์ผู้ดูแลได้ Proxy only จะปิดการลงชื่อเข้าใช้ด้วยคีย์ผู้ดูแล และตรวจเฮดเดอร์ในทุกคำขอของแดชบอร์ด คนที่ถูกลบออกจากผู้ให้บริการยืนยันตัวตนจึงเข้าใช้ไม่ได้ทันที แม้จะเก็บโทเค็นเซสชันไว้ API key ยังใช้ได้ทั้งสองโหมด Cap จะเปลี่ยนเป็น Proxy only ก็ต่อเมื่อคำขอที่เปิดโหมดนี้มีเฮดเดอร์ติดมาด้วย คุณจึงล็อกตัวเองออกจากแดชบอร์ดแบบนี้ไม่ได้

Cap เก็บไว้แค่แฮชของรหัสลับ ถ้าทำหายให้สร้างใหม่ ถ้าพร็อกซีที่ตั้งค่าผิดยังล็อกคุณออกอยู่ ให้ลบการตั้งค่าด้วย docker compose exec valkey valkey-cli DEL settings:proxy-auth และถ้าตั้ง REDIS_PREFIX ไว้ ให้ใส่ไว้หน้าชื่อคีย์ด้วย

ไฟล์วิดเจ็ต

โดยค่าเริ่มต้น วิดเจ็ตโหลดสคริปต์และไฟล์ WebAssembly จาก jsDelivr เมื่อเปิด Instance settings > Widget files > Serve widget files from this server Cap จะดาวน์โหลดไฟล์เหล่านี้ลงใน Valkey และเสิร์ฟไว้ใต้ /assets/ และตัวอย่างโค้ด Add Cap to your site ของแต่ละคีย์จะชี้ไปที่นั่น ส่วนเดียวกันนี้ใช้เลือกเวอร์ชันของวิดเจ็ตและ WASM ด้วย

ข้อมูล IP

การค้นหาด้วย DB-IP และ MaxMind จะดาวน์โหลดไฟล์ .mmdb ไปที่ /usr/src/app/data คอนเทนเนอร์รันด้วย UID 1000 ดังนั้นถ้าคุณ bind-mount โฟลเดอร์ไว้ ผู้ใช้นี้ต้องเขียนลงโฟลเดอร์นั้นได้:

bash

mkdir -p ./cap-data && sudo chown 1000:1000 ./cap-data

การตรวจสุขภาพ

GET /health ตอบ 200 เมื่อ Valkey ตอบภายใน 2 วินาที และตอบ 503 ในกรณีอื่น ให้ใช้สำหรับ readiness check ส่วน GET /health/live ตอบ 200 ตราบใดที่โปรเซสยังทำงานอยู่ ให้ใช้สำหรับ liveness check แล้วระบบ orchestration จะไม่รีสตาร์ต Cap ระหว่างที่ Valkey ล่ม

API

ทุกอย่างที่แดชบอร์ดทำได้ก็ทำผ่าน REST API ได้ โดยมีเอกสารอยู่ที่ /swagger บนอินสแตนซ์ของคุณ สร้างคีย์ที่ Instance settings > API keys แล้วส่งไปเป็น Authorization: Bot <api-key>

โดยค่าเริ่มต้น คีย์ทำได้ทุกอย่าง คุณจะตั้งให้อ่านได้อย่างเดียว จำกัดให้ใช้ได้กับบาง site key หรือทั้งสองอย่างก็ได้ คีย์แบบอ่านอย่างเดียวสำหรับ site key เดียวสามารถให้เจ้าของไซต์นั้นไว้ดูสถิติได้อย่างปลอดภัย

การตั้งค่า ​

ตัวแปรสภาพแวดล้อม ​

IP ของไคลเอนต์เมื่ออยู่หลังพร็อกซี ​

ลงชื่อเข้าใช้ผ่านพร็อกซี ​

ไฟล์วิดเจ็ต ​

ข้อมูล IP ​

การตรวจสุขภาพ ​

API ​