# Gitea 局域网部署设计

## 概述

使用 Docker Compose 在局域网中部署 Gitea Git 服务，支持 HTTP 和 SSH 访问，启用 Git LFS 支持。使用 PostgreSQL 替代 SQLite 以获得更好的并发性能（尤其是 LFS 大文件上传）。

## 需求

- 仅局域网使用
- Docker Compose 容器化部署
- 数据库：PostgreSQL（解决 SQLite 文件锁导致的 LFS 上传瓶颈）
- 访问方式：HTTP + SSH
- 端口配置：通过 `.env` 文件灵活配置
- 数据存储：宿主机目录挂载
- 支持 Git LFS
- 镜像版本：固定版本（避免 latest）

## 技术选型

| 组件 | 选择 | 说明 |
|-----|------|------|
| Gitea 版本 | 1.25.4 | 当前最新稳定版 |
| 数据库 | PostgreSQL 16 | 并发写入性能好，解决 SQLite 文件锁瓶颈 |
| 容器镜像 | gitea/gitea:1.25.4 | 官方镜像，固定版本 |
| 数据库镜像 | postgres:16-alpine | 轻量 PostgreSQL，~80MB |

### 为什么从 SQLite 迁移到 PostgreSQL

SQLite 使用文件级写锁，在 LFS 大文件上传时，元数据写入被串行化，导致上传速度被限制在约 1.7 MB/s。PostgreSQL 支持并发写入，消除了这个瓶颈。

## 目录结构

```
gitea/
├── docker-compose.yml    # 容器编排配置
├── .env                  # 环境变量（端口等配置）
├── .env.example          # 环境变量示例
├── .gitignore            # 忽略数据目录和敏感文件
├── Caddyfile             # Caddy 反向代理配置（可选）
├── README.md             # 使用说明
└── data/                 # Gitea 数据（挂载目录）
    ├── git/              # Git 仓库数据
    │   ├── repositories/ # 仓库存储
    │   └── lfs/          # LFS 文件存储
    ├── gitea/            # Gitea 配置
    │   ├── gitea.db      # SQLite 数据库（迁移后保留作备份）
    │   └── conf/app.ini  # 配置文件
    ├── postgres/         # PostgreSQL 数据
    └── ssh/              # SSH 密钥
```

## 配置文件

### .env - 环境变量

```env
# 镜像版本
GITEA_VERSION=1.25.4

# 端口配置
HTTP_PORT=3000
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` 文件读取（数据库连接通过 `GITEA__database__*` 环境变量覆盖 app.ini）
- 依赖：`postgres`（健康检查通过后启动）
- 重启策略：`always`

#### 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` 文件、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}` | 密码 |

## 数据存储说明

| 数据类型 | 容器内路径 | 宿主机路径 |
|---------|-----------|-----------|
| 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/ |
| 配置文件 | /data/gitea/conf/app.ini | ./data/gitea/conf/app.ini |

## 使用方式

### 启动服务

```bash
docker compose up -d
```

### 访问方式

- Web 界面：`http://<服务器IP>:3000`
- HTTP 克隆：`git clone http://<服务器IP>:3000/用户/仓库.git`
- SSH 克隆：`git clone ssh://git@<服务器IP>:2222/用户/仓库.git`

### 初始配置

首次访问 Web 界面会进入安装向导，需要：
1. 设置管理员账户
2. 数据库已通过环境变量配置为 PostgreSQL，无需手动设置

### 备份

```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/
```

## 文件清单

| 文件 | 职责 |
|-----|------|
| `docker-compose.yml` | 容器编排：Gitea + PostgreSQL + Caddy |
| `.env` | 环境变量：版本、端口、数据库、域名 |
| `.env.example` | 环境变量示例 |
| `.gitignore` | 忽略数据目录和敏感文件 |
| `Caddyfile` | Caddy 反向代理配置 |
| `README.md` | 使用说明文档 |