Compare commits
8 Commits
a43815d4a0
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
| d75f1a9ece | |||
| 73425c6e8f | |||
| 09f9f14b93 | |||
| b68c715f6b | |||
| ff0929dc02 | |||
| 866c059ee4 | |||
| af7d49b685 | |||
| 83ca0632f6 |
14
.env.example
14
.env.example
@@ -17,3 +17,17 @@ GITEA__lfs__PATH=/data/git/lfs
|
||||
|
||||
# 禁用公开注册（仅管理员可创建账号）
|
||||
GITEA__service__DISABLE_REGISTRATION=true
|
||||
|
||||
# PostgreSQL 配置
|
||||
POSTGRES_VERSION=16-alpine
|
||||
POSTGRES_DB=gitea
|
||||
POSTGRES_USER=gitea
|
||||
POSTGRES_PASSWORD=changeme
|
||||
|
||||
# 域名配置
|
||||
DOMAIN=git.example.com
|
||||
|
||||
# ROOT_URL：决定 Gitea UI 中的链接生成
|
||||
# 不使用 Caddy（仅 HTTP）：ROOT_URL=http://${DOMAIN}:${HTTP_PORT}/
|
||||
# 使用 Caddy（HTTP + HTTPS）：ROOT_URL=https://${DOMAIN}/
|
||||
ROOT_URL=http://${DOMAIN}:${HTTP_PORT}/
|
||||
|
||||
7
.gitignore
vendored
7
.gitignore
vendored
@@ -4,5 +4,12 @@ data/
|
||||
# 环境变量（可能包含敏感信息）
|
||||
.env
|
||||
|
||||
# Caddy 数据
|
||||
caddy_data/
|
||||
caddy_config/
|
||||
|
||||
# 备份
|
||||
backup/
|
||||
|
||||
# macOS
|
||||
.DS_Store
|
||||
|
||||
7
Caddyfile
Normal file
7
Caddyfile
Normal file
@@ -0,0 +1,7 @@
|
||||
http://{$DOMAIN} {
|
||||
reverse_proxy gitea:3000
|
||||
}
|
||||
|
||||
https://{$DOMAIN} {
|
||||
reverse_proxy gitea:3000
|
||||
}
|
||||
128
README.md
128
README.md
@@ -1,48 +1,98 @@
|
||||
# Gitea 局域网部署
|
||||
# Gitea Docker 部署
|
||||
|
||||
使用 Docker Compose 部署的 Gitea Git 服务。
|
||||
使用 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)
|
||||
```
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 配置环境变量
|
||||
### 前提条件
|
||||
|
||||
复制并编辑 `.env` 文件：
|
||||
- 服务器 `SSH_PORT`（默认 2222）端口可从外网访问
|
||||
- 如使用 Caddy 模式：域名已解析到服务器公网 IP，且 80、443 端口可从外网访问
|
||||
|
||||
### 1. 配置环境变量
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
修改端口等配置：
|
||||
编辑 `.env`，关键配置：
|
||||
|
||||
```env
|
||||
HTTP_PORT=3000 # Web 界面端口
|
||||
SSH_PORT=2222 # SSH 端口（宿主机端口，容器内仍为 22）
|
||||
DOMAIN=git.example.com # 你的域名
|
||||
SSH_PORT=2222 # SSH 端口（宿主机端口，容器内仍为 22）
|
||||
POSTGRES_PASSWORD=changeme # PostgreSQL 密码（务必修改）
|
||||
```
|
||||
|
||||
> `GITEA__server__SSH_PORT` 已通过 `.env` 传递给容器，告知 Gitea 对外 SSH 端口为 `2222`，
|
||||
> 使 Web 界面中的 SSH clone 地址正确显示端口号。
|
||||
#### HTTP 模式
|
||||
|
||||
```env
|
||||
ROOT_URL=http://git.example.com:3000/
|
||||
```
|
||||
|
||||
#### Caddy 模式
|
||||
|
||||
```env
|
||||
ROOT_URL=https://git.example.com/
|
||||
```
|
||||
|
||||
### 2. 启动服务
|
||||
|
||||
```bash
|
||||
# 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. 初始配置
|
||||
|
||||
首次访问 `http://<服务器IP>:3000` 会进入安装向导：
|
||||
首次访问会进入安装向导：
|
||||
|
||||
1. 设置管理员账户
|
||||
2. 配置服务器域名（可选）
|
||||
3. 数据库已默认使用 SQLite
|
||||
2. 数据库已通过环境变量配置为 PostgreSQL，无需手动设置
|
||||
|
||||
## 访问方式
|
||||
|
||||
### HTTP 模式
|
||||
|
||||
| 方式 | 地址 |
|
||||
|-----|------|
|
||||
| Web 界面 | `http://<IP>:3000` |
|
||||
| HTTP 克隆 | `git clone http://<IP>:3000/<用户>/<仓库>.git` |
|
||||
| SSH 克隆 | `git clone ssh://git@<IP>:2222/<用户>/<仓库>.git` |
|
||||
| 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
|
||||
|
||||
@@ -58,37 +108,71 @@ git push
|
||||
|
||||
## 数据备份
|
||||
|
||||
备份 `data/` 目录：
|
||||
### 备份 PostgreSQL 数据库
|
||||
|
||||
```bash
|
||||
# 备份
|
||||
tar -czvf gitea-backup-$(date +%Y%m%d).tar.gz data/
|
||||
docker exec postgres pg_dump -U gitea gitea > gitea-db-$(date +%Y%m%d).sql
|
||||
```
|
||||
|
||||
# 恢复
|
||||
tar -xzvf gitea-backup-20260320.tar.gz
|
||||
### 备份全部数据
|
||||
|
||||
```bash
|
||||
# 备份数据目录 + 数据库导出
|
||||
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](docs/sqlite-to-postgres-migration.md)。
|
||||
|
||||
### 恢复数据库
|
||||
|
||||
```bash
|
||||
cat gitea-db-20260327.sql | docker exec -i postgres psql -U gitea gitea
|
||||
```
|
||||
|
||||
重要文件：
|
||||
- `data/gitea/gitea.db` - 用户和配置数据
|
||||
|
||||
- `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](docs/sqlite-to-postgres-migration.md)。
|
||||
|
||||
## 常用命令
|
||||
|
||||
```bash
|
||||
# 启动
|
||||
# 启动（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
|
||||
```
|
||||
|
||||
@@ -4,16 +4,61 @@ services:
|
||||
container_name: gitea
|
||||
environment:
|
||||
- TZ=${TZ}
|
||||
- GITEA__database__DB_TYPE=postgres
|
||||
- GITEA__database__HOST=postgres:5432
|
||||
- GITEA__database__NAME=${POSTGRES_DB}
|
||||
- GITEA__database__USER=${POSTGRES_USER}
|
||||
- GITEA__database__PASSWD=${POSTGRES_PASSWORD}
|
||||
- GITEA__lfs__START_SERVER=${GITEA__lfs__START_SERVER}
|
||||
- GITEA__lfs__PATH=${GITEA__lfs__PATH}
|
||||
- GITEA__service__DISABLE_REGISTRATION=${GITEA__service__DISABLE_REGISTRATION}
|
||||
- GITEA__server__SSH_PORT=${GITEA__server__SSH_PORT}
|
||||
- GITEA__server__ROOT_URL=${ROOT_URL}
|
||||
- GITEA__server__DOMAIN=${DOMAIN}
|
||||
- GITEA__server__SSH_DOMAIN=${DOMAIN}
|
||||
restart: always
|
||||
volumes:
|
||||
- ./data:/data
|
||||
ports:
|
||||
- "${HTTP_PORT}:3000"
|
||||
- "${SSH_PORT}:22"
|
||||
depends_on:
|
||||
postgres:
|
||||
condition: service_healthy
|
||||
|
||||
postgres:
|
||||
image: postgres:${POSTGRES_VERSION}
|
||||
container_name: postgres
|
||||
environment:
|
||||
POSTGRES_DB: ${POSTGRES_DB}
|
||||
POSTGRES_USER: ${POSTGRES_USER}
|
||||
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
|
||||
restart: always
|
||||
volumes:
|
||||
- ./data/postgres:/var/lib/postgresql/data
|
||||
healthcheck:
|
||||
test: ["CMD", "pg_isready", "-U", "${POSTGRES_USER}"]
|
||||
interval: 5s
|
||||
timeout: 3s
|
||||
retries: 5
|
||||
|
||||
caddy:
|
||||
image: caddy:2
|
||||
container_name: caddy
|
||||
profiles:
|
||||
- caddy
|
||||
environment:
|
||||
- DOMAIN=${DOMAIN}
|
||||
restart: always
|
||||
ports:
|
||||
- "80:80"
|
||||
- "443:443"
|
||||
volumes:
|
||||
- ./Caddyfile:/etc/caddy/Caddyfile:ro
|
||||
- ./caddy_data:/data
|
||||
- ./caddy_config:/config
|
||||
depends_on:
|
||||
- gitea
|
||||
|
||||
networks:
|
||||
default:
|
||||
|
||||
179
docs/lfs-cos-storage.md
Normal file
179
docs/lfs-cos-storage.md
Normal file
@@ -0,0 +1,179 @@
|
||||
# Gitea LFS 对接腾讯云 COS
|
||||
|
||||
本文档适用于已通过本项目 Docker Compose 部署 Gitea，希望将 LFS 存储从本地磁盘迁移到腾讯云 COS 对象存储的场景。
|
||||
|
||||
腾讯云轻量应用服务器（Lighthouse）可以正常使用，COS 通过 HTTPS 公网端点访问，无需额外网络配置。
|
||||
|
||||
---
|
||||
|
||||
## 一、腾讯云侧准备
|
||||
|
||||
### 1.1 创建 COS Bucket
|
||||
|
||||
进入 [COS 控制台](https://console.cloud.tencent.com/cos) → 存储桶列表 → 创建存储桶：
|
||||
|
||||
| 选项 | 建议值 |
|
||||
|------|--------|
|
||||
| 地域 | 与服务器相同地域（降低延迟） |
|
||||
| 访问权限 | **私有读写** |
|
||||
| 版本控制 | 关闭（LFS 对象不需要） |
|
||||
|
||||
创建后记录完整的 Bucket 名称，格式为 `<name>-<appid>`，例如 `gitea-lfs-1234567890`。
|
||||
|
||||
### 1.2 创建 CAM 子账号并授权
|
||||
|
||||
进入 [CAM 控制台](https://console.cloud.tencent.com/cam) → 用户管理 → 新建用户：
|
||||
|
||||
- 用户类型选**编程访问**（只需 API 密钥，无需登录控制台）
|
||||
- 直接关联策略：搜索并勾选 `QcloudCOSDataFullControl`
|
||||
|
||||
> 如需最小权限，自定义策略只需包含：
|
||||
> `GetObject` `PutObject` `DeleteObject` `HeadObject` `ListBucket`
|
||||
|
||||
创建完成后保存 **SecretId** 和 **SecretKey**，页面关闭后无法再次查看。
|
||||
|
||||
### 1.3 地域 ID 参考
|
||||
|
||||
| 地域 | ID |
|
||||
|------|----|
|
||||
| 广州 | `ap-guangzhou` |
|
||||
| 上海 | `ap-shanghai` |
|
||||
| 北京 | `ap-beijing` |
|
||||
| 深圳 | `ap-shenzhen` |
|
||||
| 成都 | `ap-chengdu` |
|
||||
| 中国香港 | `ap-hongkong` |
|
||||
| 新加坡 | `ap-singapore` |
|
||||
|
||||
---
|
||||
|
||||
## 二、修改项目配置
|
||||
|
||||
### 2.1 修改 `.env`
|
||||
|
||||
将原来的本地 LFS 配置：
|
||||
|
||||
```bash
|
||||
GITEA__lfs__START_SERVER=true
|
||||
GITEA__lfs__PATH=/data/git/lfs
|
||||
```
|
||||
|
||||
替换为：
|
||||
|
||||
```bash
|
||||
# Git LFS 配置 - 腾讯云 COS
|
||||
GITEA__lfs__START_SERVER=true
|
||||
GITEA__lfs__STORAGE_TYPE=minio
|
||||
GITEA__lfs__MINIO_ENDPOINT=cos.ap-guangzhou.myqcloud.com # 改为你的地域
|
||||
GITEA__lfs__MINIO_ACCESS_KEY_ID=AKIDxxxxxxxxxx # CAM SecretId
|
||||
GITEA__lfs__MINIO_SECRET_ACCESS_KEY=xxxxxxxxxx # CAM SecretKey
|
||||
GITEA__lfs__MINIO_BUCKET=gitea-lfs-1234567890 # Bucket 完整名称
|
||||
GITEA__lfs__MINIO_LOCATION=ap-guangzhou # 改为你的地域
|
||||
GITEA__lfs__MINIO_USE_SSL=true
|
||||
GITEA__lfs__MINIO_BASE_PATH=lfs/
|
||||
GITEA__lfs__MINIO_BUCKET_LOOKUP_TYPE=dns
|
||||
```
|
||||
|
||||
> `GITEA__lfs__PATH` 仅在本地存储模式下生效，切换到 minio 后删除该行即可。
|
||||
|
||||
### 2.2 修改 `docker-compose.yml`
|
||||
|
||||
在 `gitea` 服务的 `environment` 下，将原来的 LFS 条目：
|
||||
|
||||
```yaml
|
||||
- GITEA__lfs__START_SERVER=${GITEA__lfs__START_SERVER}
|
||||
- GITEA__lfs__PATH=${GITEA__lfs__PATH}
|
||||
```
|
||||
|
||||
替换为：
|
||||
|
||||
```yaml
|
||||
- GITEA__lfs__START_SERVER=${GITEA__lfs__START_SERVER}
|
||||
- GITEA__lfs__STORAGE_TYPE=${GITEA__lfs__STORAGE_TYPE}
|
||||
- GITEA__lfs__MINIO_ENDPOINT=${GITEA__lfs__MINIO_ENDPOINT}
|
||||
- GITEA__lfs__MINIO_ACCESS_KEY_ID=${GITEA__lfs__MINIO_ACCESS_KEY_ID}
|
||||
- GITEA__lfs__MINIO_SECRET_ACCESS_KEY=${GITEA__lfs__MINIO_SECRET_ACCESS_KEY}
|
||||
- GITEA__lfs__MINIO_BUCKET=${GITEA__lfs__MINIO_BUCKET}
|
||||
- GITEA__lfs__MINIO_LOCATION=${GITEA__lfs__MINIO_LOCATION}
|
||||
- GITEA__lfs__MINIO_USE_SSL=${GITEA__lfs__MINIO_USE_SSL}
|
||||
- GITEA__lfs__MINIO_BASE_PATH=${GITEA__lfs__MINIO_BASE_PATH}
|
||||
- GITEA__lfs__MINIO_BUCKET_LOOKUP_TYPE=${GITEA__lfs__MINIO_BUCKET_LOOKUP_TYPE}
|
||||
```
|
||||
|
||||
### 2.3 同步更新 `.env.example`
|
||||
|
||||
`.env.example` 是提交到 git 的模板，需同步更新（不填真实密钥）：
|
||||
|
||||
```bash
|
||||
# Git LFS 配置 - 腾讯云 COS
|
||||
GITEA__lfs__START_SERVER=true
|
||||
GITEA__lfs__STORAGE_TYPE=minio
|
||||
GITEA__lfs__MINIO_ENDPOINT=cos.ap-guangzhou.myqcloud.com
|
||||
GITEA__lfs__MINIO_ACCESS_KEY_ID=AKIDxxxxxxxxxx
|
||||
GITEA__lfs__MINIO_SECRET_ACCESS_KEY=xxxxxxxxxx
|
||||
GITEA__lfs__MINIO_BUCKET=your-bucket-name
|
||||
GITEA__lfs__MINIO_LOCATION=ap-guangzhou
|
||||
GITEA__lfs__MINIO_USE_SSL=true
|
||||
GITEA__lfs__MINIO_BASE_PATH=lfs/
|
||||
GITEA__lfs__MINIO_BUCKET_LOOKUP_TYPE=dns
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、迁移已有 LFS 数据（可选）
|
||||
|
||||
如果切换前本地 `data/git/lfs/` 已有文件，需手动同步到 COS，否则历史 LFS 对象会返回 404。
|
||||
|
||||
使用腾讯云官方 CLI 工具 [coscli](https://cloud.tencent.com/document/product/436/63143)：
|
||||
|
||||
```bash
|
||||
# 安装 coscli（macOS 示例）
|
||||
curl -o coscli https://github.com/tencentyun/coscli/releases/latest/download/coscli-darwin
|
||||
|
||||
chmod +x coscli
|
||||
|
||||
# 配置认证（交互式）
|
||||
./coscli config init
|
||||
|
||||
# 上传本地 LFS 目录到 COS（同步模式，不重复上传）
|
||||
./coscli sync ./data/git/lfs/ cos://gitea-lfs-1234567890/lfs/ --recursive
|
||||
```
|
||||
|
||||
同步完成后再重启 Gitea，避免服务重启期间出现 LFS 对象丢失。
|
||||
|
||||
---
|
||||
|
||||
## 四、重启并验证
|
||||
|
||||
```bash
|
||||
# 重启 Gitea 服务（Compose 会自动检测 .env 变更并重建容器）
|
||||
docker compose up -d gitea
|
||||
|
||||
# 查看启动日志，确认无报错
|
||||
docker compose logs -f gitea
|
||||
```
|
||||
|
||||
验证 COS 是否生效：推送一个包含 LFS 文件的提交，然后到 COS 控制台的 `lfs/` 路径下确认对象是否出现。
|
||||
|
||||
```bash
|
||||
# 本地测试推送
|
||||
git lfs track "*.bin"
|
||||
git add .gitattributes largefile.bin
|
||||
git commit -m "test: lfs upload to cos"
|
||||
git push
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、常见问题
|
||||
|
||||
**Q：Bucket 名称填什么格式？**
|
||||
填完整名称（含 AppId），例如 `gitea-lfs-1234567890`。不含 `.cos.ap-xxx.myqcloud.com` 后缀。
|
||||
|
||||
**Q：轻量服务器能用 COS 内网端点吗？**
|
||||
轻量服务器使用独立的轻量网络，不在标准 VPC 内，默认无法访问 COS 内网端点。直接使用公网端点 `cos.<region>.myqcloud.com` 即可。若已通过云联网（CCN）打通网络，可将端点改为 `cos-internal.<region>.myqcloud.com` 以节省公网流量费用。
|
||||
|
||||
**Q：推送 LFS 报 `403 Forbidden`？**
|
||||
检查 CAM 子账号的策略是否包含目标 Bucket 的操作权限，以及 SecretId / SecretKey 是否填写正确。
|
||||
|
||||
**Q：推送 LFS 报 `SignatureDoesNotMatch`？**
|
||||
确认 `MINIO_LOCATION` 与 Bucket 实际所在地域一致。
|
||||
253
docs/sqlite-to-postgres-migration.md
Normal file
253
docs/sqlite-to-postgres-migration.md
Normal file
@@ -0,0 +1,253 @@
|
||||
# SQLite 迁移到 PostgreSQL
|
||||
|
||||
本文档适用于已有 Gitea 服务仍在使用旧版 Docker Compose 和 SQLite，尚未更新到引入 PostgreSQL 的最新 commit 的场景。
|
||||
|
||||
迁移目标是把 `data/gitea/gitea.db` 中的业务数据导入到新的 PostgreSQL 数据库，同时继续复用现有的仓库、LFS、附件和配置目录。
|
||||
|
||||
> `gitea migrate` 不是 SQLite 到 PostgreSQL 的数据搬迁工具。它只会对当前 Gitea 配置指向的数据库执行 Gitea schema migration。
|
||||
>
|
||||
> Gitea 自带的跨数据库导出入口是 `gitea dump --database postgres`。Gitea 没有对应的自动 `gitea restore` 命令，恢复或导入 PostgreSQL 时需要手动解压 dump 包，并用 `psql` 导入其中的 `gitea-db.sql`。
|
||||
|
||||
## 迁移前准备
|
||||
|
||||
- 预留维护窗口。迁移期间必须停止 Gitea，避免 SQLite 继续写入。
|
||||
- 保持 `GITEA_VERSION` 不变。不要在同一次操作中同时升级 Gitea 版本和切换数据库。
|
||||
- 准备 `.env` 中的 PostgreSQL 配置：
|
||||
|
||||
```env
|
||||
POSTGRES_VERSION=16-alpine
|
||||
POSTGRES_DB=gitea
|
||||
POSTGRES_USER=gitea
|
||||
POSTGRES_PASSWORD=<强密码>
|
||||
```
|
||||
|
||||
- 确认可以运行 `sqlite3`、`unzip`，并且 PostgreSQL 容器里可以运行 `psql`。
|
||||
- 本文档假设 `docker-compose.yml` 把宿主机 `./data` 挂载到 Gitea 容器内的 `/data`。因此 dump 输出到容器内 `/data/gitea-dump-postgres.zip` 时，宿主机对应文件是 `data/gitea-dump-postgres.zip`。
|
||||
|
||||
## 1. 停止旧 Gitea
|
||||
|
||||
在仍使用 SQLite 的旧版 compose 下停止 Gitea：
|
||||
|
||||
```bash
|
||||
docker compose stop gitea
|
||||
```
|
||||
|
||||
如果启用了 Caddy，可以保持 Caddy 运行显示维护页，也可以一起停止：
|
||||
|
||||
```bash
|
||||
docker compose stop caddy
|
||||
```
|
||||
|
||||
## 2. 冷备份 SQLite 和数据目录
|
||||
|
||||
```bash
|
||||
ts=$(date +%Y%m%d-%H%M%S)
|
||||
mkdir -p backups/$ts
|
||||
cp data/gitea/gitea.db backups/$ts/gitea.db
|
||||
cp data/gitea/conf/app.ini backups/$ts/app.ini
|
||||
tar -czf backups/$ts/gitea-data.tar.gz data/git data/gitea
|
||||
```
|
||||
|
||||
备份完成后，记录 SQLite 中的关键表数量，作为迁移后校验基线：
|
||||
|
||||
```bash
|
||||
sqlite3 data/gitea/gitea.db "select 'user', count(*) from user union all select 'repository', count(*) from repository union all select 'lfs_meta_object', count(*) from lfs_meta_object union all select 'public_key', count(*) from public_key union all select 'issue', count(*) from issue union all select 'release', count(*) from release;"
|
||||
```
|
||||
|
||||
## 3. 使用 Gitea dump 导出 PostgreSQL SQL
|
||||
|
||||
在仍使用旧 SQLite 配置时运行 `gitea dump`。不要先把 Gitea 配置切到 PostgreSQL，否则 dump 会尝试读取新数据库。
|
||||
|
||||
```bash
|
||||
docker compose run --rm --user git gitea \
|
||||
gitea dump -c /data/gitea/conf/app.ini \
|
||||
--database postgres \
|
||||
--file /data/gitea-dump-postgres.zip
|
||||
```
|
||||
|
||||
确认宿主机上已经生成 dump 包：
|
||||
|
||||
```bash
|
||||
ls -lh data/gitea-dump-postgres.zip
|
||||
```
|
||||
|
||||
如果当前镜像或环境不能识别 `git` 用户，可以改用官方镜像常见 UID/GID：
|
||||
|
||||
```bash
|
||||
docker compose run --rm --user 1000:1000 gitea \
|
||||
gitea dump -c /data/gitea/conf/app.ini \
|
||||
--database postgres \
|
||||
--file /data/gitea-dump-postgres.zip
|
||||
```
|
||||
|
||||
解压 dump 包，得到 `gitea-db.sql`：
|
||||
|
||||
```bash
|
||||
mkdir -p backups/gitea-dump-postgres
|
||||
unzip -o data/gitea-dump-postgres.zip -d backups/gitea-dump-postgres
|
||||
ls -lh backups/gitea-dump-postgres/gitea-db.sql
|
||||
```
|
||||
|
||||
## 4. 更新代码并只启动 PostgreSQL
|
||||
|
||||
更新到包含 PostgreSQL 服务的最新 commit，并补齐 `.env` 中的 PostgreSQL 配置。
|
||||
|
||||
```bash
|
||||
git pull
|
||||
```
|
||||
|
||||
先只启动 PostgreSQL，不要启动 Gitea：
|
||||
|
||||
```bash
|
||||
docker compose up -d postgres
|
||||
```
|
||||
|
||||
确认 PostgreSQL 可连接：
|
||||
|
||||
```bash
|
||||
docker compose exec -T postgres psql -U gitea -d gitea -c "select version();"
|
||||
```
|
||||
|
||||
## 5. 确认 PostgreSQL 是空库
|
||||
|
||||
检查目标库是否已有表：
|
||||
|
||||
```bash
|
||||
docker compose exec -T postgres psql -U gitea -d gitea -c '\dt'
|
||||
```
|
||||
|
||||
如果已经有 Gitea 业务表，先确认这些表不是生产数据。确认可丢弃后，停止 PostgreSQL，备份并移走 `data/postgres/`，再重新启动空库：
|
||||
|
||||
```bash
|
||||
docker compose stop postgres
|
||||
ts=$(date +%Y%m%d-%H%M%S)
|
||||
mv data/postgres data/postgres.before-migration-$ts
|
||||
docker compose up -d postgres
|
||||
```
|
||||
|
||||
再次运行 `\dt`，确认目标库为空。
|
||||
|
||||
## 6. 导入 dump SQL 到 PostgreSQL
|
||||
|
||||
使用 `psql` 导入 `gitea-db.sql`：
|
||||
|
||||
```bash
|
||||
docker compose exec -T postgres psql -U gitea -d gitea < backups/gitea-dump-postgres/gitea-db.sql
|
||||
```
|
||||
|
||||
导入完成后，检查目标库关键表数量：
|
||||
|
||||
```bash
|
||||
docker compose exec -T postgres psql -U gitea -d gitea -c "select 'user', count(*) from \"user\" union all select 'repository', count(*) from repository union all select 'lfs_meta_object', count(*) from lfs_meta_object union all select 'public_key', count(*) from public_key union all select 'issue', count(*) from issue union all select 'release', count(*) from release;"
|
||||
```
|
||||
|
||||
这些数量应与第 2 步 SQLite 基线一致。
|
||||
|
||||
## 7. 启动 Gitea
|
||||
|
||||
确认 `docker-compose.yml` 已通过 `GITEA__database__*` 环境变量指向 PostgreSQL，然后启动 Gitea：
|
||||
|
||||
```bash
|
||||
docker compose up -d gitea
|
||||
docker compose logs -f gitea
|
||||
```
|
||||
|
||||
Gitea 启动时会对 PostgreSQL 执行必要的 schema migration。日志中不应出现数据库连接、类型转换、唯一约束或 migration 错误。
|
||||
|
||||
如果使用 Caddy：
|
||||
|
||||
```bash
|
||||
docker compose up -d caddy
|
||||
```
|
||||
|
||||
## 8. 迁移后验证
|
||||
|
||||
- 使用原管理员账号登录 Web UI。
|
||||
- 确认用户、组织、仓库、Issue、Release、SSH Key 等数据存在。
|
||||
- 执行一次 HTTP 或 HTTPS clone。
|
||||
- 执行一次 SSH clone。
|
||||
- 推送一个普通 commit。
|
||||
- 如果使用 Git LFS，执行一次 LFS push。
|
||||
- 检查日志：
|
||||
|
||||
```bash
|
||||
docker compose logs gitea postgres
|
||||
```
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Gitea is not supposed to be run as root
|
||||
|
||||
`docker compose run` 默认可能以 root 用户启动一次性容器，但 Gitea 不允许以 root 运行。给 dump 命令加上 `--user git`：
|
||||
|
||||
```bash
|
||||
docker compose run --rm --user git gitea \
|
||||
gitea dump -c /data/gitea/conf/app.ini \
|
||||
--database postgres \
|
||||
--file /data/gitea-dump-postgres.zip
|
||||
```
|
||||
|
||||
如果 `git` 用户不可用，改用：
|
||||
|
||||
```bash
|
||||
docker compose run --rm --user 1000:1000 gitea \
|
||||
gitea dump -c /data/gitea/conf/app.ini \
|
||||
--database postgres \
|
||||
--file /data/gitea-dump-postgres.zip
|
||||
```
|
||||
|
||||
### Unable to create dump file "/gitea-dump-*.zip": permission denied
|
||||
|
||||
`gitea dump` 默认会把文件写到容器当前目录。如果当前目录是 `/`，非 root 用户没有写权限。显式指定 `--file /data/gitea-dump-postgres.zip`，让 dump 写入已挂载且可持久化的 `/data` 目录。
|
||||
|
||||
### pgloader 备选方案
|
||||
|
||||
如果 `gitea dump --database postgres` 在当前版本或数据集上失败，可以把 `pgloader` 作为备选迁移工具。使用前仍然要停止 Gitea、完成冷备份，并确认 PostgreSQL 目标库为空。
|
||||
|
||||
把 `<POSTGRES_PASSWORD>` 替换为 `.env` 中的真实密码：
|
||||
|
||||
```bash
|
||||
docker run --rm \
|
||||
--network gitea_default \
|
||||
-v "$PWD/data/gitea:/data/gitea:ro" \
|
||||
dimitri/pgloader:latest \
|
||||
pgloader sqlite:///data/gitea/gitea.db postgresql://gitea:<POSTGRES_PASSWORD>@postgres:5432/gitea
|
||||
```
|
||||
|
||||
如果 compose project 网络名不是 `gitea_default`，替换 `--network` 参数。
|
||||
|
||||
## 回滚
|
||||
|
||||
如果迁移后验证失败，先停止新 Gitea：
|
||||
|
||||
```bash
|
||||
docker compose stop gitea
|
||||
```
|
||||
|
||||
回滚到旧版 SQLite compose，或临时移除 `docker-compose.yml` 中的 `GITEA__database__*` 环境变量，避免它覆盖 `app.ini`。
|
||||
|
||||
恢复备份：
|
||||
|
||||
```bash
|
||||
cp backups/<备份时间>/gitea.db data/gitea/gitea.db
|
||||
cp backups/<备份时间>/app.ini data/gitea/conf/app.ini
|
||||
```
|
||||
|
||||
再启动旧 SQLite 版本：
|
||||
|
||||
```bash
|
||||
docker compose up -d gitea
|
||||
```
|
||||
|
||||
在迁移完全确认前，不要删除 `data/gitea/gitea.db`、`backups/`、`data/gitea-dump-postgres.zip` 或迁移前的 `data/postgres.before-migration-*`。
|
||||
|
||||
## 演练建议
|
||||
|
||||
正式迁移前，建议在复制出来的目录中完整演练一次：
|
||||
|
||||
```bash
|
||||
cp -a gitea gitea-migration-dry-run
|
||||
cd gitea-migration-dry-run
|
||||
```
|
||||
|
||||
演练中也要验证 dump 导出、SQL 解压、空库检查、`psql` 导入、表数量对比、Gitea 启动和 Web/Git 操作。演练通过后，再在正式目录执行维护窗口迁移。
|
||||
@@ -2,11 +2,11 @@
|
||||
|
||||
> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** 使用 Docker Compose 部署 Gitea Git 服务，支持 HTTP/SSH 访问和 Git LFS
|
||||
**Goal:** 使用 Docker Compose 部署 Gitea Git 服务，支持 HTTP/SSH 访问、Git LFS 和 PostgreSQL 数据库
|
||||
|
||||
**Architecture:** 单容器部署，SQLite 数据库，宿主机目录挂载持久化数据，通过 .env 文件配置端口和环境变量
|
||||
**Architecture:** Gitea + PostgreSQL 双容器部署，宿主机目录挂载持久化数据，通过 .env 文件配置端口和环境变量，Caddy 可选反向代理
|
||||
|
||||
**Tech Stack:** Docker Compose, Gitea 1.25.4, SQLite
|
||||
**Tech Stack:** Docker Compose, Gitea 1.25.4, PostgreSQL 16 (alpine), Caddy 2 (可选)
|
||||
|
||||
---
|
||||
|
||||
@@ -14,14 +14,16 @@
|
||||
|
||||
| 文件 | 职责 |
|
||||
|-----|------|
|
||||
| `docker-compose.yml` | 容器编排配置：镜像、端口、卷、环境变量 |
|
||||
| `.env` | 可配置参数：版本、端口、时区、LFS 配置 |
|
||||
| `docker-compose.yml` | 容器编排：Gitea + PostgreSQL + Caddy（可选） |
|
||||
| `.env` | 可配置参数：版本、端口、时区、数据库、域名 |
|
||||
| `.env.example` | 环境变量示例（无敏感信息） |
|
||||
| `Caddyfile` | Caddy 反向代理配置 |
|
||||
| `.gitignore` | 忽略数据目录和环境变量文件 |
|
||||
| `README.md` | 使用说明：启动、访问、备份 |
|
||||
| `README.md` | 使用说明：启动、访问、备份、迁移 |
|
||||
|
||||
---
|
||||
|
||||
## Chunk 1: 基础配置文件
|
||||
## Chunk 1: 核心配置文件
|
||||
|
||||
### Task 1: 创建 .env 环境变量文件
|
||||
|
||||
@@ -41,9 +43,25 @@ SSH_PORT=2222
|
||||
# 时区
|
||||
TZ=Asia/Shanghai
|
||||
|
||||
# SSH 端口配置（告知 Gitea 对外 SSH 端口）
|
||||
GITEA__server__SSH_PORT=${SSH_PORT}
|
||||
|
||||
# Git LFS 配置
|
||||
GITEA__lfs__START_SERVER=true
|
||||
GITEA__lfs__PATH=/data/git/lfs
|
||||
|
||||
# 禁用公开注册
|
||||
GITEA__service__DISABLE_REGISTRATION=true
|
||||
|
||||
# PostgreSQL 配置
|
||||
POSTGRES_VERSION=16-alpine
|
||||
POSTGRES_DB=gitea
|
||||
POSTGRES_USER=gitea
|
||||
POSTGRES_PASSWORD=changeme
|
||||
|
||||
# 域名配置
|
||||
DOMAIN=git.example.com
|
||||
ROOT_URL=http://${DOMAIN}:${HTTP_PORT}/
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 验证文件创建成功**
|
||||
@@ -60,28 +78,11 @@ Expected: 显示上述内容
|
||||
|
||||
- [ ] **Step 1: 创建 docker-compose.yml 文件**
|
||||
|
||||
```yaml
|
||||
services:
|
||||
gitea:
|
||||
image: gitea/gitea:${GITEA_VERSION}
|
||||
container_name: gitea
|
||||
environment:
|
||||
- TZ=${TZ}
|
||||
- GITEA__lfs__START_SERVER=${GITEA__lfs__START_SERVER}
|
||||
- GITEA__lfs__PATH=${GITEA__lfs__PATH}
|
||||
restart: always
|
||||
volumes:
|
||||
- ./data:/data
|
||||
- /etc/timezone:/etc/timezone:ro
|
||||
- /etc/localtime:/etc/localtime:ro
|
||||
ports:
|
||||
- "${HTTP_PORT}:3000"
|
||||
- "${SSH_PORT}:22"
|
||||
|
||||
networks:
|
||||
default:
|
||||
driver: bridge
|
||||
```
|
||||
关键配置：
|
||||
- Gitea 服务：通过 `GITEA__database__*` 环境变量连接 PostgreSQL
|
||||
- PostgreSQL 服务：`postgres:16-alpine`，健康检查 `pg_isready`
|
||||
- Gitea `depends_on` PostgreSQL（健康检查通过后才启动）
|
||||
- Caddy 服务：`profiles: [caddy]`，可选启用
|
||||
|
||||
- [ ] **Step 2: 验证 Docker Compose 配置语法**
|
||||
|
||||
@@ -104,154 +105,44 @@ data/
|
||||
# 环境变量（可能包含敏感信息）
|
||||
.env
|
||||
|
||||
# Caddy 数据
|
||||
caddy_data/
|
||||
caddy_config/
|
||||
|
||||
# macOS
|
||||
.DS_Store
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 验证文件创建成功**
|
||||
|
||||
Run: `cat .gitignore`
|
||||
Expected: 显示上述内容
|
||||
|
||||
---
|
||||
|
||||
### Task 4: 创建 README.md 使用说明
|
||||
|
||||
**Files:**
|
||||
- Create: `README.md`
|
||||
|
||||
- [ ] **Step 1: 创建 README.md 文件**
|
||||
|
||||
```markdown
|
||||
# Gitea 局域网部署
|
||||
|
||||
使用 Docker Compose 部署的 Gitea Git 服务。
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 配置环境变量
|
||||
|
||||
复制并编辑 `.env` 文件：
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
修改端口等配置：
|
||||
|
||||
```env
|
||||
HTTP_PORT=3000 # Web 界面端口
|
||||
SSH_PORT=2222 # SSH 端口
|
||||
```
|
||||
|
||||
### 2. 启动服务
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### 3. 初始配置
|
||||
|
||||
首次访问 `http://<服务器IP>:3000` 会进入安装向导：
|
||||
|
||||
1. 设置管理员账户
|
||||
2. 配置服务器域名（可选）
|
||||
3. 数据库已默认使用 SQLite
|
||||
|
||||
## 访问方式
|
||||
|
||||
| 方式 | 地址 |
|
||||
|-----|------|
|
||||
| Web 界面 | `http://<IP>:3000` |
|
||||
| HTTP 克隆 | `git clone http://<IP>:3000/<用户>/<仓库>.git` |
|
||||
| SSH 克隆 | `git clone ssh://git@<IP>:2222/<用户>/<仓库>.git` |
|
||||
|
||||
## Git LFS
|
||||
|
||||
已启用 Git LFS 支持，使用方法：
|
||||
|
||||
```bash
|
||||
git lfs install
|
||||
git lfs track "*.psd"
|
||||
git add .gitattributes
|
||||
git commit -m "Track PSD files with LFS"
|
||||
git push
|
||||
```
|
||||
|
||||
## 数据备份
|
||||
|
||||
备份 `data/` 目录：
|
||||
|
||||
```bash
|
||||
# 备份
|
||||
tar -czvf gitea-backup-$(date +%Y%m%d).tar.gz data/
|
||||
|
||||
# 恢复
|
||||
tar -xzvf gitea-backup-20260320.tar.gz
|
||||
```
|
||||
|
||||
重要文件：
|
||||
- `data/gitea/gitea.db` - 用户和配置数据
|
||||
- `data/git/repositories/` - 仓库数据
|
||||
- `data/git/lfs/` - LFS 文件
|
||||
|
||||
## 常用命令
|
||||
|
||||
```bash
|
||||
# 启动
|
||||
docker compose up -d
|
||||
|
||||
# 停止
|
||||
docker compose down
|
||||
|
||||
# 查看日志
|
||||
docker compose logs -f
|
||||
|
||||
# 重启
|
||||
docker compose restart
|
||||
|
||||
# 更新版本
|
||||
# 修改 .env 中的 GITEA_VERSION 后
|
||||
docker compose up -d
|
||||
```
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 验证文件创建成功**
|
||||
|
||||
Run: `cat README.md`
|
||||
Expected: 显示上述内容
|
||||
|
||||
---
|
||||
|
||||
## Chunk 2: 创建示例配置和验证
|
||||
|
||||
### Task 5: 创建 .env.example 示例文件
|
||||
### Task 4: 创建 .env.example
|
||||
|
||||
**Files:**
|
||||
- Create: `.env.example`
|
||||
|
||||
- [ ] **Step 1: 创建 .env.example 文件**
|
||||
|
||||
```env
|
||||
# Gitea 版本
|
||||
GITEA_VERSION=1.25.4
|
||||
与 `.env` 结构相同，但密码使用占位值 `changeme`。
|
||||
|
||||
# 端口配置
|
||||
HTTP_PORT=3000
|
||||
SSH_PORT=2222
|
||||
---
|
||||
|
||||
# 时区
|
||||
TZ=Asia/Shanghai
|
||||
## Chunk 2: 文档和验证
|
||||
|
||||
# Git LFS 配置
|
||||
GITEA__lfs__START_SERVER=true
|
||||
GITEA__lfs__PATH=/data/git/lfs
|
||||
```
|
||||
### Task 5: 创建 README.md 使用说明
|
||||
|
||||
- [ ] **Step 2: 验证文件创建成功**
|
||||
**Files:**
|
||||
- Create: `README.md`
|
||||
|
||||
Run: `cat .env.example`
|
||||
Expected: 显示上述内容
|
||||
- [ ] **Step 1: 创建 README.md 文件**
|
||||
|
||||
内容包含：
|
||||
- 架构说明（HTTP 模式 / Caddy 模式）
|
||||
- 快速开始（配置 → 启动 → 初始设置）
|
||||
- 访问方式
|
||||
- Git LFS 使用
|
||||
- 数据备份（PostgreSQL pg_dump + 数据目录）
|
||||
- SQLite 迁移到 PostgreSQL 的安全入口说明，链接到 `docs/sqlite-to-postgres-migration.md`
|
||||
- 常用命令
|
||||
|
||||
---
|
||||
|
||||
@@ -265,12 +156,12 @@ Expected: 显示 `docker-compose.yml`, `.env`, `.env.example`, `.gitignore`, `RE
|
||||
- [ ] **Step 2: 验证 Docker Compose 配置**
|
||||
|
||||
Run: `docker compose config`
|
||||
Expected: 无错误输出，显示完整配置
|
||||
Expected: 无错误输出，显示完整配置（包含 gitea、postgres、caddy 服务）
|
||||
|
||||
- [ ] **Step 3: （可选）启动服务测试**
|
||||
|
||||
Run: `docker compose up -d`
|
||||
Expected: 容器启动成功
|
||||
Expected: postgres 和 gitea 容器均启动成功
|
||||
|
||||
---
|
||||
|
||||
@@ -278,5 +169,6 @@ Expected: 容器启动成功
|
||||
|
||||
- [ ] 所有配置文件已创建
|
||||
- [ ] `docker compose config` 验证通过
|
||||
- [ ] 服务可以正常启动
|
||||
- [ ] 服务可以正常启动（Gitea + PostgreSQL）
|
||||
- [ ] 可以通过 Web 界面访问安装向导
|
||||
- [ ] 数据库连接正常（安装向导中数据库类型显示为 PostgreSQL）
|
||||
|
||||
@@ -2,13 +2,13 @@
|
||||
|
||||
## 概述
|
||||
|
||||
使用 Docker Compose 在局域网中部署 Gitea Git 服务，支持 HTTP 和 SSH 访问，启用 Git LFS 支持。
|
||||
使用 Docker Compose 在局域网中部署 Gitea Git 服务，支持 HTTP 和 SSH 访问，启用 Git LFS 支持。使用 PostgreSQL 替代 SQLite 以获得更好的并发性能（尤其是 LFS 大文件上传）。
|
||||
|
||||
## 需求
|
||||
|
||||
- 仅局域网使用
|
||||
- Docker Compose 容器化部署
|
||||
- 数据库：SQLite（简单可靠）
|
||||
- 数据库：PostgreSQL（解决 SQLite 文件锁导致的 LFS 上传瓶颈）
|
||||
- 访问方式：HTTP + SSH
|
||||
- 端口配置：通过 `.env` 文件灵活配置
|
||||
- 数据存储：宿主机目录挂载
|
||||
@@ -18,10 +18,15 @@
|
||||
## 技术选型
|
||||
|
||||
| 组件 | 选择 | 说明 |
|
||||
|-----|------|-----|
|
||||
|-----|------|------|
|
||||
| Gitea 版本 | 1.25.4 | 当前最新稳定版 |
|
||||
| 数据库 | SQLite | 零配置，适合小规模使用 |
|
||||
| 数据库 | PostgreSQL 16 | 并发写入性能好，解决 SQLite 文件锁瓶颈 |
|
||||
| 容器镜像 | gitea/gitea:1.25.4 | 官方镜像，固定版本 |
|
||||
| 数据库镜像 | postgres:16-alpine | 轻量 PostgreSQL，~80MB |
|
||||
|
||||
### 为什么从 SQLite 迁移到 PostgreSQL
|
||||
|
||||
SQLite 使用文件级写锁，在 LFS 大文件上传时，元数据写入被串行化，导致上传速度被限制在约 1.7 MB/s。PostgreSQL 支持并发写入，消除了这个瓶颈。
|
||||
|
||||
## 目录结构
|
||||
|
||||
@@ -29,14 +34,18 @@
|
||||
gitea/
|
||||
├── docker-compose.yml # 容器编排配置
|
||||
├── .env # 环境变量（端口等配置）
|
||||
├── .env.example # 环境变量示例
|
||||
├── .gitignore # 忽略数据目录和敏感文件
|
||||
├── Caddyfile # Caddy 反向代理配置（可选）
|
||||
├── README.md # 使用说明
|
||||
└── data/ # Gitea 数据（挂载目录）
|
||||
├── git/ # Git 仓库数据
|
||||
│ ├── repositories/ # 仓库存储
|
||||
│ └── lfs/ # LFS 文件存储
|
||||
├── gitea/ # Gitea 配置和数据库
|
||||
│ ├── gitea.db # SQLite 数据库（用户数据）
|
||||
├── gitea/ # Gitea 配置
|
||||
│ ├── gitea.db # SQLite 数据库（迁移后保留作备份）
|
||||
│ └── conf/app.ini # 配置文件
|
||||
├── postgres/ # PostgreSQL 数据
|
||||
└── ssh/ # SSH 密钥
|
||||
```
|
||||
|
||||
@@ -55,31 +64,73 @@ SSH_PORT=2222
|
||||
# 时区
|
||||
TZ=Asia/Shanghai
|
||||
|
||||
# PostgreSQL 配置
|
||||
POSTGRES_VERSION=16-alpine
|
||||
POSTGRES_DB=gitea
|
||||
POSTGRES_USER=gitea
|
||||
POSTGRES_PASSWORD=changeme
|
||||
|
||||
# Git LFS 配置
|
||||
GITEA__lfs__START_SERVER=true
|
||||
GITEA__lfs__PATH=/data/git/lfs
|
||||
|
||||
# 禁用公开注册
|
||||
GITEA__service__DISABLE_REGISTRATION=true
|
||||
|
||||
# 域名配置
|
||||
DOMAIN=git.example.com
|
||||
ROOT_URL=http://${DOMAIN}:${HTTP_PORT}/
|
||||
```
|
||||
|
||||
### docker-compose.yml
|
||||
|
||||
#### Gitea 服务
|
||||
|
||||
- 镜像：`gitea/gitea:${GITEA_VERSION}`
|
||||
- 端口映射：
|
||||
- `${HTTP_PORT}:3000` - Web 界面和 HTTP Git 操作
|
||||
- `${SSH_PORT}:22` - SSH Git 操作
|
||||
- 数据卷挂载：`./data:/data`
|
||||
- 环境变量：从 `.env` 文件读取
|
||||
- 环境变量：从 `.env` 文件读取（数据库连接通过 `GITEA__database__*` 环境变量覆盖 app.ini）
|
||||
- 依赖：`postgres`（健康检查通过后启动）
|
||||
- 重启策略：`always`
|
||||
- 网络：bridge 模式
|
||||
|
||||
#### PostgreSQL 服务
|
||||
|
||||
- 镜像：`postgres:${POSTGRES_VERSION}`（默认 16-alpine）
|
||||
- 环境变量：`POSTGRES_DB`、`POSTGRES_USER`、`POSTGRES_PASSWORD`
|
||||
- 数据卷挂载：`./data/postgres:/var/lib/postgresql/data`
|
||||
- 健康检查：`pg_isready`，5 秒间隔，3 秒超时，5 次重试
|
||||
- 重启策略：`always`
|
||||
|
||||
#### Caddy 服务（可选，--profile caddy）
|
||||
|
||||
- 镜像：`caddy:2`
|
||||
- 端口：80、443
|
||||
- 配置：`./Caddyfile` 只读挂载
|
||||
- 依赖：`gitea`
|
||||
|
||||
### .gitignore
|
||||
|
||||
忽略 `data/` 目录和 `.env` 文件（避免敏感信息提交）
|
||||
忽略 `data/` 目录、`.env` 文件、Caddy 数据目录（避免敏感信息提交）
|
||||
|
||||
## 数据库配置说明
|
||||
|
||||
数据库配置通过 docker-compose.yml 中的 `GITEA__database__*` 环境变量设置，优先级高于 `app.ini`：
|
||||
|
||||
| 环境变量 | 值 | 说明 |
|
||||
|---------|---|------|
|
||||
| `GITEA__database__DB_TYPE` | `postgres` | 数据库类型 |
|
||||
| `GITEA__database__HOST` | `postgres:5432` | Docker 内部网络连接 |
|
||||
| `GITEA__database__NAME` | `${POSTGRES_DB}` | 数据库名 |
|
||||
| `GITEA__database__USER` | `${POSTGRES_USER}` | 用户名 |
|
||||
| `GITEA__database__PASSWD` | `${POSTGRES_PASSWORD}` | 密码 |
|
||||
|
||||
## 数据存储说明
|
||||
|
||||
| 数据类型 | 容器内路径 | 宿主机路径 |
|
||||
|---------|-----------|-----------|
|
||||
| 用户账户、权限 | /data/gitea/gitea.db | ./data/gitea/gitea.db |
|
||||
| PostgreSQL 数据 | /var/lib/postgresql/data | ./data/postgres/ |
|
||||
| Git 仓库 | /data/git/repositories/ | ./data/git/repositories/ |
|
||||
| SSH 密钥 | /data/git/.ssh/ | ./data/git/.ssh/ |
|
||||
| LFS 文件 | /data/git/lfs/ | ./data/git/lfs/ |
|
||||
@@ -103,20 +154,25 @@ docker compose up -d
|
||||
|
||||
首次访问 Web 界面会进入安装向导，需要：
|
||||
1. 设置管理员账户
|
||||
2. 配置服务器域名等基本信息
|
||||
3. 数据库已使用 SQLite，无需额外配置
|
||||
2. 数据库已通过环境变量配置为 PostgreSQL，无需手动设置
|
||||
|
||||
### 备份
|
||||
|
||||
备份 `./data/` 目录即可，特别是：
|
||||
- `./data/gitea/gitea.db` - 用户和配置数据
|
||||
- `./data/git/repositories/` - 仓库数据
|
||||
- `./data/git/lfs/` - LFS 文件
|
||||
```bash
|
||||
# 导出数据库
|
||||
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/
|
||||
```
|
||||
|
||||
## 文件清单
|
||||
|
||||
需要创建的文件：
|
||||
1. `docker-compose.yml` - Docker Compose 配置
|
||||
2. `.env` - 环境变量配置
|
||||
3. `.gitignore` - Git 忽略规则
|
||||
4. `README.md` - 使用说明文档
|
||||
| 文件 | 职责 |
|
||||
|-----|------|
|
||||
| `docker-compose.yml` | 容器编排：Gitea + PostgreSQL + Caddy |
|
||||
| `.env` | 环境变量：版本、端口、数据库、域名 |
|
||||
| `.env.example` | 环境变量示例 |
|
||||
| `.gitignore` | 忽略数据目录和敏感文件 |
|
||||
| `Caddyfile` | Caddy 反向代理配置 |
|
||||
| `README.md` | 使用说明文档 |
|
||||
|
||||
Reference in New Issue
Block a user