ubuntu gitlab文档编写与维护

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，确保对外口径一致。

三 文档内容模板与示例

• 建议统一使用以下模板字段，便于快速定位与复用：

  • 元数据：适用版本（如 Ubuntu 22.04/24.04、GitLab 16.x/17.x）、角色（管理员/开发者）、阅读前置条件
  • 目标与范围：本文档解决什么问题、不适用场景
  • 前置检查：依赖、权限、端口、磁盘空间
  • 操作步骤：分步骤编号，命令用代码块，关键步骤加注意/警告
  • 验证与回滚：如何确认成功、失败如何回滚
  • 常见问题：FAQ 与排错指引
  • 参考与变更记录：链接、版本变更说明

• 示例片段（备份与恢复）

  • 备份
    • 命令：sudo gitlab-backup create（旧版可用：gitlab-rake gitlab:backup:create）
    • 默认目录：/var/opt/gitlab/backups/，文件名示例：1710123456_2025_03_10_16.8.0_gitlab_backup.tar
    • 注意：备份不包含配置文件与密钥，需另行备份：/etc/gitlab/gitlab.rb、/etc/gitlab/gitlab-secrets.json
  • 恢复
    • 版本要求：恢复环境 GitLab 版本需与备份一致（从备份文件名读取，如 16.8.0）
    • 步骤：安装相同版本 → 放置备份到 /var/opt/gitlab/backups/ → 执行恢复（gitlab-backup restore BACKUP=时间戳） → 重启（gitlab-ctl reconfigure && gitlab-ctl restart）
  • 验证
    • 查看服务状态：gitlab-ctl status
    • 检查环境信息：gitlab-rake gitlab:env:info
    • 登录 Web 界面核对项目、用户、Runner 等是否完整

• Markdown 写作要点（Wiki 与仓库文档均适用）

  • 标题层级、列表、代码块、链接、图片、强调与转义语法要规范；支持 GFM（如 ```go 高亮）
  • 相对路径示例：链接到上级目录页面可用 wiki链接；图片语法
  • 提及与任务清单：使用 @用户名 通知；待办用 - [ ] / - [x] 管理

四 日常维护与变更记录

• 例行巡检与信息记录
  • 服务状态：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 用户后设置新密码并保存
  • 迁移恢复失败提示版本不一致：确认备份文件名的版本号，安装相同版本后再恢复