极狐 GitLab Logo

Pages 域名 API

  • Tier: 基础版，专业版，旗舰版
  • Offering: JihuLab.com, 私有化部署

用于连接自定义域名和 TLS 证书的极狐GitLab Pages端点。

必须启用极狐GitLab Pages 功能才能使用这些端点。了解更多关于管理和使用该功能的信息。

列出所有 Pages 域名#

先决条件：

  • 您必须拥有实例的管理员访问权限。

获取所有 Pages 域名的列表。

plaintext
GET /pages/domains

如果成功，将返回200及以下响应属性：

属性类型描述
domainstring极狐GitLab Pages 站点的自定义域名。
urlstringPages 站点的完整 URL，包括协议。
project_idinteger与此 Pages 域名关联的极狐GitLab 项目 ID。
verifiedboolean指示域名是否已验证。
verification_codestring用于验证域名所有权的唯一记录。
enabled_untildate域名启用的日期。随着域名的重新验证，这一日期会定期更新。
auto_ssl_enabledboolean指示是否为此域名启用了使用 Let's Encrypt 自动生成 的 SSL 证书。
certificate_expirationobjectSSL 证书到期信息。
certificate_expiration.expiredboolean指示 SSL 证书是否已到期。
certificate_expiration.expirationdateSSL 证书的到期日期和时间。

示例请求：

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/pages/domains"

示例响应：

json
1[
2  {
3    "domain": "ssl.domain.example",
4    "url": "https://ssl.domain.example",
5    "project_id": 1337,
6    "verified": true,
7    "verification_code": "1234567890abcdef",
8    "enabled_until": "2020-04-12T14:32:00.000Z",
9    "auto_ssl_enabled": false,
10    "certificate": {
11      "expired": false,
12      "expiration": "2020-04-12T14:32:00.000Z"
13    }
14  }
15]

列出 Pages 域名#

获取项目 Pages 域名的列表。用户必须具有查看 Pages 域名的权限。

plaintext
GET /projects/:id/pages/domains

支持的属性：

属性类型必需描述
idinteger/string是项目 ID 或项目的 URL 编码路径

如果成功，将返回200及以下响应属性：

属性类型描述
domainstring极狐GitLab Pages 站点的自定义域名。
urlstringPages 站点的完整 URL，包括协议。
verifiedboolean指示域名是否已验证。
verification_codestring用于验证域名所有权的唯一记录。
enabled_untildate域名启用的日期。随着域名的重新验证，这一日期会定期更新。
auto_ssl_enabledboolean指示是否为此域名启用了使用 Let's Encrypt 自动生成 的 SSL 证书。
certificateobjectSSL 证书信息。
certificate.subjectstringSSL 证书的主题，通常包含有关域名的信息。
certificate.expireddate指示 SSL 证书是否已到期（true）或仍然有效（false）。
certificate.certificatestring完整的 PEM 格式的 SSL 证书。
certificate.certificate_textdateSSL 证书的人类可读文本表示，包括发行者、有效期、主题和其他证书信息。

示例请求：

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/pages/domains"

示例响应：

json
1[
2  {
3    "domain": "www.domain.example",
4    "url": "http://www.domain.example",
5    "verified": true,
6    "verification_code": "1234567890abcdef",
7    "enabled_until": "2020-04-12T14:32:00.000Z",
8    "auto_ssl_enabled": false,
9  },
10  {
11    "domain": "ssl.domain.example",
12    "url": "https://ssl.domain.example",
13    "verified": true,
14    "verification_code": "1234567890abcdef",
15    "enabled_until": "2020-04-12T14:32:00.000Z",
16    "auto_ssl_enabled": false,
17    "certificate": {
18      "subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate",
19      "expired": false,
20      "certificate": "-----BEGIN CERTIFICATE-----\n … \n-----END CERTIFICATE-----",
21      "certificate_text": "Certificate:\n … \n"
22    }
23  }
24]

单个 Pages 域名#

获取单个项目 Pages 域名。用户必须具有查看 Pages 域名的权限。

plaintext
GET /projects/:id/pages/domains/:domain

支持的属性：

属性类型必需描述
idinteger/string是项目 ID 或项目的 URL 编码路径
domainstring是用户指示的自定义域名

如果成功，将返回200及以下响应属性：

属性类型描述
domainstring极狐GitLab Pages 站点的自定义域名。
urlstringPages 站点的完整 URL，包括协议。
verifiedboolean指示域名是否已验证。
verification_codestring用于验证域名所有权的唯一记录。
enabled_untildate域名启用的日期。随着域名的重新验证，这一日期会定期更新。
auto_ssl_enabledboolean指示是否为此域名启用了使用 Let's Encrypt 自动生成 的 SSL 证书。
certificateobjectSSL 证书信息。
certificate.subjectstringSSL 证书的主题，通常包含有关域名的信息。
certificate.expireddate指示 SSL 证书是否已到期（true）或仍然有效（false）。
certificate.certificatestring完整的 PEM 格式的 SSL 证书。
certificate.certificate_textdateSSL 证书的人类可读文本表示，包括发行者、有效期、主题和其他证书信息。

示例请求：

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example"

示例响应：

json
1{
2  "domain": "ssl.domain.example",
3  "url": "https://ssl.domain.example",
4  "verified": true,
5  "verification_code": "1234567890abcdef",
6  "enabled_until": "2020-04-12T14:32:00.000Z",
7  "auto_ssl_enabled": false,
8  "certificate": {
9    "subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate",
10    "expired": false,
11    "certificate": "-----BEGIN CERTIFICATE-----\n … \n-----END CERTIFICATE-----",
12    "certificate_text": "Certificate:\n … \n"
13  }
14}

创建新的 Pages 域名#

创建新的 Pages 域名。用户必须具有创建新 Pages 域名的权限。

plaintext
POST /projects/:id/pages/domains

支持的属性：

属性类型必需描述
idinteger/string是项目 ID 或项目的 URL 编码路径
domainstring是用户指示的自定义域名
auto_ssl_enabledboolean否为自定义域名启用由 Let's Encrypt 签发的 SSL 证书自动生成。
certificatefile/string否PEM 格式的证书，后面跟着从最具体到最不具体顺序的中间证书。
keyfile/string否PEM 格式的证书密钥。

如果成功，将返回201及以下响应属性：

属性类型描述
domainstring极狐GitLab Pages 站点的自定义域名。
urlstringPages 站点的完整 URL，包括协议。
verifiedboolean指示域名是否已验证。
verification_codestring用于验证域名所有权的唯一记录。
enabled_untildate域名启用的日期。随着域名的重新验证，这一日期会定期更新。
auto_ssl_enabledboolean指示是否为此域名启用了使用 Let's Encrypt 自动生成 的 SSL 证书。
certificateobjectSSL 证书信息。
certificate.subjectstringSSL 证书的主题，通常包含有关域名的信息。
certificate.expireddate指示 SSL 证书是否已到期（true）或仍然有效（false）。
certificate.certificatestring完整的 PEM 格式的 SSL 证书。
certificate.certificate_textdateSSL 证书的人类可读文本表示，包括发行者、有效期、主题和其他证书信息。

示例请求：

使用 .pem 文件中的证书创建新的 Pages 域名：

shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "domain=ssl.domain.example" --form "certificate=@/path/to/cert.pem" \
     --form "key=@/path/to/key.pem" "https://gitlab.example.com/api/v4/projects/5/pages/domains"

使用包含证书的变量创建新的 Pages 域名：

shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "domain=ssl.domain.example" --form "certificate=$CERT_PEM" \
     --form "key=$KEY_PEM" "https://gitlab.example.com/api/v4/projects/5/pages/domains"

使用自动证书创建新的 Pages 域名：

shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "domain=ssl.domain.example" \
     --form "auto_ssl_enabled=true" "https://gitlab.example.com/api/v4/projects/5/pages/domains"

示例响应：

json
1{
2  "domain": "ssl.domain.example",
3  "url": "https://ssl.domain.example",
4  "auto_ssl_enabled": true,
5  "certificate": {
6    "subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate",
7    "expired": false,
8    "certificate": "-----BEGIN CERTIFICATE-----\n … \n-----END CERTIFICATE-----",
9    "certificate_text": "Certificate:\n … \n"
10  }
11}

更新 Pages 域名#

更新现有项目 Pages 域名。用户必须具有更改现有 Pages 域名的权限。

plaintext
PUT /projects/:id/pages/domains/:domain

支持的属性：

属性类型必需描述
idinteger/string是项目 ID 或项目的 URL 编码路径
domainstring是用户指示的自定义域名
auto_ssl_enabledboolean否为自定义域名启用由 Let's Encrypt 签发的 SSL 证书自动生成。
certificatefile/string否PEM 格式的证书，后面跟着从最具体到最不具体顺序的中间证书。
keyfile/string否PEM 格式的证书密钥。

如果成功，将返回200及以下响应属性：

属性类型描述
domainstring极狐GitLab Pages 站点的自定义域名。
urlstringPages 站点的完整 URL，包括协议。
verifiedboolean指示域名是否已验证。
verification_codestring用于验证域名所有权的唯一记录。
enabled_untildate域名启用的日期。随着域名的重新验证，这一日期会定期更新。
auto_ssl_enabledboolean指示是否为此域名启用了使用 Let's Encrypt 自动生成 的 SSL 证书。
certificateobjectSSL 证书信息。
certificate.subjectstringSSL 证书的主题，通常包含有关域名的信息。
certificate.expireddate指示 SSL 证书是否已到期（true）或仍然有效（false）。
certificate.certificatestring完整的 PEM 格式的 SSL 证书。
certificate.certificate_textdateSSL 证书的人类可读文本表示，包括发行者、有效期、主题和其他证书信息。

添加证书#

从 .pem 文件添加 Pages 域名的证书：

shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certificate=@/path/to/cert.pem" \
     --form "key=@/path/to/key.pem" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example"

使用包含证书的变量添加 Pages 域名的证书：

shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certificate=$CERT_PEM" \
     --form "key=$KEY_PEM" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example"

示例响应：

json
1{
2  "domain": "ssl.domain.example",
3  "url": "https://ssl.domain.example",
4  "auto_ssl_enabled": false,
5  "certificate": {
6    "subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate",
7    "expired": false,
8    "certificate": "-----BEGIN CERTIFICATE-----\n … \n-----END CERTIFICATE-----",
9    "certificate_text": "Certificate:\n … \n"
10  }
11}

启用 Let's Encrypt 集成以支持 Pages 自定义域名#

shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "auto_ssl_enabled=true" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example"

示例响应：

json
{
  "domain": "ssl.domain.example",
  "url": "https://ssl.domain.example",
  "auto_ssl_enabled": true
}

移除证书#

要移除附加到 Pages 域名的 SSL 证书，请运行：

shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certificate=" \
     --form "key=" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example"

示例响应：

json
{
  "domain": "ssl.domain.example",
  "url": "https://ssl.domain.example",
  "auto_ssl_enabled": false
}

验证 Pages 域名#

History
    • 引入于极狐GitLab 17.7。

验证现有项目 Pages 域名。用户必须具有更新 Pages 域名的权限。

plaintext
PUT /projects/:id/pages/domains/:domain/verify

支持的属性：

属性类型必需描述
idinteger/string是项目 ID 或 URL 编码路径
domainstring是要验证的自定义域名

如果成功，将返回200及以下响应属性：

属性类型描述
domainstring极狐GitLab Pages 站点的自定义域名。
urlstringPages 站点的完整 URL，包括协议。
verifiedboolean指示域名是否已验证。
verification_codestring用于验证域名所有权的唯一记录。
enabled_untildate域名启用的日期。随着域名的重新验证，这一日期会定期更新。
auto_ssl_enabledboolean指示是否为此域名启用了使用 Let's Encrypt 自动生成 的 SSL 证书。
certificateobjectSSL 证书信息。
certificate.subjectstringSSL 证书的主题，通常包含有关域名的信息。
certificate.expireddate指示 SSL 证书是否已到期（true）或仍然有效（false）。
certificate.certificatestring完整的 PEM 格式的 SSL 证书。
certificate.certificate_textdateSSL 证书的人类可读文本表示，包括发行者、有效期、主题和其他证书信息。

示例请求：

shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example/verify"

示例响应：

json
1{
2  "domain": "ssl.domain.example",
3  "url": "https://ssl.domain.example",
4  "auto_ssl_enabled": false,
5  "verified": true,
6  "verification_code": "1234567890abcdef",
7  "enabled_until": "2020-04-12T14:32:00.000Z"
8}

删除 Pages 域名#

删除现有项目 Pages 域名。

plaintext
DELETE /projects/:id/pages/domains/:domain

支持的属性：

属性类型必需描述
idinteger/string是项目 ID 或项目的 URL 编码路径
domainstring是用户指示的自定义域名

如果成功，则应返回一个 204 No Content HTTP 响应，且正文为空。

示例请求：

shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example"