gitea Docker 容器化部署指南

概述

GITEA 是一款开源、轻量级的自托管 Git 服务，提供类似于 GitHub、GitLab 的代码托管功能，支持版本控制、代码审查、issue 跟踪、Wiki 等核心特性。其设计目标是简单易用、资源占用低，适合个人开发者、小型团队或企业内部搭建私有代码仓库。

通过 Docker 容器化部署 GITEA 可带来以下优势：

环境一致性：容器封装所有依赖，避免"在我电脑上能运行"的环境差异问题
快速部署：无需手动配置系统依赖，一条命令即可启动服务
隔离性：与主机系统及其他应用隔离，减少冲突风险
易于维护：支持数据卷持久化存储，升级或迁移时只需操作容器和数据卷
资源可控：可通过 Docker 限制 CPU、内存等资源占用

本文将详细介绍通过 Docker 容器化部署 GITEA 的完整流程，包括环境准备、镜像拉取、容器配置、功能测试及生产环境优化建议，所有操作基于轩辕镜像加速服务以确保国内环境下的部署效率。

环境准备

Docker 安装

GITEA 容器化部署需依赖 Docker 环境，推荐使用以下一键安装脚本完成 Docker 及相关组件（Docker Engine、Docker Compose）的安装与配置：

bash
bash <(wget -qO- https://xuanyuan.cloud/docker.sh)

脚本支持主流 Linux 发行版（Ubuntu、Debian、CentOS、Rocky Linux 等），会自动处理系统依赖、添加官方源、安装最新稳定版 Docker 并配置服务自启动。

镜像准备

拉取命令格式如下：

bash
docker pull xxx.xuanyuan.run/gitea/gitea:{TAG}

其中 {TAG} 为镜像版本标签，推荐使用 latest（最新稳定版），可通过 GITEA 镜像标签列表查看所有可用版本。

拉取推荐镜像

执行以下命令拉取推荐的 latest 标签镜像：

bash
docker pull xxx.xuanyuan.run/gitea/gitea:latest

若需指定特定版本（如 1.21.0），将命令中的 latest 替换为对应标签即可，例如：docker pull xxx.xuanyuan.run/gitea/gitea:1.21.0

拉取完成后，可通过 docker images 命令验证镜像是否成功下载：

bash
docker images | grep gitea/gitea
# 预期输出类似：
# xxx.xuanyuan.run/gitea/gitea   latest    xxxxxxxx    2 weeks ago    450MB

容器部署

数据卷创建

为确保 GITEA 数据持久化（配置文件、仓库数据、数据库等），需创建专用数据卷（Docker Volume）存储数据：

bash
# 创建数据存储卷（存放仓库数据、用户上传等）
docker volume create gitea-data

# 创建配置存储卷（存放配置文件）
docker volume create gitea-config

数据卷由 Docker 管理，默认存储路径为 /var/lib/docker/volumes/，相比主机目录挂载具有更好的权限管理和移植性。

容器运行命令

使用以下命令启动 GITEA 容器，包含基础配置、端口映射、数据卷挂载及自启动设置：

bash
docker run -d \
  --name gitea \
  --restart always \
  --publish 3000:3000 \  # HTTP 服务端口（Web 界面）
  --publish 2222:22 \    # SSH 服务端口（代码仓库 SSH 访问）
  --volume gitea-data:/data \       # 数据卷挂载（核心数据）
  --volume gitea-config:/etc/gitea \ # 配置卷挂载（配置文件）
  --env USER_UID=1000 \             # 运行用户 UID（与主机用户保持一致可避免权限问题）
  --env USER_GID=1000 \             # 运行用户 GID
  xxx.xuanyuan.run/gitea/gitea:latest

参数说明：

--name gitea：指定容器名称为 gitea，便于后续管理
--restart always：设置容器开机自启，异常退出后自动重启
--publish 3000:3000：将主机 3000 端口映射到容器 3000 端口（GITEA Web 界面默认端口）
--publish 2222:22：将主机 2222 端口映射到容器 22 端口（GITEA SSH 服务默认端口，避免与主机 SSH 22 端口冲突）
--volume：挂载数据卷，确保容器重启或重建后数据不丢失
--env USER_UID/GID=1000：设置容器内运行用户的 UID/GID，建议与主机当前用户保持一致（可通过 id 命令查看主机用户 UID/GID）

容器状态检查

容器启动后，通过以下命令确认运行状态：

bash
# 查看容器运行状态
docker ps | grep gitea
# 预期输出类似（STATUS 为 Up 表示运行正常）：
# abc12345  xxx.xuanyuan.run/gitea/gitea:latest  "/usr/bin/entrypoint…"  5 minutes ago  Up 5 minutes  0.0.0.0:3000->3000/tcp, 0.0.0.0:2222->22/tcp  gitea

# 查看容器日志（验证启动过程是否有错误）
docker logs -f gitea
# 正常启动会输出类似 "Listen: http://0.0.0.0:3000" 的日志

功能测试

Web 界面访问验证

初始配置
容器启动后，通过浏览器访问 http://<服务器IP>:3000 进入 GITEA 初始配置页面，关键配置项说明：
- 数据库设置：默认使用 SQLite3（文件数据库，适合单机部署），也可选择 MySQL/PostgreSQL（需提前准备数据库服务）
- 应用基本设置：
  - 站点名称：自定义（如"我的代码仓库"）
  - 服务器域名：填写实际访问域名或服务器 IP
  - SSH 端口：填写主机映射的 SSH 端口（即 2222，而非容器内的 22）
  - HTTP 端口：保持 3000（容器内端口）
- 管理员账户设置：创建初始管理员账号（用户名、密码、邮箱）
界面验证
完成配置后点击"安装 Gitea"，等待约 10-30 秒，自动跳转至登录页面。使用管理员账户登录，确认以下功能正常：
- 仪表盘显示（统计信息、最近活动）
- 导航菜单（仓库、组织、用户、设置等）
- 响应式布局（PC 端/移动端适配）

仓库功能测试

创建测试仓库
登录后点击右上角"+"图标 → "新建仓库"，填写仓库名称（如 test-repo），选择"初始化仓库"并勾选"添加 README 文件"，点击"创建仓库"。

HTTP 克隆测试
在本地终端执行以下命令克隆仓库（替换 <服务器IP> 为实际 IP）：

bash
git clone http://<服务器IP>:3000/<用户名>/test-repo.git

克隆成功后，修改 README.md 并推送提交：

bash
cd test-repo
echo "测试内容" >> README.md
git add README.md
git commit -m "first commit"
git push origin main

返回 Web 界面刷新，确认提交已成功显示。

SSH 克隆测试
首先在 GITEA 个人设置 → "SSH/GPG 密钥"中添加本地 SSH 公钥（~/.ssh/id_rsa.pub 内容）。
然后执行以下命令克隆仓库（注意 SSH 端口为 2222）：
```
bash
git clone ssh://git@<服务器IP>:2222/<用户名>/test-repo.git
```
若无需输入密码即可克隆，说明 SSH 访问配置正常。

生产环境建议

数据库优化

默认 SQLite3 适合小规模使用，生产环境建议使用外部数据库以提升性能和可靠性：

推荐配置：MySQL 8.0+ 或 PostgreSQL 14+

创建数据库（以 MySQL 为例）：

sql
CREATE DATABASE gitea CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'gitea'@'%' IDENTIFIED BY 'StrongPassword123!';
GRANT ALL PRIVILEGES ON gitea.* TO 'gitea'@'%';
FLUSH PRIVILEGES;

容器启动时添加数据库环境变量：

bash
--env DB_TYPE=mysql \
--env DB_HOST=<mysql-ip>:3306 \
--env DB_NAME=gitea \
--env DB_USER=gitea \
--env DB_PASSWD=StrongPassword123! \

HTTPS 配置

生产环境必须启用 HTTPS 以保障数据传输安全，推荐通过 Nginx 反向代理实现：

Nginx 配置示例：

nginx
server {
    listen 80;
    server_name git.example.com;
    return 301 https://$host$request_uri;  # HTTP 重定向到 HTTPS
}

server {
    listen 443 ssl;
    server_name git.example.com;

    ssl_certificate /etc/letsencrypt/live/git.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/git.example.com/privkey.pem;
    # 其他 SSL 安全配置（如协议、密码套件等）

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

GITEA 配置调整：
在 GITEA 管理界面 → "设置" → "服务器设置"中，将"SSH 服务器域名"和"HTTP 服务器域名"改为实际域名（如 git.example.com），并将"ROOT_URL"设置为 https://git.example.com/。

数据备份策略

定期备份 GITEA 数据卷以防止数据丢失：

bash
# 创建备份脚本 backup-gitea.sh
#!/bin/bash
BACKUP_DIR="/var/backups/gitea"
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
mkdir -p $BACKUP_DIR

# 备份数据卷
docker run --rm -v gitea-data:/source -v $BACKUP_DIR:/backup alpine \
  tar -czf /backup/gitea-data-$TIMESTAMP.tar.gz -C /source .

docker run --rm -v gitea-config:/source -v $BACKUP_DIR:/backup alpine \
  tar -czf /backup/gitea-config-$TIMESTAMP.tar.gz -C /source .

# 保留最近30天备份
find $BACKUP_DIR -name "*.tar.gz" -mtime +30 -delete

添加可执行权限并通过 crontab 设置每日自动备份：

bash
chmod +x /path/to/backup-gitea.sh
crontab -e
# 添加：0 2 * * * /path/to/backup-gitea.sh  # 每天凌晨2点执行备份

资源限制与监控

资源限制：启动容器时添加以下参数限制资源占用：

bash
--memory=2g \          # 限制最大内存为 2GB
--memory-swap=2g \     # 限制内存+交换分区总和为 2GB（禁止使用交换分区）
--cpus=1 \             # 限制 CPU 核心数为 1

容器监控：
- 基础监控：通过 docker stats gitea 实时查看资源占用
- 高级监控：集成 Prometheus + Grafana，启用 GITEA 的 Prometheus 指标（在配置文件 app.ini 中设置 [metrics] ENABLED = true）

故障排查

常见问题及解决方法

1. 容器启动后 Web 界面无法访问

检查端口映射：docker port gitea 确认 3000 端口是否正确映射到主机
检查防火墙：ufw status（Ubuntu）或 firewall-cmd --list-ports（CentOS）确认 3000 端口已开放
查看应用日志：docker logs gitea | grep -i error 查找错误信息（如端口被占用、配置文件错误）

2. 数据卷权限问题

现象：容器日志出现 "permission denied" 错误，或数据无法持久化

解决：确保数据卷挂载目录权限正确，可通过以下命令修复：

bash
# 查看数据卷实际路径
docker volume inspect gitea-data | grep Mountpoint
# 修复权限（假设路径为 /var/lib/docker/volumes/gitea-data/_data）
sudo chown -R 1000:1000 /var/lib/docker/volumes/gitea-data/_data
sudo chown -R 1000:1000 /var/lib/docker/volumes/gitea-config/_data

3. SSH 克隆失败

检查 SSH 端口映射：确认容器 22 端口映射到主机的 2222 端口（或其他非 22 端口）
验证 SSH 密钥配置：检查公钥是否正确添加到 GITEA 用户设置中，格式是否完整（以 ssh-rsa 或 ssh-ed25519 开头）
测试 SSH 连接：ssh -p 2222 git@<服务器IP>，若提示 "Hi there, You've successfully authenticated..." 说明连接正常

日志查看与分析

GITEA 容器日志包含详细运行信息，关键日志位置：

容器标准输出日志：docker logs -f gitea（主要应用日志）
数据卷内日志：docker exec -it gitea cat /data/log/gitea/gitea.log（详细访问日志、错误日志）

可通过以下命令筛选错误日志：

bash
docker logs gitea | grep -iE "error|fatal|panic"

参考资源

GITEA 官方文档：https://docs.gitea.com/（项目官方指南，包含详细功能说明和配置选项）
轩辕镜像文档：GITEA 镜像文档（轩辕）（镜像相关说明及加速配置）
镜像标签列表：GITEA 镜像标签列表（所有可用版本标签）
Docker 官方文档：Docker 容器运行参考（容器运行参数详细说明）
GITEA 配置指南：配置 cheat sheet（app.ini 配置项详解）

总结

本文详细介绍了 GITEA 的 Docker 容器化部署方案，从环境准备、镜像拉取、容器配置到功能测试，提供了完整的操作流程。通过轩辕镜像加速服务可显著提升国内环境下的镜像下载速度，而容器化部署则简化了 GITEA 的安装与维护流程，同时保证了环境一致性和数据安全性。

关键要点：

使用轩辕一键脚本可快速配置 Docker 环境并启用镜像加速，无需手动处理复杂依赖
GITEA 拉取命令格式为 docker pull xxx.xuanyuan.run/gitea/gitea:{TAG}
必须通过数据卷（Volume）持久化存储 GITEA 数据，避免容器重建导致数据丢失
生产环境需重点关注数据库优化、HTTPS 配置、定期备份及资源监控，确保服务稳定运行

后续建议：

深入学习 GITEA 高级特性，如 LDAP 认证集成、CI/CD 功能、WebHook 配置等，提升团队协作效率
根据实际用户规模和访问量调整容器资源配置，必要时通过 Docker Compose 或 Kubernetes 实现多实例部署
定期关注 GITEA 官方更新和安全公告，通过 docker pull 拉取新版本镜像并重启容器完成升级
结合业务需求定制备份策略，建议采用异地备份或云存储备份以应对极端故障场景

参考链接：