1. 为什么选择Docker部署Gitea?
作为一款轻量级的Git服务,Gitea凭借其开箱即用的特性和极低的资源占用,已经成为众多开发团队和个人的首选代码托管方案。而Docker的容器化部署方式,则让Gitea的安装和维护变得更加简单高效。
在实际生产环境中,我遇到过各种Gitea部署方式:从直接二进制安装到Kubernetes集群部署。对比下来,Docker Compose方案在易用性和灵活性之间取得了最佳平衡。它不仅能保持服务的隔离性,还能通过简单的配置文件实现版本升级、数据迁移等复杂操作。特别适合中小型团队或个人开发者快速搭建私有代码仓库。
2. 环境准备与基础配置
2.1 系统要求与依赖安装
在开始之前,请确保你的主机满足以下基本要求:
- Linux系统(推荐Ubuntu 20.04+/CentOS 7+)
- Docker Engine 20.10+
- Docker Compose v2.0+
- 至少2GB可用内存
- 10GB以上磁盘空间
安装Docker和Docker Compose的推荐方式:
bash复制# Ubuntu/Debian系统
sudo apt-get update
sudo apt-get install docker.io docker-compose-plugin
sudo systemctl enable --now docker
# CentOS/RHEL系统
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo systemctl enable --now docker
注意:生产环境建议使用Docker官方源安装指定版本,避免使用发行版自带的旧版本。
2.2 目录结构与权限设置
合理的目录结构能避免后续维护时的混乱。我通常采用以下组织方式:
code复制~/gitea/
├── docker-compose.yml # 主配置文件
├── data/ # 数据卷目录
│ ├── gitea/ # Gitea主数据
│ ├── mysql/ # MySQL数据(如使用)
│ └── postgres/ # PostgreSQL数据(如使用)
└── backups/ # 备份目录
设置目录权限(假设使用1000:1000的用户组):
bash复制mkdir -p ~/gitea/{data,backups}
chown -R 1000:1000 ~/gitea/data
3. Docker Compose配置详解
3.1 基础服务配置
创建docker-compose.yml文件,这是最简配置示例:
yaml复制version: "3.8"
networks:
gitea:
driver: bridge
services:
server:
image: docker.gitea.com/gitea:1.25.3
container_name: gitea
environment:
- USER_UID=1000
- USER_GID=1000
restart: unless-stopped
networks:
- gitea
volumes:
- ./data/gitea:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "222:22"
关键参数说明:
USER_UID/USER_GID:必须与宿主机数据目录所有者一致restart: unless-stopped:确保服务异常退出后自动重启- 时区挂载:保持容器内外时间一致
- 端口映射:
- 3000:Web界面端口
- 222:SSH端口(避免与宿主机22端口冲突)
3.2 数据库配置选项
MySQL配置示例
yaml复制services:
server:
# 保留基础配置
environment:
- GITEA__database__DB_TYPE=mysql
- GITEA__database__HOST=db:3306
- GITEA__database__NAME=gitea
- GITEA__database__USER=gitea
- GITEA__database__PASSWD=gitea
depends_on:
- db
db:
image: mysql:8.0
restart: unless-stopped
environment:
- MYSQL_ROOT_PASSWORD=gitea
- MYSQL_USER=gitea
- MYSQL_PASSWORD=gitea
- MYSQL_DATABASE=gitea
- MYSQL_INITDB_SKIP_TZINFO=1
networks:
- gitea
volumes:
- ./data/mysql:/var/lib/mysql
healthcheck:
test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
interval: 10s
timeout: 5s
retries: 3
PostgreSQL配置示例
yaml复制services:
server:
# 保留基础配置
environment:
- GITEA__database__DB_TYPE=postgres
- GITEA__database__HOST=db:5432
- GITEA__database__NAME=gitea
- GITEA__database__USER=gitea
- GITEA__database__PASSWD=gitea
depends_on:
db:
condition: service_healthy
db:
image: postgres:14
restart: unless-stopped
environment:
- POSTGRES_USER=gitea
- POSTGRES_PASSWORD=gitea
- POSTGRES_DB=gitea
networks:
- gitea
volumes:
- ./data/postgres:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U gitea"]
interval: 10s
timeout: 5s
retries: 3
专业建议:生产环境推荐使用PostgreSQL,它在高并发场景下表现更稳定。小型项目可以用SQLite简化部署。
4. 高级配置与优化
4.1 邮件通知配置
yaml复制environment:
- GITEA__mailer__ENABLED=true
- GITEA__mailer__FROM=git@yourdomain.com
- GITEA__mailer__PROTOCOL=smtps
- GITEA__mailer__HOST=smtp.yourmail.com
- GITEA__mailer__USER=yourmail@yourdomain.com
- GITEA__mailer__PASSWD=yourpassword
4.2 性能优化参数
yaml复制environment:
- GITEA__server__PROVIDER=virtualbox
- GITEA__cache__ENABLED=true
- GITEA__cache__ADAPTER=redis
- GITEA__cache__HOST=redis:6379
- GITEA__session__PROVIDER=redis
- GITEA__session__CONN_STR=redis:6379
- GITEA__queue__TYPE=redis
- GITEA__queue__CONN_STR=redis:6379
对应的Redis服务配置:
yaml复制services:
redis:
image: redis:7
restart: unless-stopped
networks:
- gitea
volumes:
- ./data/redis:/data
command: ["redis-server", "--save", "60", "1", "--loglevel", "notice"]
5. 服务部署与初始化
5.1 启动服务
bash复制docker-compose up -d
验证服务状态:
bash复制docker-compose ps
docker-compose logs -f
5.2 首次访问配置
通过浏览器访问 http://your-server-ip:3000,按照向导完成初始化:
-
数据库设置:
- 如果使用内置数据库,保持默认SQLite3配置
- 如果使用MySQL/PostgreSQL,填写对应容器服务名(如
db)和凭证
-
常规设置:
- 站点标题:你的组织名称
- 仓库根目录:保持默认
/data/git/repositories - LFS根目录:
/data/git/lfs - 管理员账号:建议立即创建
-
服务器配置:
- SSH服务器域名:填写你的公网IP或域名
- SSH端口:222(与docker-compose映射一致)
- Gitea基本URL:
http://your-domain:3000/
6. 日常维护与管理
6.1 数据备份方案
完整的备份应包含:
- 数据库数据
- Gitea主数据目录
- 配置文件
备份脚本示例:
bash复制#!/bin/bash
BACKUP_DIR=~/gitea/backups
DATE=$(date +%Y%m%d%H%M)
# 备份数据库
docker-compose exec db mysqldump -u gitea -pgitea gitea > $BACKUP_DIR/gitea-db-$DATE.sql
# 备份数据目录
tar -czvf $BACKUP_DIR/gitea-data-$DATE.tar.gz -C ~/gitea/data gitea
# 保留最近7天备份
find $BACKUP_DIR -type f -mtime +7 -delete
6.2 版本升级步骤
-
停止服务:
bash复制
docker-compose down -
备份数据:
bash复制cp -r ~/gitea/data ~/gitea/data-backup-$(date +%Y%m%d) -
修改
docker-compose.yml中的镜像版本号 -
拉取新镜像并启动:
bash复制
docker-compose pull docker-compose up -d -
验证升级:
bash复制
docker-compose logs -f
重要提示:大版本升级(如1.15→1.16)前,务必查看官方升级说明,可能需要特殊处理。
7. 常见问题排查
7.1 容器启动失败
典型错误及解决方案:
-
权限问题:
code复制Error: failed to create directory /data/gitea: permission denied解决方案:
bash复制chown -R 1000:1000 ~/gitea/data -
端口冲突:
code复制Bind for 0.0.0.0:3000 failed: port is already allocated解决方案:
- 修改
docker-compose.yml中的端口映射 - 或停止占用端口的服务
- 修改
-
数据库连接失败:
code复制dial tcp: lookup db on 127.0.0.11:53: no such host解决方案:
- 确保数据库服务名称与配置一致
- 添加
depends_on和健康检查
7.2 性能优化技巧
-
启用缓存:
- 配置Redis缓存可显著提升响应速度
- 修改
app.ini:ini复制[cache] ENABLED = true ADAPTER = redis HOST = redis:6379
-
调整工作线程数:
ini复制[server] PROTOCOL = http HTTP_PORT = 3000 DOMAIN = yourdomain.com ROOT_URL = http://yourdomain.com:3000/ LANDING_PAGE = explore START_SSH_SERVER = true SSH_PORT = 22 OFFLINE_MODE = false DISABLE_ROUTER_LOG = false ENABLE_PPROF = false APP_DATA_PATH = /data/gitea -
定期维护:
bash复制# 清理无用数据 docker-compose exec server gitea admin repo --delete-stale-mirrors docker-compose exec server gitea admin user --delete-inactive
8. 安全加固建议
8.1 基础安全配置
-
修改默认端口:
- 将3000端口改为非常用端口(如8080)
- 或者通过Nginx反向代理并启用HTTPS
-
禁用注册功能:
ini复制[service] DISABLE_REGISTRATION = true -
强制HTTPS:
ini复制[server] PROTOCOL = https CERT_FILE = /data/gitea/ssl/cert.pem KEY_FILE = /data/gitea/ssl/key.pem
8.2 防火墙配置
bash复制# 只开放必要端口
sudo ufw allow 22/tcp
sudo ufw allow 3000/tcp
sudo ufw enable
8.3 定期安全更新
- 订阅Gitea安全公告
- 建立定期更新机制
- 关键操作审计日志:
ini复制[log] LEVEL = Info ROOT_PATH = /data/gitea/log ROUTER = console ENABLE_ACCESS_LOG = true ACCESS = file ACCESS_LOG_TEMPLATE = {{.Ctx.RemoteHost}} - {{.Identity}} {{.Start.Format "[02/Jan/2006:15:04:05 -0700]" }} "{{.Ctx.Req.Method}} {{.Ctx.Req.RequestURI}} {{.Ctx.Req.Proto}}" {{.ResponseWriter.Status}} {{.ResponseWriter.Size}} "{{.Ctx.Req.Referer}}" "{{.Ctx.Req.UserAgent}}"
9. 生产环境部署建议
经过多个项目的实践验证,以下配置组合在中小型团队(5-50人)中表现最佳:
-
硬件配置:
- 4核CPU
- 8GB内存
- 100GB SSD存储
- 单独的数据盘挂载到
/data
-
软件栈:
- Gitea + PostgreSQL + Redis
- Nginx反向代理 + Let's Encrypt证书
- 每日增量备份 + 每周全量备份
-
监控方案:
yaml复制services: prometheus: image: prom/prometheus ports: - "9090:9090" volumes: - ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml networks: - gitea grafana: image: grafana/grafana ports: - "3001:3000" volumes: - ./monitoring/grafana:/var/lib/grafana networks: - gitea -
高可用方案:
- 使用云数据库服务替代容器内数据库
- 配置共享存储(如NFS)实现多节点部署
- 设置负载均衡和故障转移
10. 从其他系统迁移到Gitea
10.1 从GitLab迁移
-
使用gitea-gitlab-migrator工具:
bash复制docker run --rm -it -v ~/gitea/data:/data gitea/migrator:v0.1.0 gitlab \ --gitlab-url https://gitlab.example.com \ --gitlab-token your_access_token \ --gitea-url http://gitea:3000 \ --gitea-token your_gitea_token -
手动迁移步骤:
- 在GitLab导出项目
- 在Gitea创建同名仓库
- 添加GitLab为远程源并推送:
bash复制
git remote add gitlab git@gitlab.com:user/repo.git git push --mirror git@your-gitea.com:user/repo.git
10.2 从GitHub迁移
-
使用GitHub Importer:
- 在Gitea创建新仓库
- 选择"迁移外部仓库"
- 填写GitHub仓库URL和认证信息
-
API方式批量迁移:
bash复制# 获取GitHub仓库列表 curl -H "Authorization: token YOUR_GITHUB_TOKEN" https://api.github.com/user/repos > repos.json # 使用Gitea API创建仓库 jq -c '.[]' repos.json | while read repo; do name=$(echo "$repo" | jq -r '.name') desc=$(echo "$repo" | jq -r '.description') git clone --mirror git@github.com:user/$name.git cd $name.git curl -X POST "http://gitea:3000/api/v1/user/repos" \ -H "Authorization: token YOUR_GITEA_TOKEN" \ -d '{"name":"'$name'", "description":"'$desc'", "private":true}' git push --mirror git@gitea:user/$name.git cd .. done
11. 集成与扩展
11.1 CI/CD集成
-
Drone CI配置:
yaml复制services: drone-server: image: drone/drone:2 ports: - "3080:80" volumes: - ./drone:/data environment: - DRONE_GITEA_SERVER=http://gitea:3000 - DRONE_GITEA_CLIENT_ID=your_client_id - DRONE_GITEA_CLIENT_SECRET=your_client_secret - DRONE_RPC_SECRET=your_rpc_secret - DRONE_SERVER_HOST=drone.yourdomain.com - DRONE_SERVER_PROTO=http drone-agent: image: drone/agent:2 depends_on: - drone-server volumes: - /var/run/docker.sock:/var/run/docker.sock environment: - DRONE_RPC_SERVER=http://drone-server - DRONE_RPC_SECRET=your_rpc_secret - DRONE_RUNNER_CAPACITY=2 -
Gitea Actions:
在app.ini中启用:ini复制[actions] ENAABLED = true
11.2 插件系统
虽然Gitea本身不支持插件,但可以通过以下方式扩展功能:
-
Web钩子集成:
- 配置Slack/MS Teams通知
- 触发Jenkins构建
- 同步到其他系统
-
自定义模板:
bash复制# 覆盖默认模板 cp custom-template.tmpl ~/gitea/data/gitea/templates/ -
API开发:
Gitea提供完整的REST API,可用于开发定制功能:bash复制curl -X GET "http://gitea:3000/api/v1/repos/search?q=project" \ -H "Authorization: token YOUR_GITEA_TOKEN"
12. 性能监控与调优
12.1 监控指标收集
配置Prometheus监控:
yaml复制# docker-compose.yml
services:
gitea:
environment:
- GITEA__metrics__ENABLED=true
- GITEA__metrics__TOKEN=your_metrics_token
Prometheus配置示例:
yaml复制# prometheus.yml
scrape_configs:
- job_name: 'gitea'
metrics_path: '/metrics'
static_configs:
- targets: ['gitea:3000']
bearer_token: 'your_metrics_token'
12.2 关键性能指标
-
响应时间:
- Web页面加载:<500ms
- API响应:<200ms
- Git操作:<100ms
-
资源使用:
- 内存占用:<2GB(中等负载)
- CPU使用率:<50%(峰值)
- 磁盘IO:<50MB/s
-
数据库性能:
- 查询时间:<100ms(99%)
- 连接数:<50(默认连接池)
12.3 性能瓶颈排查
-
慢查询分析:
sql复制-- PostgreSQL SELECT * FROM pg_stat_statements ORDER BY total_time DESC LIMIT 10; -- MySQL SELECT * FROM performance_schema.events_statements_summary_by_digest ORDER BY SUM_TIMER_WAIT DESC LIMIT 10; -
Gitea Profiling:
bash复制# 启用pprof docker-compose exec server gitea admin regenerate app.ini --enable-pprof # 生成CPU profile curl -o cpu.pprof http://localhost:3000/debug/pprof/profile?seconds=30 # 分析结果 go tool pprof -http=:8080 cpu.pprof
13. 备份与灾难恢复
13.1 完整备份方案
-
数据库备份:
bash复制# MySQL docker-compose exec db mysqldump -u root -p$MYSQL_ROOT_PASSWORD --all-databases | gzip > gitea-db-$(date +%Y%m%d).sql.gz # PostgreSQL docker-compose exec db pg_dumpall -U gitea | gzip > gitea-db-$(date +%Y%m%d).sql.gz -
数据目录备份:
bash复制tar -czvf gitea-data-$(date +%Y%m%d).tar.gz -C ~/gitea/data . -
配置文件备份:
bash复制cp ~/gitea/data/gitea/conf/app.ini ~/gitea/backups/app.ini-$(date +%Y%m%d)
13.2 恢复流程
-
数据库恢复:
bash复制# MySQL gunzip < gitea-db-20230101.sql.gz | docker-compose exec -T db mysql -u root -p$MYSQL_ROOT_PASSWORD # PostgreSQL gunzip < gitea-db-20230101.sql.gz | docker-compose exec -T db psql -U gitea -
数据恢复:
bash复制
tar -xzvf gitea-data-20230101.tar.gz -C ~/gitea/data -
配置恢复:
bash复制cp ~/gitea/backups/app.ini-20230101 ~/gitea/data/gitea/conf/app.ini -
重启服务:
bash复制
docker-compose down && docker-compose up -d
14. 容器化最佳实践
14.1 资源限制
yaml复制services:
server:
deploy:
resources:
limits:
cpus: '2'
memory: 4G
reservations:
cpus: '0.5'
memory: 1G
14.2 健康检查
yaml复制healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3000/healthz"]
interval: 30s
timeout: 10s
retries: 3
14.3 日志管理
yaml复制logging:
driver: "json-file"
options:
max-size: "10m"
max-file: "3"
15. 替代方案对比
15.1 与其他Git服务对比
| 特性 | Gitea | GitLab CE | Gogs | Bitbucket |
|---|---|---|---|---|
| 资源占用 | 低 | 高 | 极低 | 中等 |
| 功能完整性 | 中高 | 高 | 中 | 高 |
| 扩展性 | 中 | 高 | 低 | 高 |
| 社区支持 | 活跃 | 非常活跃 | 一般 | 商业支持 |
| Docker支持 | 优秀 | 优秀 | 良好 | 官方镜像 |
15.2 不同部署方式对比
| 方式 | 复杂度 | 维护成本 | 适合场景 |
|---|---|---|---|
| 直接二进制 | 低 | 中 | 简单测试 |
| Docker | 中 | 低 | 生产环境 |
| Kubernetes | 高 | 高 | 大规模集群 |
16. 实际案例分享
16.1 中小团队协作平台
背景:
- 15人开发团队
- 30+活跃仓库
- 每日50+次推送
配置:
- 4核CPU/8GB内存云主机
- Gitea + PostgreSQL
- Drone CI集成
- 每周自动备份
成效:
- 响应时间<200ms
- 零宕机记录
- 资源使用率<30%
16.2 个人开发者知识管理
需求:
- 私有代码仓库
- 文档Wiki功能
- 跨设备同步
方案:
- 树莓派4B部署
- Gitea + SQLite
- 动态DNS + Let's Encrypt
- 每日增量备份到NAS
优势:
- 极低功耗
- 完全自主控制
- 成本近乎为零
17. 未来升级路径
随着项目规模扩大,可以考虑以下演进路线:
-
集群化部署:
- 使用Kubernetes编排
- 实现多副本高可用
- 共享存储解决方案
-
企业级功能:
- 对接LDAP/AD认证
- 审计日志集成
- 细粒度权限控制
-
DevOps扩展:
- 完整CI/CD流水线
- 制品仓库集成
- 自动化测试平台
18. 终极配置建议
经过多个生产环境验证,以下配置组合在性能和稳定性方面表现最佳:
yaml复制version: "3.8"
networks:
gitea:
driver: bridge
services:
server:
image: docker.gitea.com/gitea:1.25.3
container_name: gitea
environment:
- USER_UID=1000
- USER_GID=1000
- GITEA__database__DB_TYPE=postgres
- GITEA__database__HOST=db:5432
- GITEA__database__NAME=gitea
- GITEA__database__USER=gitea
- GITEA__database__PASSWD=gitea
- GITEA__cache__ENABLED=true
- GITEA__cache__ADAPTER=redis
- GITEA__cache__HOST=redis:6379
- GITEA__session__PROVIDER=redis
- GITEA__session__CONN_STR=redis:6379
- GITEA__queue__TYPE=redis
- GITEA__queue__CONN_STR=redis:6379
restart: unless-stopped
networks:
- gitea
volumes:
- ./data/gitea:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "222:22"
depends_on:
db:
condition: service_healthy
redis:
condition: service_healthy
db:
image: postgres:14
restart: unless-stopped
environment:
- POSTGRES_USER=gitea
- POSTGRES_PASSWORD=gitea
- POSTGRES_DB=gitea
networks:
- gitea
volumes:
- ./data/postgres:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U gitea"]
interval: 10s
timeout: 5s
retries: 3
redis:
image: redis:7
restart: unless-stopped
networks:
- gitea
volumes:
- ./data/redis:/data
command: ["redis-server", "--save", "60", "1", "--loglevel", "notice"]
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 10s
timeout: 5s
retries: 3
这套配置实现了:
- 数据库与缓存分离
- 健康状态监控
- 自动故障恢复
- 数据持久化保障
- 资源高效利用
19. 个人经验总结
在多个Gitea部署项目中,我积累了一些特别实用的经验:
-
版本选择:
- 生产环境避免使用
:latest标签 - 选择
.x.x的稳定版本(如1.25.3) - 升级前务必测试小版本更新
- 生产环境避免使用
-
数据管理:
- 使用命名卷更易维护
- 定期执行
gitea admin regenerate重建索引 - 设置
cron任务自动清理临时文件
-
性能调优:
- PostgreSQL的
shared_buffers设为内存25% - Redis配置适当超时避免内存泄漏
- 调整Gitea的
QUEUE_LENGTH匹配负载
- PostgreSQL的
-
安全实践:
- 定期轮换数据库密码
- 限制SSH访问IP范围
- 启用登录失败锁定机制
-
备份策略:
- 3-2-1原则:3份备份,2种介质,1份异地
- 备份前停止服务保证一致性
- 定期验证备份可恢复性
20. 延伸学习资源
-
官方文档:
-
性能优化:
-
安全加固:
-
社区支持:
-
相关工具: