macos-tools/gitlab/README.md

GitLab 维护模块

概述

这是 macOS 工具集中的 GitLab 维护模块，提供完整的 GitLab 代码托管平台管理解决方案，包括服务部署、自动备份、健康监控和一键恢复功能。

功能特性

• ✅ 一键部署: Docker Compose 快速部署 GitLab 服务
• ✅ 自动备份: 双重定时任务保障 (cron + launchd)
• ✅ 安全恢复: 支持一键恢复和安全回滚
• ✅ 健康监控: 实时监控服务状态和数据完整性
• ✅ 数据迁移: 支持从现有 GitLab 无损迁移
• ✅ macOS 集成: 原生支持 macOS 系统特性

目录结构

gitlab/
├── docker-compose.yml               # Docker 服务配置
├── gitlab-data-protection.sh        # 主管理脚本
├── gitlab-backup.sh                # 快速备份脚本
├── gitlab-restore.sh               # 快速恢复脚本
├── .env.example                    # 环境变量模板
├── config/                         # GitLab 配置目录
└── README.md                      # 本文档

快速开始

1. 环境准备

确保系统已安装：

• Docker Desktop for Mac
• Git (用于版本控制)

2. 初始化设置

# 进入项目目录
cd /path/to/macos/gitlab

# 复制环境配置文件
cp .env.example .env

# 根据需要修改配置（可选）
nano .env

# 初始化设置（自动配置定时任务等）
./gitlab-data-protection.sh setup

3. 启动服务

# 启动 GitLab 服务
./gitlab-data-protection.sh start

# 等待服务启动（可能需要几分钟）
./gitlab-data-protection.sh health

4. 访问 GitLab

• Web 界面: http://192.168.1.83:8890
• SSH: [email protected].1.83:8929

首次访问设置:

1. 打开 http://192.168.1.83:8890
2. 设置 root 密码（建议使用强密码）
3. 创建管理员账户
4. 配置基本设置

使用说明

服务管理

# 启动服务
./gitlab-data-protection.sh start

# 停止服务
./gitlab-data-protection.sh stop

# 重启服务
./gitlab-data-protection.sh restart

# 健康检查
./gitlab-data-protection.sh health

# 查看统计信息
./gitlab-data-protection.sh stats

备份操作

# 手动备份（自动命名）
./gitlab-backup.sh

# 手动备份（指定名称）
./gitlab-backup.sh my-backup-20231019

# 查看备份文件
ls -la ~/ops/backups/gitlab/

恢复操作

# 查看可用备份
./gitlab-restore.sh

# 从指定备份恢复
./gitlab-restore.sh gitlab-20231019-120000.tar.gz

高级操作

# 完整功能菜单
./gitlab-data-protection.sh help

# 重新初始化设置
./gitlab-data-protection.sh setup

# 查看统计信息
./gitlab-data-protection.sh stats

配置说明

环境变量 (.env)

变量名	默认值	说明
GITLAB_DOMAIN	192.168.1.83	GitLab 服务器域名
GITLAB_HTTP_PORT	8890	HTTP Web UI 端口
GITLAB_SSH_PORT	8929	SSH 端口
GITLAB_DATA_DIR	~/ops/data/gitlab	GitLab 数据目录
GITLAB_CONFIG_DIR	~/ops/gitlab/config	GitLab 配置目录
GITLAB_BACKUP_DIR	~/ops/backups/gitlab	备份存储目录
GITLAB_BACKUP_RETENTION_DAYS	30	备份保留天数
GITLAB_BACKUP_INTERVAL_HOURS	6	自动备份间隔（小时）
GITLAB_ROOT_PASSWORD	admin123	root 用户初始密码

Docker Compose 配置

主要配置项：

• GitLab CE 版本：16.9.1
• 内存限制：1GB shm_size
• 健康检查：内置 healthcheck
• 环境变量：通过 GITLAB_OMNIBUS_CONFIG 配置

迁移说明

从现有 GitLab 迁移

如果已经有运行的 GitLab 实例，可以按照以下步骤无损迁移：

1. 备份现有数据

   # 停止现有服务
   cd ~/gitlab && docker-compose down
   
   # 备份数据目录
   tar -czf gitlab-backup-$(date +%Y%m%d-%H%M%S).tar.gz data/ config/
   

2. 使用新模块

   # 部署新模块
   ./init-ops.sh
   
   # 恢复数据
   ./gitlab-restore.sh gitlab-backup-*.tar.gz
   

3. 验证迁移结果

   # 检查服务状态
   ./gitlab-data-protection.sh health
   
   # 验证仓库数量
   ./gitlab-data-protection.sh stats
   

备份机制

自动备份

系统提供双重保障的自动备份：

1. Cron 任务: 传统 Unix 定时任务
2. Launchd 任务: macOS 原生定时任务

默认每 6 小时自动备份一次，保留 30 天的备份文件。

备份内容

• GitLab 配置目录
• GitLab 数据目录（repositories、builds、uploads 等）
• PostgreSQL 数据库
• Docker Compose 配置文件

备份位置

~/ops/backups/gitlab/
├── gitlab-20231019-120000.tar.gz    # 备份文件
├── gitlab-20231019-120000.tar.gz.meta # 备份元数据
└── safety-backup-*.tar.gz          # 恢复时的安全备份

恢复机制

安全恢复流程

1. 停止服务: 安全停止所有 GitLab 服务
2. 安全备份: 自动创建当前状态的安全备份
3. 数据恢复: 从指定备份恢复数据
4. 服务启动: 重启服务并验证状态
5. 完整性检查: 验证数据完整性

恢回滚

如果恢复出现问题，可以使用安全备份回滚：

./gitlab-restore.sh safety-backup-20231019-130000.tar.gz

监控和日志

健康检查内容

• Docker 环境状态
• GitLab 服务运行状态
• 数据卷完整性
• 仓库数量统计
• 备份状态检查
• 定时任务状态

日志文件位置

~/ops/logs/
├── gitlab-protection.log           # 主脚本日志
├── gitlab-backup_stdout.log        # 备份输出日志
└── gitlab-backup_stderr.log        # 备份错误日志

查看日志

# 查看主日志
tail -f ~/ops/logs/gitlab-protection.log

# 查看定时任务日志
tail -f ~/ops/logs/gitlab-backup_*.log

故障排除

常见问题

1. Docker 服务未启动

   # 启动 Docker Desktop
   open /Applications/Docker.app
   

2. 端口冲突

   # 检查端口占用
   lsof -i :8890
   lsof -i :8929
   

3. 权限问题

   # 设置脚本权限
   chmod +x gitlab-*.sh
   

4. 服务启动缓慢

   # GitLab 首次启动需要较长时间（5-15分钟）
   # 检查服务日志
   docker logs gitlab-ce
   

5. 定时任务未执行

   # 检查 launchd 任务
   launchctl list | grep gitlab
   
   # 检查 cron 任务
   crontab -l | grep gitlab
   

手动恢复定时任务

# 重新加载 launchd 任务
launchctl unload ~/Library/LaunchAgents/com.ljwx.gitlab.backup.plist 2>/dev/null || true
launchctl load -w ~/Library/LaunchAgents/com.ljwx.gitlab.backup.plist

# 重新设置 cron 任务
./gitlab-data-protection.sh setup

性能优化

备份优化

• 调整备份频率：修改 GITLAB_BACKUP_INTERVAL_HOURS
• 调整保留策略：修改 GITLAB_BACKUP_RETENTION_DAYS
• 使用外部存储：修改 GITLAB_BACKUP_DIR 到外部磁盘

服务优化

• 调整 Docker 资源限制
• 使用外部数据库（PostgreSQL）
• 配置 CDN 或反向代理

安全建议

1. 定期备份: 确保自动备份正常运行
2. 异地备份: 将重要备份同步到云存储
3. 访问控制: 配置防火墙规则限制访问
4. 定期更新: 定期更新 GitLab 版本
5. 监控告警: 配置服务状态监控
6. 强密码: 为 root 用户设置强密码
7. SSL 配置: 生产环境建议使用 HTTPS

升级指南

GitLab 版本升级

# 1. 备份当前数据
./gitlab-backup.sh pre-upgrade-$(date +%Y%m%d)

# 2. 停止服务
./gitlab-data-protection.sh stop

# 3. 更新镜像版本
# 编辑 docker-compose.yml，修改 image 标签

# 4. 启动服务
./gitlab-data-protection.sh start

# 5. 验证升级
./gitlab-data-protection.sh health

扩展集成

与 CI/CD 集成

# CI 脚本示例
./gitlab-backup.sh ci-pre-build-$(BUILD_NUMBER)
# 执行构建任务
./gitlab-restore.sh ci-pre-build-$(BUILD_NUMBER).tar.gz

与监控系统集成

# 健康检查 API 调用
./gitlab-data-protection.sh health
echo $?

GitLab Runner 集成

# 注册 GitLab Runner
docker run -d --name gitlab-runner --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/ops/gitlab/gitlab-runner-config:/etc/gitlab-runner \
  gitlab/gitlab-runner:latest

# 配置 Runner
docker exec -it gitlab-runner gitlab-runner register \
  --url http://192.168.1.83:8890 \
  --registration-token <YOUR_TOKEN> \
  --executor docker \
  --description "Docker Runner" \
  --tag-list "docker,macos" \
  --docker-privileged

常用命令

日常维护

# 检查服务状态
./gitlab-data-protection.sh status

# 查看资源使用
docker stats gitlab-ce

# 查看服务日志
docker logs -f gitlab-ce

# 清理 Docker 资源
docker system prune -f

用户管理

# 进入 GitLab 容器
docker exec -it gitlab-ce /bin/bash

# 重置 root 密码
docker exec -it gitlab-ce gitlab-rake "gitlab:password:reset[root]"

许可证

MIT License - 可自由使用和修改

支持

如有问题或建议，请通过以下方式联系：

1. 查看日志文件排查问题
2. 检查 GitHub Issues
3. 提交新的 Issue 或 Pull Request