自定义域名

CNAME 指的是别名记录，也被称为规范名字，用于将自有域名解析至其它域名上。

由 Apifox 生成的 API 在线文档默认使用 xx.apifox.cn 格式的 URL。如果你希望通过使用自有域名 （比如：www.your-domain.com） 访问 API 在线文档，那么就需要进行 CNAME 配置。

注意请确保自有域名已完成备案。

CNAME 方式

获取 CNAME 值

进入 “分享文档 -> 发布文档站” 的发布设置页面，点击 “自定义域名” 标签页找到对应的 CNAME 值并进行复制。

添加 CNAME 记录

添加 CNAME 记录需要在 “域名厂商” 内进行配置，比如在阿里云 / 腾讯云 / 新网等厂商中购买的域名。你需要前往对应的管理控制台添加域名解析。

在控制台中找到您的域名解析添加页面，例如：

a. 阿里云：在控制台页面的左侧，产品与服务栏中选择域名。

b. 腾讯云：在控制台的云产品中，搜索并选择云解析。

c. DNSPOD：在控制台页面左侧，选择域名。

其他域名厂商请参考产品文档说明或咨询产品售后。

在域名产品的列表中找到对应的 “主域名”，点击域名后面的 “解析设置” 或 “解析” ，进入解析设置页。

选择 “添加记录”，依次填写主机记录、记录类型以及记录值，其它可设为默认值。

参数说明	填写说明	注意事项
主机记录	一般是指子域名的前缀（如需创建子域名为 `www.apifox-doc.com` ，主机记录输入 www；如需实现 apifox-doc.com，主机记录输入 @ )	该参数唯一，请勿自定义
记录类型	选择 CNAME 类型	该参数唯一，请勿自定义
线路类型	保持默认	该参数可以根据需求自行调整
记录值	从 Apifox 复制过来的 CNAME	该参数唯一，请勿自定义
TTL	保持默认	该参数可以根据需求自行调整

启用 HTTPS

API 在线文档支持开启 HTTPS 协议。相较于 HTTP 协议，HTTPS 协议具有以下的优势：

数据传输安全

HTTPS 使用 SSL/TLS 协议对数据进行加密，保证了数据传输的安全性。加密后的数据无法被第三方解读，保护了用户信息的机密性。

SEO 优化

搜索引擎爬虫更喜欢使用 HTTPS，因为其具有更好的安全性和隐私保护。因此，HTTPS 网站可能会比 HTTP 网站在搜索引擎排名中获得更高的权威性。

进入 “发布设置” 页面，然后轻点 “自定义域名” 标签页并打开 “启用 HTTPS” 开关或同时启用 “强制使用 HTTPS”，可以确保网站通信双方的身份，防止被劫持或中间人攻击。

SSL 证书

开启 HTTPS 后，你可以选择由 Apifox 自动生成 SSL 证书，或自行在页面中填写由证书颁发机构所下发的 SSL 证书内容与私钥。常见的证书颁发机构有 Let's Encrypt。

常见问题

自定义域名一直显示未生效怎么办？

首先，配置 CNAME 一般需要 10 分钟左右才生效，请耐心等待。如果长时间未生效，可能是以下原因导致：

CNAME 配置不成功，请前往域名管理界面，确认 CNAME 是否正确配置。

域名尚未完成备案。

如何检查 CNAME 配置是否正确？

Apifox 自定义域名的 SSL 证书生成失败怎么办？

自有服务器中转方式

Apifox 版本号需 ≥ 2.2.19。

除了使用 CNAME 方式以外，Apifox 还支持使用自有服务器中转功能来实现自定义域名访问 API 在线文档。

使用 Nginx 等 Web 服务器做简单配置即可实现，即 Web 服务器代理。

使用阿里云、腾讯云、七牛云等云厂商的全站加速服务 (DCDN) 。即全站加速服务将您的域名代理到指定的地址且正确设置请求头后即可成功访问域名从而展现您的项目文档。

Web 服务器

你可以使用 Nginx 来代理您的服务从而使用自有服务器中转功能。

在 Nginx 中可以使用 proxy_pass 命令，这个命令用于将请求转发到其他服务器。

在 Nginx 中可以使用 proxy_set_header 命令，这个命令用于设置代理服务器发送给上游服务器的请求头。

例如，你可以在 Nginx 配置文件中添加如下内容来进行简单配置。

{docsSiteId} 为你的文档站 id，即自定义域名面板显示的 Docs Site ID，请确保填写正确的 id。

全站加速（CDN）服务

你可以使用阿里云、腾讯云、七牛云等云厂商的全站加速服务（DCDN）配置源站和自定义回源 HTTP 头从而来使用自有服务器中转功能。

在全站加速服务中可以添加您的加速域名，并执行以下三个操作：

配置源站信息，选择源站类型为域名且正确配置域名为：{docsSiteId}.n3.apifox.cn

回源 HOST 配置选择或设置为加速域名，即您的 自定义域名

在回源配置中添加自定义回源 HTTP 请求头：

参数：X-Apifox-Docs-Site-ID

取值：{docsSiteId}

{docsSiteId} 为你的文档站 id，即自定义域名面板显示的 Docs Site ID，请确保填写正确的 id。

阿里云

如下为配置示例，实际参数需要改为软件内对应的值：

添加域名。

回源 HOST 配置。

设置回源 HTTP 请求头。

腾讯云

如下为配置示例，实际参数需要改为软件内对应的值：

添加域名和回源 HOST 配置。

参考设置回源 HTTP 请求头，添加 X-Apifox-Project-ID 请求头。

七牛云

如下为配置示例，实际参数需要改为软件内对应的值：

添加域名和回源 HOST 配置。

设置回源 HTTP 请求头，需要通过七牛云控制台提交工单的方式设置回源 HTTP 请求头。

嵌入至自有域名的子目录

Apifox 版本号需 ≥ 2.5.24。

Apifox 支持使用自有服务器的中转功能，可以将 API 在线文档嵌入至自定义域名的子目录。

在 “自定义域名” 选项页内，填写自定义域名 (如：example.com)。然后点击 “自有服务器中转”，启用 “使用子目录”，并输入子目录名称 (如：api-docs)。

接下来，你需要修改自有 Web 服务器 （例如：Nginx） 的配置文件，参考以下内容进行配置：

在 Nginx 中可以使用 proxy_pass 命令，这个命令用于将请求转发到其他服务器。

在 Nginx 中可以使用 proxy_set_header 命令，这个命令用于设置代理服务器发送给上游服务器的请求头。

Nginx 配置文件示例代码：

/api-docs 为你的自定义域名下的子目录，请根据你的文档地址自行修改，尾部一定要添加斜杠 /，见上述示例代码。

http://{docsSiteId}.n3.apifox.cn 尾部也需添加斜杠 /，见上述示例代码。

{docsSiteId} 为你的文档站 id，即自定义域名面板显示的 Docs Site ID，请确保填写正确的 id。

CNAME 方式#

获取 CNAME 值#

添加 CNAME 记录#

启用 HTTPS#

SSL 证书#

常见问题#

自有服务器中转方式#

Web 服务器#

全站加速（CDN）服务#

阿里云#

腾讯云#

七牛云#

嵌入至自有域名的子目录#

CNAME 方式

获取 CNAME 值

添加 CNAME 记录

启用 HTTPS

SSL 证书

常见问题

自有服务器中转方式

Web 服务器

全站加速（CDN）服务

阿里云

腾讯云

七牛云

嵌入至自有域名的子目录