OpenProject reCAPTCHA 配置指南：为登录流程接入 Google reCAPTCHA 与 Cloudflare Turnstile

OpenProject reCAPTCHA 配置指南为登录流程接入 Google reCAPTCHA 与 Cloudflare Turnstile【免费下载链接】openprojectOpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub项目地址: https://gitcode.com/GitHub_Trending/op/openproject本文基于 OpenProject 系统管理员的官方文档完整讲解如何在 OpenProject 中启用并配置 reCAPTCHAv2 / v3、HCaptcha 以及 Cloudflare Turnstile覆盖管理界面操作步骤、每一项配置参数的含义并结合modules/recaptcha模块源码深入剖析验证流程与底层实现。读完本文你将能够在自托管 OpenProject 实例上独立完成 CAPTCHA 服务的接入、密钥配置与行为验证并理解登录时“先验 CAPTCHA 再完成认证”这一认证阶段的完整链路。功能概览与启用入口OpenProject 将 CAPTCHA 能力以独立插件模块modules/recaptcha形式提供。启用后所有尚未完成 CAPTCHA 验证的用户在登录时都会被要求先通过一个人机验证表单验证成功后才能继续后续登录流程。配置入口在 Web 管理界面Administration管理 →Authentication认证 →reCAPTCHA对应源码中的管理页面控制器为 modules/recaptcha/app/controllers/recaptcha/admin_controller.rb其路由定义在 modules/recaptcha/config/routes.rbnamespace recaptcha do get :settings, to: admin#show post :settings, to: admin#update get :request, to: request#perform, as: request post :verify, to: request#verify, as: verify end其中GET /recaptcha/settings展示配置页POST /recaptcha/settings提交并保存配置GET /recaptcha/request与POST /recaptcha/verify则服务于登录流程中的验证表单渲染与结果校验。支持的 CAPTCHA 类型在模块入口文件 modules/recaptcha/lib/open_project/recaptcha.rb 中定义了全部可选类型常量TYPE_DISABLED disabled TYPE_V2 v2 TYPE_V3 v3 TYPE_HCAPTCHA hcaptcha TYPE_TURNSTILE turnstile管理界面下拉框的候选选项由 modules/recaptcha/app/helpers/recaptcha_helper.rb 中的recaptcha_available_options生成包含五档禁用disabled、reCAPTCHA v2、reCAPTCHA v3、HCaptcha、Turnstile。也就是说“reCAPTCHA 设置”页面实际承载了 Google reCAPTCHA、HCaptcha 与 Cloudflare Turnstile 三种服务的统一配置任何服务都复用同一套管理表单与验证入口。配置项详解官方文档列出的可配置项与 modules/recaptcha/app/views/recaptcha/admin/show.html.erb 中的表单字段一一对应配置项表单字段说明CAPTCHA 类型recaptcha_type在下拉框中选择 disabled / v2 / v3 / hcaptcha / turnstileWebsite key网站密钥website_key在 CAPTCHA 服务商后台创建的公钥用于前端表单渲染Secret key密钥secret_key服务商后台生成的私钥用于服务端校验用户响应HCaptcha response limitresponse_limitHCaptcha 专用响应值长度限制默认5000见下文源码Apply 按钮—提交并保存全部设置所有设置最终保存到 OpenProject 的插件设置项Setting.plugin_openproject_recaptcha控制器中允许提交的参数被严格白名单限制为:recaptcha_type, :website_key, :secret_key, :response_limit见 admin_controller.rb。HCaptcha response limit 的底层默认值配置类 modules/recaptcha/lib/open_project/recaptcha/configuration.rb 展示了该参数的默认行为def hcaptcha_response_limit (::Setting.plugin_openproject_recaptcha[response_limit] || 5000).to_i end即当管理界面未填写该字段时默认按5000处理同时该配置类还固定了 HCaptcha 的服务端校验地址https://hcaptcha.com/siteverify与前端脚本地址https://hcaptcha.com/1/api.js。分步配置激活 Google reCAPTCHA按照官方文档的操作流程在 OpenProject 中启用 Google reCAPTCHA 需要完成以下步骤进入管理界面访问Administration→Authentication→reCAPTCHA。选择 CAPTCHA 类型在类型下拉框中根据需求选择reCAPTCHA v2或reCAPTCHA v3。v2 需要用户点击“我不是机器人”复选框或图片挑战v3 在后台根据行为评分、对用户几乎无感两种版本在使用体验与安全模型上有明显差异请结合站点自身的防滥用需求选择。获取密钥前往 Google 官方 reCAPTCHA 服务页面注册你的域名并分别生成Website key网站密钥与Secret key密钥。网站密钥会以公开形式嵌入登录页面密钥必须严格保密、只保存在服务端。填入网站密钥将 Website key 粘贴到对应输入框。填入密钥将 Secret key 粘贴到对应输入框。如使用 HCaptcha填写响应值长度限制仅当类型选择 HCaptcha 时该参数生效留空则使用默认值5000。点击 Apply 保存保存成功后界面会提示更新成功并跳回设置页。需要说明的是由于管理表单由styled_select_tag渲染类型选择与密钥填写必须在同一次提交中完成admin_controller.rb 中的validate_settings会在更新前校验recaptcha_type是否属于合法候选值若传入非法值会直接返回 400 错误提示不会写入设置。Cloudflare Turnstile 配置Turnstile 是 Cloudflare 提供的无感验证服务。使用前需先在 Cloudflare 控制台创建站点并获取sitekey站点密钥与secret key密钥官方文档中的操作步骤如下在 Cloudflare 控制台创建 Turnstile 站点获得 sitekey 与 secret key。在 OpenProject 管理界面的 reCAPTCHA 设置中将类型下拉框选择为“Turnstile”。将 Cloudflare 生成的sitekey 填入 Website key 字段表单字段名仍为website_key。将secret key 填入 Secret key 字段。点击Apply保存。配置完成后前端页面会加载 Cloudflare 的 Turnstile 脚本并在登录页渲染验证组件。前端渲染逻辑位于 modules/recaptcha/app/views/recaptcha/request/perform.html.erb它通过onloadTurnstileCallback回调调用turnstile.render(#turnstile-container, { sitekey, callback: submitTurnstileForm })拿到 token 后写入隐藏字段turnstile-response并自动提交表单。登录时的验证流程与源码机制认证阶段Authentication Stage设计CAPTCHA 验证被设计为 OpenProject 登录流程中的一个认证阶段。用户提交用户名密码通过初步校验后若其尚未验证过 CAPTCHA会被重定向到验证表单GET /recaptcha/request完成验证后再回到登录流程POST /recaptcha/verify。请求控制器 modules/recaptcha/app/controllers/recaptcha/request_controller.rb 定义了一系列前置过滤条件构成完整的跳转决策链skip_if_disabledCAPTCHA 类型为 disabled 时直接完成该阶段require_authenticated_user从会话session[:authenticated_user_id]取出已通过密码验证的用户取不到则走失败分支skip_if_admin管理员用户自动跳过 CAPTCHAskip_if_user_verified用户若已有验证记录则直接跳过。验证结果的持久化验证成功的用户会在recaptcha_entries表中写入一条记录模型见 modules/recaptcha/app/models/recaptcha/entry.rb为Recaptcha::Entry属于User再次验证时会先删除旧记录再写入新记录::Recaptcha::Entry.where(user_id: authenticated_user.id).delete_all ::Recaptcha::Entry.create!(user_id: authenticated_user.id, version: recaptcha_version)这解释了官方文档中“所有尚未验证 CAPTCHA 的用户”的含义已验证用户含管理员登录时不再出现验证表单只有新用户或验证记录被清除的用户需要验证。服务端校验与版本映射verify动作对 reCAPTCHA 使用verify_recaptchav3 时额外携带action: login对 Turnstile 则直接向https://challenges.cloudflare.com/turnstile/v0/siteverify发起POST请求携带response前端 token、remoteip用户 IP与secret以响应 JSON 中的success字段判定是否通过request_controller.rb。recaptcha_version方法给出了类型与版本号的映射v2 与 HCaptcha 记为版本 2v3 记为版本 3Turnstile 记为99注释明确说明 Turnstile 与 reCAPTCHA 不可比、不兼容该版本号仅作记录用途。内容安全策略CSP适配由于登录页需要加载第三方脚本与 iframe控制器在渲染验证表单时通过allow_captcha_service动态追加 CSP 指令request_controller.rbreCAPTCHA放行www.recaptcha.net/recaptcha/与www.gstatic.com/recaptcha/的frame-srcHCaptcha放行*.hcaptcha.com的frame-src / script-src / style-src / connect-srcTurnstile放行challenges.cloudflare.com的frame-src / style-src / connect-src。这意味着即使你的站点启用了严格 CSP三种服务也能正常工作无需手工修改安全策略。行为要点总结场景行为CAPTCHA 类型为 disabled不渲染任何验证表单登录流程直接跳过管理员登录自动跳过验证已有Recaptcha::Entry记录的用户自动跳过验证新用户首次登录必须先通过 CAPTCHA 才能完成登录验证失败跳回登录流程并展示错误提示recaptcha.error_captcha密钥/类型不合法管理端返回 400不写入设置相关源码索引如需深入阅读实现细节可继续查看以下仓库文件管理界面与设置保存modules/recaptcha/app/controllers/recaptcha/admin_controller.rb、modules/recaptcha/app/views/recaptcha/admin/show.html.erb类型常量与配置读取modules/recaptcha/lib/open_project/recaptcha.rb、modules/recaptcha/lib/open_project/recaptcha/configuration.rb登录验证流程modules/recaptcha/app/controllers/recaptcha/request_controller.rb、modules/recaptcha/app/views/recaptcha/request/perform.html.erb数据模型与路由modules/recaptcha/app/models/recaptcha/entry.rb、modules/recaptcha/config/routes.rb相关测试modules/recaptcha/spec/controllers/admin_controller_spec.rb、modules/recaptcha/spec/controllers/request_controller_spec.rb总而言之OpenProject 的 reCAPTCHA 配置只需在管理界面完成“选类型、填两组密钥、点 Apply”三个动作即可生效其背后则是一个以认证阶段为骨架、以recaptcha_entries记录为记忆、以服务商验证接口为准绳的完整验证链路理解这些源码细节能帮助你在排查“为什么某些用户不弹验证”“为什么 Turnstile 验证失败”等问题时快速定位到对应环节。【免费下载链接】openprojectOpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub项目地址: https://gitcode.com/GitHub_Trending/op/openproject创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考