Help us learn about your current experience with the documentation. Take the survey.

自编译安装的 GitLab Pages 管理

  • 版本：Free, Premium, Ultimate
  • 提供：GitLab Self-Managed

在尝试启用 GitLab Pages 之前，请确保您已成功 安装 GitLab。

本文档介绍如何为自编译的 GitLab 安装配置 GitLab Pages。

有关为 Linux 包安装（推荐）配置 GitLab Pages 的更多信息，请参阅 Linux 包文档。

使用 Linux 包安装的优势在于它包含最新支持的 GitLab Pages 版本。

GitLab Pages 工作原理

GitLab Pages 使用 GitLab Pages 守护进程，这是一个轻量级 HTTP 服务器，监听外部 IP 地址并提供自定义域名和证书支持。它通过 SNI 支持动态证书，并默认使用 HTTP2 暴露页面。 我们鼓励您阅读其 README 以全面了解其工作原理。

在 自定义域名 的情况下（但不是 通配符域名），Pages 守护进程需要监听 端口 80 和/或 443。因此，您可以通过以下几种方式灵活设置：

  • 在与 GitLab 相同的服务器上运行 Pages 守护进程，监听辅助 IP。
  • 在独立服务器上运行 Pages 守护进程。在这种情况下， Pages 路径 也必须存在于安装 Pages 守护进程的服务器上，因此您必须通过网络共享它。
  • 在与 GitLab 相同的服务器上运行 Pages 守护进程，监听相同的 IP 但使用不同的端口。在这种情况下，您必须使用负载均衡器代理流量。如果选择此方式，您应该对 HTTPS 使用 TCP 负载均衡。如果您使用 TLS 终止（HTTPS 负载均衡），则无法使用用户提供的证书提供服务。对于 HTTP，您可以使用 HTTP 或 TCP 负载均衡。

在本文档中，我们假设采用第一种方案。如果您不支持自定义域名，则不需要辅助 IP。

先决条件

在进行 Pages 配置之前，请确保：

  • 您有一个单独的域名来托管 GitLab Pages。在本文档中，我们假设为 example.io。
  • 您已为该域名配置了 通配符 DNS 记录。
  • 您已在安装 GitLab 的相同服务器上安装了 zip 和 unzip 包，因为它们需要用于压缩和解压缩 Pages 工件。
  • 可选。如果您决定在 HTTPS 下提供 Pages 服务（*.example.io），则您拥有该 Pages 域名的 通配符证书。
  • 可选但推荐。您已配置并启用了 实例运行器，这样您的用户就不需要自己提供。

DNS 配置

GitLab Pages 期望在自己的虚拟主机上运行。在您的 DNS 服务器/提供商中， 您需要添加一个指向 GitLab 运行主机的 通配符 DNS A 记录。例如，条目如下所示：

*.example.io. 1800 IN A 192.0.2.1

其中 example.io 是用于托管 GitLab Pages 的域名， 而 192.0.2.1 是您的 GitLab 实例的 IP 地址。

您不应使用 GitLab 域名来托管用户页面。更多信息请参阅 安全部分。

配置

根据您的需求，您可以通过 4 种不同的方式设置 GitLab Pages。 以下选项从最简单的设置到最高级的设置列出。 绝对最低要求是设置通配符 DNS，因为所有配置都需要它。

通配符域名

先决条件：

URL 方案：http://<namespace>.example.io/<project_slug>

这是您可以使用 Pages 的最低设置。它是下面描述的所有其他设置的基础。 NGINX 将所有请求代理到守护进程。Pages 守护进程不监听外部世界。

  1. 安装 Pages 守护进程：

    cd /home/git
sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git
cd gitlab-pages
sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION)
sudo -u git -H make

  2. 进入 GitLab 安装目录：

    cd /home/git/gitlab

  3. 编辑 gitlab.yml 并在 pages 设置下，将 enabled 设置为 true， 将 host 设置为用于托管 GitLab Pages 的 FQDN：

    ## GitLab Pages
pages:
  enabled: true
  # 页面存储的位置（默认：shared/pages）。
  # path: shared/pages

  host: example.io
  access_control: false
  port: 8090
  https: false
  artifacts_server: false
  external_http: ["127.0.0.1:8090"]
  secret_file: /home/git/gitlab/gitlab-pages-secret

  4. 将以下配置文件添加到 /home/git/gitlab-pages/gitlab-pages.conf，并确保将 example.io 更改为您想要从其托管 GitLab Pages 的 FQDN， 将 gitlab.example.com 更改为您的 GitLab 实例的 URL：

    listen-http=:8090
pages-root=/home/git/gitlab/shared/pages
api-secret-key=/home/git/gitlab/gitlab-pages-secret
pages-domain=example.io
internal-gitlab-server=https://gitlab.example.com

    当 GitLab Pages 和 GitLab 在同一主机上运行时，您可以使用 http 地址。 如果您使用 https 并使用自签名证书，请确保使您的自定义 CA 对 GitLab Pages 可用。 例如，您可以通过设置 SSL_CERT_DIR 环境变量来实现。

  5. 添加秘密 API 密钥：

    sudo -u git -H openssl rand -base64 32 > /home/git/gitlab/gitlab-pages-secret

  6. 启用 pages 守护进程：

    • 如果您的系统使用 systemd 作为 init，请运行：

      sudo systemctl edit gitlab.target

      在打开的编辑器中，添加以下内容并保存文件：

      [Unit]
Wants=gitlab-pages.service

    • 如果您的系统使用 SysV init，请编辑 /etc/default/gitlab 并将 gitlab_pages_enabled 设置为 true：

      gitlab_pages_enabled=true

  7. 复制 gitlab-pages NGINX 配置文件：

    sudo cp lib/support/nginx/gitlab-pages /etc/nginx/sites-available/gitlab-pages.conf
sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages.conf

  8. 重启 NGINX。

  9. 重启 GitLab。

支持 TLS 的通配符域名

先决条件：

URL 方案：https://<namespace>.example.io/<project_slug>

NGINX 将所有请求代理到守护进程。Pages 守护进程不监听外部世界。

  1. 安装 Pages 守护进程：

    cd /home/git
sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git
cd gitlab-pages
sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION)
sudo -u git -H make

  2. 在 gitlab.yml 中，将端口设置为 443，将 https 设置为 true：

    ## GitLab Pages
pages:
  enabled: true
  # 页面存储的位置（默认：shared/pages）。
  # path: shared/pages

  host: example.io
  port: 443
  https: true

  3. 编辑 /etc/default/gitlab 并将 gitlab_pages_enabled 设置为 true 以启用 pages 守护进程。 在 gitlab_pages_options 中，-pages-domain 必须与您之前设置的 host 值匹配。 -root-cert 和 -root-key 设置是 example.io 域名的通配符 TLS 证书：

    gitlab_pages_enabled=true
gitlab_pages_options="-pages-domain example.io -pages-root $app_root/shared/pages -listen-proxy 127.0.0.1:8090 -root-cert /path/to/example.io.crt -root-key /path/to/example.io.key"

  4. 复制 gitlab-pages-ssl NGINX 配置文件：

    sudo cp lib/support/nginx/gitlab-pages-ssl /etc/nginx/sites-available/gitlab-pages-ssl.conf
sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages-ssl.conf

  5. 重启 NGINX。

  6. 重启 GitLab。

高级配置

除了通配符域名，您还可以选择配置 GitLab Pages 以与自定义域名一起工作。 同样，这里有两个选项：支持带和不带 TLS 证书的自定义域名。 最简单的设置是不带 TLS 证书的设置。

自定义域名

先决条件：

URL 方案：http://<namespace>.example.io/<project_slug> 和 http://custom-domain.com

在这种情况下，pages 守护进程正在运行。NGINX 仍然将请求代理到守护进程， 但守护进程也能够接收来自外部世界的请求。支持自定义域名，但不支持 TLS。

  1. 安装 Pages 守护进程：

    cd /home/git
sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git
cd gitlab-pages
sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION)
sudo -u git -H make

  2. 编辑 gitlab.yml 使其如下所示。您需要将 host 更改为用于托管 GitLab Pages 的 FQDN。将 external_http 设置为 pages 守护进程监听连接的辅助 IP：

    pages:
  enabled: true
  # 页面存储的位置（默认：shared/pages）。
  # path: shared/pages

  host: example.io
  port: 80
  https: false

  external_http: 192.0.2.2:80

  3. 要启用守护进程，请编辑 /etc/default/gitlab 并将 gitlab_pages_enabled 设置为 true。 在 gitlab_pages_options 中，-pages-domain 的值必须与 host 匹配，-listen-http 必须与 external_http 匹配：

    gitlab_pages_enabled=true
gitlab_pages_options="-pages-domain example.io -pages-root $app_root/shared/pages -listen-proxy 127.0.0.1:8090 -listen-http 192.0.2.2:80"

  4. 复制 gitlab-pages-ssl NGINX 配置文件：

    sudo cp lib/support/nginx/gitlab-pages /etc/nginx/sites-available/gitlab-pages.conf
sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages.conf

  5. 编辑 /etc/nginx/site-available/ 中的所有 GitLab 相关配置，并将 0.0.0.0 替换为 192.0.2.1，其中 192.0.2.1 是 GitLab 监听的主 IP。

  6. 重启 NGINX。

  7. 重启 GitLab。

支持 TLS 的自定义域名

先决条件：

URL 方案：https://<namespace>.example.io/<project_slug> 和 https://custom-domain.com

在这种情况下，pages 守护进程正在运行。NGINX 仍然将请求代理到守护进程， 但守护进程也能够接收来自外部世界的请求。支持自定义域名和 TLS。

  1. 安装 Pages 守护进程：

    cd /home/git
sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git
cd gitlab-pages
sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION)
sudo -u git -H make

  2. 编辑 gitlab.yml 使其如下所示。您需要将 host 更改为用于托管 GitLab Pages 的 FQDN。将 external_http 和 external_https 设置为 pages 守护进程监听连接的辅助 IP：

    ## GitLab Pages
pages:
  enabled: true
  # 页面存储的位置（默认：shared/pages）。
  # path: shared/pages

  host: example.io
  port: 443
  https: true

  external_http: 192.0.2.2:80
  external_https: 192.0.2.2:443

  3. 编辑 /etc/default/gitlab 并将 gitlab_pages_enabled 设置为 true 以启用 pages 守护进程。 在 gitlab_pages_options 中，您必须将 -pages-domain 与 host 匹配，-listen-http 与 external_http 匹配，-listen-https 与 external_https 设置匹配。 -root-cert 和 -root-key 设置是 example.io 域名的通配符 TLS 证书：

    gitlab_pages_enabled=true
gitlab_pages_options="-pages-domain example.io -pages-root $app_root/shared/pages -listen-proxy 127.0.0.1:8090 -listen-http 192.0.2.2:80 -listen-https 192.0.2.2:443 -root-cert /path/to/example.io.crt -root-key /path/to/example.io.key"

  4. 复制 gitlab-pages-ssl NGINX 配置文件：

    sudo cp lib/support/nginx/gitlab-pages-ssl /etc/nginx/sites-available/gitlab-pages-ssl.conf
sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages-ssl.conf

  5. 编辑 /etc/nginx/site-available/ 中的所有 GitLab 相关配置，并将 0.0.0.0 替换为 192.0.2.1，其中 192.0.2.1 是 GitLab 监听的主 IP。

  6. 重启 NGINX。

  7. 重启 GitLab。

NGINX 注意事项

以下信息仅适用于自编译安装。

在 NGINX 配置中设置域名时要格外小心。您必须 不要删除反斜杠。

如果您的 GitLab Pages 域名是 example.io，请替换：

server_name ~^.*\.YOUR_GITLAB_PAGES\.DOMAIN$;

为：

server_name ~^.*\.example\.io$;

如果您使用子域名，请确保用反斜杠 () 转义所有点 (.)，除了第一个点。 例如 pages.example.io 将是：

server_name ~^.*\.pages\.example\.io$;

访问控制

GitLab Pages 访问控制可以按项目配置。对 Pages 站点的访问可以基于用户在该项目中的成员身份进行控制。

访问控制的工作原理是将 Pages 守护进程注册为 GitLab 的 OAuth 应用程序。 每当未认证用户请求访问私有 Pages 站点时，Pages 守护进程会将用户重定向到 GitLab。 如果认证成功，用户将带着令牌重定向回 Pages，该令牌会持久化在 cookie 中。 Cookie 使用密钥签名，因此可以检测到篡改。

每次查看私有站点中的资源时，Pages 都会使用该令牌进行认证。 对于它收到的每个请求，它会向 GitLab API 发送请求以检查用户是否有权读取该站点。

Pages 的访问控制参数在配置文件中设置，按照惯例该文件名为 gitlab-pages-config。 配置文件通过 -config flag 或 CONFIG 环境变量传递给 pages。

Pages 访问控制默认禁用。要启用它：

  1. 修改您的 config/gitlab.yml 文件：

    pages:
  access_control: true

  2. 重启 GitLab。

  3. 创建一个新的 系统 OAuth 应用程序。 这应该称为 GitLab Pages，并具有 Redirect URL 为 https://projects.example.io/auth。它不需要是"受信任"的应用程序， 但它需要 api 范围。

  4. 通过传递具有以下参数的配置文件启动 Pages 守护进程：

      auth-client-id=<GitLab 生成的 OAuth 应用程序 ID>
  auth-client-secret=<GitLab 生成的 OAuth 代码>
  auth-redirect-uri='http://projects.example.io/auth'
  auth-secret=<40 个随机十六进制字符>
  auth-server=<GitLab 实例的 URL>

  5. 用户现在可以在其 项目设置 中配置它。

更改存储路径

按照以下步骤更改 GitLab Pages 内容的默认存储路径。

  1. Pages 默认存储在 /home/git/gitlab/shared/pages。 如果您希望将它们存储在其他位置，您必须在 gitlab.yml 的 pages 部分中设置：

    pages:
  enabled: true
  # 页面存储的位置（默认：shared/pages）。
  path: /mnt/storage/pages

  2. 重启 GitLab。

设置最大 Pages 大小

每个项目解压存档的最大默认大小为 100 MB。

要更改此值：

  1. 在左侧边栏底部，选择 管理员。
  2. 选择 设置 > 偏好设置。
  3. 展开 Pages。
  4. 更新 页面最大大小 (MB) 的值。

备份

Pages 是 常规备份 的一部分，因此无需额外配置。

安全

您应该强烈考虑在与 GitLab 不同的主机名下运行 GitLab Pages，以防止 XSS 攻击。