从零搭建机器人技术文档中心：GitLab + Antora + CI/CD + Nginx 实战教程

CI（持续集成）负责自动验证和构建；本实验的 CD（持续部署）把成功构建的网页自动复制到网站目录。Pipeline 是一次流水线，Stage 是阶段，Job 是实际执行命令的任务。

本文中 Bash 命令在 Ubuntu/WSL 执行。带 \ 的多行命令是一条命令，反斜杠必须是该行最后一个字符；改成一行时去掉反斜杠即可。命令中的示例邮箱、版本和 Token 占位符需替换，不要把提示符 $ 一起复制。

原实验 100 GB 虚拟磁盘使用 LVM，根分区约 49 GB，其余空间留在卷组中。虚拟磁盘大小和根分区可用空间是两回事，Docker 镜像、GitLab 数据和 Artifact 主要消耗根分区空间。

在 Windows PowerShell 或 WSL 登录服务器：

在 Ubuntu Server 更新系统与安装常用工具：

验收：Windows 能 SSH 登录；服务器有默认路由，软件源可访问；确认实际 IP 后，后续所有配置使用同一地址。

Windows PowerShell 中可查看 WSL：

如果尚未安装，在有相应权限的 PowerShell 中执行 wsl --install -d Ubuntu，按系统提示完成重启和初始化。已有 WSL Ubuntu 可直接使用。以后文中的 WSL 表示编辑与本地构建环境，Ubuntu Server 表示运行 GitLab/Runner/Nginx 的虚拟机。

原实验曾在 Windows 10 升级到 Windows 11 后出现：

如果旧虚拟机也无法启动，应先检查 VMware 主机驱动、服务与 Windows 版本兼容性。关闭虚拟机、备份虚拟机文件，使用具有管理员权限的安装程序修复或更新 VMware，重启 Windows 后再次测试。出现 “You must have administrative privileges…​” 时，说明当前修复程序没有提升权限。这个错误发生在 Ubuntu 启动前，不应通过修改 Docker 或 GitLab 配置处理。

原实验访问 download.docker.com 出现连接重置，因此改用 Ubuntu 软件仓库。以下是一条完整的 Ubuntu Server 实验安装路线：

重新 SSH 登录，使用户组生效，然后执行：

docker.io 是 Ubuntu 打包的 Engine；docker-compose-v2 提供 docker compose 子命令。另一条路线是使用 Docker 官方 APT 源安装 docker-ce 与 docker-compose-plugin，不要混装两条路线。软件包不存在时检查 Ubuntu 版本、软件源和 universe 仓库配置。官方路线参见 Docker Ubuntu 安装说明。

Registry 返回 HTTP 401 Unauthorized 通常说明已经连通，只是尚未认证；连接超时、重置和无法解析是另一类故障。一次 DNS 查询不能单独证明根因，应结合解析、TCP/HTTPS 和 Docker 日志。原实验先发现 NAT DNS 可疑，切换 DNS 后 Docker Hub 的 HTTPS 仍失败，说明只换 DNS 没有解决全部问题。

临时修改 DNS（网卡名须取自 ip -br addr）：

该设置可能在重启或网络重配后失效。需要持久化时先查看 /etc/netplan/，在原有网卡配置中修改 nameservers，避免覆盖原路由和地址；远程操作优先 sudo netplan try。不要将第三方公共 DNS 强行用于依赖公司内部域名的网络。

原实验成功使用了显式镜像代理路径：

同样的路径用于 library/node:22、library/nginx:alpine、gitlab/gitlab-ce 与 gitlab/gitlab-runner-helper。代理路径会直接出现在镜像名称里，与 Docker daemon 的 registry-mirrors 配置不同。Docker Hub 代理不会自动解决 registry.gitlab.com 的访问问题。

如果该历史代理不可用，可使用自己信任且可访问的镜像仓库、正确配置 Docker daemon 的网络代理，或者离线导入。以下在 能联网且架构匹配的电脑 执行：

然后在 Ubuntu Server：

如果导入镜像名是 node:22，CI 中也应使用 node:22，或先 docker tag 为 CI 配置使用的完整镜像名。预拉取与离线导入必须针对 Job 实际使用的 Docker daemon。

验收：Docker/Compose 能报告版本，至少一个测试镜像能成功运行。不要把拉取失败误认为 Docker 安装失败。

在 Ubuntu Server：

compose.yaml（保留原实验启动方式）：

external_url 决定 GitLab 对外链接以及这里内部 Nginx 的监听端口，因此本例使用 8181:8181。2222:22 只用于 GitLab 的 Git SSH。三个卷分别保存配置、日志和数据，使容器重建不等于仓库消失。持久化不替代备份。

latest 是原实验使用方式；建立长期运行环境前，应将其改成已验证的具体版本标签并记录镜像摘要，升级按 GitLab 支持的升级路径执行。不能通过随意拉取新 latest 跳过版本升级要求。

参见 GitLab Docker 安装说明。

第一次下载与初始化可能较慢。查看日志时按 Ctrl+C 仅退出日志跟随，不会停止后台容器。网页短暂 502 或 health: starting 时继续检查容器初始化，不要反复删容器重建。

浏览器访问 http://192.168.179.129:8181，使用 root 和初始密码登录，随后修改密码。初始密码只用于第一次登录，不要放入文档、仓库或截图。资料初始化页面可跳过。

验收：GitLab 登录成功，可进入项目创建页面；8181 是 GitLab 页面，8080 暂时还没有正式文档服务。

在 WSL 使用已有 Node 22 环境。若没有 nvm，可从其官方 Git 仓库安装一个明确版本（下面使用 v0.40.3），再安装 Node 22：

如果 ~/.nvm 已存在，不要覆盖，加载其 nvm.sh 即可。在 ~/.bashrc 中添加以下两行，使新终端也能加载：

nvm 是独立开源项目；GitHub 或 Node 下载受限时，先解决网络，或从 Node 官方下载页 取得对应 Linux 架构的 Node 22 并按其说明安装。不要把 Windows Node 误当作 WSL Linux Node。先检查：

3.2.0 是原对话安装输出记录的版本。若所用 npm 源不能提供该版本，先 npm view @antora/cli versions --json 与 npm view @antora/site-generator versions --json，选择二者共同支持的版本，再将两个版本同步替换。不要只替换 CLI。--save-exact 与 package-lock.json 让依赖可重现；CI 后续使用 npm ci 严格按 lock 文件安装。

创建 abb/antora.yml：

创建 abb/modules/ROOT/pages/index.adoc：

创建 abb/modules/ROOT/pages/network.adoc：

创建 abb/modules/ROOT/pages/faq.adoc：

创建 abb/modules/ROOT/nav.adoc：

name 是组件标识，title 是显示名称，version 是文档版本；ROOT 是默认模块，pages 放页面，images 放图片，nav.adoc 决定左侧导航。右侧页内目录由正文标题生成。

本地内容源也需要 Git 仓库和至少一次提交；Antora 通过 Git 识别版本。这里仅初始化 abb，不要把包含其他子仓库、node_modules 与构建结果的整个 Demo 目录当成内容仓库。

创建 ~/robot_docs_demo/antora-playbook.yml：

site、content、ui、output 是平级配置。ui.bundle.url 必须是字符串。UI 下载受限时，在可联网环境取得默认 UI bundle，放到 ui/ui-bundle.zip，将 URL 改为 ./ui/ui-bundle.zip，并把文件纳入 Site 仓库以供 CI 使用。

打开 Windows 浏览器 http://localhost:8080/abb/1.0/index.html。该服务运行于 WSL，不能假定 VM 的 192.168.179.129:8080 也可访问。终端关闭或按 Ctrl+C 后，临时服务会停止。

验收：能看到 ABB 首页、左侧导航、代码和提示框；日志出现 Site generation complete!。如果只显示目录列表，检查是否错误地从 ~/robot_docs_demo 而非 build/site 提供服务。

在 WSL：

fanuc/antora.yml：

fanuc/modules/ROOT/pages/index.adoc：

fanuc/modules/ROOT/nav.adoc：

将 version 改为 '1.1'，编辑该版本页面，再提交：

两个分支分别必须声明 1.0、1.1；仅创建分支但不修改 version，可能导致组件版本重复。分支名 v1.1 和文档版本 '1.1' 不必相同；网站路径由组件版本决定，本文预期 /abb/1.1/，不带 v。

将 playbook 的 content 部分改为：

验收：组件选择器中有 ABB 1.0、ABB 1.1、FANUC 1.0，版本切换后 URL 与正文对应。改版本名后使用 --clean 清理 构建输出，避免旧 /abb/v1.0/ 路径残留。

浏览器进入 GitLab：

在 WSL 创建专用于本实验的密钥，已有合适密钥可复用：

把 .pub 公钥添加到 GitLab 用户的 SSH Keys。私钥不要上传。可在 ~/.ssh/config 追加：

若已有 origin，先 git remote -v 核对，再使用 git remote set-url origin …​。首推后检查 GitLab 默认分支、分支保护状态与用户权限；它们可能影响后续变量和 CI。

SSH 的标准完整 URL 形式是 ssh://git@192.168.179.129:2222/robot-docs/robot-docs-abb.git。此时 2222 是端口；不要在不带 ssh:// 的普通 SCP 形式中把它误写成目录。

验收：GitLab 中能浏览 ABB 两个版本分支及 FANUC 的 v1.0；WSL push 成功。

先理解三类凭据：

原实验先为 ABB 使用项目 Deploy Token，加入 FANUC 后改为 Group Deploy Token。在 Group 的 Settings → Repository → Deploy tokens 创建只带 read_repository 权限的 Token，记录实际用户名和 Token。只有需要读取镜像仓库时才增加对应 registry 权限。

删除或撤销旧项目 Token 前，应先验证 Group Token 能读取所有目标仓库。Group Token 的读取范围更广，应限制使用者与有效期。

将 playbook 中 content 替换为：

Token 不应写入 URL 并提交。原实验通过 GIT_CREDENTIALS 提供认证，下面用交互输入避免真实 Token 留在命令历史中：

用户名和 Token 如包含 URL 保留字符，应先按 URL userinfo 规则编码。默认 GitLab 生成的 Deploy Token 通常适用于该形式。若改用凭据文件，限制权限并放在仓库外，通过 GIT_CREDENTIALS_PATH 指定，避免提交到 Git。

Antora 自己负责仓库获取，不要假定命令行 Git 已登录就等于 Antora 已认证。参见 Antora 私有仓库认证。

验收：本地构建能生成 ABB 与 FANUC。若有疑问，可临时改名本地 ABB 目录，验证仍从远端构建，之后恢复目录。--fetch 刷新远端内容，--clean 清理输出，两者作用不同。

进入 Site 项目的 Settings → CI/CD → Runners，创建 Project Runner（界面名称随版本可能变化）：

记录创建后显示的 glrt-…​ authentication token。新注册流程是在 GitLab 创建 Runner 后使用该 Token，不应把旧 registration token 和 --registration-token 流程混用。

交互输入：

按照实际版本提示填写；也可使用 GitLab 创建页给出的 register --url …​ --token …​ 命令，但不要把实际 Token 保存到脚本、聊天或教程里。

docker.sock 让 Runner 能通过宿主机 Docker 创建 Job 容器，不是 Docker-in-Docker。本实验不要求 Job 挂载这个 socket，也不要求 privileged = true。Runner 本身拥有强大的主机权限，应只用于可信项目。

config.toml 中保存实际认证 Token，不要把完整配置输出到公开日志。参见 Runner 注册文档。

验收：GitLab 显示 Online / Idle；Idle 表示在线等待任务。Project Runner 分配给 Site 即可，内容仓库仅使用 trigger job 时不需要执行脚本的 Runner。

Docker executor 启动业务镜像之前，使用 helper image 完成源码获取、缓存和 Artifact 上传下载。原实验 Runner 已在线，但 Job 卡在：

这是 GitLab Registry 拉取问题，不是 Node、Antora 或 CI script 的问题。

在 Ubuntu Server 查版本与架构，并预拉取 *匹配*的 helper：

x86_64-v19.3.3 是原实验值。若 Runner 为其他版本或 ARM，按实际 helper 标签替换，不要复制这个标签搭配不同版本 Runner。

在现有 Runner 的 [runners.docker] 段内修改或添加，保留已生成的 URL、Token 等字段，不重复创建第二个段：

if-not-present 优先使用本地存在的镜像，不会自动更新浮动标签。它适合此独立实验机的网络情况，长期运行应采用明确版本/摘要及可控更新流程。升级 Runner 时同步更新 helper；很多 Runner 配置能自动重载，此处重启是便于实验确认。

参见 Runner 高级配置。

验收：Job 日志显示已使用配置的 helper，之后开始拉取 Node。如果卡点转移到 Node 的下载，说明 helper 这一层已经通过。首次 Node 下载曾耗时较长，应观察日志和拉取进度，不能仅凭时间长判定挂死。

Site 项目 Settings → CI/CD → Variables：

实验中的分支若未保护，Protected 变量不会提供给相应任务。应使变量与分支保护策略一致：初期可按原实验不勾 Protected，稳定后保护 main 与需要发布的分支，再启用对应保护。不要为了解决缺变量，把 Token 写进 playbook。

将测试配置替换成：

提交后观察构建日志：

仓库存的是 .adoc 和配置；Artifact 是 Job 执行结束前上传给 GitLab 的 build/site/ 成品包。Job 容器是临时的，没有 Artifact，构建结果会随着临时环境清理而失去。

在 build-docs 的 Job 页面，右侧 Job artifacts 下可以 Browse / Download；这些按钮不在项目仓库首页。Browse 便于核对生成文件，Download 下载成品包，Keep 可保留该次产物。expire_in 是过期配置，具体保留还受 GitLab “保留最近成功产物”等设置影响。

Artifact 不等于已经发布的网站，也不是 cache：Artifact 用于交付本次结果，cache 通常用于复用依赖、减少下载。

验收：构建成功，Artifact 中有 ABB 1.0、ABB 1.1、FANUC 1.0 和入口 index.html；此时还不能仅凭构建成功就认定 VM 的 8080 网站已更新。

在 Ubuntu Server 修改 Runner 的 config.toml 中原有 volumes：

该设置决定 Job 容器 的挂载，而不是只给 Runner 管理容器增加卷。目录映射最终是：

本实验应将有发布目录权限的 Runner 限制给可信 Site 项目；否则使用这个 Runner 的其他 Job 也能改网站目录。

将 Site 的 .gitlab-ci.yml 改为以下完整版本。沿用原实验的直接复制部署，并增加入口检查与部署互斥：

needs: artifacts: true 将 build-docs 的产物下载到部署 Job，两个 Job 不共享临时工作目录。rules 限制只有 main 部署；environment 登记部署环境，不会自动启动服务器。resource_group 防止本项目的部署 Job 同时复制目录，但不会自动保证所有排队 Pipeline 按内容新旧顺序发布。

cp -a build/site/. 包含隐藏文件，避免 build/site/* 漏复制。Node 镜像默认以 root 运行时通常能写入；若自定义非 root 用户，需按实际 UID/GID 配置目录权限，不建议以 chmod 777 掩盖问题。

提交与验证：

验收：Build 和 Deploy Passed；VM 8080 的测试标题变成真正 Antora 页面；/abb/1.1/network.html 和 /fanuc/1.0/index.html 可访问。无需重启 Nginx。

在 WSL：

先用独立配置理解触发机制：

trigger 是 GitLab 调度的多项目触发任务，不是运行 curl 的脚本 Job，因此不需要 Docker 镜像或 Runner tags。它以触发 Pipeline 用户的权限创建下游 Pipeline；该用户必须有权限在 Site 的 main 上运行 Pipeline。Deploy Token 只解决 Antora 仓库读取，不能替代这个用户权限。

strategy: mirror 让上游任务等待下游并镜像成功/失败状态，要求 GitLab 18.2+；较旧实例可按其版本使用 depend，语义并不完全相同，需参考对应版本文档。本规则只匹配 v1.0、v1.1 等分支，不匹配 main、v1.0.1 或 Tag。

在 network.adoc 增加：

验收：ABB Pipeline 的 trigger job 指向 Site 下游 Pipeline，Site Build/Deploy 成功，刷新 Nginx 页面可见新段落。检查 Site playbook 确实包含被更新的分支，否则触发成功也不会收录该分支。

先确定待同步提交只包含目标 CI 配置，避免把 ABB 1.1 的正文和 version 一并带到 1.0：

尖括号处替换为实际提交 SHA；不要原样执行占位符。

原实验出现 modify/delete 冲突：

当前 v1.0 没有文件，但引入提交修改了文件，Git 无法替你决定保留还是删除。目标是给 v1.0 增加 CI，因此检查工作区已有文件并选择保留：

如目标确实是删除该文件，使用 git rm .gitlab-ci.yml 后 continue；如果选错提交或想撤销本次操作，使用 git cherry-pick --abort。普通内容冲突需要手工编辑，删除 <<<<<<<、=======、>>>>>>> 标记后再 add/continue。不要在未解决冲突时继续创建其他提交。

只同步单文件时也可在确认没有未保存修改后，使用 git restore --source=v1.1 — .gitlab-ci.yml，再创建一个明确的新提交；这样不必引入混合提交。

FANUC 的 v1.0 增加同样的触发配置，提交后在其首页增加自动发布验证段落并 push。

验收：ABB v1.0、ABB v1.1、FANUC v1.0 各自更新能触发 Site。发布三个版本依赖 playbook 明确列出三个来源，不是给任何分支 push 都会自动加入站点。

在 WSL 的 Site 仓库：

ci/trigger-site.yml：

Site 自己的根 .gitlab-ci.yml 仍是 Build/Deploy 配置，不引用这个触发模板，避免触发自身形成循环。

将 ABB 的 v1.0、v1.1 和 FANUC v1.0 中 .gitlab-ci.yml 改为：

逐个分支提交 push。各内容仓库无需再复制 trigger 的完整逻辑。

include:project 在创建 Pipeline 时从指定项目读取 YAML，用户必须能访问私有模板项目。ref: main 会使用当时 main 的模板；模板修改不会主动重跑所有内容 Pipeline，下一次内容更新才使用新模板。长期稳定使用可固定模板 Tag 或 SHA，升级时有计划地更新引用。

本模板声明 stages: [trigger] 适用于原实验的纯文档内容仓库；若以后加入其他 build/test job，需统一规划 stages，不能忽略 include 合并后阶段覆盖的问题。可在 GitLab CI Editor 的 Validate / 合并配置视图检查实际展开结果。

验收：三个版本分支都使用 include，内容修改仍能触发 Site Build/Deploy；Site Pipeline 不反向触发内容仓库。共享模板成功是原对话已经完成的实验终点。

不必先完成 home 组件，可把本包放到 已被 playbook 读取的 ABB v1.1 中：

包内 README 和 examples 是接入说明及配置参考，不要求复制到页面目录。不要为了导入本文覆盖自己的 .gitlab-ci.yml、playbook 或 antora.yml。

curl: (35) Connection reset by peer 后又出现 chmod: cannot access docker.asc，先处理密钥下载失败；后面的文件不存在是连锁错误。不要继续配置一个引用不存在密钥的 APT 源。切换 Ubuntu 仓库安装路线前检查 /etc/apt/sources.list.d/，禁用自己刚添加且无效的 Docker 源，不要误删系统 Ubuntu 源。

Docker Hub 拉取失败：先检查 DNS、HTTPS，再检查 daemon 日志。ping 成功不代表 HTTPS Registry 可达。shell 的代理环境变量也不自动等于 Docker daemon 已使用代理；必要时按 Docker 服务的代理配置方式设置并验证。

GitLab Registry 拉取失败：观察是否是 helper image；Docker Hub 镜像代理可用不代表 GitLab Registry 可达。使用匹配 Runner 版本和架构的 helper 镜像，确认本地镜像名与配置完全一致。

403 或 Token 验证失败：确认使用新 authentication token、Runner 未删除、地址指向正确实例。不要重复创建多个 Runner 掩盖问题。

Pending：检查 Runner Online、是否分配给项目、是否暂停、Job tags 是否都匹配、是否允许 untagged，以及 Protected Runner 是否允许当前分支。antora docker 单标签与 antora,docker 两标签不同。

Job 已运行但长期卡在 Preparing：查看 helper 或业务镜像拉取日志；这不是 Pending。Runner 的 verify 仅证明认证通信，不证明整个 Docker executor 能完成 Job。

HTTP Basic: Access denied：检查 Deploy Token 用户名、过期状态、read_repository、Group 范围和 URL。CI 中变量为空：检查变量拼写、Environment scope、Protected 与分支保护条件。避免打开 set -x 或打印 GIT_CREDENTIALS。

downstream pipeline cannot be created：确认 project 路径、main 存在，触发用户有权限，目标分支保护允许，且 Site 的 workflow/rules 没有排除 CI_PIPELINE_SOURCE == "pipeline"。跨项目 include 失败还要核对模板 file/ref 和读取权限。API Job Token allowlist 与用户权限是不同机制；本实验的原生 trigger 不需要先添加一个 curl API Token。

网站内容未更新：确认内容 commit 已 push 到 playbook 列出的分支；Site Job 使用 --fetch；检查 Site Pipeline 是否真的 deploy；最后才处理浏览器缓存。不要只看上游绿色就推断最终 HTML 一定包含目标内容。

site.content.sources not declared：content 错误缩进到了 site 下；它应是顶层键。ui.bundle.url must be String：检查 bundle/url 的层级和 URL 是否变成映射。

重复组件版本：检查每个分支 antora.yml 的 name/version 组合。分支名带 v 不代表输出 URL 一定带 v。原 /abb/v1.0/ 残留属于旧输出时，用 --clean；若部署时仅追加复制未删除旧文件，发布目录也可能残留。

No files to upload：检查 output.dir 是否为 build/site、Job 工作目录、Antora 是否成功，artifacts.paths 必须相对项目工作目录。不要把 output 改为 public 后还继续上传 build/site。

部署 Job 找不到 build/site：检查 needs 的 job 名和 artifacts: true，确认产物未过期。不同 Job 的临时目录独立存在，cache 不替代 Artifact 交付。

仓库首页没有 build/site 是预期行为，去 build-docs Job 的 Job artifacts 查看。Artifact 被删除不等于 Nginx 中已部署文件也自动删除；两者是不同存储。

在 Ubuntu Server：

ERR_CONNECTION_REFUSED：检查容器与端口映射是否存在，网址是否指向正确机器；Windows localhost、WSL localhost 与 VM IP 不应混淆。如果 VM 本机可访问而 Windows 不可访问，检查 VMware 网络、地址变化与防火墙。若有 UFW，按可信局域网范围开放 8080/8181/2222，并保留管理 SSH 的规则。

403：检查网页入口文件、目录遍历权限与文件读取权限；不要仅确认目录存在。404：检查请求版本路径、实际 HTML 文件、部署是否成功。临时 Python 服务显示目录列表时，通常是提供服务的根目录错误。

Deploy Passed 但网站仍旧：先确认 Job 挂载和 Nginx 挂载指向同一个主机路径，检查服务器上文件时间与内容；最后使用强制刷新排除客户端缓存。写入失败时应核对 UID/GID、挂载的 rw/ro 和磁盘空间。

根分区不足会导致镜像解压、GitLab 数据写入、Artifact 上传与部署失败。先判断数据类型和保留策略，再清理；不要执行带 volumes 的全局 prune 删除持久化数据。LVM 有空闲空间并不代表根文件系统已经扩容，扩容前核对实际逻辑卷名并备份。

服务器重启后检查三个容器是否恢复、IP 是否变化。若 IP 变化，external_url、Runner URL、playbook、凭据匹配地址和 environment URL 都需要一致调整。