🏠首页 › Discuz!插件模板 › Discuz!X3.5 X3.4腾讯云验证码（CAPTCHA）插件(tencentcloud_captcha)

admin 发表于 2020-8-11 09:44:04

Discuz!X3.5 X3.4腾讯云验证码（CAPTCHA）插件(tencentcloud_captcha)

# 腾讯云验证码插件

## [#](https://openapp.qq.com/docs/DiscuzX/captcha.html#_1-%E6%8F%92%E4%BB%B6%E4%BB%8B%E7%BB%8D)1.插件介绍

> tencentcloud_captcha插件是一款腾讯云研发的，提供给Discuz! X站长使用的官方插件。基于原有的验证码基础上提供腾讯云验证码机制进行安全验证。


| 标题 | 名称 |
| - | - |
| 中文名称 | 腾讯云验证码（CAPTCHA）插件 |
| 英文名称 | tencentcloud_captcha |
| 最新版本 | v1.0.0 (2020.07.17) |
| 适用平台 | (https://www.discuz.net/forum.php) |
| 适用产品 | [腾讯云验证码](https://www.discuz.net/forum.php) |
| GitHub项目 | (https://github.com/Tencent-Cloud-Plugins/tencentcloud-discuzx-plugin-captcha) |
| 主创团队 | 腾讯云中小企业产品中心（SMB Product Center of Tencent Cloud） |

## [#](https://openapp.qq.com/docs/DiscuzX/captcha.html#_2-%E5%8A%9F%E8%83%BD%E7%89%B9%E6%80%A7)2.功能特性

* 在Discuz! X上提供腾讯云的增强版验证码功能
* 支持登录、注册腾讯云验证码验证功能
* 支持评论、发帖腾讯云验证码验证功能
* 支持修改密码、赞助充值卡·密腾讯云验证码验证功能

## [#](https://openapp.qq.com/docs/DiscuzX/captcha.html#_3-%E5%AE%89%E8%A3%85%E6%8C%87%E5%BC%95)3.安装指引

### [#](https://openapp.qq.com/docs/DiscuzX/captcha.html#_3-1-%E9%83%A8%E7%BD%B2%E6%96%B9%E5%BC%8F%E4%B8%80%EF%BC%9A%E9%80%9A%E8%BF%87github%E9%83%A8%E7%BD%B2%E5%AE%89%E8%A3%85)3.1.部署方式一：通过GitHub部署安装

> 1. git clone https://github.com/Tencent-Cloud-Plugins/tencentcloud-discuzx-plugin-captcha.git
> 2. 复制tencentcloud-captcha 文件夹 到Discuz! X安装路径/source/plugin/文件夹里面

## [#](https://openapp.qq.com/docs/DiscuzX/captcha.html#_4-%E4%BD%BF%E7%94%A8%E6%8C%87%E5%BC%95)4.使用指引

### [#](https://openapp.qq.com/docs/DiscuzX/captcha.html#_4-1-%E9%A1%B5%E9%9D%A2%E5%8A%9F%E8%83%BD%E4%BB%8B%E7%BB%8D)4.1. 页面功能介绍


> 验证码设置页面，本插件已接入系统的验证码模块，开启后请前往系统后台-防灌-验证设置进行具体场景的验证码配置。


> 开启验证码之后的效果。

### [#](https://openapp.qq.com/docs/DiscuzX/captcha.html#_4-2-%E5%90%8D%E8%AF%8D%E8%A7%A3%E9%87%8A)4.2. 名词解释

* **自定义密钥**：插件提供统一密钥管理，在多个腾讯云插件时可以共享SecretId和SecretKey，支持各插件自定义密钥。
* **SecretId**：在腾讯云云平台API密钥上申请的标识身份的 SecretId,用于身份验证。详情参考[腾讯云文档](https://cloud.tencent.com/document/product)。
* **SecretKey**：在腾讯云云平台API密钥上申请的标识身份的SecretId对应的SecretKey，用于身份验证。详情参考[腾讯云文档](https://cloud.tencent.com/document/product)。
* **CaptchaAppId**： 在腾讯云短信验证码控制台应用的应用ID，该应用ID默认应用全部场景。详情参考[腾讯云文档](https://cloud.tencent.com/document/product)。
* **CaptchaAppSecretKey**： 在腾讯云短信验证码控制台应用的密钥，需和应用ID匹配。详情参考[腾讯云文档](https://cloud.tencent.com/document/product)。

## [#](https://openapp.qq.com/docs/DiscuzX/captcha.html#_5-%E8%8E%B7%E5%8F%96%E5%85%A5%E5%8F%A3)5.获取入口


| 插件入口 | 链接 |
| - | - |
| GitHub | (https://github.com/Tencent-Cloud-Plugins/tencentcloud-discuzx-plugin-captcha) |

## [#](https://openapp.qq.com/docs/DiscuzX/captcha.html#_6-faq)6.FAQ

> 暂无

## [#](https://openapp.qq.com/docs/DiscuzX/captcha.html#_7-github%E7%89%88%E6%9C%AC%E8%BF%AD%E4%BB%A3%E8%AE%B0%E5%BD%95)7.GitHub版本迭代记录

### [#](https://openapp.qq.com/docs/DiscuzX/captcha.html#_7-1-tencentcloud-discuzx-plugin-captcha-v1-0-0)7.1 tencentcloud-discuzx-plugin-captcha v1.0.0

* 在Discuz! X上提供腾讯云的增强版验证码功能
* 支持登录、注册腾讯云验证码验证功能
* 支持评论、发帖腾讯云验证码验证功能
* 支持修改密码、赞助充值卡·密腾讯云验证码验证功能

## [#](https://openapp.qq.com/docs/DiscuzX/captcha.html#_8-%E8%87%B4%E8%B0%A2)8.致谢

> 该插件参考了Discuz! X插件(https://github.com/popcorner/discuz_recaptcha) 的实现方法，特此对其主创团队进行致谢。

Discuz智能体 发表于 2025-3-13 15:07:27

针对腾讯云验证码插件在Discuz中的使用，以下是一些常见问题的专业解决方案：

### 一、插件安装后未生效
1. **文件权限检查**
   - 确认`source/plugin/tencentcloud_captcha`目录权限为755，文件权限644
   - 通过FTP检查文件完整性，确保无上传中断导致的文件缺失

2. **目录结构验证**
   正确结构应为：
   source/plugin/tencentcloud_captcha/
   ├── captcha
   │   └── ...（验证码核心文件）
   ├── template
   │   └── ...（模板文件）
   └── discuz_plugin_tencentcloud_captcha.xml

### 二、验证码无法显示
1. **密钥配置核对**
   - 登录腾讯云控制台，进入[验证码控制台](https://console.cloud.tencent.com/captcha)
   - 确认获取的：
   - CaptchaAppId（以`20******`开头的9位数字）
   - CaptchaAppSecretKey（32位字符串）
   - 注意区分「插件密钥」与「验证码密钥」的不同位置

2. **前端冲突排查**
   <!-- 检查页面源码是否加载以下资源 -->
   <script src="https://ssl.captcha.qq.com/TCaptcha.js"></script>
   <script src="plugin/tencentcloud_captcha/captcha/js/index.js"></script>

### 三、验证流程失败
1. **服务器时间校准**
   # Linux服务器执行时间同步
   ntpdate ntp.tencent.com
   - 时区应设置为`Asia/Shanghai`
   - 时间误差需控制在90秒内

2. **API连通性测试**
   curl -I https://captcha.tencentcloudapi.com
   telnet captcha.tencentcloudapi.com 443
   确保服务器出站放通HTTPS协议

### 四、多插件兼容处理
1. **验证码冲突解决**
   修改`source/plugin/tencentcloud_captcha/captcha/class目录下的处理类：
   // 在文件顶部添加优先级声明
   define('PLUGIN_PRIORITY', 999);
   class plugin_tencentcloud_captcha extends discuz_plugin {
       //...原有代码
   }

2. **模板覆盖问题**
   在`template/default/member/login.htm`等模板文件中：
   <!-- 查找原有验证码代码 -->
   <!--{subtemplate common/header}-->
   <!-- 替换为 -->
   <!--{hook/tencentcloud_captcha::render}-->

### 五、高级调试方法
1. **开启调试模式**
   // 修改captcha/class/Captcha.php
   define('CAPTCHA_DEBUG', true);
   会在data目录生成`captcha_debug.log`记录验证过程

2. **自定义样式调整**
   修改`template/captcha.htm`：
   .tc-captcha-btn {
       width: 300px!important;/* 适配不同分辨率 */
       background: #00a4ff!important;/* 品牌色定制 */
   }

### 六、安全加固建议
1. **频率限制配置**
   // 在插件配置中设置
   $_config['security']['max_attempts'] = 5;// 每小时最大尝试次数
   $_config['security']['ban_time'] = 3600;// 封禁时长(秒)

2. **验证结果二次验证**
   // 在验证通过后添加
   if(!defined('IN_DISCUZ') || !$GLOBALS['_G']['uid']) {
       showmessage('request_illegal');
   }

遇到具体问题时可提供以下信息以便快速定位：
1. Discuz版本号（X3.4/X3.5）
2. PHP版本（5.6/7.2/7.4）
3. 浏览器控制台错误截图
4. 插件配置界面截图（需模糊处理密钥信息）
5. 服务器错误日志片段

更多技术细节可参考DZ插件网（www.dz-x.net）的《Discuz!插件开发规范》和《验证码集成指南》。
-- 本回答由 人工智能 AI智能体 生成，内容仅供参考，请仔细甄别。

Discuz智能体 发表于 2025-3-13 15:21:40

在部署和使用腾讯云验证码插件时，站长需注意以下技术要点：

1. **环境兼容性验证**
- 确认Discuz!版本为X3.4/X3.5（检查source/discuz_version.php）
- 验证PHP版本≥7.0且开启curl扩展（通过phpinfo确认）
- 检查服务器443端口开放状态（telnet captcha.tencentcloudapi.com 443）

2. **密钥安全处理方案**
// 密钥加密存储示例（/plugin/tencentcloud_captcha/tencentcloud_captcha.class.php）
$secretId = authcode($_G['setting']['tencentcloud_captcha']['secretid'], 'DECODE', MD5($_G['config']['security']['authkey']));
$secretKey = authcode($_G['setting']['tencentcloud_captcha']['secretkey'], 'DECODE', MD5($_G['config']['security']['authkey']));

3. **前端验证码渲染优化**
// 动态加载验证码组件（/template/default/member/login.htm）
window.TencentCaptcha = function(appId, callback) {
    var script = document.createElement('script');
    script.src = 'https://ssl.captcha.qq.com/TCaptcha.js?' + Date.now();
    document.head.appendChild(script);
    script.onload = function() {
      new TencentCaptcha(appId, function(res) {
            callback(res.ticket, res.randstr);
      });
    }
};

4. **请求频率限制策略**
在验证码验证接口添加：
// /plugin/tencentcloud_captcha/tencentcloud_captcha.inc.php
$client_ip = $_G['clientip'];
if(!cache_load("captcha_limit_$client_ip")) {
    cache_save("captcha_limit_$client_ip", 1, 60);
} else {
    $count = intval(cache_read("captcha_limit_$client_ip"));
    if($count > 5) {
      showmessage('操作过于频繁，请稍后再试');
    }
    cache_save("captcha_limit_$client_ip", $count+1, 60);
}

5. **验证码服务端校验强化**
$api = new TencentCloud\Captcha\V20190722\CaptchaClient(
    $secretId,
    $secretKey,
    "ap-guangzhou",
    [
      'http' => [
            'timeout' => 3,
            'verify' => false
      ]
    ]
);
$req = new TencentCloud\Captcha\V20190722\Models\DescribeCaptchaResultRequest();
$req->setCaptchaType(9);
$req->setTicket($ticket);
$req->setRandstr($randstr);
$req->setUserIp($_G['clientip']);
$resp = $api->DescribeCaptchaResult($req);
if($resp->getCaptchaCode() != 1) {
    showmessage('验证码校验失败：'.$resp->getCaptchaMsg());
}

6. **跨站请求伪造防护**
// 表单增加CSRF令牌
$formhash = formhash();
echo '<input type="hidden" name="formhash" value="'.$formhash.'">';

// 验证时校验
if($_GET['formhash'] != formhash()) {
    showmessage('无效的请求来源');
}

7. **验证码样式定制**
通过修改/plugin/tencentcloud_captcha/template/captcha.htm：
<style>
#TencentCaptcha {
    width: 300px!important;
    height: 40px!important;
    border-radius: 4px;
    box-shadow: 0 2px 6px rgba(0,0,0,0.1);
}
#TencentCaptcha iframe {
    transform: scale(0.9);
    transform-origin: left top;
}
</style>

8. **异常处理机制**
try {
    // 验证码校验逻辑
} catch (TencentCloudSDKException $e) {
    log_error('腾讯云验证码异常：'.$e->getMessage());
    showmessage('验证服务暂时不可用，请稍后重试');
} catch (Exception $e) {
    log_error('系统异常：'.$e->getMessage());
    showmessage('系统繁忙，请稍后再试');
}

// 错误日志记录函数
function log_error($msg) {
    $log = date("") . " $_SERVER $msg\n";
    file_put_contents('./data/log/captcha_error.log', $log, FILE_APPEND);
}

遇到验证码不显示时，可通过以下步骤排查：
1. 浏览器控制台查看JS加载错误
2. 检查腾讯云API密钥是否绑定CaptchaAppId
3. 验证服务器时间是否同步（使用ntpdate进行时间同步）
4. 查看PHP错误日志（/data/log/目录）
5. 临时关闭防火墙测试（iptables -F）

如需深度定制验证规则，可修改/plugin/tencentcloud_captcha/tencentcloud_captcha.class.php中的validate方法，添加业务特定的验证逻辑。建议在dz-x.net获取技术支持文档，了解高级配置方案。
-- 本回答由 人工智能 AI智能体 生成，内容仅供参考，请仔细甄别。

查看完整版本: Discuz!X3.5 X3.4腾讯云验证码（CAPTCHA）插件(tencentcloud_captcha)