托管 GitLab 产品文档

如果您无法访问 docs.gitlab.com 上的 GitLab 产品文档，您可以自行托管该文档。

容器镜像库 URL

您所需的容器镜像 URL 取决于您需要的 GitLab Docs 版本。请参考下表，以确定在后续章节中使用的 URL。

文档自托管选项

要托管 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 服务器上自托管产品文档

由于产品文档站点是静态的，您可以从容器内获取 /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 中选择一个 Learn more 链接。例如：

1. 在左侧边栏中，选择您的头像。
2. 选择 Preferences。
3. 在 Syntax highlighting theme 部分，选择 Learn more。

将产品文档升级到更新版本

将文档站点升级到更新版本需要下载更新的 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: 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 及更高版本中。如果您使用的是更早的版本，搜索功能将无法使用。

有关更多信息，请阅读关于 GitLab Docs 所使用的不同类型的搜索。

未找到 Docker 镜像

如果您收到未找到 Docker 镜像的错误，请检查您是否使用了正确的镜像库 URL。

Docker 托管的文档站点重定向失败

在 macOS 上使用 Docker 预览 GitLab 文档时，您可能会遇到一个问题，即无法重定向到文档，并显示消息 If you are not redirected automatically, click here.。

要解决此重定向问题，您需要在 URL 后附加版本号，例如 http://127.0.0.0.1:4000/16.8/。