{{< details >}}

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

{{< /details >}}

如果您无法访问极狐GitLab产品文档，您可以自己托管文档。

{{< alert type=”note” >}}

您的实例的本地帮助不包括所有文档（例如，它不包括极狐GitLab Runner 或极狐GitLab Operator 的文档），而且不可搜索或浏览。它仅用于支持从您的实例内直接链接到特定页面。

{{< /alert >}}

文档自托管选项

要托管极狐GitLab产品文档，您可以使用：

  • Docker 容器
  • 极狐GitLab Pages
  • 您自己的 Web 服务器

以下示例使用极狐GitLab 17.8，但请确保使用与您的极狐GitLab实例对应的版本。

使用 Docker 自托管产品文档

文档网站在容器内的端口 4000 下提供。在以下示例中，我们将其在主机下暴露于相同的端口。

确保您要么：

  • 在防火墙中允许端口 4000。
  • 使用不同的端口。在以下示例中，将最左侧的 4000 替换为不同的端口号。

要在 Docker 容器中运行极狐GitLab产品文档网站：

  1. 在您托管极狐GitLab的服务器上，或在任何其他您的极狐GitLab实例可以通信的服务器上：

    • 如果您使用普通 Docker，运行：

      docker run --detach --name gitlab_docs -it --rm -p 4000:4000 registry.gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/archives:17.8

    • 如果您使用 Docker compose 托管极狐GitLab实例， 将以下内容添加到您现有的 docker-compose.yaml 文件中：

      version: '3.6'
services:
  gitlab_docs:
    image: registry.gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/archives:17.8
    hostname: 'https://docs.gitlab.example.com:4000'
    ports:
      - '4000:4000'

      然后，拉取更改：

      docker-compose up -d
  2. 访问 http://0.0.0.0:4000 查看文档网站并验证其是否正常工作。
  3. 重定向帮助链接到新的文档站点。

使用极狐GitLab Pages 自托管产品文档

您可以使用极狐GitLab Pages 托管极狐GitLab产品文档。

先决条件：

  • 确保 Pages 站点 URL 不使用子文件夹。由于网站是预编译的，CSS 和 JavaScript 文件是相对于主域或子域的。例如，https://example.com/docs/ 这样的 URL 不受支持。

要使用极狐GitLab Pages 托管产品文档站点：

  1. 创建一个空项目。

  2. 创建一个新的或编辑您现有的 .gitlab-ci.yml 文件，并添加以下 pages 作业，同时确保版本与您的极狐GitLab安装相同：

    pages:
  image: registry.gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/archives:17.8
  script:
    - mkdir public
    - cp -a /usr/share/nginx/html/* public/
  artifacts:
    paths:
    - public

  3. 可选。设置极狐GitLab Pages 域名。根据极狐GitLab Pages 网站的类型，您有两个选项：

    网站类型 默认域名 自定义域名
    项目网站 不支持 支持
    用户或群组网站 支持 支持
  4. 重定向帮助链接到新的文档站点。

在您自己的 Web 服务器上自托管产品文档

{{< alert type=”note” >}}

您创建的网站必须托管在与您安装的极狐GitLab 版本匹配的子目录下（例如，17.8/）。

{{< /alert >}}

因为产品文档站点是静态的，您可以从容器内部获取 /usr/share/nginx/html 的内容，并使用您自己的 Web 服务器在任何您想要的位置托管文档。

html 目录应该按原样提供，其结构如下：

├── 17.8/
├── index.html

在此示例中：

  • 17.8/ 是托管文档的目录。
  • index.html 是一个简单的 HTML 文件，重定向到包含文档的目录。在此例中，是 17.8/。

要提取文档站点的 HTML 文件：

  1. 创建包含文档网站 HTML 文件的容器：

    docker create -it --name gitlab_docs registry.gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/archives:17.8

  2. 将网站复制到 /srv/gitlab/：

    docker cp gitlab-docs:/usr/share/nginx/html /srv/gitlab/

    您将得到一个包含文档网站的 /srv/gitlab/html/ 目录。

  3. 移除容器：

    docker rm -f gitlab_docs
  4. 指定您的 Web 服务器服务 /srv/gitlab/html/ 的内容。
  5. 重定向帮助链接到新的文档站点。

重定向 /help 链接到新的文档站点

在您的本地产品文档站点运行后，在极狐GitLab应用程序中重定向帮助链接到您的本地站点，使用完全限定的域名作为文档 URL。例如，如果您使用了 Docker 方法，输入 http://0.0.0.0:4000。

您不需要附加版本。极狐GitLab会检测并根据需要将其附加到文档 URL 请求中。例如，如果您的极狐GitLab版本是 17.8：

  • 极狐GitLab文档 URL 变成 http://0.0.0.0:4000/17.8/。
  • 极狐GitLab中的链接显示为 <instance_url>/help/administration/settings/help_page#destination-requirements。
  • 当您选择该链接时，您将被重定向到 http://0.0.0.0:4000/17.8/administration/settings/help_page/#destination-requirements。

要测试设置，在极狐GitLab中，选择一个 了解更多 链接。例如：

  1. 在左侧侧边栏，选择您的头像。
  2. 选择 偏好。
  3. 在 语法高亮主题 部分，选择 了解更多。

升级产品文档到更高版本

升级文档站点到更高版本需要下载更新的 Docker 镜像标签。

使用 Docker 升级

要升级到更高版本使用 Docker：

  • 如果您使用 Docker：

    1. 停止正在运行的容器：

      sudo docker stop gitlab_docs

    2. 移除现有容器：

      sudo docker rm gitlab_docs

    3. 拉取新镜像。例如，17.8：

      docker run --detach --name gitlab_docs -it --rm -p 4000:4000 registry.gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/archives:17.8

  • 如果您使用 Docker Compose：

    1. 更改 docker-compose.yaml 中的版本，例如 17.8：

      version: '3.6'
services:
  gitlab_docs:
    image: registry.gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/archives:17.8
    hostname: 'https://docs.gitlab.example.com:4000'
    ports:
      - '4000:4000'

    2. 拉取更改：

      docker-compose up -d

使用极狐GitLab Pages 升级

要升级到更高版本使用极狐GitLab Pages：

  1. 编辑您现有的 .gitlab-ci.yml 文件，并替换 image 版本号：

    image: registry.gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/archives:17.8

  2. 提交更改，推送，极狐GitLab Pages 拉取新的文档站点版本。

使用您自己的 Web 服务器升级

要升级到更高版本使用您自己的 Web 服务器：

  1. 复制文档站点的 HTML 文件：

    docker create -it --name gitlab_docs registry.gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/archives:17.8
docker cp gitlab_docs:/usr/share/nginx/html /srv/gitlab/
docker rm -f gitlab_docs

  2. 可选。移除旧站点：

    rm -r /srv/gitlab/html/17.8/

故障排除

搜索不起作用

本地搜索包含在版本 15.6 及更高版本中。如果您使用的是更早版本，搜索不起作用。

找不到 Docker 镜像

如果您使用的是版本 15.5 及更早版本，您应删除 Docker 镜像名称中的 /archives。

例如：

registry.gitlab.com/gitlab-org/gitlab-docs:15.5

如果您使用的是版本 17.8 或更早，Docker 镜像在 gitlab-docs 项目中。

例如：

registry.gitlab.com/gitlab-org/gitlab-docs:17.2

Docker 托管的文档站点无法重定向

在 macOS 上使用 Docker 预览极狐GitLab文档时，您可能会遇到阻止重定向到文档的问题，显示消息“如果您没有被自动重定向，请点击这里。”

要跳过重定向，您需要将版本号附加到 URL，例如 http://127.0.0.0.1:4000/16.8/。