极狐 GitLab

参与极狐GitLab Pages 开发

了解如何配置极狐GitLab Pages，以便协助开发该功能。

配置极狐GitLab Pages 主机名#

极狐GitLab Pages 需要一个主机名或域，因为每个不同的极狐GitLab Pages 站点都通过子域访问。你可以设置极狐GitLab Pages 主机名：

不使用通配符，编辑你的 hosts 文件#

由于 /etc/hosts 不支持通配符主机名，你必须为极狐GitLab Pages 配置一个条目，然后为每个页面站点配置一个条目：

plaintext
127.0.0.1 gdk.test           # 如果你正在使用 GDK
127.0.0.1 pages.gdk.test     # Pages 主机
# 需要将任何命名空间/群组/用户添加为 Pages 主机的子域。
# 这是因为 /etc/hosts 不接受通配符。
127.0.0.1 root.pages.gdk.test # 用于根 Pages

使用 DNS 通配符替代方案#

如果你不想编辑 /etc/hosts，而更愿意使用 DNS 通配符，你可以使用：

在没有 GDK 的情况下配置极狐GitLab Pages#

在极狐GitLab Pages 站点的根目录中创建一个 gitlab-pages.conf，例如：

toml
1# 默认端口为 3010，但你可以使用任何其他端口
2listen-http=:3010
3
4# 你的本地极狐GitLab Pages 域
5pages-domain=pages.gdk.test
6
7# 存储页面的目录
8pages-root=shared/pages
9
10# 在日志中显示更多信息
11log-verbose=true

要查看更多选项，你可以查看 internal/config/flags.go 或运行 gitlab-pages --help。

手动运行极狐GitLab Pages#

对于代码中的任何更改，你必须运行 make 来构建应用。最好在启动应用之前始终运行它。构建速度很快，不用担心！

shell
make && ./gitlab-pages -config=gitlab-pages.conf

使用 GDK 配置极狐GitLab Pages#

在以下步骤中，$GDK_ROOT 是你克隆 GDK 的目录。

  1. 设置 GDK 主机名。

  2. 将 极狐GitLab Pages 主机名 添加到 gdk.yml：

    yaml
    1gitlab_pages:
2  enabled: true         # 启用极狐GitLab Pages 由 gdk 管理
3  port: 3010            # 默认端口为 3010
4  host: pages.gdk.test  # 极狐GitLab Pages 域
5  auto_update: true     # gdk 是否必须更新极狐GitLab Pages git
6  verbose: true         # 在日志中显示更多信息

使用 GDK 运行极狐GitLab Pages#

完成这些配置后，GDK 会管理一个极狐GitLab Pages 进程，你可以使用如下命令访问它：

  • 启动：gdk start gitlab-pages
  • 停止：gdk stop gitlab-pages
  • 重启：gdk restart gitlab-pages
  • 查看日志：gdk tail gitlab-pages

手动运行极狐GitLab Pages#

你也可以独立于 GDK 进程管理来构建和启动应用。

对于代码中的任何更改，你必须运行 make 来构建应用。最好在启动应用之前始终运行它。构建速度很快，不用担心！

shell
make && ./gitlab-pages -config=gitlab-pages.conf

在 FIPS 模式下构建极狐GitLab Pages#

shell
FIPS_MODE=1 make && ./gitlab-pages -config=gitlab-pages.conf

创建极狐GitLab Pages 站点#

要在本地构建极狐GitLab Pages 站点，你必须 配置 gitlab-runner。

更多信息，请参考 用户手册。

启用访问控制#

极狐GitLab Pages 支持私有站点。私有站点只能由有权访问你的极狐GitLab 项目的用户访问。

极狐GitLab Pages 访问控制默认是禁用的。要启用它：

  1. 在极狐GitLab 本身中启用极狐GitLab Pages 访问控制。你可以通过两种方式做到这一点：

    • 如果你没有使用 GDK，编辑 gitlab.yml：

      yaml
      # gitlab/config/gitlab.yml
pages:
  access_control: true

    • 如果你正在使用 GDK，编辑 gdk.yml：

      yaml
      # $GDK_ROOT/gdk.yml
gitlab_pages:
  enabled: true
  access_control: true

  2. 重启极狐GitLab（如果通过 GDK 运行，运行 gdk restart）。运行 gdk reconfigure 会覆盖 config/gitlab.yml 中 access_control 的值。

  3. 在你的本地极狐GitLab 实例中，在浏览器中访问 http://gdk.test:3000/admin/applications。

  4. 创建一个具有 api 范围的 实例范围的 OAuth 应用。

  5. 将你的 redirect-uri 的值设置为 pages-domain 授权端点 （例如，http://pages.gdk.test:3010/auth）。 redirect-uri 不得包含任何极狐GitLab Pages 站点域。

  6. 添加认证客户端配置：

    • 使用 GDK，在 gdk.yml 中：

      yaml
      gitlab_pages:
  enabled: true
  access_control: true
  auth_client_id: $CLIENT_ID           # 在 http://gdk.test:3000/admin/applications 中创建的 OAuth 应用 ID
  auth_client_secret: $CLIENT_SECRET   # 在 http://gdk.test:3000/admin/applications 中创建的 OAuth 应用密钥

      GDK 会生成随机的 auth_secret，并根据极狐GitLab Pages 主机配置构建 auth_redirect_uri。

    • 不使用 GDK，在 gitlab-pages.conf 中：

      conf
      ## 以下仅在你想测试私有项目的认证时才需要
auth-client-id=$CLIENT_ID                         # 在 http://gdk.test:3000/admin/applications 中创建的 OAuth 应用 ID
auth-client-secret=$CLIENT_SECRET                 # 在 http://gdk.test:3000/admin/applications 中创建的 OAuth 应用密钥
auth-secret=$SOME_RANDOM_STRING                   # 至少应为 32 字节长
auth-redirect-uri=http://pages.gdk.test:3010/auth # 极狐GitLab Pages 的认证回调 URL

  7. 如果在 GDK 内运行 Pages，你可以在 gdk.yml 中的 gdk 下使用 GDK protected_config_files 部分，以避免 gitlab-pages.conf 配置被重写：

    yaml
    gdk:
  protected_config_files:
  - 'gitlab-pages/gitlab-pages.conf'

启用对象存储#

极狐GitLab Pages 支持使用对象存储来存储产物，但对象存储默认是禁用的。你可以在 GDK 中启用它：

  1. 编辑 gdk.yml 以在极狐GitLab 本身中启用对象存储：

    yaml
    # $GDK_ROOT/gdk.yml
object_store:
  enabled: true

  2. 通过运行 gdk reconfigure 和 gdk restart 命令重新配置并重启极狐GitLab。

更多信息，请参考 GDK 文档。

代码检查#

shell
# 在本地运行代码检查器
make lint

# 运行代码检查器并修复问题（如果代码检查器支持）
make format

测试#

要运行测试，你可以使用以下命令：

shell
1# 这将运行代码库中的所有测试
2make test
3
4# 运行特定的测试文件
5go test ./internal/serving/disk/
6
7# 运行文件中的特定测试
8go test ./internal/serving/disk/ -run TestDisk_ServeFileHTTP
9
10# 运行除 acceptance_test.go 之外的所有单元测试
11go test ./... -short
12
13# 仅运行 acceptance_test.go
14make acceptance
15# 运行特定的验收测试
16# 我们在这里添加 `make`，因为验收测试使用最后编译的二进制文件，
17# 所以我们希望测试的构建中包含最新的更改
18make && go test ./ -run TestRedirect

贡献#

功能标志#

所有新引入的功能标志都应 [默认禁用](https://handbook.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#how-to-use-feature-flags)。

考虑为任何非平凡的更改添加 功能标志。 功能标志可以使这些更改的发布和回滚更容易，避免事件和停机。要向极狐GitLab Pages 添加新的功能标志：

  1. 在 internal/feature/feature.go 中创建功能标志，该标志必须默认关闭。
  2. 使用 Feature flag 模板创建一个议题来跟踪该功能标志。
  3. 将 ~"feature flag" 标签添加到任何处理功能标志的合并请求中。

对于极狐GitLab Pages，功能标志由全局环境变量控制。 需要在服务级别进行部署才能更改功能标志的状态。 启用极狐GitLab Pages 功能标志的合并请求示例： Enforce GitLab Pages rate limits

成为极狐GitLab Pages 维护者#

本文档为希望成为极狐GitLab Pages 项目维护者的极狐GitLab 团队成员提供指南。 维护者应该对极狐GitLab Pages 代码库有深入的理解。 在申请成为项目维护者之前，个人应该对代码库有良好的感觉，在一个或多个功能方面有专业知识， 并对我们的编码标准有深刻的理解。

期望#

成为极狐GitLab 维护者的流程在手册中有定义， 这是此流程的基线。期望的一件事是大量的审查，然而； 与极狐GitLab Rails 项目相比，极狐GitLab Pages 的变更率太低。

为了解决这个问题，你必须熟悉代码库的以下领域：

主要领域：

  • 命名空间/项目解析
  • ZIP 服务和虚拟文件系统
  • 认证

次要领域：

  • 重定向
  • 产物代理
  • TLS 证书处理
  • 速率限制
  • 指标和监控

为了实现这一点，你应该尝试在上述所有主要领域和 2-3 个次要领域中做出相关贡献， 以便你对功能有更好的理解。相关贡献可以是错误修复、性能改进、新功能或重大重构。

审核者#

在成为维护者之前，你应该首先成为项目的审核者。这应该包括对代码库任何部分的更改，包括文档。

要成为审核者，请遵循 手册中概述的步骤。 在成为维护者之前，你应该担任审核者多长时间没有固定的时间表，但你应该 在本文档的 期望部分 中提到的领域获得足够的经验。

维护者#

要成为维护者，请遵循 手册中概述的步骤。 当以下陈述感觉真实时，你可能已经准备好成为维护者：

  • 你审查的合并请求始终能够通过维护者审查，而无需进行重大的额外更改
  • 你创建的合并请求始终能够通过审核者和维护者审查，而无需进行重大的更改
  • 你能够舒适地处理运维任务

如果这些主观要求得到满足，打开一个合并请求 将你提升为维护者，并标记现有的维护者。