# 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. 初始化设置

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

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

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

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

### 3. 启动服务

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

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

### 4. 访问 GitLab

- **Web 界面**: http://192.168.1.83:8890
- **SSH**: git@192.168.1.83:8929

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

## 使用说明

### 服务管理

```bash
# 启动服务
./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
```

### 备份操作

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

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

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

### 恢复操作

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

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

### 高级操作

```bash
# 完整功能菜单
./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. **备份现有数据**
   ```bash
   # 停止现有服务
   cd ~/gitlab && docker-compose down

   # 备份数据目录
   tar -czf gitlab-backup-$(date +%Y%m%d-%H%M%S).tar.gz data/ config/
   ```

2. **使用新模块**
   ```bash
   # 部署新模块
   ./init-ops.sh

   # 恢复数据
   ./gitlab-restore.sh gitlab-backup-*.tar.gz
   ```

3. **验证迁移结果**
   ```bash
   # 检查服务状态
   ./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. **完整性检查**: 验证数据完整性

### 恢回滚

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

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

## 监控和日志

### 健康检查内容

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

### 日志文件位置

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

### 查看日志

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

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

## 故障排除

### 常见问题

1. **Docker 服务未启动**
   ```bash
   # 启动 Docker Desktop
   open /Applications/Docker.app
   ```

2. **端口冲突**
   ```bash
   # 检查端口占用
   lsof -i :8890
   lsof -i :8929
   ```

3. **权限问题**
   ```bash
   # 设置脚本权限
   chmod +x gitlab-*.sh
   ```

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

5. **定时任务未执行**
   ```bash
   # 检查 launchd 任务
   launchctl list | grep gitlab

   # 检查 cron 任务
   crontab -l | grep gitlab
   ```

### 手动恢复定时任务

```bash
# 重新加载 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 版本升级

```bash
# 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 集成

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

### 与监控系统集成

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

### GitLab Runner 集成

```bash
# 注册 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
```

## 常用命令

### 日常维护

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

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

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

# 清理 Docker 资源
docker system prune -f
```

### 用户管理

```bash
# 进入 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