Halo博客实人验证接入指南

🚀 Halo博客实人验证接入指南 | Cloudflare Turnstile本地化部署方案
针对Halo博客系统特性，推荐采用 精准验证模式 保护核心交互（评论/登录），同时保持全站访问流畅。以下是分步实施方案：

一、前置条件准备

1. 域名托管

   • 确保域名DNS已托管至Cloudflare
   • 检查Halo后台「系统」→「博客设置」中的域名与Cloudflare一致

2. 获取Turnstile密钥

   • 访问 Cloudflare控制台
   • 进入「网站」→「Turnstile」→「添加站点」
   • 填写信息：

     站点名称：Halo验证组件  
     域名：yourdomain.com  
     小组件模式：托管（Managed）  
     

   • 记录生成的 Site Key 和 Secret Key

二、前端验证组件集成

方案A：修改主题模板（推荐）

1. 定位模板文件

   • 进入Halo后台「外观」→「主题编辑」
   • 找到评论模块模板：/templates/comment.html
   • 找到登录页模板：/templates/login.html

2. 插入验证代码
   在表单标签内添加：

   <!-- 在提交按钮前插入 -->
   <div class="cf-turnstile" 
        data-sitekey="您的SiteKey" 
        data-action="comment-submit"></div>
   

3. 加载JS脚本
   在页面底部（footer.html）添加：

   <script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
   

方案B：使用插件注入（无需改代码）

1. 安装 Halo插件：Code Injector
2. 在插件设置中添加：

   位置：Footer
   内容：<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
   

3. 在评论框下方通过HTML部件添加验证组件

三、后端Token校验

由于Halo原生不支持Turnstile，需通过 反向代理层 或 插件扩展 实现：

方案1：Nginx中间校验（高性能）

location /apis/comments {
    # 先向Cloudflare验证token
    access_by_lua_block {
        local res = ngx.location.capture("/validate-turnstile?token="..ngx.var.arg_token)
        if res.status ~= 200 then
            ngx.exit(403)
        end
    }
    # 转发到Halo后端
    proxy_pass http://localhost:8090;
}

方案2：开发简易验证插件

1. 创建Spring Boot组件：

   @Component
   public class TurnstileValidator {
       private static final String API_URL = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
       
       public boolean validate(String token) {
           // 发送POST请求验证token
       }
   }
   

2. 在CommentController中添加拦截：

   @PostMapping("/comments")
   public ResponseEntity<?> createComment(@RequestParam String cfToken) {
       if (!turnstileValidator.validate(cfToken)) {
           throw new ForbiddenException("验证失败");
       }
       // 原处理逻辑
   }
   

四、凌霞软件适配建议

若您通过凌霞平台托管Halo，建议：

1. 联系技术支持开通 自定义HTTP Header 权限
2. 在Cloudflare设置规则：

   路径：/admin/*  
   规则：启用Turnstile验证  
   

3. 使用边缘函数实现零代码验证：

   export default {
       async fetch(request) {
           const token = request.headers.get('cf-turnstile-token');
           const { success } = await validateToken(token);
           return success ? fetch(request) : new Response('Blocked', { status: 403 });
       }
   }
   

🔧 验证效果测试

1. 隐身访问博客提交评论，应出现旋转盾牌图标
2. 成功提交后，在Cloudflare控制台查看验证统计：

   安全 → Turnstile → 请求分析  
   

📌 注意事项

• 开启验证后建议禁用Halo自带验证码
• 移动端适配需添加CSS样式：

  .cf-turnstile { transform: scale(0.9); margin: 10px 0; }
  

• 遇到加载问题可添加data-language="zh"参数支持中文

需要Turnstile定制样式代码或遇到部署障碍？可提供具体页面URL协助诊断。