验证码
校对日期:2026-10-28。适用于社区版及全部商业版;接入第三方验证码服务需要商业版基础版。
本指南面向站点管理员,介绍系统的人机验证方式、“全局设置 › 验证码”各项设置的含义,以及接入第三方验证码服务的步骤。
一、系统提供哪些验证方式
| 方式 | 说明 | 版本 |
|---|---|---|
| 滑块拼图(默认) | 把拼图块拖到缺口处。背景由系统即时生成,不依赖图库,支持键盘操作(左右方向键移动、回车提交) | 全部 |
| 字符验证码 | 输入图片中的字符,不区分大小写。始终可用:滑块界面上有“使用字符验证码”的切换入口,作为无障碍回退 | 全部 |
| 免验证提交 | 评论、留言、表单等互动场景在同一 IP 一小时内的提交未达设定次数时不显示验证码,浏览器在后台完成一次“工作量证明”计算即可提交;达到次数后显示可见验证 | 全部 |
| 第三方验证码 | 极验、腾讯云天御、阿里云验证码 2.0、网易易盾、Cloudflare Turnstile。前台显示厂商的验证组件,服务端向厂商二次校验,由厂商的风控引擎判定 | 基础版 |
哪里会要求验证:
- 互动表单(评论、留言、自定义表单、领导信箱、依申请公开、访谈提问):按“免验证提交次数”静默或显示。参考主题在需要显示时于点击提交后弹出滑块,表单里不占位置;文章页的评论框在首次点击输入时才加载组件;
- 会员注册(验证方式为“不验证”或“人工审核”时)、发送短信 / 邮件验证码:始终需要可见验证。参考主题的注册页在点击“注册”时才弹出滑块,答完后显示“已验证”;
- 登录(控制台与前台会员登录):同一 IP 登录失败超过“安全设置 › IP 验证码次数”后显示。
二、设置项
入口:管理后台 → 配置 → 全局设置 → 验证码(需具有“验证码”设置的修改权限)。
| 设置项 | 默认 | 说明 |
|---|---|---|
| 验证码类型 | 滑块拼图 | 可见验证使用的方式。选第三方厂商时须填齐该厂商的凭据,保存即生效 |
| 免验证提交次数 | 3 | 互动表单同一 IP 一小时内免验证的提交次数;0 表示总是显示验证码 |
| 工作量证明难度 | 18 | 免验证提交时浏览器需要完成的计算量(10–24)。18 在普通手机上不到一秒;每加 1 翻一倍。遭遇批量灌水时可适当调高 |
页面底部的“预览”显示已保存设置的实际效果;修改类型后请先保存再看预览。
密钥类字段(验证 KEY、Secret Key 等)保存后不回显,再次打开时留空即表示不修改。
三、接入第三方验证码服务(基础版)
- 在厂商控制台创建验证场景,记下公开标识与密钥(见下表)。
- 在“全局设置 › 验证码”选中该厂商,填入凭据,保存。
- 打开任意前台表单或控制台登录页(登录失败三次后)确认厂商组件正常显示并能通过。
| 厂商 | 需要填写 | 厂商控制台 |
|---|---|---|
| 极验 GeeTest v4 | 验证 ID、验证 KEY | 极验后台 → 验证管理 |
| 腾讯云天御验证码 | 验证码 CaptchaAppId、App Secret Key,以及调用云 API 的 SecretId / SecretKey(建议子账号,授权 captcha:DescribeCaptchaResult) | 腾讯云 → 验证码 → 验证管理;访问管理 → API 密钥 |
| 阿里云验证码 2.0 | AccessKey ID / Secret(建议 RAM 子账号,授权 captcha:VerifyIntelligentCaptcha)、场景 ID、身份标(prefix)、地域 | 阿里云 → 验证码 2.0 → 场景管理、概览 |
| 网易易盾 | 验证码 ID、密钥 ID、密钥 | 易盾 → 行为式验证码 → 验证码管理、密钥管理 |
| Cloudflare Turnstile | Site Key、Secret Key | Cloudflare → Turnstile |
注意事项:
- 服务端需要能访问厂商接口(公网)。内网、离线部署无法使用第三方验证码,请使用滑块拼图或字符验证码。
- 厂商接口不可达或返回失败时,提交一律判为未通过,不会放行;浏览器端厂商脚本加载失败时自动切换为滑块拼图。
- 控制台页面带有内容安全策略,系统只放行当前选中厂商的域名;切换厂商后无需额外配置。
- 社区版与未填凭据的情况下无法选中厂商;从高版本降级后库中残留的厂商设置会自动按滑块拼图出题。
四、主题开发
参考主题的所有表单已改用共用组件 /static/,无需在主题里实现验证码界面:
html
<script src="${ctx}/static/captcha.js?v=${v}" data-lang="zh" defer></script>
<div x-ref="captcha" data-captcha></div>
<script>
const cap = window.UjcmsCaptcha.mount(el, { api: '${api}', scope: 'comment', popup: true });
const { captcha, captchaToken } = await cap.answer(); // 随表单一起 POST
cap.refresh(); // 提交失败后换一题
</script>- 脚本标签上的
data-lang(zh|en)按主题自己的文案语言钉一次:组件文案与主题文案同处一屏,跟主题走,不跟站点语言走;不写则按<html lang>; scope为互动场景代码(comment、messageBoard、form、mailbox、disclosure、interview),不传则始终显示可见验证(注册、短信);popup: true(或元素上的data-popup)为弹层模式:挂载时不出题,answer()时才把滑块 / 字符题弹出,答完关闭并返回答案,关闭或取消则拒绝(message可直接提示)。参考主题的全部表单都用它:静默场景照旧后台完成,需要可见验证时点击提交才弹出,第三方厂商照旧即时渲染;挂载前、答题前宿主为空,主题样式用[data-captcha]:折叠它;empty { display: none } - 传统表单提交(如会员登录页 POST 到
/login)加data-hidden,组件把答案写入隐藏域captcha、captchaToken; - 自行调用接口的客户端可用
GET /固定取字符验证码(返回api/ captcha?type= char token与image),其余类型见接口文档。
五、集群部署
验证码令牌由 captcha.secret 签名,多台服务器须使用一致的固定值(见集群部署); 免验证次数、验证码尝试次数等计数在启用 Redis 缓存时各节点共享。