17. 文档自动发布:GitLab Pages 代码改文档同步更新

「GitLab」系列已发布: 00. GitLab 不只是代码托管:一套 DevOps 平台的 6 大核心能力 | 01. GitLab 怎么装最省心?Omnibus/Docker/K8s 三种姿势 | 02. 装完 GitLab 先配啥?管理员视角的初始化设置清单 | 03. GitLab 角色搞不清?Member/Maintainer/Owner 权限全解 | 04. 从零建好第一个 GitLab 项目:权限、变量、CI 配置入门 | 05. GitLab MR 代码审查:Code Review 最佳实践 | 06. CI/CD 到底是什么?GitLab 流水线架构从概念到实战 | 07. Runner 装不好?GitLab Runner 单机/分布式/高可用全攻略 | 08. .gitlab-ci.yml 怎么写?从 Hello World 到生产配置 | 09. 从 0 到 1:Go + React 项目的 GitLab CI/CD 实战部署 | 10. 构建太慢?GitLab 缓存与工件管理:加速构建省时间 | 11. 测试/预发/生产怎么管?GitLab 多环境部署与金丝雀发布 | 12. 安全左移:GitLab SAST/DAST 自动化扫描,漏洞提前拦截 | 13. 镜像仓库不用 Harbor?GitLab Container Registry 一站式管理 | 14. 私有包怎么存?GitLab Package Registry:Maven/PyPI/NPM 全覆盖 | 15. GitLab 挂了怎么办?高可用架构 + 备份恢复业务不中断 | 16. 自动化触发:GitLab Webhooks + API 打通你的工具链 | 17. 文档自动发布:GitLab Pages 代码改文档同步更新(本文)

文档和代码不同步是技术团队通病。GitLab Pages 在流水线里自动构建静态站点,代码一改文档就更新,告别手动搬文档。

前置条件

已掌握基础 CI/CD 配置(第 08-09 篇)。需要启用 GitLab Pages 功能并配置域名。

一、Pages 概述

GitLab Pages 允许你从 GitLab CI/CD Pipeline 托管静态网站。支持的技术栈:

技术 框架 文档生成
Vue.js VuePress, VitePress VuePress
React Docusaurus, Gatsby Create React App
Hugo Hugo Hugo
Jekyll Jekyll Jekyll
MkDocs MkDocs MkDocs
Hexo Hexo Hexo
Astro Astro Astro
flowchart TD A[代码仓库] --> B[CI/CD Pipeline] B --> C{构建站点} C --> D[静态文件] D --> E[GitLab Pages] E --> F[访问 URL] subgraph GitLab["GitLab Pages"] G[HTTPS 自动启用] H[CDN 加速] I[自定义域名] end

二、构建配置

2.1 基础配置

pages:
  stage: deploy
  image: node:20-alpine
  before_script:
    - npm ci
  script:
    - npm run docs:build
  artifacts:
    paths:
      - public              # 必须是 public 目录
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

2.2 VuePress 配置

// docs/.vuepress/config.js
module.exports = {
  title: 'My Project',
  base: '/my-project/',   // 项目 Pages 需要 base
  themeConfig: {
    nav: [
      { text: 'Guide', link: '/guide/' },
      { text: 'API', link: '/api/' }
    ]
  }
}
pages:
  stage: deploy
  image: ruby:3.3
  before_script:
    - gem install bundler
    - bundle install
  script:
    - bundle exec jekyll build -d public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

2.3 Hugo 配置

pages:
  stage: deploy
  image: klakegg/hugo:ext-alpine
  script:
    - hugo --destination public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

三、Review Apps(每个 MR 独立页面)

review-pages:
  stage: deploy
  image: node:20-alpine
  before_script:
    - npm ci
  script:
    - npm run docs:build
  artifacts:
    paths:
      - public
  environment:
    name: review/pages/$CI_MERGE_REQUEST_IID
    url: https://$CI_PROJECT_ROOT_NAMESPACE.gitlab.io/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.html
  on_stop: stop-review-pages
  rules:
    - if: $CI_MERGE_REQUEST_ID

stop-review-pages:
  stage: .post
  environment:
    name: review/pages/$CI_MERGE_REQUEST_IID
  action: stop
  rules:
    - if: $CI_MERGE_REQUEST_ID
      when: manual
  variables:
    GIT_STRATEGY: none

四、多分支部署

pages:
  script:
    - npm run docs:build
    - |
      if [ "$CI_COMMIT_BRANCH" != "main" ]; then
        mkdir -p public/$CI_COMMIT_BRANCH
        mv public/*.html public/$CI_COMMIT_BRANCH/
      fi
  artifacts:
    paths:
      - public

五、自定义域名

5.1 GitLab 侧配置

项目 → Settings → Pages → New Domain。填域名后勾选 Let’s Encrypt 自动签发,GitLab 自动续期。

5.2 DNS 配置


# CNAME 记录
pages.example.com → <username>.gitlab.io
或
pages.example.com → xx.gitlab.io

六、访问控制

Settings → General → Visibility:Private(仅成员)/ Internal(登录用户)/ Public(所有人)。

GitLab Pages 访问控制 (Premium):

  • Private Pages:仅项目成员可访问
  • Internal Pages:登录 GitLab 即可访问
  • Public Pages:所有人可访问

七、性能优化

7.1 压缩

pages:
  script:
    - npm run build
    - find public -name '*.html' -exec gzip -k {} \;
  artifacts:
    paths:
      - public
    expire_in: 30 days

7.2 CDN 缓存

pages:
  script:
    - npm run build
    - |
      echo '<meta http-equiv="cache-control" content="max-age=31536000">' >> public/index.html
  artifacts:
    paths:
      - public

八、状态监控

项目 → Deploy → Pages:部署时间、状态、访问 URL、证书状态。
CI/CD → Jobs → Pages Job:部署日志、可下载构建产物预览。

九、Pages 工作流程

sequenceDiagram participant Dev as 开发者 participant GitLab as GitLab participant Build as CI/CD participant Pages as Pages Server participant CDN as CDN Dev->>GitLab: push 代码到 main GitLab->>Build: 触发 Pages Pipeline Build->>Build: 构建静态文件 Build->>Pages: 上传 artifacts Pages->>CDN: 分发到边缘节点 CDN-->>User: 提供访问

十、文章引用

📌 本文首发于微信公众号 【运维知识点滴】——专注运维实战干货,微信搜索“运维知识点滴”或扫下方二维码关注,更新不迷路。

微信公众号【运维知识点滴】 微信小程序【A5单据合并&大试卷拆分转A4打印】
运维实战干货 · 关注追更 Word 转 PDF · 试卷/发票打印神器 · 免费
运维实战干货 · 关注追更 Word 转 PDF · 试卷/发票打印神器 · 免费

💡 小程序【A5单据合并&大试卷拆分转A4打印】是干嘛的? 一个 Word 转 PDF 的打印神器,专治“文档版式和打印机对不上”:

  • A3 试卷打不出来? 学校发的电子版试卷多是 A3,家用打印机只吃 A4——上传 Word 一键转换:可缩到一页 A4(页数不变),也可对半拆成两张 A4(1:1 原大、字更清晰),两种模式自选;
  • 版式不乱:真实渲染引擎原样转换、绝不重排内容,转出的 PDF 和原 Word 排版一致,公式/表格/图片不跑版;
  • 两张 A5 单据拼一张 A4:出租车票、火车票等报销凭证拼版后,一次打印、整齐粘贴;
  • 隐私省心:无需注册,转换结果留存 5 天、最多下载 5 次即自动删除,不留任何历史记录;
  • 微信扫码即用,免费、免安装,支持 doc / docx(≤50MB)。

上一篇:16. 自动化触发:GitLab Webhooks + API 打通你的工具链