网络安全应用安全后端【免费下载链接】capFree, open-source and self-hosted CAPTCHA alternative to reCAPTCHA. Privacy-first and powered by proof-of-work and instrumentation challenges.项目地址https://gitcode.com/gh_mirrors/cap13/cap点击查看免费下载本指南以 Cap Standalone 的 配置选项文档 为核心系统讲解自托管部署该开源 CAPTCHA 服务时需要掌握的全部配置项从 CORS 跨域策略、静态资源Asset server托管到基于 IP 的请求限流、Redis/Valkey 存储、健康检查与优雅关闭再到 HashWX / SHA-256 / RSW 三种证明工作量PoW协议与 instrumentation 挑战的逐键配置最后涵盖 IP 地理数据库的接入与 Docker 卷权限问题。读完本文你将能够为生产环境正确设置环境变量、锁定组件版本、排查资源缓存与限流故障并为每个 site key 制定合适的挑战协议与难度。本文所有结论均以本仓库 standalone/ 目录下的实际源码与 官方文档 为依据文中给出的默认值、取值范围与环境变量名均与当前仓库代码一致。一、CORS控制谁可以发起与交换 challengeCap Standalone 默认允许任意来源origin的网页请求挑战并完成挑战交换这一默认策略可以通过环境变量CORS_ORIGIN在启动服务时覆盖。默认值*即允许所有 origin。多个 origin使用英文逗号分隔例如domain1.tld,domain2.tld,...。在源码层面CORS_ORIGIN的解析逻辑位于 settings-cache.js当值为*或未设置时解析结果为{ origins: null }等价于全部放行否则会先按逗号切分、去除空白与*条目得到一个白名单数组。该默认值会在服务启动时通过loadCorsDefault()载入内存缓存见 index.js。CORS 的最终判定在 index.js 的elysiajs/cors插件中完成/assets及其子路径始终放行资源需要被任意站点加载其余路径交由checkCorsOrigin(request)判定其实现位于 settings-cache.js优先使用每个 site key 的corsOrigins配置可在 APIPUT /server/keys/:siteKey/config中按键设置见 server.js未按键配置时回退到全局默认即CORS_ORIGIN解析结果判定时既支持完整的Origin头字符串精确匹配也支持仅传host的宽松匹配判定结果在内存中缓存 60 秒CORS_CACHE_TTL修改配置后通过invalidateCorsCache立即失效。从源码结构看这套机制同时支持全局白名单 按键白名单两层覆盖适合多站点共用一台 Cap 的场景。二、Asset Server自托管 widget 与 WASM 静态资源Cap Standalone 内置一个静态资源服务Asset server用于让前端页面不再依赖第三方 CDN 加载 widget 脚本与 WASM 二进制文件从而满足隐私优先、自托管的要求。2.1 开启与版本锁定Asset server默认关闭需要显式设置环境变量开启ENABLE_ASSETS_SERVERtrue WIDGET_VERSION0.1.58 WASM_VERSION0.0.8ENABLE_ASSETS_SERVER置为true后资源将从/assets端点对外提供WIDGET_VERSION与WASM_VERSION必须与你希望托管的 widget / WASM 文件版本一致可用的版本号即 npm 上cap.js/widget与cap.js/wasm的发布版本两者默认值均为latest会提供最新版本但不建议在生产环境使用——小版本更新可能带来破坏性变更导致线上系统突然不可用。对应源码实现见 assets.js只要ENABLE_ASSETS_SERVERtrue且任一版本为latest启动时就会打印警告日志提醒生产环境应固定版本号。2.2 资源路径与前端接入方式开启后文件会从以下路径对外提供对应路由实现在 assets.js/assets/widget.js—— 标准 widget 脚本/assets/floating.js—— 浮动模式floatingwidget 脚本/assets/cap_wasm_bg.wasm—— 主 WASM 二进制/assets/hashwx.wasm—— HashWX 专用 WASM/assets/cap_wasm.js—— WASM 加载器loader前端接入时把script的src指向你服务器的对应路径即可例如script srchttps://server url/assets/widget.js/script浮动floating模式则使用script srchttps://server url/assets/floating.js/script同时将window.CAP_CUSTOM_WASM_URL与window.CAP_CUSTOM_HASHWX_URL分别指向cap_wasm_bg.wasm与hashwx.wasm让 widget 从你的服务器加载 WASM 而不是第三方 CDNwindow.CAP_CUSTOM_WASM_URL https://server url/assets/cap_wasm_bg.wasm; window.CAP_CUSTOM_HASHWX_URL https://server url/assets/hashwx.wasm;需要特别注意一个版本边界hashwx.wasm从cap.js/wasm0.0.8 起才存在。如果WASM_VERSION指向更早的版本/assets/hashwx.wasm会返回503。此时不要设置CAP_CUSTOM_HASHWX_URLwidget 会自动改从 jsdelivr 加载该文件这一回退逻辑同样体现在 assets.js当拉取hashwx.wasm失败时会打印警告并删除缓存键。2.3 资源来源CACHE_HOST默认情况下上述文件在服务启动时从process.env.CACHE_HOST拉取该变量默认值为https://cdn.jsdelivr.net可在启动服务时通过设置CACHE_HOST替换为任意可访问的镜像或自建源对应实现见 assets.js资源 URL 形如${CACHE_HOST}/npm/cap.js/widget${WIDGET_VERSION}与${CACHE_HOST}/npm/cap.js/wasm${WASM_VERSION}/browser/...文件被下载后写入 Redis键名如asset:widget.js、asset:cap_wasm_bg.wasm等随后由/assets/*路由从 Redis 读出并提供给客户端资源路由还会附加Cache-Control: max-age31536000, immutable响应头assets.js便于浏览器长期缓存。2.4 常见故障排查若访问某个资源端点得到Asset not cached yet的响应说明文件尚未成功下载到 Redis 缓存该响应对应路由内缓存缺失时返回的503见 assets.js。请按以下顺序检查确认容器内真的设置了ENABLE_ASSETS_SERVERtrue如果你在 compose 文件中修改了该值需要重建容器使其生效否则/assets/*会返回404并附带说明 Asset server is disabled见 assets.js。确认容器可以访问CACHE_HOST若下载失败启动时日志中会打印包含[asset server] failed to update assets cache的行之后每1 小时重试一次setInterval(updateCache, 1000 * 60 * 60)见 assets.js。确认WIDGET_VERSION与WASM_VERSION指向 npm 上真实存在的版本版本号不存在时拉取必然失败同上记录错误日志。补充一点缓存刷新机制updateCache会读取 Redis 中的asset:cache-config只有距上次更新超过 1 天或WIDGET_VERSION/WASM_VERSION发生变化时才重新拉取assets.js因此锁定版本后资源缓存是长期稳定的。三、请求限流按客户端 IP 的固定窗口Challenge 相关端点按客户端 IP 进行限流采用固定时间窗口fixed window算法。3.1 默认值与调整方式默认限制每个 IP 每 5 秒最多 30 次请求全局调整在仪表盘Settings页面修改或通过 APIPUT /settings/ratelimit设置按键覆盖在某个 site key 的Configuration标签页中可为该键单独设置ratelimitMax与ratelimitDuration超限响应返回 HTTP429并带响应头X-RateLimit-Remaining: 0。以上默认值max: 30, duration: 5000与 API 校验范围max1–10000、duration1000–3600000 毫秒在 server.js 中有完整定义。限流核心实现在 ratelimit.js窗口键形如rl:{scope}:{ip}:{windowMs}:{window}通过 RedisINCR计数、首次计数时EXPIRE设置窗口过期响应头同时包含X-RateLimit-Limit与X-RateLimit-Remaining超过max时返回429与{ error: Rate limit exceeded }支持getLimits回调实现按 site key 读取各自的限流参数对应Configuration 标签页按键覆盖。3.2 siteverify 端点不受限流/siteverify端点专为服务器到服务器server-to-server的验证设计默认不参与限流。对应的端点实现见 siteverify.js它接收secret与response参数校验密钥与一次性 token 后返回{ success: true }。3.3 代理背后的客户端 IP 识别Standalone 识别客户端 IP 时依次检查以下请求头X-Forwarded-ForX-Real-IPCF-Connecting-IP全部缺失时才回退到 socket 层地址。这一顺序在 ratelimit.js 的DEFAULT_IP_HEADERS常量中原样体现实现还处理了逗号分隔的链式值取第一个条目。如果你位于使用其他请求头的反向代理之后有两种方式指定 IP 来源设置环境变量RATELIMIT_IP_HEADER例如位于 Cloudflare 之后时可设为cf-connecting-ip或在仪表盘Settings Headers中配置 IP 头。以 nginx 为例务必确保代理把真实客户端 IP 传给 Caplocation / { proxy_pass http://localhost:3000; proxy_set_header X-Forwarded-For $remote_addr; }两个必须警惕的后果如果不转发真实 IP所有请求都会被视为来自代理自身 IP所有客户端将共享同一个限流配额桶等于限流失效X-Forwarded-For等头部按原样被信任。因此服务器绝不能直接暴露在公网否则客户端可以伪造头部绕过限流代码逻辑见 ratelimit.js它无条件信任这些头。四、Redis / Valkey全部持久化依赖Cap Standalone 的所有持久化数据site key、配置、会话、令牌、指标、资产缓存等都存储在 Redis或其兼容替代品 Valkey中。连接配置设置环境变量REDIS_URL为你的 Redis 连接字符串默认值为redis://localhost:6379Valkey 推荐官方快速开始指南推荐通过 docker-compose 使用 ValkeyRedis 兼容存储多实例隔离如果多个 Cap 实例或其他应用共用同一个 Redis 实例应设置REDIS_PREFIX为所有键添加命名空间前缀。例如REDIS_PREFIXcap:后会话键存储为cap:session:...、指标键存储为cap:metrics:...。默认值为空字符串因此已有部署不会受到影响。对应源码见 db.js连接 URL 实际是REDIS_URL || VALKEY_URL || redis://localhost:6379的三级回退REDIS_PREFIX通过一个 Proxy 包装所有 Redis 命令自动为get/set/hget/hmset/sadd/incr/expire等键名前置前缀KEY_FIRST/KEY_ALL两组命令集合见 db.js读取KEYS结果时还会反向剥离前缀。此外 db.js 还实现了连接中断自动重连检测到连接类错误码时以指数退避500ms 起、上限 15s重新建立连接并对重连前的操作进行一次性重试增强了自托管场景下的可用性。五、健康检查与优雅关闭Cap Standalone 提供两个无需认证的端点供容器编排系统与监控告警使用。5.1 /health 与 /health/liveGET /health当 Redis 在2 秒内响应PING时返回200 {status:ok}否则返回503 {status:unavailable}。用于 readiness check就绪探针与告警GET /health/live只要进程存活就返回200即使 Redis 已宕机。用于 liveness check存活探针避免 Redis 故障期间编排系统反复重启 Cap。同秒内到达的健康检查会复用同一次 PING因此频繁调用/health不会给 Redis 增加额外负担。源码实现在 health.jsREDIS_TIMEOUT_MS 2000对应 2 秒超时REDIS_CHECK_REUSE_MS 1000对应 1 秒内的结果复用/health/live是无条件返回ok的纯静态端点。5.2 Kubernetes 探针示例readinessProbe: httpGet: path: /health port: 3000 livenessProbe: httpGet: path: /health/live port: 30005.3 Docker Compose 健康检查若使用 Docker Compose可在cap服务中追加以下配置。注意纯 Docker 模式只会把容器标记为 unhealthy不会自动重启healthcheck: test: [CMD, bun, -e, fetch(http://127.0.0.1:3000/health).then((r) process.exit(r.ok ? 0 : 1)).catch(() process.exit(1))] interval: 30s timeout: 5s retries: 35.4 SIGTERM / SIGINT 优雅关闭行为收到SIGTERM或SIGINT时Cap 会停止接受新连接等待正在处理的请求完成关闭 Redis 连接以退出码0正常结束。若 8 秒后仍有请求在运行则立即以退出码1结束——因此总能落在 Docker 默认 10 秒停止时限之内如果在关闭过程中再次收到信号则直接立即退出。上述逻辑与常量SHUTDOWN_TIMEOUT_MS 8000在 index.js 与 index.js 中完整实现。另外两个部署相关的环境变量也值得留意SERVER_PORT默认3000与SERVER_HOSTNAME默认0.0.0.0。六、错误消息默认脱敏按需开启详情错误响应默认脱敏——内部错误细节不会出现在响应体中而是记录到控制台日志同时响应会附带一个随机错误 IDBun.randomUUIDv7()的尾部片段便于在日志中检索。两个开关控制该行为DISABLE_ERROR_LOGGINGtrue关闭错误日志输出SHOW_ERRORStrue关闭消息脱敏把完整的错误序列化详情名称、消息、堆栈、错误码、原因暴露在响应体detail字段中。对应实现见 index.js 的全局onError处理器VALIDATION与NOT_FOUND两类错误默认不写日志其余错误默认打印结构化日志含时间戳、Bun 版本、平台与内存快照并把troubleshooting指引指向本文档对应章节。七、HashWXGPU 抗性的默认 PoW 协议7.1 协议与默认行为Standalone 以HashWX作为新建 site key 的默认 challenge 协议。HashWX 是 Cap 的 GPU 抗性 proof-of-work与固定哈希函数 SHA-256 不同它每个 challenge 都基于 seed 生成一个全新的单向函数由整数运算与分支构成使得 GPU 相对 CPU 几乎没有吞吐优势。三个关键特性按键独立协议是按 site key 单独设置的因此可以出现部分键用 SHA-256、部分键用 HashWX 的混合状态旧键不受影响在 HashWX 成为默认值之前创建的键会保留原有协议直到你手动更改无需密钥对HashWX 不要求生成或保存任何密钥对配置成本为零。切换方式打开该 site key 的Configuration标签页在Challenge protocol下选择所需协议即可。对应的默认配置在 server.js 的keyDefaults中定义protocol: hashwx、hashwxDifficulty: 1_000_000API 层允许的协议值为sha256-pow、rsw、hashwx三选一server.js。7.2 难度配置与设备耗时参考HashWX difficulty滑条控制难度其数值含义是预期客户端需要执行的哈希次数默认值1_000_000被拆分为4 个子挑战sub-challenges实测参考8 核桌面 Chrome 上中位数约578 毫秒手机上约1.1 到 5.9 秒调高难度前务必先参考 hashwx.md 中的手机实测数据取值范围50_000到5_000_000。上述取值范围与默认值同样在 server.js 的 API 校验层minimum: 50000, maximum: 5000000与配置默认值中原样体现。7.3 WebAssembly 前提与回退方案无法运行 WebAssembly 的客户端无法求解 HashWX challenge。如果需要兼容这类客户端请把该键切换为SHA-256 PoW——它提供纯 JavaScript 实现作为回退路径。作为对比cap-core非 Standalone 场景默认仍使用 SHA-256 PoW除非显式开启参见 capjs-core 的 HashWX 说明。7.4 已废弃的 RSW time-lockRSWRivest-Shamir-Wagner time-lock 谜题仍然可以对存量部署按键启用但已废弃GPU 每秒可求解的数量约为 CPU 的170 倍无法提供设计初衷所期望的 GPU 抗性。相关配置RSW difficulty滑条设置参数t需要顺序执行的平方运算次数范围10_000–300_000默认75_000见 server.js 的rswT默认值及其校验范围 server.jsRSW_BITS2048用于在启动时覆盖 RSA 模数的位宽对应 rsw-store.js 中的密钥对加载与刷新逻辑。小提示widget 能够根据数据格式自动检测挑战协议因此当你调整键的协议时唯一需要做的就是切换键本身无需修改前端代码。八、Instrumentation 挑战拦截自动化与 headless 浏览器除了 PoWCap Standalone 还支持JavaScript instrumentation challenge用于应对能自动求解 proof-of-work 的攻击者并可选择性地拦截 headless 浏览器默认开启新建 site key 时instrumentation challenge 默认启用对应 server.js 中instrumentation: false为 API 入参默认而仪表盘新建流程会开启它配置结构支持每个键独立开关开关位置在 site key 的设置页面中开启或关闭拦截 headless如需屏蔽 headless 浏览器在该键设置中打开Attempt to block headless browsers对应配置字段blockAutomatedBrowsers见 server.js混淆级别obfuscationLevel默认3取值范围 1–10server.js。官方建议保持级别 3除非你需要更强的混淆效果过高的级别会显著降低成功率。如果觉得级别 3 太慢级别 1 在单核上会快得多。九、IP 数据库国家与 ASN 归属查询Cap Standalone 的统计与地理功能依赖 IP 归属查询支持在仪表盘Settings IP Data Country ASN data中从三个提供商中选择DB-IP Lite免费无需凭据自动尝试最近 3 个月的数据文件MaxMind GeoLite2需要 MaxMind 账户 ID 与 License Key通过 Basic Auth 下载 tar.gz 并解包出.mmdbIPInfo API需要 API token走远程 HTTP 查询本地不落地文件。对于 DB-IP 与 MaxMind.mmdb文件会被下载到容器内的/usr/src/app/data/目录。对应实现见 ipdb.jsDATA_DIR指向standalone/data在容器中即/usr/src/app/data下载、解压、进度上报与每 2 小时重载RELOAD_INTERVAL的完整流程均在该文件中。Docker volume 权限问题容器以非特权用户bunUID 1000运行见 Dockerfile 的USER bun。如果你把宿主机目录 bind-mount 到/usr/src/app/data该目录必须允许 UID 1000 写入否则下载会失败并报EACCES: permission denied。正确做法mkdir -p ./cap-data sudo chown 1000:1000 ./cap-dataservices: cap: image: tiago2/cap:latest volumes: - ./cap-data:/usr/src/app/data # ...如果无法修改宿主机文件属主部分平台如 Coolify 操作起来较麻烦最简单的替代方案有三个不做 bind mount让 Docker 管理数据目录——镜像在构建时已创建好目录并设置了正确属主Dockerfile 中的mkdir -p data chown bun:bun data改用named volume代替 bind mount切换到无需本地文件的 IP 数据提供商即 IPInfo API 模式。值得补充的是ipdb.js 启动时会对数据目录做可写性探测写入并删除.write-test文件失败时会直接输出包含chown 1000:1000建议的错误日志方便你在容器日志中第一时间定位该问题。总结生产部署配置速查结合本文与源码一份自托管生产部署的最小关注清单如下关注点环境变量 / 配置默认值生产建议跨域CORS_ORIGIN*收窄为你的域名白名单静态资源ENABLE_ASSETS_SERVER关闭自托管时置true资源版本WIDGET_VERSION/WASM_VERSIONlatest固定到已发布的具体版本资源来源CACHE_HOSTjsdelivr CDN可替换为自建镜像限流仪表盘或PUT /settings/ratelimit30 次 / 5 秒按业务峰值调整勿直接暴露公网代理 IPRATELIMIT_IP_HEADER或 Settings Headers标准三头按代理类型设置并确保转发真实 IP存储REDIS_URLredis://localhost:6379生产建议独立实例多实例隔离REDIS_PREFIX空共享实例时务必设置健康检查/health、/health/live—接入编排系统探针挑战协议每键 ConfigurationHashWX按客户端兼容性选择混淆级别obfuscationLevel3保持 3慢则降 1IP 数据目录/usr/src/app/data—bind mount 时确保 UID 1000 可写若需从头部署请结合 Cap Standalone 快速开始指南含 Valkey 的 docker-compose 配置与 API 文档 一起阅读HashWX 协议的设计原理与成本实测可继续参考 HashWX 详解。赞分享网络安全应用安全后端【免费下载链接】capFree, open-source and self-hosted CAPTCHA alternative to reCAPTCHA. Privacy-first and powered by proof-of-work and instrumentation challenges.项目地址https://gitcode.com/gh_mirrors/cap13/cap点击查看免费下载相关推荐Cap Standalone 配置指南CORS、资源服务器、限流、健康检查与挑战协议全解析Cap Standalone 配置指南CORS、资源服务器、限流、健康检查与挑战协议全解析 Cap Standalone 是 Cap https://link网络安全应用安全后端Cap Standalone 配置完全指南CORS、Asset Server、限流与 HashWX Proof-of-Work 环境变量详解Cap Standalone 配置完全指南CORS、Asset Server、限流与 HashWX Proof of Work 环境变量详解 Cap Stan网络安全应用安全后端Cap Standalone 配置选项与环境变量完全指南CORS、资源服务器、限流、健康检查与哈希工作量证明Cap Standalone 配置选项与环境变量完全指南CORS、资源服务器、限流、健康检查与哈希工作量证明 本篇技术指南以 Cap Standalone开网络安全应用安全后端上一篇Arnis终极部署指南5种环境配置策略与高效管理技巧下一篇最全面Manim版本解析社区版vs原版核心差异与选择指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考