本指南用于在 WHMCS 中接入 GNAME 域名注册商模块，覆盖插件下载、文件部署、后台激活、API 凭据配置与完成检查。
| 模块名称 |
Gname Domain Registrar for WHMCS |
| 兼容版本 |
请以插件市场 Compatibility 页面为准；原始说明面向 WHMCS 8.x，所附截图显示 v9.0 兼容标识 |
| 安装目录 |
<WHMCS 根目录>/modules/registrars/gname/ |
| 所需凭据 |
GNAME AppID、AppKey |
开始前准备
- 确认拥有 WHMCS 管理后台权限，以及服务器文件上传或部署权限。
- 准备 GNAME AppID 与 AppKey；建议先备份 WHMCS，并在非生产环境验证。
1、获取插件
访问 WHMCS Marketplace 的 GNAME 插件页面，按照页面提示下载插件包。
GNAME 插件在 WHMCS Marketplace 中的产品页面
2、部署模块文件
- 解压下载包，确认模块文件夹名为 gname。若解压后的模块目录名称不同，请将其重命名为 gname。
- 将整个 gname 文件夹上传到 WHMCS 的域名注册商模块目录。
目标路径<WHMCS 根目录>/modules/registrars/gname/
- 检查目录层级，避免出现 modules/registrars/gname/gname/ 这类重复嵌套。
- 确认 Web 服务器运行用户可以读取模块文件。
3、在 WHMCS 后台激活
- 登录 WHMCS 管理后台，打开“应用集成”（Apps & Integrations）。
- 进入 Domains 分类，找到 Gname 模块并点击“激活”。
图 1 在 Domains 分类中定位 Gname 模块
激活判断：模块行显示“禁用”和“配置”按钮时，通常表示模块已经处于激活状态。
4、配置 AppID 与 AppKey
在 Gname 模块行点击“配置”，将 GNAME 管理后台中的 API 凭据填写到对应字段。
图 2 填写 AppID 与 AppKey 后保存更改
- AppID：填写 GNAME 管理后台中生成或分配的 AppID。
- AppKey：填写与该 AppID 配套的 AppKey。
- TestMode：仅在已确认测试环境可用并准备测试时启用；正式使用通常保持关闭。
- 点击“保存更改”，确认页面没有返回错误提示。
GNAME 管理后台的 API 设置页面
凭据安全：AppKey 属于敏感信息。请勿通过聊天记录、工单截图或公开文档传播，也不要把它提交到代码仓库。
5、完成检查
- Gname 模块保持激活状态，配置入口可以正常打开。
- AppID 与 AppKey 已保存，页面无鉴权或连接错误。
- 先执行一项非生产验证，例如域名可用性查询；确认正常后再用于正式业务。
常见问题
| 现象 |
优先检查 |
| 后台找不到 Gname |
确认文件夹位于 modules/registrars/gname，且没有多套一层 gname 目录。 |
| 模块无法激活 |
核对 WHMCS 兼容版本、文件完整性与服务器读取权限，并查看 WHMCS/PHP 错误日志。 |
| API 连接或鉴权失败 |
重新复制 AppID 与 AppKey，检查首尾空格；如启用了 IP 白名单或 API 权限限制，也需同步核对。 |
版本提示：WHMCS、PHP 或插件升级前，请重新核对 Marketplace 的 Compatibility 与 Changelog 信息，并先在测试环境验证。
联系支持前准备
- 记录 WHMCS 版本、PHP 版本和插件下载时间。
- 整理错误发生时间、操作步骤与已脱敏的错误日志。
- 提供截图前遮盖客户数据；任何情况下都不要提供 AppKey。
