網(wǎng)絡(luò)安全應(yīng)用安全后端【免費(fèi)下載鏈接】capFree, open-source and self-hosted CAPTCHA alternative to reCAPTCHA. Privacy-first and powered by proof-of-work and instrumentation challenges.項(xiàng)目地址https://gitcode.com/gh_mirrors/cap13/cap點(diǎn)擊查看免費(fèi)下載本指南以 Cap Standalone 的 配置選項(xiàng)文檔 為核心系統(tǒng)講解自托管部署該開(kāi)源 CAPTCHA 服務(wù)時(shí)需要掌握的全部配置項(xiàng)從 CORS 跨域策略、靜態(tài)資源Asset server托管到基于 IP 的請(qǐng)求限流、Redis/Valkey 存儲(chǔ)、健康檢查與優(yōu)雅關(guān)閉再到 HashWX / SHA-256 / RSW 三種證明工作量PoW協(xié)議與 instrumentation 挑戰(zhàn)的逐鍵配置最后涵蓋 IP 地理數(shù)據(jù)庫(kù)的接入與 Docker 卷權(quán)限問(wèn)題。讀完本文你將能夠?yàn)樯a(chǎn)環(huán)境正確設(shè)置環(huán)境變量、鎖定組件版本、排查資源緩存與限流故障并為每個(gè) site key 制定合適的挑戰(zhàn)協(xié)議與難度。本文所有結(jié)論均以本倉(cāng)庫(kù) standalone/ 目錄下的實(shí)際源碼與 官方文檔 為依據(jù)文中給出的默認(rèn)值、取值范圍與環(huán)境變量名均與當(dāng)前倉(cāng)庫(kù)代碼一致。一、CORS控制誰(shuí)可以發(fā)起與交換 challengeCap Standalone 默認(rèn)允許任意來(lái)源origin的網(wǎng)頁(yè)請(qǐng)求挑戰(zhàn)并完成挑戰(zhàn)交換這一默認(rèn)策略可以通過(guò)環(huán)境變量CORS_ORIGIN在啟動(dòng)服務(wù)時(shí)覆蓋。默認(rèn)值*即允許所有 origin。多個(gè) origin使用英文逗號(hào)分隔例如domain1.tld,domain2.tld,...。在源碼層面CORS_ORIGIN的解析邏輯位于 settings-cache.js當(dāng)值為*或未設(shè)置時(shí)解析結(jié)果為{ origins: null }等價(jià)于全部放行否則會(huì)先按逗號(hào)切分、去除空白與*條目得到一個(gè)白名單數(shù)組。該默認(rèn)值會(huì)在服務(wù)啟動(dòng)時(shí)通過(guò)loadCorsDefault()載入內(nèi)存緩存見(jiàn) index.js。CORS 的最終判定在 index.js 的elysiajs/cors插件中完成/assets及其子路徑始終放行資源需要被任意站點(diǎn)加載其余路徑交由checkCorsOrigin(request)判定其實(shí)現(xiàn)位于 settings-cache.js優(yōu)先使用每個(gè) site key 的corsOrigins配置可在 APIPUT /server/keys/:siteKey/config中按鍵設(shè)置見(jiàn) server.js未按鍵配置時(shí)回退到全局默認(rèn)即CORS_ORIGIN解析結(jié)果判定時(shí)既支持完整的Origin頭字符串精確匹配也支持僅傳host的寬松匹配判定結(jié)果在內(nèi)存中緩存 60 秒CORS_CACHE_TTL修改配置后通過(guò)invalidateCorsCache立即失效。從源碼結(jié)構(gòu)看這套機(jī)制同時(shí)支持全局白名單 按鍵白名單兩層覆蓋適合多站點(diǎn)共用一臺(tái) Cap 的場(chǎng)景。二、Asset Server自托管 widget 與 WASM 靜態(tài)資源Cap Standalone 內(nèi)置一個(gè)靜態(tài)資源服務(wù)Asset server用于讓前端頁(yè)面不再依賴第三方 CDN 加載 widget 腳本與 WASM 二進(jìn)制文件從而滿足隱私優(yōu)先、自托管的要求。2.1 開(kāi)啟與版本鎖定Asset server默認(rèn)關(guān)閉需要顯式設(shè)置環(huán)境變量開(kāi)啟ENABLE_ASSETS_SERVERtrue WIDGET_VERSION0.1.58 WASM_VERSION0.0.8ENABLE_ASSETS_SERVER置為true后資源將從/assets端點(diǎn)對(duì)外提供WIDGET_VERSION與WASM_VERSION必須與你希望托管的 widget / WASM 文件版本一致可用的版本號(hào)即 npm 上cap.js/widget與cap.js/wasm的發(fā)布版本兩者默認(rèn)值均為latest會(huì)提供最新版本但不建議在生產(chǎn)環(huán)境使用——小版本更新可能帶來(lái)破壞性變更導(dǎo)致線上系統(tǒng)突然不可用。對(duì)應(yīng)源碼實(shí)現(xiàn)見(jiàn) assets.js只要ENABLE_ASSETS_SERVERtrue且任一版本為latest啟動(dòng)時(shí)就會(huì)打印警告日志提醒生產(chǎn)環(huán)境應(yīng)固定版本號(hào)。2.2 資源路徑與前端接入方式開(kāi)啟后文件會(huì)從以下路徑對(duì)外提供對(duì)應(yīng)路由實(shí)現(xiàn)在 assets.js/assets/widget.js—— 標(biāo)準(zhǔn) widget 腳本/assets/floating.js—— 浮動(dòng)模式floatingwidget 腳本/assets/cap_wasm_bg.wasm—— 主 WASM 二進(jìn)制/assets/hashwx.wasm—— HashWX 專用 WASM/assets/cap_wasm.js—— WASM 加載器loader前端接入時(shí)把script的src指向你服務(wù)器的對(duì)應(yīng)路徑即可例如script srchttps://server url/assets/widget.js/script浮動(dòng)floating模式則使用script srchttps://server url/assets/floating.js/script同時(shí)將window.CAP_CUSTOM_WASM_URL與window.CAP_CUSTOM_HASHWX_URL分別指向cap_wasm_bg.wasm與hashwx.wasm讓 widget 從你的服務(wù)器加載 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;需要特別注意一個(gè)版本邊界hashwx.wasm從cap.js/wasm0.0.8 起才存在。如果WASM_VERSION指向更早的版本/assets/hashwx.wasm會(huì)返回503。此時(shí)不要設(shè)置CAP_CUSTOM_HASHWX_URLwidget 會(huì)自動(dòng)改從 jsdelivr 加載該文件這一回退邏輯同樣體現(xiàn)在 assets.js當(dāng)拉取hashwx.wasm失敗時(shí)會(huì)打印警告并刪除緩存鍵。2.3 資源來(lái)源CACHE_HOST默認(rèn)情況下上述文件在服務(wù)啟動(dòng)時(shí)從process.env.CACHE_HOST拉取該變量默認(rèn)值為https://cdn.jsdelivr.net可在啟動(dòng)服務(wù)時(shí)通過(guò)設(shè)置CACHE_HOST替換為任意可訪問(wèn)的鏡像或自建源對(duì)應(yīng)實(shí)現(xiàn)見(jiàn) assets.js資源 URL 形如${CACHE_HOST}/npm/cap.js/widget${WIDGET_VERSION}與${CACHE_HOST}/npm/cap.js/wasm${WASM_VERSION}/browser/...文件被下載后寫(xiě)入 Redis鍵名如asset:widget.js、asset:cap_wasm_bg.wasm等隨后由/assets/*路由從 Redis 讀出并提供給客戶端資源路由還會(huì)附加Cache-Control: max-age31536000, immutable響應(yīng)頭assets.js便于瀏覽器長(zhǎng)期緩存。2.4 常見(jiàn)故障排查若訪問(wèn)某個(gè)資源端點(diǎn)得到Asset not cached yet的響應(yīng)說(shuō)明文件尚未成功下載到 Redis 緩存該響應(yīng)對(duì)應(yīng)路由內(nèi)緩存缺失時(shí)返回的503見(jiàn) assets.js。請(qǐng)按以下順序檢查確認(rèn)容器內(nèi)真的設(shè)置了ENABLE_ASSETS_SERVERtrue如果你在 compose 文件中修改了該值需要重建容器使其生效否則/assets/*會(huì)返回404并附帶說(shuō)明 Asset server is disabled見(jiàn) assets.js。確認(rèn)容器可以訪問(wèn)CACHE_HOST若下載失敗啟動(dòng)時(shí)日志中會(huì)打印包含[asset server] failed to update assets cache的行之后每1 小時(shí)重試一次setInterval(updateCache, 1000 * 60 * 60)見(jiàn) assets.js。確認(rèn)WIDGET_VERSION與WASM_VERSION指向 npm 上真實(shí)存在的版本版本號(hào)不存在時(shí)拉取必然失敗同上記錄錯(cuò)誤日志。補(bǔ)充一點(diǎn)緩存刷新機(jī)制updateCache會(huì)讀取 Redis 中的asset:cache-config只有距上次更新超過(guò) 1 天或WIDGET_VERSION/WASM_VERSION發(fā)生變化時(shí)才重新拉取assets.js因此鎖定版本后資源緩存是長(zhǎng)期穩(wěn)定的。三、請(qǐng)求限流按客戶端 IP 的固定窗口Challenge 相關(guān)端點(diǎn)按客戶端 IP 進(jìn)行限流采用固定時(shí)間窗口fixed window算法。3.1 默認(rèn)值與調(diào)整方式默認(rèn)限制每個(gè) IP 每 5 秒最多 30 次請(qǐng)求全局調(diào)整在儀表盤(pán)Settings頁(yè)面修改或通過(guò) APIPUT /settings/ratelimit設(shè)置按鍵覆蓋在某個(gè) site key 的Configuration標(biāo)簽頁(yè)中可為該鍵單獨(dú)設(shè)置ratelimitMax與ratelimitDuration超限響應(yīng)返回 HTTP429并帶響應(yīng)頭X-RateLimit-Remaining: 0。以上默認(rèn)值max: 30, duration: 5000與 API 校驗(yàn)范圍max1–10000、duration1000–3600000 毫秒在 server.js 中有完整定義。限流核心實(shí)現(xiàn)在 ratelimit.js窗口鍵形如rl:{scope}:{ip}:{windowMs}:{window}通過(guò) RedisINCR計(jì)數(shù)、首次計(jì)數(shù)時(shí)EXPIRE設(shè)置窗口過(guò)期響應(yīng)頭同時(shí)包含X-RateLimit-Limit與X-RateLimit-Remaining超過(guò)max時(shí)返回429與{ error: Rate limit exceeded }支持getLimits回調(diào)實(shí)現(xiàn)按 site key 讀取各自的限流參數(shù)對(duì)應(yīng)Configuration 標(biāo)簽頁(yè)按鍵覆蓋。3.2 siteverify 端點(diǎn)不受限流/siteverify端點(diǎn)專為服務(wù)器到服務(wù)器server-to-server的驗(yàn)證設(shè)計(jì)默認(rèn)不參與限流。對(duì)應(yīng)的端點(diǎn)實(shí)現(xiàn)見(jiàn) siteverify.js它接收secret與response參數(shù)校驗(yàn)密鑰與一次性 token 后返回{ success: true }。3.3 代理背后的客戶端 IP 識(shí)別Standalone 識(shí)別客戶端 IP 時(shí)依次檢查以下請(qǐng)求頭X-Forwarded-ForX-Real-IPCF-Connecting-IP全部缺失時(shí)才回退到 socket 層地址。這一順序在 ratelimit.js 的DEFAULT_IP_HEADERS常量中原樣體現(xiàn)實(shí)現(xiàn)還處理了逗號(hào)分隔的鏈?zhǔn)街等〉谝粋€(gè)條目。如果你位于使用其他請(qǐng)求頭的反向代理之后有兩種方式指定 IP 來(lái)源設(shè)置環(huán)境變量RATELIMIT_IP_HEADER例如位于 Cloudflare 之后時(shí)可設(shè)為cf-connecting-ip或在儀表盤(pán)Settings Headers中配置 IP 頭。以 nginx 為例務(wù)必確保代理把真實(shí)客戶端 IP 傳給 Caplocation / { proxy_pass http://localhost:3000; proxy_set_header X-Forwarded-For $remote_addr; }兩個(gè)必須警惕的后果如果不轉(zhuǎn)發(fā)真實(shí) IP所有請(qǐng)求都會(huì)被視為來(lái)自代理自身 IP所有客戶端將共享同一個(gè)限流配額桶等于限流失效X-Forwarded-For等頭部按原樣被信任。因此服務(wù)器絕不能直接暴露在公網(wǎng)否則客戶端可以偽造頭部繞過(guò)限流代碼邏輯見(jiàn) ratelimit.js它無(wú)條件信任這些頭。四、Redis / Valkey全部持久化依賴Cap Standalone 的所有持久化數(shù)據(jù)site key、配置、會(huì)話、令牌、指標(biāo)、資產(chǎn)緩存等都存儲(chǔ)在 Redis或其兼容替代品 Valkey中。連接配置設(shè)置環(huán)境變量REDIS_URL為你的 Redis 連接字符串默認(rèn)值為redis://localhost:6379Valkey 推薦官方快速開(kāi)始指南推薦通過(guò) docker-compose 使用 ValkeyRedis 兼容存儲(chǔ)多實(shí)例隔離如果多個(gè) Cap 實(shí)例或其他應(yīng)用共用同一個(gè) Redis 實(shí)例應(yīng)設(shè)置REDIS_PREFIX為所有鍵添加命名空間前綴。例如REDIS_PREFIXcap:后會(huì)話鍵存儲(chǔ)為cap:session:...、指標(biāo)鍵存儲(chǔ)為cap:metrics:...。默認(rèn)值為空字符串因此已有部署不會(huì)受到影響。對(duì)應(yīng)源碼見(jiàn) db.js連接 URL 實(shí)際是REDIS_URL || VALKEY_URL || redis://localhost:6379的三級(jí)回退REDIS_PREFIX通過(guò)一個(gè) Proxy 包裝所有 Redis 命令自動(dòng)為get/set/hget/hmset/sadd/incr/expire等鍵名前置前綴KEY_FIRST/KEY_ALL兩組命令集合見(jiàn) db.js讀取KEYS結(jié)果時(shí)還會(huì)反向剝離前綴。此外 db.js 還實(shí)現(xiàn)了連接中斷自動(dòng)重連檢測(cè)到連接類錯(cuò)誤碼時(shí)以指數(shù)退避500ms 起、上限 15s重新建立連接并對(duì)重連前的操作進(jìn)行一次性重試增強(qiáng)了自托管場(chǎng)景下的可用性。五、健康檢查與優(yōu)雅關(guān)閉Cap Standalone 提供兩個(gè)無(wú)需認(rèn)證的端點(diǎn)供容器編排系統(tǒng)與監(jiān)控告警使用。5.1 /health 與 /health/liveGET /health當(dāng) Redis 在2 秒內(nèi)響應(yīng)PING時(shí)返回200 {status:ok}否則返回503 {status:unavailable}。用于 readiness check就緒探針與告警GET /health/live只要進(jìn)程存活就返回200即使 Redis 已宕機(jī)。用于 liveness check存活探針避免 Redis 故障期間編排系統(tǒng)反復(fù)重啟 Cap。同秒內(nèi)到達(dá)的健康檢查會(huì)復(fù)用同一次 PING因此頻繁調(diào)用/health不會(huì)給 Redis 增加額外負(fù)擔(dān)。源碼實(shí)現(xiàn)在 health.jsREDIS_TIMEOUT_MS 2000對(duì)應(yīng) 2 秒超時(shí)REDIS_CHECK_REUSE_MS 1000對(duì)應(yīng) 1 秒內(nèi)的結(jié)果復(fù)用/health/live是無(wú)條件返回ok的純靜態(tài)端點(diǎn)。5.2 Kubernetes 探針示例readinessProbe: httpGet: path: /health port: 3000 livenessProbe: httpGet: path: /health/live port: 30005.3 Docker Compose 健康檢查若使用 Docker Compose可在cap服務(wù)中追加以下配置。注意純 Docker 模式只會(huì)把容器標(biāo)記為 unhealthy不會(huì)自動(dòng)重啟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 優(yōu)雅關(guān)閉行為收到SIGTERM或SIGINT時(shí)Cap 會(huì)停止接受新連接等待正在處理的請(qǐng)求完成關(guān)閉 Redis 連接以退出碼0正常結(jié)束。若 8 秒后仍有請(qǐng)求在運(yùn)行則立即以退出碼1結(jié)束——因此總能落在 Docker 默認(rèn) 10 秒停止時(shí)限之內(nèi)如果在關(guān)閉過(guò)程中再次收到信號(hào)則直接立即退出。上述邏輯與常量SHUTDOWN_TIMEOUT_MS 8000在 index.js 與 index.js 中完整實(shí)現(xiàn)。另外兩個(gè)部署相關(guān)的環(huán)境變量也值得留意SERVER_PORT默認(rèn)3000與SERVER_HOSTNAME默認(rèn)0.0.0.0。六、錯(cuò)誤消息默認(rèn)脫敏按需開(kāi)啟詳情錯(cuò)誤響應(yīng)默認(rèn)脫敏——內(nèi)部錯(cuò)誤細(xì)節(jié)不會(huì)出現(xiàn)在響應(yīng)體中而是記錄到控制臺(tái)日志同時(shí)響應(yīng)會(huì)附帶一個(gè)隨機(jī)錯(cuò)誤 IDBun.randomUUIDv7()的尾部片段便于在日志中檢索。兩個(gè)開(kāi)關(guān)控制該行為DISABLE_ERROR_LOGGINGtrue關(guān)閉錯(cuò)誤日志輸出SHOW_ERRORStrue關(guān)閉消息脫敏把完整的錯(cuò)誤序列化詳情名稱、消息、堆棧、錯(cuò)誤碼、原因暴露在響應(yīng)體detail字段中。對(duì)應(yīng)實(shí)現(xiàn)見(jiàn) index.js 的全局onError處理器VALIDATION與NOT_FOUND兩類錯(cuò)誤默認(rèn)不寫(xiě)日志其余錯(cuò)誤默認(rèn)打印結(jié)構(gòu)化日志含時(shí)間戳、Bun 版本、平臺(tái)與內(nèi)存快照并把troubleshooting指引指向本文檔對(duì)應(yīng)章節(jié)。七、HashWXGPU 抗性的默認(rèn) PoW 協(xié)議7.1 協(xié)議與默認(rèn)行為Standalone 以HashWX作為新建 site key 的默認(rèn) challenge 協(xié)議。HashWX 是 Cap 的 GPU 抗性 proof-of-work與固定哈希函數(shù) SHA-256 不同它每個(gè) challenge 都基于 seed 生成一個(gè)全新的單向函數(shù)由整數(shù)運(yùn)算與分支構(gòu)成使得 GPU 相對(duì) CPU 幾乎沒(méi)有吞吐優(yōu)勢(shì)。三個(gè)關(guān)鍵特性按鍵獨(dú)立協(xié)議是按 site key 單獨(dú)設(shè)置的因此可以出現(xiàn)部分鍵用 SHA-256、部分鍵用 HashWX 的混合狀態(tài)舊鍵不受影響在 HashWX 成為默認(rèn)值之前創(chuàng)建的鍵會(huì)保留原有協(xié)議直到你手動(dòng)更改無(wú)需密鑰對(duì)HashWX 不要求生成或保存任何密鑰對(duì)配置成本為零。切換方式打開(kāi)該 site key 的Configuration標(biāo)簽頁(yè)在Challenge protocol下選擇所需協(xié)議即可。對(duì)應(yīng)的默認(rèn)配置在 server.js 的keyDefaults中定義protocol: hashwx、hashwxDifficulty: 1_000_000API 層允許的協(xié)議值為sha256-pow、rsw、hashwx三選一server.js。7.2 難度配置與設(shè)備耗時(shí)參考HashWX difficulty滑條控制難度其數(shù)值含義是預(yù)期客戶端需要執(zhí)行的哈希次數(shù)默認(rèn)值1_000_000被拆分為4 個(gè)子挑戰(zhàn)sub-challenges實(shí)測(cè)參考8 核桌面 Chrome 上中位數(shù)約578 毫秒手機(jī)上約1.1 到 5.9 秒調(diào)高難度前務(wù)必先參考 hashwx.md 中的手機(jī)實(shí)測(cè)數(shù)據(jù)取值范圍50_000到5_000_000。上述取值范圍與默認(rèn)值同樣在 server.js 的 API 校驗(yàn)層minimum: 50000, maximum: 5000000與配置默認(rèn)值中原樣體現(xiàn)。7.3 WebAssembly 前提與回退方案無(wú)法運(yùn)行 WebAssembly 的客戶端無(wú)法求解 HashWX challenge。如果需要兼容這類客戶端請(qǐng)把該鍵切換為SHA-256 PoW——它提供純 JavaScript 實(shí)現(xiàn)作為回退路徑。作為對(duì)比cap-core非 Standalone 場(chǎng)景默認(rèn)仍使用 SHA-256 PoW除非顯式開(kāi)啟參見(jiàn) capjs-core 的 HashWX 說(shuō)明。7.4 已廢棄的 RSW time-lockRSWRivest-Shamir-Wagner time-lock 謎題仍然可以對(duì)存量部署按鍵啟用但已廢棄GPU 每秒可求解的數(shù)量約為 CPU 的170 倍無(wú)法提供設(shè)計(jì)初衷所期望的 GPU 抗性。相關(guān)配置RSW difficulty滑條設(shè)置參數(shù)t需要順序執(zhí)行的平方運(yùn)算次數(shù)范圍10_000–300_000默認(rèn)75_000見(jiàn) server.js 的rswT默認(rèn)值及其校驗(yàn)范圍 server.jsRSW_BITS2048用于在啟動(dòng)時(shí)覆蓋 RSA 模數(shù)的位寬對(duì)應(yīng) rsw-store.js 中的密鑰對(duì)加載與刷新邏輯。小提示widget 能夠根據(jù)數(shù)據(jù)格式自動(dòng)檢測(cè)挑戰(zhàn)協(xié)議因此當(dāng)你調(diào)整鍵的協(xié)議時(shí)唯一需要做的就是切換鍵本身無(wú)需修改前端代碼。八、Instrumentation 挑戰(zhàn)攔截自動(dòng)化與 headless 瀏覽器除了 PoWCap Standalone 還支持JavaScript instrumentation challenge用于應(yīng)對(duì)能自動(dòng)求解 proof-of-work 的攻擊者并可選擇性地?cái)r截 headless 瀏覽器默認(rèn)開(kāi)啟新建 site key 時(shí)instrumentation challenge 默認(rèn)啟用對(duì)應(yīng) server.js 中instrumentation: false為 API 入?yún)⒛J(rèn)而儀表盤(pán)新建流程會(huì)開(kāi)啟它配置結(jié)構(gòu)支持每個(gè)鍵獨(dú)立開(kāi)關(guān)開(kāi)關(guān)位置在 site key 的設(shè)置頁(yè)面中開(kāi)啟或關(guān)閉攔截 headless如需屏蔽 headless 瀏覽器在該鍵設(shè)置中打開(kāi)Attempt to block headless browsers對(duì)應(yīng)配置字段blockAutomatedBrowsers見(jiàn) server.js混淆級(jí)別obfuscationLevel默認(rèn)3取值范圍 1–10server.js。官方建議保持級(jí)別 3除非你需要更強(qiáng)的混淆效果過(guò)高的級(jí)別會(huì)顯著降低成功率。如果覺(jué)得級(jí)別 3 太慢級(jí)別 1 在單核上會(huì)快得多。九、IP 數(shù)據(jù)庫(kù)國(guó)家與 ASN 歸屬查詢Cap Standalone 的統(tǒng)計(jì)與地理功能依賴 IP 歸屬查詢支持在儀表盤(pán)Settings IP Data Country ASN data中從三個(gè)提供商中選擇DB-IP Lite免費(fèi)無(wú)需憑據(jù)自動(dòng)嘗試最近 3 個(gè)月的數(shù)據(jù)文件MaxMind GeoLite2需要 MaxMind 賬戶 ID 與 License Key通過(guò) Basic Auth 下載 tar.gz 并解包出.mmdbIPInfo API需要 API token走遠(yuǎn)程 HTTP 查詢本地不落地文件。對(duì)于 DB-IP 與 MaxMind.mmdb文件會(huì)被下載到容器內(nèi)的/usr/src/app/data/目錄。對(duì)應(yīng)實(shí)現(xiàn)見(jiàn) ipdb.jsDATA_DIR指向standalone/data在容器中即/usr/src/app/data下載、解壓、進(jìn)度上報(bào)與每 2 小時(shí)重載RELOAD_INTERVAL的完整流程均在該文件中。Docker volume 權(quán)限問(wèn)題容器以非特權(quán)用戶bunUID 1000運(yùn)行見(jiàn) Dockerfile 的USER bun。如果你把宿主機(jī)目錄 bind-mount 到/usr/src/app/data該目錄必須允許 UID 1000 寫(xiě)入否則下載會(huì)失敗并報(bào)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 # ...如果無(wú)法修改宿主機(jī)文件屬主部分平臺(tái)如 Coolify 操作起來(lái)較麻煩最簡(jiǎn)單的替代方案有三個(gè)不做 bind mount讓 Docker 管理數(shù)據(jù)目錄——鏡像在構(gòu)建時(shí)已創(chuàng)建好目錄并設(shè)置了正確屬主Dockerfile 中的mkdir -p data chown bun:bun data改用named volume代替 bind mount切換到無(wú)需本地文件的 IP 數(shù)據(jù)提供商即 IPInfo API 模式。值得補(bǔ)充的是ipdb.js 啟動(dòng)時(shí)會(huì)對(duì)數(shù)據(jù)目錄做可寫(xiě)性探測(cè)寫(xiě)入并刪除.write-test文件失敗時(shí)會(huì)直接輸出包含chown 1000:1000建議的錯(cuò)誤日志方便你在容器日志中第一時(shí)間定位該問(wèn)題?？偨Y(jié)生產(chǎn)部署配置速查結(jié)合本文與源碼一份自托管生產(chǎn)部署的最小關(guān)注清單如下關(guān)注點(diǎn)環(huán)境變量 / 配置默認(rèn)值生產(chǎn)建議跨域CORS_ORIGIN*收窄為你的域名白名單靜態(tài)資源ENABLE_ASSETS_SERVER關(guān)閉自托管時(shí)置true資源版本W(wǎng)IDGET_VERSION/WASM_VERSIONlatest固定到已發(fā)布的具體版本資源來(lái)源CACHE_HOSTjsdelivr CDN可替換為自建鏡像限流儀表盤(pán)或PUT /settings/ratelimit30 次 / 5 秒按業(yè)務(wù)峰值調(diào)整勿直接暴露公網(wǎng)代理 IPRATELIMIT_IP_HEADER或 Settings Headers標(biāo)準(zhǔn)三頭按代理類型設(shè)置并確保轉(zhuǎn)發(fā)真實(shí) IP存儲(chǔ)REDIS_URLredis://localhost:6379生產(chǎn)建議獨(dú)立實(shí)例多實(shí)例隔離REDIS_PREFIX空共享實(shí)例時(shí)務(wù)必設(shè)置健康檢查/health、/health/live—接入編排系統(tǒng)探針挑戰(zhàn)協(xié)議每鍵 ConfigurationHashWX按客戶端兼容性選擇混淆級(jí)別obfuscationLevel3保持 3慢則降 1IP 數(shù)據(jù)目錄/usr/src/app/data—bind mount 時(shí)確保 UID 1000 可寫(xiě)若需從頭部署請(qǐng)結(jié)合 Cap Standalone 快速開(kāi)始指南含 Valkey 的 docker-compose 配置與 API 文檔 一起閱讀HashWX 協(xié)議的設(shè)計(jì)原理與成本實(shí)測(cè)可繼續(xù)參考 HashWX 詳解。贊分享網(wǎng)絡(luò)安全應(yīng)用安全后端【免費(fèi)下載鏈接】capFree, open-source and self-hosted CAPTCHA alternative to reCAPTCHA. Privacy-first and powered by proof-of-work and instrumentation challenges.項(xiàng)目地址https://gitcode.com/gh_mirrors/cap13/cap點(diǎn)擊查看免費(fèi)下載相關(guān)推薦Cap Standalone 配置指南CORS、資源服務(wù)器、限流、健康檢查與挑戰(zhàn)協(xié)議全解析Cap Standalone 配置指南CORS、資源服務(wù)器、限流、健康檢查與挑戰(zhàn)協(xié)議全解析 Cap Standalone 是 Cap https://link網(wǎng)絡(luò)安全應(yīng)用安全后端Cap Standalone 配置完全指南CORS、Asset Server、限流與 HashWX Proof-of-Work 環(huán)境變量詳解Cap Standalone 配置完全指南CORS、Asset Server、限流與 HashWX Proof of Work 環(huán)境變量詳解 Cap Stan網(wǎng)絡(luò)安全應(yīng)用安全后端Cap Standalone 配置選項(xiàng)與環(huán)境變量完全指南CORS、資源服務(wù)器、限流、健康檢查與哈希工作量證明Cap Standalone 配置選項(xiàng)與環(huán)境變量完全指南CORS、資源服務(wù)器、限流、健康檢查與哈希工作量證明 本篇技術(shù)指南以 Cap Standalone開(kāi)網(wǎng)絡(luò)安全應(yīng)用安全后端上一篇Arnis終極部署指南5種環(huán)境配置策略與高效管理技巧下一篇最全面Manim版本解析社區(qū)版vs原版核心差異與選擇指南創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考