{{< details >}}
- Tier: 基础版,专业版,旗舰版
- Offering: JihuLab.com, 私有化部署
{{< /details >}}
用于连接自定义域名和 TLS 证书的极狐GitLab Pages端点。
必须启用极狐GitLab Pages 功能才能使用这些端点。了解更多关于管理和使用该功能的信息。
列出所有 Pages 域名
先决条件:
- 您必须拥有实例的管理员访问权限。
获取所有 Pages 域名的列表。
GET /pages/domains
如果成功,将返回200
及以下响应属性:
属性 | 类型 | 描述 |
---|---|---|
domain |
string | 极狐GitLab Pages 站点的自定义域名。 |
url |
string | Pages 站点的完整 URL,包括协议。 |
project_id |
integer | 与此 Pages 域名关联的极狐GitLab 项目 ID。 |
verified |
boolean | 指示域名是否已验证。 |
verification_code |
string | 用于验证域名所有权的唯一记录。 |
enabled_until |
date | 域名启用的日期。随着域名的重新验证,这一日期会定期更新。 |
auto_ssl_enabled |
boolean | 指示是否为此域名启用了使用 Let’s Encrypt 自动生成 的 SSL 证书。 |
certificate_expiration |
object | SSL 证书到期信息。 |
certificate_expiration.expired |
boolean | 指示 SSL 证书是否已到期。 |
certificate_expiration.expiration |
date | SSL 证书的到期日期和时间。 |
示例请求:
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/pages/domains"
示例响应:
[
{
"domain": "ssl.domain.example",
"url": "https://ssl.domain.example",
"project_id": 1337,
"verified": true,
"verification_code": "1234567890abcdef",
"enabled_until": "2020-04-12T14:32:00.000Z",
"auto_ssl_enabled": false,
"certificate": {
"expired": false,
"expiration": "2020-04-12T14:32:00.000Z"
}
}
]
列出 Pages 域名
获取项目 Pages 域名的列表。用户必须具有查看 Pages 域名的权限。
GET /projects/:id/pages/domains
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer/string | 是 | 项目 ID 或项目的 URL 编码路径 |
如果成功,将返回200
及以下响应属性:
属性 | 类型 | 描述 |
---|---|---|
domain |
string | 极狐GitLab Pages 站点的自定义域名。 |
url |
string | Pages 站点的完整 URL,包括协议。 |
verified |
boolean | 指示域名是否已验证。 |
verification_code |
string | 用于验证域名所有权的唯一记录。 |
enabled_until |
date | 域名启用的日期。随着域名的重新验证,这一日期会定期更新。 |
auto_ssl_enabled |
boolean | 指示是否为此域名启用了使用 Let’s Encrypt 自动生成 的 SSL 证书。 |
certificate |
object | SSL 证书信息。 |
certificate.subject |
string | SSL 证书的主题,通常包含有关域名的信息。 |
certificate.expired |
date | 指示 SSL 证书是否已到期(true)或仍然有效(false)。 |
certificate.certificate |
string | 完整的 PEM 格式的 SSL 证书。 |
certificate.certificate_text |
date | SSL 证书的人类可读文本表示,包括发行者、有效期、主题和其他证书信息。 |
示例请求:
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/pages/domains"
示例响应:
[
{
"domain": "www.domain.example",
"url": "http://www.domain.example",
"verified": true,
"verification_code": "1234567890abcdef",
"enabled_until": "2020-04-12T14:32:00.000Z",
"auto_ssl_enabled": false,
},
{
"domain": "ssl.domain.example",
"url": "https://ssl.domain.example",
"verified": true,
"verification_code": "1234567890abcdef",
"enabled_until": "2020-04-12T14:32:00.000Z",
"auto_ssl_enabled": false,
"certificate": {
"subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate",
"expired": false,
"certificate": "-----BEGIN CERTIFICATE-----\n … \n-----END CERTIFICATE-----",
"certificate_text": "Certificate:\n … \n"
}
}
]
单个 Pages 域名
获取单个项目 Pages 域名。用户必须具有查看 Pages 域名的权限。
GET /projects/:id/pages/domains/:domain
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer/string | 是 | 项目 ID 或项目的 URL 编码路径 |
domain |
string | 是 | 用户指示的自定义域名 |
如果成功,将返回200
及以下响应属性:
属性 | 类型 | 描述 |
---|---|---|
domain |
string | 极狐GitLab Pages 站点的自定义域名。 |
url |
string | Pages 站点的完整 URL,包括协议。 |
verified |
boolean | 指示域名是否已验证。 |
verification_code |
string | 用于验证域名所有权的唯一记录。 |
enabled_until |
date | 域名启用的日期。随着域名的重新验证,这一日期会定期更新。 |
auto_ssl_enabled |
boolean | 指示是否为此域名启用了使用 Let’s Encrypt 自动生成 的 SSL 证书。 |
certificate |
object | SSL 证书信息。 |
certificate.subject |
string | SSL 证书的主题,通常包含有关域名的信息。 |
certificate.expired |
date | 指示 SSL 证书是否已到期(true)或仍然有效(false)。 |
certificate.certificate |
string | 完整的 PEM 格式的 SSL 证书。 |
certificate.certificate_text |
date | SSL 证书的人类可读文本表示,包括发行者、有效期、主题和其他证书信息。 |
示例请求:
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example"
示例响应:
{
"domain": "ssl.domain.example",
"url": "https://ssl.domain.example",
"verified": true,
"verification_code": "1234567890abcdef",
"enabled_until": "2020-04-12T14:32:00.000Z",
"auto_ssl_enabled": false,
"certificate": {
"subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate",
"expired": false,
"certificate": "-----BEGIN CERTIFICATE-----\n … \n-----END CERTIFICATE-----",
"certificate_text": "Certificate:\n … \n"
}
}
创建新的 Pages 域名
创建新的 Pages 域名。用户必须具有创建新 Pages 域名的权限。
POST /projects/:id/pages/domains
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer/string | 是 | 项目 ID 或项目的 URL 编码路径 |
domain |
string | 是 | 用户指示的自定义域名 |
auto_ssl_enabled |
boolean | 否 | 为自定义域名启用由 Let’s Encrypt 签发的 SSL 证书自动生成。 |
certificate |
file/string | 否 | PEM 格式的证书,后面跟着从最具体到最不具体顺序的中间证书。 |
key |
file/string | 否 | PEM 格式的证书密钥。 |
如果成功,将返回201
及以下响应属性:
属性 | 类型 | 描述 |
---|---|---|
domain |
string | 极狐GitLab Pages 站点的自定义域名。 |
url |
string | Pages 站点的完整 URL,包括协议。 |
verified |
boolean | 指示域名是否已验证。 |
verification_code |
string | 用于验证域名所有权的唯一记录。 |
enabled_until |
date | 域名启用的日期。随着域名的重新验证,这一日期会定期更新。 |
auto_ssl_enabled |
boolean | 指示是否为此域名启用了使用 Let’s Encrypt 自动生成 的 SSL 证书。 |
certificate |
object | SSL 证书信息。 |
certificate.subject |
string | SSL 证书的主题,通常包含有关域名的信息。 |
certificate.expired |
date | 指示 SSL 证书是否已到期(true)或仍然有效(false)。 |
certificate.certificate |
string | 完整的 PEM 格式的 SSL 证书。 |
certificate.certificate_text |
date | SSL 证书的人类可读文本表示,包括发行者、有效期、主题和其他证书信息。 |
示例请求:
使用 .pem
文件中的证书创建新的 Pages 域名:
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 域名:
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 域名:
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"
示例响应:
{
"domain": "ssl.domain.example",
"url": "https://ssl.domain.example",
"auto_ssl_enabled": true,
"certificate": {
"subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate",
"expired": false,
"certificate": "-----BEGIN CERTIFICATE-----\n … \n-----END CERTIFICATE-----",
"certificate_text": "Certificate:\n … \n"
}
}
更新 Pages 域名
更新现有项目 Pages 域名。用户必须具有更改现有 Pages 域名的权限。
PUT /projects/:id/pages/domains/:domain
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer/string | 是 | 项目 ID 或项目的 URL 编码路径 |
domain |
string | 是 | 用户指示的自定义域名 |
auto_ssl_enabled |
boolean | 否 | 为自定义域名启用由 Let’s Encrypt 签发的 SSL 证书自动生成。 |
certificate |
file/string | 否 | PEM 格式的证书,后面跟着从最具体到最不具体顺序的中间证书。 |
key |
file/string | 否 | PEM 格式的证书密钥。 |
如果成功,将返回200
及以下响应属性:
属性 | 类型 | 描述 |
---|---|---|
domain |
string | 极狐GitLab Pages 站点的自定义域名。 |
url |
string | Pages 站点的完整 URL,包括协议。 |
verified |
boolean | 指示域名是否已验证。 |
verification_code |
string | 用于验证域名所有权的唯一记录。 |
enabled_until |
date | 域名启用的日期。随着域名的重新验证,这一日期会定期更新。 |
auto_ssl_enabled |
boolean | 指示是否为此域名启用了使用 Let’s Encrypt 自动生成 的 SSL 证书。 |
certificate |
object | SSL 证书信息。 |
certificate.subject |
string | SSL 证书的主题,通常包含有关域名的信息。 |
certificate.expired |
date | 指示 SSL 证书是否已到期(true)或仍然有效(false)。 |
certificate.certificate |
string | 完整的 PEM 格式的 SSL 证书。 |
certificate.certificate_text |
date | SSL 证书的人类可读文本表示,包括发行者、有效期、主题和其他证书信息。 |
添加证书
从 .pem
文件添加 Pages 域名的证书:
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 域名的证书:
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"
示例响应:
{
"domain": "ssl.domain.example",
"url": "https://ssl.domain.example",
"auto_ssl_enabled": false,
"certificate": {
"subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate",
"expired": false,
"certificate": "-----BEGIN CERTIFICATE-----\n … \n-----END CERTIFICATE-----",
"certificate_text": "Certificate:\n … \n"
}
}
启用 Let’s Encrypt 集成以支持 Pages 自定义域名
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"
示例响应:
{
"domain": "ssl.domain.example",
"url": "https://ssl.domain.example",
"auto_ssl_enabled": true
}
移除证书
要移除附加到 Pages 域名的 SSL 证书,请运行:
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"
示例响应:
{
"domain": "ssl.domain.example",
"url": "https://ssl.domain.example",
"auto_ssl_enabled": false
}
验证 Pages 域名
{{< history >}}
- 引入于极狐GitLab 17.7。
{{< /history >}}
验证现有项目 Pages 域名。用户必须具有更新 Pages 域名的权限。
PUT /projects/:id/pages/domains/:domain/verify
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer/string | 是 | 项目 ID 或 URL 编码路径 |
domain |
string | 是 | 要验证的自定义域名 |
如果成功,将返回200
及以下响应属性:
属性 | 类型 | 描述 |
---|---|---|
domain |
string | 极狐GitLab Pages 站点的自定义域名。 |
url |
string | Pages 站点的完整 URL,包括协议。 |
verified |
boolean | 指示域名是否已验证。 |
verification_code |
string | 用于验证域名所有权的唯一记录。 |
enabled_until |
date | 域名启用的日期。随着域名的重新验证,这一日期会定期更新。 |
auto_ssl_enabled |
boolean | 指示是否为此域名启用了使用 Let’s Encrypt 自动生成 的 SSL 证书。 |
certificate |
object | SSL 证书信息。 |
certificate.subject |
string | SSL 证书的主题,通常包含有关域名的信息。 |
certificate.expired |
date | 指示 SSL 证书是否已到期(true)或仍然有效(false)。 |
certificate.certificate |
string | 完整的 PEM 格式的 SSL 证书。 |
certificate.certificate_text |
date | SSL 证书的人类可读文本表示,包括发行者、有效期、主题和其他证书信息。 |
示例请求:
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example/verify"
示例响应:
{
"domain": "ssl.domain.example",
"url": "https://ssl.domain.example",
"auto_ssl_enabled": false,
"verified": true,
"verification_code": "1234567890abcdef",
"enabled_until": "2020-04-12T14:32:00.000Z"
}
删除 Pages 域名
删除现有项目 Pages 域名。
DELETE /projects/:id/pages/domains/:domain
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer/string | 是 | 项目 ID 或项目的 URL 编码路径 |
domain |
string | 是 | 用户指示的自定义域名 |
如果成功,则应返回一个 204 No Content
HTTP 响应,且正文为空。
示例请求:
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example"