179 lines
5.4 KiB
Markdown
179 lines
5.4 KiB
Markdown
# 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` | 使用说明文档 |
|