3步掌握GitLab Pages静态网站托管：从Docker部署到自定义域名全攻略

GitLab Pages是GitLab提供的静态网站托管服务，能直接从代码仓库部署HTML、CSS、JavaScript等静态资源。本文将指导你在Docker环境中搭建GitLab并配置GitLab Pages，实现静态网站的自动化部署与高效管理。

一、从零开始：Docker GitLab环境搭建

1.1 克隆项目仓库

首先获取docker-gitlab项目源码：

git clone https://gitcode.com/gh_mirrors/do/docker-gitlab

1.2 启动GitLab容器

使用docker-compose快速启动GitLab服务：

cd docker-gitlab
docker-compose up -d

默认配置文件位于项目根目录的docker-compose.yml，可根据需求调整端口映射和数据卷配置。

二、GitLab Pages核心配置详解

2.1 启用Pages服务

修改assets/runtime/env-defaults文件，添加Pages启用配置：

GITLAB_PAGES_ENABLED=true
GITLAB_PAGES_DOMAIN=pages.example.com

2.2 配置Nginx反向代理

GitLab Pages的Nginx配置文件位于assets/runtime/config/nginx/gitlab-pages，主要配置项包括：

• 监听端口设置
• 域名解析规则
• 静态资源缓存策略
• SSL证书路径配置

图：GitLab Pages客户端配置界面，显示基础URL和重定向设置

三、静态网站部署完整流程

3.1 创建CI/CD配置文件

在项目根目录创建.gitlab-ci.yml文件，添加Pages部署任务：

pages:
  stage: deploy
  script:
    - mkdir public
    - cp -r docs/* public/
  artifacts:
    paths:
      - public
  only:
    - main

3.2 配置客户端访问设置

在GitLab管理界面中配置Pages访问参数：

图：GitLab Pages客户端详细配置界面，包含URL设置和访问控制选项

3.3 部署与访问验证

提交代码后，GitLab CI/CD会自动执行部署任务。访问地址格式为： http://<项目命名空间>.<pages域名>

四、高级配置与安全强化

4.1 配置SSL证书

1. 将SSL证书文件放置于assets/runtime/config/nginx/ssl/目录
2. 修改assets/runtime/config/nginx/gitlab-pages-ssl配置文件
3. 更新环境变量启用HTTPS：

GITLAB_PAGES_HTTPS=true

图：GitLab Pages SSL密钥配置界面，显示安全证书管理选项

4.2 自定义域名设置

1. 在DNS提供商添加CNAME记录指向GitLab Pages域名
2. 在项目设置中添加自定义域名
3. 上传域名验证文件至项目public目录

五、实用技巧与性能优化

5.1 构建缓存优化

在.gitlab-ci.yml中添加缓存配置：

cache:
  paths:
    - node_modules/
    - .cache/

5.2 静态资源压缩

修改Nginx配置启用Gzip压缩：

gzip on;
gzip_types text/css application/javascript image/svg+xml;

5.3 访问控制设置

通过环境变量启用Pages访问控制：

GITLAB_PAGES_ACCESS_CONTROL=true

六、常见问题解决方案

6.1 部署权限问题

检查项目设置中的"Pages访问控制"选项，确保设置为"Everyone"或适当的访问级别。

6.2 静态资源加载失败

确认CI/CD配置中的artifacts.paths指向正确的静态文件目录，通常为public/。

6.3 域名解析问题

使用dig命令验证DNS记录是否生效：

dig your-custom-domain.example.com CNAME

通过以上步骤，你已成功在Docker环境中配置GitLab Pages服务，实现静态网站的自动化部署与管理。合理利用GitLab CI/CD流水线和Pages功能，可以显著提升静态网站的开发与发布效率。