gitlab使用gitlab-runner配置mkdocs文档中心

gitlab使用gitlab-runner配置mkdocs文档中心注本文所部署为内部局域网部署无网络环境若公网或外网部署可直接配置域名与使用yml运行1. 系统概述1.1 系统用途企业内部文档中心用于统一管理技术文档运维手册开发规范安全规范项目资料采用 GitLab MkDocs 架构用户浏览器 | | doc.anghui.com | | GitLab Pages | | GitLab Runner | | MkDocs 构建 | | Git仓库 Markdown文档2. 系统组件说明2.1 GitLab作用保存 Markdown 文档源码管理版本触发自动构建部署方式Docker主要目录/home/dell/gitlab目录结构gitlab │ ├── docker-compose.yml │ ├── config │ ├── data │ └── logs启动docker compose up -d查看状态docker ps正常状态gitlab/gitlab-ce Up (healthy)3. GitLab Runner 部署3.1 作用GitLab Runner 用于执行自动发布任务。例如用户提交文档git push触发GitLab CI | | Runner | | mkdocs build | | 生成静态网页3.2 Runner目录位置/home/gitlab-runner结构gitlab-runner │ ├── docker-compose.yml │ └── srv └── gitlab-runner └── config └── config.toml3.3 docker-compose配置文件docker-compose.yml内容version: 3.6 services: gitlab-runner: image: gitlab/gitlab-runner:latest restart: always container_name: gitlab-runner-2 volumes: - ./srv/gitlab-runner/config:/etc/gitlab-runner - /var/run/docker.sock:/var/run/docker.sock启动docker compose up -d查看docker ps4. Runner注册进入Runner容器docker exec -it gitlab-runner-2 bash执行gitlab-runner register4.1 填写信息GitLab地址填写http://pages.anghui.com注册Token位置GitLab项目 ↓ Settings ↓ CI/CD ↓ Runners ↓ New project runner复制token填写。Runner名称例如docker-runner-internalTags填写docker注意GitLab CItags: - docker必须对应。Executor选择docker默认镜像填写mkdocs-builder:1.05. MkDocs构建环境5.1 镜像说明使用mkdocs-builder:1.0包含Python MkDocs Material主题 搜索插件检查docker run --rm mkdocs-builder:1.0 pip list正常mkdocs mkdocs-material拓展镜像制作过程不用每次都拉取所需文件或者直接在内网使用Dockerfile示例FROM python:3.10 RUN pip install \ mkdocs \ mkdocs-material WORKDIR /docs构建docker build \ -t mkdocs-builder:1.0 .查看docker images结果mkdocs-builder 1.0之后可打包mkdocs-builder 1.0镜像进行(转移到内网registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:x86_64-v19.0.1也同样)# 打包镜像 docker save -o images/mkdocs-builder.tar mkdocs-builder:1.0 # 解压缩镜像 docker load -i mkdocs-builder.ta注部分需要在runner注册的config.toml对应文件位置增加两行helper_image registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:x86_64-v19.0.1 pull_policy [never]6. 文档项目结构Git仓库docs-center目录docs-center │ ├── docs │ │ ├── index.md │ ├── dev │ ├── ops │ └── sec │ │ ├── mkdocs.yml │ └── .gitlab-ci.yml7. MkDocs配置文件mkdocs.yml示例site_name: EasySAR Document Center theme: name: readthedocs plugins: - search: lang: - zh - en8. 自动发布配置文件.gitlab-ci.yml最终版本stages: - deploy pages: stage: deploy image: mkdocs-builder:1.0 tags: - docker script: # 生成网页 - mkdocs build # 删除公网CDN引用(部署内网附加本条可解决访问过慢速度问题) - find site -type f -name *.html \ - exec sed -i /cdnjs.cloudflare.com/d {} \; # GitLab Pages要求目录名称public - mv site public artifacts: paths: - public only: - master9. 发布流程9.1 修改文档例如修改docs/ops/nginx.md9.2 提交执行git add .提交git commit -m 更新Nginx文档上传git push9.3 查看发布状态GitLab项目 ↓ CI/CD ↓ Pipelines看到passed表示发布成功。10. 静态页面访问访问http://pages.anghui.comDNS由内部 Bind9 提供pages.anghui.com | | GitLab Pages11. 页面加载缓慢问题处理11.1 问题现象首次打开网页浏览器等待github.min.css highlight.min.js cdnjs.cloudflare.com导致内网访问慢页面加载失败原因MkDocs主题引用公网 CDNcdnjs.cloudflare.com但是企业内网无法访问公网。12. 解决方案在 GitLab CI 构建阶段增加清理。增加find site -type f -name *.html \ -exec sed -i /cdnjs.cloudflare.com/d {} \;作用构建完成后自动删除script srchttps://cdnjs.cloudflare.com重新发布。13. 故障排查13.1 页面没有更新检查GitLab:CI/CD | Pipeline确认passed13.2 Runner没有执行任务检查docker logs gitlab-runner-2正常Checking for jobs异常403 forbidden处理重新注册Runner。13.3 DNS问题测试ping pages.anghui.com测试ping pages.anghui.com如果失败检查Bind9配置。14. 整体迁移方法迁移到新服务器需要迁移GitLab目录config data logsRunner目录srv/gitlab-runner/config镜像导出docker save mkdocs-builder:1.0 \ -o mkdocs-builder.tar导入docker load \ -i mkdocs-builder.tar15. 日常维护更新文档只需要修改Markdown ↓ git push ↓ 自动发布无需登录服务器手动生成网页重启服务问题一gitlab的pages界面没有开启解决方法完整开启 GitLab Pages 四步操作一、进入 GitLab 容器编辑/etc/gitlab/gitlab.rbdocker exec -it gitlab bash vim /etc/gitlab/gitlab.rb粘贴全套 Pages 配置复制到文件末尾全部取消注释# 1、开启Pages总开关 gitlab_pages[enable] true # 2、Pages对外域名你的内网通配域名 pages_external_url http://pages.anghui.com # 4、Pages监听本地端口供Nginx反向代理转发 gitlab_pages[listen_proxy] 0.0.0.0:8090 # 5、开启自定义域名权限后台Pages页面出现New Domain按钮 gitlab_pages[allow_custom_domains] true # 静态文件持久化目录默认路径不用改 gitlab_rails[pages_path] /var/opt/gitlab/gitlab-rails/shared/pages保存退出ESC→:wq二、重载 GitLab 配置启动 Pages 服务#加载配置通常这一步就可以了 gitlab-ctl reconfigure # 重载完成后重启pages进程 gitlab-ctl restart gitlab-pages # 验证pages是否正常监听端口 ss -tuln | grep 8090