Gitea Docker 部署

使用 Docker Compose 部署 Gitea，支持两种模式：

• HTTP 模式：Gitea 直接暴露端口，仅 HTTP
• Caddy 模式：通过 Caddy 反向代理，同时支持 HTTP 和 HTTPS（自动证书）

架构

HTTP 模式（默认）

Client → Gitea (HTTP_PORT, e.g. 3000)
           ├─ PostgreSQL (5432, Docker 内部网络)
           └─ Gitea SSH (22 → 宿主机 SSH_PORT)

Caddy 模式（--profile caddy）

Client → Caddy (80/443, HTTP + HTTPS) → Gitea (3000, Docker 内部网络)
                                         ├─ PostgreSQL (5432, Docker 内部网络)
                                         └─ Gitea SSH (22 → 宿主机 SSH_PORT)

快速开始

前提条件

• 服务器 SSH_PORT（默认 2222）端口可从外网访问
• 如使用 Caddy 模式：域名已解析到服务器公网 IP，且 80、443 端口可从外网访问

1. 配置环境变量

cp .env.example .env

编辑 .env，关键配置：

DOMAIN=git.example.com    # 你的域名
SSH_PORT=2222             # SSH 端口（宿主机端口，容器内仍为 22）
POSTGRES_PASSWORD=changeme  # PostgreSQL 密码（务必修改）

HTTP 模式

ROOT_URL=http://git.example.com:3000/

Caddy 模式

ROOT_URL=https://git.example.com/

2. 启动服务

# HTTP 模式（仅 Gitea + PostgreSQL，无 Caddy）
docker compose up -d

# Caddy 模式（HTTP + HTTPS，Caddy 反向代理）
docker compose --profile caddy up -d

Caddy 会自动为 DOMAIN 申请 Let's Encrypt 证书，稍等片刻后即可通过 HTTPS 访问。

3. 初始配置

首次访问会进入安装向导：

1. 设置管理员账户
2. 数据库已通过环境变量配置为 PostgreSQL，无需手动设置

访问方式

HTTP 模式

方式	地址
Web 界面	http://<DOMAIN>:<HTTP_PORT>
HTTP 克隆	git clone http://<DOMAIN>:<HTTP_PORT>/<用户>/<仓库>.git
SSH 克隆	git clone ssh://git@<DOMAIN>:<SSH_PORT>/<用户>/<仓库>.git

Caddy 模式

方式	地址
Web 界面	https://<DOMAIN>
HTTP 克隆	git clone http://<DOMAIN>/<用户>/<仓库>.git
HTTPS 克隆	git clone https://<DOMAIN>/<用户>/<仓库>.git
SSH 克隆	git clone ssh://git@<DOMAIN>:<SSH_PORT>/<用户>/<仓库>.git

Git LFS

已启用 Git LFS 支持，使用方法：

git lfs install
git lfs track "*.psd"
git add .gitattributes
git commit -m "Track PSD files with LFS"
git push

数据备份

备份 PostgreSQL 数据库

docker exec postgres pg_dump -U gitea gitea > gitea-db-$(date +%Y%m%d).sql

备份全部数据

# 备份数据目录 + 数据库导出
tar -czvf gitea-data-$(date +%Y%m%d).tar.gz data/
docker exec postgres pg_dump -U gitea gitea > gitea-db-$(date +%Y%m%d).sql

如果当前生产服务仍在使用旧版 SQLite，请在迁移前停止 Gitea，并至少备份 data/gitea/gitea.db 和完整 data/ 目录。完整流程见 SQLite 迁移到 PostgreSQL。

恢复数据库

cat gitea-db-20260327.sql | docker exec -i postgres psql -U gitea gitea

重要文件：

• data/postgres/ - PostgreSQL 数据
• data/git/repositories/ - 仓库数据
• data/git/lfs/ - LFS 文件
• data/gitea/conf/app.ini - Gitea 配置

SQLite 迁移到 PostgreSQL

如果已有生产 Gitea 仍在使用旧版 Docker Compose 和 SQLite，不要直接启动最新 compose 覆盖数据库配置，也不要把 gitea migrate 当作数据搬迁命令。

推荐流程是：停止旧 Gitea，冷备份 data/gitea/gitea.db 和 data/，更新到包含 PostgreSQL 的最新 commit，只启动空 PostgreSQL，用 pgloader 导入 SQLite 数据，最后启动 Gitea 并验证。

完整步骤见 docs/sqlite-to-postgres-migration.md。

常用命令

# 启动（HTTP 模式）
docker compose up -d

# 启动（Caddy 模式）
docker compose --profile caddy up -d

# 停止
docker compose down

# 查看日志
docker compose logs -f

# 查看 PostgreSQL 日志
docker compose logs -f postgres

# 查看 Caddy 日志
docker compose logs -f caddy

# 重启
docker compose restart

# 更新版本
# 修改 .env 中的 GITEA_VERSION 后
docker compose up -d

# 连接 PostgreSQL
docker exec -it postgres psql -U gitea