前言
Gitea 是一个轻量级、自托管的 Git 服务，使用 Go 语言编写。相比 GitLab，Gitea 资源占用极低（256MB 内存即可运行），安装配置简单，功能却不输大厂——支持 Issue、PR、CI/CD、Webhook、LDAP 等。
如果你不想把代码放在 GitHub/GitLab 上，或者想搭建一个私有的代码托管平台，Gitea 是最佳选择。
方案对比
| 方案 | 内存占用 | 部署难度 | 推荐场景 |
|---|---|---|---|
| Gitea + SQLite | ~200MB | ⭐ | 个人仓库、小团队（<10人） |
| Gitea + PostgreSQL | ~300MB | ⭐⭐ | 生产环境、多团队协作 |
| Gitea + PostgreSQL + 备用 | ~400MB | ⭐⭐⭐ | 高可用场景 |
本教程采用 Gitea + PostgreSQL 方案，兼顾性能和数据安全。
环境准备
前提条件
- 已安装 Docker 和 Docker Compose（参考上篇 Docker 部署教程）
- 至少 512MB 可用内存
- 开放端口（默认 3000 HTTP, 2222 SSH）
- 一个域名（可选，推荐用于 HTTPS）
准备工作目录
mkdir -p /root/docker/gitea
cd /root/docker/gitea
编写 docker-compose.yml
下面是完整的 docker-compose.yml，包含 Gitea 和 PostgreSQL 两个服务：
services:
# ─── 数据库 ───
db:
image: postgres:16-alpine
container_name: gitea_db
restart: unless-stopped
environment:
POSTGRES_USER: gitea
POSTGRES_PASSWORD: gitea_secure_password
POSTGRES_DB: gitea
volumes:
- ./db:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U gitea"]
interval: 10s
timeout: 5s
retries: 5
networks:
- gitea_net
# ─── Gitea ───
server:
image: gitea/gitea:latest
container_name: gitea
restart: unless-stopped
depends_on:
db:
condition: service_healthy
ports:
- "3000:3000" # HTTP 端口
- "2222:22" # SSH 端口（映射到宿主机非特权端口）
volumes:
- ./data:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
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_secure_password
# ── 服务器配置 ──
GITEA__server__DOMAIN: git.yourdomain.com
GITEA__server__HTTP_PORT: 3000
GITEA__server__ROOT_URL: https://git.yourdomain.com
GITEA__server__SSH_DOMAIN: git.yourdomain.com
GITEA__server__SSH_PORT: 2222
GITEA__server__SSH_LISTEN_PORT: 22
# ── 禁用用户注册（生产环境建议） ──
GITEA__service__DISABLE_REGISTRATION: true
# ── 邮件配置（可选） ──
# GITEA__mailer__ENABLED: true
# GITEA__mailer__HOST: smtp.example.com:587
# GITEA__mailer__FROM: [email protected]
# GITEA__mailer__USER: [email protected]
# GITEA__mailer__PASSWD: your_email_password
networks:
- gitea_net
networks:
gitea_net:
driver: bridge
⚠️ 请把以下配置换成你自己的：
POSTGRES_PASSWORD→ 改成安全的随机密码GITEA__server__DOMAIN→ 换成你的域名GITEA__server__ROOT_URL→ 换成你的域名GITEA__server__SSH_DOMAIN→ 换成你的域名
启动服务
cd /root/docker/gitea
docker compose up -d
查看启动日志：
docker compose logs -f
# 看到 like "Server listen on http://0.0.0.0:3000" 即启动完成
确认所有容器正常运行：
docker compose ps
输出应该类似：
NAME IMAGE STATUS PORTS
gitea gitea/gitea:latest Up 2 minutes 0.0.0.0:3000->3000/tcp, 0.0.0.0:2222->22/tcp
gitea_db postgres:16-alpine Up 2 minutes (healthy)
初始化配置（首次启动）
浏览器访问 http://你的服务器IP:3000，会进入安装页面：
第一步：数据库设置
| 字段 | 值 |
|---|---|
| 数据库类型 | PostgreSQL（默认） |
| 主机 | db:5432 |
| 数据库名 | gitea |
| 用户名 | gitea |
| 密码 | 你在 docker-compose.yml 中设置的密码 |
第二步：通用设置
| 字段 | 推荐值 |
|---|---|
| 站点名称 | 你的 Git 服务名称 |
| 仓库根路径 | 保持默认 |
| Git 钩子路径 | 保持默认 |
| 运行系统用户 | git |
| 域名 | 你的域名 |
| SSH 端口 | 2222 |
| HTTP 端口 | 3000 |
| 应用 URL | https://git.yourdomain.com |
✅ 如果不需要注册功能，可以在安装页面勾选 “禁止自助注册”。
第三步：管理员账号
安装页面底部可以设置初始管理员账号。建议立即创建一个：
| 字段 | 值 |
|---|---|
| 用户名 | admin |
| 密码 | 强密码 |
| 邮箱 | 你的邮箱 |
点击 “安装 Gitea” 完成配置。
配置 Caddy 反向代理（HTTPS）
有了域名，用 Caddy 一键搞定 HTTPS。Caddyfile 配置：
git.yourdomain.com {
reverse_proxy localhost:3000
}
如果你已有 Caddy 在运行，只需把上面内容追加到 Caddyfile 并重载：
# 添加反向代理配置
echo "git.yourdomain.com {
reverse_proxy localhost:3000
}" | sudo tee -a /etc/caddy/Caddyfile
# 重载 Caddy
sudo systemctl reload caddy
🎉 配置完成后，就可以通过
https://git.yourdomain.com安全访问 Gitea 了
SSH 配置详解
Gitea 默认 SSH 端口是 22，但在 Docker 中为了避免和宿主机 SSH 冲突，映射为 2222 端口。
客户端 Clone 仓库
# HTTPS 方式（推荐）
git clone https://git.yourdomain.com/username/repo.git
# SSH 方式（需要指定端口）
git clone ssh://[email protected]:2222/username/repo.git
简化 SSH 克隆（可选）
如果想直接用 [email protected]:username/repo.git 的简洁格式，需要在宿主机上做端口转发：
方法 A：使用 iptables 转发（推荐）
# 将宿主机 22 端口的 SSH 流量按域名转发到 Gitea 的 2222 端口
# ⚠️ 注意：这会与宿主机 SSH 冲突，仅当宿主机 SSH 改了端口时可用
方法 B：使用 SSH 配置文件
在客户端 ~/.ssh/config 中添加：
Host git.yourdomain.com
HostName git.yourdomain.com
Port 2222
User git
之后就可以直接用简写拉取代码：
git clone [email protected]:username/repo.git
常用运维命令
# 查看服务状态
cd /root/docker/gitea
docker compose ps
docker compose logs --tail=50 -f
# 重启服务
docker compose restart
# 更新 Gitea 版本
docker compose pull
docker compose up -d
# 备份数据（重要！定期执行）
tar -czf gitea-backup-$(date +%Y%m%d).tar.gz ./data ./db
# 恢复备份
# 先停止服务：docker compose down
# 解压 backup 到目录
# 再启动：docker compose up -d
# 完全停止并删除容器
docker compose down
# 清理不再使用的镜像
docker system prune -a
配置 CI/CD（Gitea Actions）
Gitea 内置了 Actions（与 GitHub Actions 兼容），配置非常简单。
1. 启动 Act Runner
在 Gitea 服务器上（或单独的 runner 机器上）：
# 先获取注册 token：在 Gitea Web 界面 → 站点管理 → Actions → Runners → 创建 runner
mkdir -p /root/docker/gitea-runner
cd /root/docker/gitea-runner
创建 docker-compose.yml：
services:
runner:
image: gitea/act_runner:latest
container_name: gitea_runner
restart: unless-stopped
environment:
GITEA_INSTANCE_URL: https://git.yourdomain.com
GITEA_RUNNER_REGISTRATION_TOKEN: YOUR_REGISTRATION_TOKEN
GITEA_RUNNER_NAME: my-runner
# GITEA_RUNNER_LABELS: "ubuntu-latest,ubuntu-22.04"
volumes:
- ./data:/data
- /var/run/docker.sock:/var/run/docker.sock
启动 runner：
docker compose up -d
2. 在仓库中使用 Actions
在仓库根目录创建 .gitea/workflows/build.yml：
name: Build and Test
on: [push]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: 显示提交信息
run: echo "Commit ${{ github.sha }}"
- name: 运行测试
run: echo "Tests passed!"
生产环境最佳实践
1. 定期备份
加入 crontab，每天凌晨自动备份：
crontab -e
# 添加：
0 3 * * * cd /root/docker/gitea && tar -czf /backup/gitea/gitea-$(date +\%Y\%m\%d).tar.gz ./data ./db && find /backup/gitea -name "gitea-*.tar.gz" -mtime +30 -delete
2. 资源限制
在 docker-compose.yml 中添加资源限制：
services:
server:
deploy:
resources:
limits:
memory: 512M
cpus: "1.0"
db:
deploy:
resources:
limits:
memory: 256M
cpus: "0.5"
3. 使用非 root 运行 Gitea
确保 USER_UID 和 USER_GID 与宿主机上的用户匹配，避免文件权限问题：
# 查看当前用户的 UID/GID
id
# uid=1000(youruser) gid=1000(youruser)
4. 配置 Webhook
Gitea 支持在代码推送时触发 Webhook，可以搭配 CI/CD 或通知服务：
- 进入仓库 → 设置 → Webhooks
- 添加 Webhook，填入目标 URL
- 选择触发事件（Push、PR、Issue 等）
常见问题排查
❌ Gitea 启动后页面 502/连接拒绝
# 检查数据库是否先启动
docker compose logs db
# 检查端口映射
docker compose ps
# 可能问题：数据库还没完全就绪，Gitea 正在重试
docker compose logs server
❌ Authentication failed 连接数据库
# 确认 docker-compose.yml 中的密码完全一致
# GITEA__database__PASSWD 要与 POSTGRES_PASSWORD 一致
# 重新创建数据库容器
docker compose down
rm -rf ./db
docker compose up -d
❌ 推送代码报 Permission denied (publickey)
# 1. 确认 SSH 密钥已添加到 Gitea
# 用户设置 → SSH/GPG Keys → 添加密钥
# 2. 确认使用了正确的 SSH 端口
ssh -T -p 2222 [email protected]
# 看到 "Hi there, username! You've successfully authenticated..." 即正常
# 3. 检查 SSH 密钥权限（在客户端）
chmod 600 ~/.ssh/id_rsa
chmod 700 ~/.ssh
❌ 推送大文件超时
在 Gitea 容器配置中增加超时限制：
environment:
GITEA__server__LFS_START_SERVER: true
GITEA__git__TIMEOUT_DEFAULT: 360
GITEA__git__TIMEOUT_MIGRATE: 600
GITEA__git__TIMEOUT_CLONE: 300
GITEA__git__TIMEOUT_PUSH: 300
❌ 忘记管理员密码
# 进入 Gitea 容器
docker exec -it gitea bash
# 使用 Gitea 命令行重设密码
gitea admin user change-password --username admin --password 新密码
# 退出容器
exit
升级 Gitea
cd /root/docker/gitea
# 1. 备份（永远先备份）
tar -czf /tmp/gitea-pre-upgrade-$(date +%Y%m%d-%H%M%S).tar.gz ./
# 2. 拉取新镜像
docker compose pull
# 3. 重新创建容器
docker compose up -d
# 4. 确认升级成功
docker compose logs --tail=20
💡 Gitea 升级非常稳定，通常只需替换镜像即可，数据库迁移会自动进行。升级后建议去 Web 界面检查一下功能是否正常。
总结
通过 Docker Compose，不到 10 分钟就能搭建一个完整的 Gitea 代码托管平台：
# 三步启动
mkdir -p /root/docker/gitea && cd /root/docker/gitea
# 创建 docker-compose.yml
docker compose up -d
访问 http://你的IP:3000 完成初始化配置，一个属于你自己的 Git 服务就上线了 🚀
进阶方向：
- 接入 LDAP/OAuth 实现统一登录
- 配置 Gitea Actions 实现 CI/CD 流水线
- 对接 Drone/Jenkins 等第三方 CI 工具
- 使用 Gitea + Tea 命令行工具管理仓库