ljwx-harbor/gitea/README.md

Gitea 维护模块

概述

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

功能特性

• ✅ 一键部署: Docker Compose 快速部署 Gitea 服务
• ✅ 自动备份: 可配置调度器 + 防重入防重复触发
• ✅ 安全恢复: 支持一键恢复和安全回滚
• ✅ 健康监控: 实时监控服务状态和数据完整性
• ✅ 自动自愈: watchdog 探活失败后自动重启 Gitea
• ✅ 环境配置: 灵活的环境变量配置管理
• ✅ macOS 集成: 原生支持 macOS 系统特性

目录结构

gitea/
├── docker-compose.yml          # Docker 服务配置
├── gitea-data-protection.sh    # 主管理脚本
├── gitea-backup.sh            # 快速备份脚本
├── gitea-restore.sh           # 快速恢复脚本
├── gitea-auto-backup.sh       # 定时任务备份脚本
├── fix-backup-issues.sh       # 备份问题诊断工具 (NEW)
├── fix-backup-volume.sh       # Volume 配置修复工具 (NEW)
├── .env.example               # 环境变量模板
└── README.md                  # 本文档

快速开始

1. 环境准备

确保系统已安装：

• Docker Desktop for Mac
• Git

2. 初始化设置

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

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

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

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

3. 启动服务

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

# 检查服务状态
./gitea-data-protection.sh health

4. 访问 Gitea

• Web 界面: http://192.168.1.83:33000
• SSH: [email protected].1.83:32222

使用说明

服务管理

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

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

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

# 手动执行一次 watchdog 自愈检查
./gitea-data-protection.sh watchdog

备份操作

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

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

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

恢复操作

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

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

高级操作

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

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

配置说明

环境变量 (.env)

变量名	默认值	说明
GITEA_DOMAIN	192.168.1.83	Gitea 服务器域名
GITEA_SSH_DOMAIN	192.168.1.83	SSH 服务器域名
GITEA_BACKUP_DIR	~/ops/backups/gitea	备份存储目录
GITEA_BACKUP_RETENTION_DAYS	30	备份保留天数
GITEA_BACKUP_INTERVAL_HOURS	6	自动备份间隔（小时）
GITEA_BACKUP_MIN_GAP_SECONDS	21600	自动备份最小间隔秒数（防重复触发）
GITEA_BACKUP_STOP_SERVICE	false	备份时是否停机（默认不停机）
GITEA_ENABLE_CRON_BACKUP	false	是否启用 cron 备份任务
GITEA_ENABLE_LAUNCHD_BACKUP	true	是否启用 launchd 备份任务
GITEA_ENABLE_WATCHDOG	true	是否启用 watchdog 自动自愈
GITEA_WATCHDOG_INTERVAL_SECONDS	60	watchdog 探活周期（秒）
GITEA_WATCHDOG_CONSECUTIVE_FAILURES	3	连续失败阈值，达到后自动重启

Docker 配置

• 镜像: docker.m.daocloud.io/gitea/gitea:1.21
• 端口: 33000 (HTTP), 32222 (SSH)
• 数据库: SQLite3
• 数据卷: gitea-data（部分 Compose 项目名场景会显示为 gitea_gitea-data）

备份机制

自动备份

系统支持两种调度器（推荐只启用一种，避免重复触发）：

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

默认每 6 小时自动备份一次，保留 30 天的备份文件。
默认开启在线备份（GITEA_BACKUP_STOP_SERVICE=false），不会因备份主动停掉 Gitea。

备份内容

• Gitea 数据库 (SQLite)
• Git 仓库数据
• 用户配置和设置
• LFS 数据 (如果启用)

备份位置

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

恢复机制

安全恢复流程

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

恢回滚

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

./gitea-restore.sh safety-backup-20251019-130000.tar.gz

监控和日志

健康检查内容

• Docker 环境状态
• Gitea 服务运行状态
• HTTP 端口探活 (127.0.0.1:33000)
• 数据卷完整性
• 仓库数量统计
• 备份状态检查
• 定时任务状态（backup + watchdog）

日志文件位置

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

查看日志

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

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

故障排除

🚨 备份问题诊断（重要）

如果发现备份大小异常（所有备份大小相同或过小），可能是 Docker Volume 配置错误：

# 运行备份诊断工具
./fix-backup-issues.sh

# 选项 4: 查看备份时间分布和大小统计
# 如果发现问题，使用 Volume 修复工具
./fix-backup-volume.sh

典型症状：

• ❌ 所有备份大小都是 1.5GB（不随业务增长）
• ❌ 备份不包含 Git 仓库代码
• ❌ 恢复后代码丢失

原因：备份脚本使用了错误的 Docker Volume 名称

解决方案：

1. 运行 ./fix-backup-volume.sh 选择选项 1（修复脚本）
2. 运行选项 2（执行完整备份验证）
3. 运行选项 3（清理错误的历史备份）

常见问题

1. Docker 服务未启动

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

2. 端口冲突

   # 检查端口占用
   lsof -i :33000
   lsof -i :32222
   

3. 权限问题

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

4. 定时任务未执行

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

5. 服务会周期性不可用（常见于备份窗口）

   # 确认当前是在线备份模式（推荐）
   grep GITEA_BACKUP_STOP_SERVICE .env
   
   # 检查是否同时启用了 cron + launchd
   grep -E "GITEA_ENABLE_(CRON|LAUNCHD)_BACKUP" .env
   

6. 定时任务重复执行

   # 诊断重复任务
   ./fix-backup-issues.sh
   # 选择选项 1 清理重复的 crontab 任务
   

7. 备份文件过多占用磁盘空间

   # 查看备份统计
   du -sh ~/ops/backups/gitea/
   ls ~/ops/backups/gitea/*.tar.gz | wc -l
   
   # 清理旧备份（保留最近 7 天）
   ./fix-backup-issues.sh
   # 选择选项 3
   

手动恢复定时任务

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

# 按 .env 重新生成调度任务
./gitea-data-protection.sh setup

性能优化

备份优化

• 调整备份频率：修改 GITEA_BACKUP_INTERVAL_HOURS
• 调整保留策略：修改 GITEA_BACKUP_RETENTION_DAYS
• 使用外部存储：修改 GITEA_BACKUP_DIR 到外部磁盘

服务优化

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

安全建议

1. 定期备份: 确保自动备份正常运行
2. 异地备份: 将重要备份同步到云存储
3. 访问控制: 配置防火墙规则限制访问
4. 定期更新: 定期更新 Gitea 版本
5. 监控告警: 配置服务状态监控

最佳实践

备份验证

定期验证备份的完整性和大小：

# 1. 检查最新备份大小
ls -lh ~/ops/backups/gitea/*.tar.gz | tail -5

# 2. 验证备份内容
tar -tzf ~/ops/backups/gitea/[最新备份].tar.gz | grep -E "git/repositories|gitea.db"

# 3. 运行健康检查
./gitea-data-protection.sh health

正常备份大小参考：

• 基础安装（无仓库）：~500 MB
• 包含小型仓库：1-5 GB
• 包含大型仓库：5+ GB
• ⚠️ 如果所有备份大小完全相同，请立即运行诊断工具

定时任务维护

避免重复的定时任务导致资源浪费：

# 定期检查定时任务
crontab -l | grep gitea
launchctl list | grep gitea

# 推荐配置：
# - 仅启用 1 个备份调度器（cron 或 launchd）
# - 启用 1 个 launchd watchdog 任务

磁盘空间管理

根据实际需求调整备份保留策略：

# 编辑 .env 文件
nano .env

# 调整保留天数（默认 30 天）
GITEA_BACKUP_RETENTION_DAYS=14  # 改为 14 天

# 手动清理旧备份
find ~/ops/backups/gitea -name "*.tar.gz" -mtime +14 -delete

Volume 配置检查

确保使用正确的 Docker Volume：

# 1. 检查当前运行的容器使用的 volume
docker inspect $(docker ps -q -f name=gitea) | grep -A5 "Mounts"

# 2. 检查备份脚本配置
grep -E "gitea-data|gitea_gitea-data" /Users/brunogao/ops/gitea/gitea-data-protection.sh

# 3. 如果不匹配，运行修复工具
./fix-backup-volume.sh

升级指南

Gitea 版本升级

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

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

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

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

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

诊断工具

备份问题诊断

fix-backup-issues.sh - 诊断和修复常见备份问题：

./fix-backup-issues.sh

# 功能选项：
# 1. 清理重复的 Crontab 任务
# 2. 清理旧备份（保留最近 14 天）
# 3. 清理旧备份（保留最近 7 天）
# 4. 查看备份时间分布统计

使用场景：

• 发现多个重复的定时任务
• 备份文件过多占用磁盘空间
• 需要了解备份频率和分布

Volume 配置修复

fix-backup-volume.sh - 修复 Docker Volume 配置问题：

./fix-backup-volume.sh

# 功能选项：
# 1. 修复备份脚本 volume 配置
# 2. 执行完整备份并验证
# 3. 清理错误的历史备份
# 4. 查看详细 volume 对比

使用场景：

• 备份大小异常（所有备份大小相同）
• 备份不包含 Git 仓库数据
• 升级或迁移后需要验证配置

扩展集成

与 CI/CD 集成

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

与监控系统集成

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

变更日志

2024-12-30 - 重大更新

新增功能：

• ✨ 添加备份问题诊断工具 fix-backup-issues.sh
• ✨ 添加 Volume 配置修复工具 fix-backup-volume.sh
• 🔧 修复备份脚本 Docker Volume 配置问题
• 📝 完善故障排除和最佳实践文档

重要修复：

• 🐛 修复备份使用错误 Volume 导致数据不完整的问题
• 🐛 修复重复定时任务导致备份过于频繁的问题
• 💾 优化磁盘空间使用（通过清理错误备份释放 300+ GB）

配置变更：

• ⚠️ Docker Volume 名称从 gitea-data 更新为 gitea_gitea-data
• ⚠️ 如果从旧版本升级，请运行 ./fix-backup-volume.sh 进行修复

常见问题 FAQ

Q: 为什么我的所有备份大小都是 1.5GB？

A: 这表明备份脚本使用了错误的 Docker Volume。运行 ./fix-backup-volume.sh 进行修复。

Q: 如何验证备份是否包含完整数据？

A: 运行以下命令：

# 查看备份内容
tar -tzf ~/ops/backups/gitea/[备份文件].tar.gz | grep "git/repositories"

# 检查备份大小（应该随仓库增长而增大）
ls -lh ~/ops/backups/gitea/*.tar.gz

Q: 磁盘空间不足怎么办？

A: 运行 ./fix-backup-issues.sh 选择选项 2 或 3 清理旧备份，或调整 .env 中的 GITEA_BACKUP_RETENTION_DAYS。

Q: 如何检查是否有重复的定时任务？

A: 运行 ./fix-backup-issues.sh 选择选项 1 查看并清理重复任务。

许可证

MIT License - 可自由使用和修改

支持

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

1. 查看日志文件排查问题
2. 运行诊断工具 fix-backup-issues.sh 和 fix-backup-volume.sh
3. 检查 GitHub Issues
4. 提交新的 Issue 或 Pull Request