Ubuntu 上 GitLab 文档编写与维护实操指南
一 文档体系与存放位置
- 采用“单一事实来源 SSoT”原则：将运维、部署、升级、备份恢复、故障排查等文档集中维护，避免信息分散。文档类型建议覆盖：概念、任务、参考、故障排查，便于检索与复用。
- 推荐目录结构（示例）：
- docs/
- setup/ # 安装与初始化
- upgrade/ # 升级与迁移
- backup-restore/ # 备份与恢复
- maintenance/ # 日常维护与巡检
- troubleshooting/ # 常见问题与排错
- security/ # 安全与合规
- images/ # 架构图、流程图（源文件一并纳入版本控制）
- 写作规范与风格：统一术语、避免口语化；提供必要上下文与风险提示；图片优先使用矢量/可源文件；引用外部资料需注明来源。可参考成熟的文档风格与流程实践，结合团队 A-Z 词表与术语库统一用语。
二 写作与发布流程
- 分支与协作：从官方或组织仓库 Fork，在本地创建特性分支（如：docs/update-backup），完成编辑后提交 Merge Request（MR）。
- MR 规范：标题控制在3–5 个词、首字母大写、句末不加句号；描述中简述变更要点，并关联相关 Issue（如有）。
- 模板与评审：使用 Documentation 模板；按团队流程进行技术评审与语言/风格检查；必要时在 MR 中 @ 相关技术写作者或领域负责人。
- 标签体系：为议题与 MR 添加类型标签（如 ~documentation）、阶段/组标签（如 ~devops::create、~group::source code）以及 ~documentation 专业化标签，便于路由与度量。
- 发布与版本：文档与代码同库管理，随代码变更自动版本化；对对外发布可配套生成静态站点或导出 PDF，确保对外口径一致。
三 文档内容模板与示例
四 日常维护与变更记录
- 例行巡检与信息记录
- 服务状态：gitlab-ctl status
- 环境信息：gitlab-rake gitlab:env:info
- 版本核对：cat /opt/gitlab/embedded/service/gitlab-rails/VERSION
- 日志排查：gitlab-ctl tail（可按组件 tail nginx、puma、sidekiq 等）
- 配置与变更管理
- 所有变更先在测试环境验证；编辑 /etc/gitlab/gitlab.rb 后执行 gitlab-ctl reconfigure 使配置生效；必要时重启相关组件
- 变更记录纳入文档：每次变更写明“变更内容—影响范围—回滚方案—验证结果—操作者/时间”
- 备份策略与演练
- 建议每日全量备份、保留至少 7–30 天；定期在预备环境演练恢复流程，验证备份可用性与完整性
- 迁移场景务必保证版本一致再恢复，避免 “GitLab version mismatch” 错误
五 快速命令与排错清单
- 常用命令
- 启停与重载：gitlab-ctl start|stop|restart|status；gitlab-ctl reconfigure
- 版本与信息：cat /opt/gitlab/embedded/service/gitlab-rails/VERSION；gitlab-rake gitlab:env:info
- 日志与追踪：gitlab-ctl tail [nginx|puma|sidekiq|gitlab-rails]
- 备份与恢复：gitlab-backup create；gitlab-backup restore BACKUP=时间戳
- 高频问题与处理
- 端口冲突（如 80/8080 被占用）：在 /etc/gitlab/gitlab.rb 调整 external_url 与组件端口（如 puma[‘port’]），执行 reconfigure 与 restart
- 访问异常：核对 external_url、防火墙（UFW/安全组）放行 80/443/22，必要时查看 nginx/puma 日志定位
- 忘记管理员密码：进入控制台 gitlab-rails console，定位 root 用户后设置新密码并保存
- 迁移恢复失败提示版本不一致：确认备份文件名的版本号，安装相同版本后再恢复
