跳到主要内容

自定义域名

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

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

提示

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

CNAME 方式​

获取 CNAME 值​

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

获取 CNAME 值

添加 CNAME 记录​

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

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

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

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

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

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

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

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

    image-20220810151204712

参数说明填写说明注意事项
主机记录一般是指子域名的前缀（如需创建子域名为 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。

SSL 证书

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

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

    • CNAME 配置不成功，请前往域名管理界面，确认 CNAME 是否正确配置。
    • 域名尚未完成备案。

自有服务器中转方式​

Apifox 版本号需 ≥ 2.2.19。

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

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

Web 服务器​

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

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

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

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

server {
    ...
    location / {
        proxy_pass  http://{docsSiteId}.n3.apifox.cn;
        proxy_set_header X-Apifox-Docs-Site-ID {docsSiteId};
        ...
    }
    ...
}
提示

注意在以上配置中 {docsSiteId} 为你的文档站 id ，请确保将正确的 id 填入并正确设置 X-Apifox-Docs-Site-ID 请求头。

全站加速（CDN）服务​

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

  • 在全站加速服务中可以添加您的加速域名，并执行以下三个操作：
    1. 配置源站信息，选择源站类型为域名且正确配置域名为：{docsSiteId}.n3.apifox.cn
    2. 回源 HOST 配置选择或设置为加速域名，即您的 自定义域名
    3. 在回源配置中添加自定义回源 HTTP 请求头：
    • 参数：X-Apifox-Docs-Site-ID
    • 取值：{docsSiteId}
提示

在以上配置中 {docsSiteId} 为你的文档站 id ，请确保填写正确的 id。

阿里云​

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

  1. 添加域名。

aliyun-domain-config

  1. 回源 HOST 配置。

aliyun-domain-config-2

  1. 设置回源 HTTP 请求头。

aliyun-domain-config-3

腾讯云​

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

  1. 添加域名和回源 HOST 配置。

tencent-domain-config

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

七牛云​

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

  1. 添加域名和回源 HOST 配置。

qiniu-domain-config

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

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

Apifox 版本号需 ≥ 2.5.24。

Apifox 支持使用自有服务器的中转功能，可以将 API 在线文档嵌入至自定义域名的子目录。（例如：访问 Your-Website.com/api-docs，实际打开的是 Apifox 的 API 在线文档）。

在“自定义域名”选项页内，填写自定义域名。然后点击“自有服务器中转” → 勾选“使用子目录”

嵌入至自有域名的子目录

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

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

Nginx 配置文件示例代码：

server {
    ...
    location /api-docs/ {
        proxy_pass  http://{docsSiteId}.n3.apifox.cn/;
        proxy_set_header X-Apifox-Docs-Site-ID {docsSiteId};
        ...
    }
    ...
}
警告

/api-docs 为你的自定义域名下的子目录，尾部一定要添加斜杠； http://{docsSiteId}.n3.apifox.cn 尾部也需添加斜杠。