Gitlab Pages是什么？

[zhongfangxiong]

下面把 GitLab Pages 按“你从未用过、但要在自建 GitLab 上把它做成团队文档统一入口”的角度，系统讲清楚：它是什么、怎么工作、你需要准备什么、怎么和 MkDocs/集中站点/NodeBB/企业微信配合。

---

1. GitLab Pages 是什么

GitLab Pages = GitLab 自带的静态网站托管能力。
你把网站的静态文件（HTML/CSS/JS/图片等）通过 CI 产出成一个 artifact，GitLab Pages 就会把它对外提供成一个网站。(GitLab 文档)

关键点：它只托管“静态网站”，不跑后端（不跑 .NET 服务、不跑数据库）。适合文档站、前端构建产物、产品手册、项目主页等。

---

2. GitLab Pages 怎么工作的（核心机制）

Pages 的发布有一个非常清晰的约定：

• CI 中有一个 Pages job（job 名可以叫 pages，也可以自定义）。
• 这个 job 必须产出一个目录（传统默认叫 public）作为 artifacts。
• GitLab 会把这个 artifacts 部署成网站。(GitLab 文档)

早期常见约定是目录名必须叫 public。(GitLab 文档)
较新的方式是：你可以在 .gitlab-ci.yml 里用 pages: publish: 指定发布目录，比如 dist。(GitLab 文档)

---

3. 你最终会得到的 URL 长什么样

GitLab Pages 的域名/路径规则跟 GitLab 的用户/组/项目结构相关，常见会区分：

• Project Pages（项目级网站）
• Group Pages / User Pages（组/用户级网站）
• 支持自定义域名(GitLab 文档)

你是自建 GitLab，所以最关键不是“规则长啥样”，而是你们管理员在 GitLab 上给 Pages 配了什么域名（通常需要一个单独的 Pages 域名，比如 pages.xxx.com 或 pages.xxx.net，并做 DNS/证书配置）。

---

4. 自建 GitLab 上，Pages 要能用，管理员侧需要什么

这部分通常由运维/管理员做一次，之后所有项目都能用 Pages。

典型前置条件包括：

• 为 Pages 准备一个独立域名（例如 pages.example.com 或 example.io）
• 为该域名配置 通配符 DNS（例如 *.pages.example.com）(GitLab 文档)
• （可选但强烈建议）配置 通配符 TLS 证书，以便 *.pages... 全部走 HTTPS(GitLab 文档)
• 自建安装还需要 zip/unzip 等用于处理 artifacts 的依赖（具体取决于部署方式）(GitLab 文档)

如果你在 GitLab UI 里看不到 Pages 相关开关/设置，一般就是管理员还没启用或没配置。(GitLab 文档)

---

5. 最小可用的 Pages 示例（用 MkDocs 举例）

你不需要理解太多，掌握一条：CI 构建 → 产出静态目录 → Pages 发布

以 MkDocs 为例：

stages: [build, deploy]

build-docs:
  stage: build
  image: python:3.12-alpine
  script:
    - pip install mkdocs-material
    - mkdocs build -d public
  artifacts:
    paths:
      - public
    expire_in: 7 days

pages:
  stage: deploy
  script:
    - echo "deploy pages"
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

说明：

• mkdocs build -d public：把站点生成到 public/
• pages job 把 public/ 作为 artifact 给 GitLab Pages 用(GitLab 文档)

你会发现：Pages 的本质就是“把某个目录托管成网站”。

---

6. Pages 的权限与访问控制（你这种“内部知识库”很关键）

GitLab Pages 支持访问控制：可以根据项目可见性/设置决定谁能访问 Pages。(GitLab 文档)

对你们团队知识库，我通常建议两种策略：

1. 内部可见（需要 GitLab 登录）：安全、适合内网知识
2. 公开可见：适合对外文档（比如开源项目）

你想做“集中网站给团队看”，大概率选第 1 种。

---

7. 回到你的痛点：为什么 GitLab Pages 适合“集中式文档站”

你担心的不是“能不能发布”，而是：

• 500 仓库文档散落，没人看
• 需要一个统一入口 + 统一导航 + 统一搜索
• 还要能通知到 NodeBB/企业微信

Pages 在这里的价值是：

• 发布非常标准化：CI 产出静态目录即可(GitLab 文档)
• 权限可继承 GitLab 的组织结构（内部站点很方便）(GitLab 文档)
• 你可以把中央聚合仓库的 Pages 当作唯一入口（docs portal）

---

8. 你问“为什么不直接 NodeBB 发帖就算了”：Pages + NodeBB 的正确分工

结论：NodeBB 负责“通知与讨论”，Pages 负责“可长期引用的最终文档”。

• Pages 站点：目录、搜索、稳定 URL、版本演进
• NodeBB：把“本次变更摘要 + 链接”推送给所有人，并在贴内讨论

这两者叠加，你会得到：

• “大家会看到”（通知推送）
• “大家能查到”（文档站可检索）
• “半年后仍然可追溯”（Git + Pages 稳定链接）

---

9. 你下一步应该怎么验证 Pages 是否已就绪（不需要猜）

在你们自建 GitLab 上，最快的验证方式是：

1. 新建一个测试项目 pages-test
2. 放一个最简单的 .gitlab-ci.yml：创建 public/index.html 并发布
3. 跑 pipeline，看项目的 Pages 设置里是否出现可访问 URL（或提示管理员启用）

官方也提供“从零创建 Pages”的指导思路（本质就是 CI 产出静态目录）。(GitLab 文档)

---

我建议你做的最短落地路径（针对你“集中站点 + 通知”）

1. 先把 Pages 跑通：pages-test 项目发布一个静态页
2. 建立 docs-portal（中央仓库）用 MkDocs 发布 Pages
3. 让 docs-portal 作为唯一入口（先不急着聚合 500 项目）
4. docs-portal 发布后：CI 同步推送到企业微信 + NodeBB（每日汇总更合理）

---

如果你愿意，我下一条可以直接给你一套“验证 Pages 就绪”的最小项目内容（index.html + .gitlab-ci.yml），以及一个 docs-portal 的 MkDocs 初始仓库骨架（导航、首页、日报/ADR 模板、发布后通知脚本接口），你复制进去就能跑。你只需要告诉我你们 GitLab 的 Pages 域名大概是怎样配置的（比如 *.pages.xxx.com 还是 pages.xxx.com/<group>/<project>），我就能把链接规则也写进模板里。