gitea/docs/superpowers/specs/2026-03-20-gitea-lan-deployment-design.md

Gitea 局域网部署设计

概述

使用 Docker Compose 在局域网中部署 Gitea Git 服务，支持 HTTP 和 SSH 访问，启用 Git LFS 支持。

需求

• 仅局域网使用
• Docker Compose 容器化部署
• 数据库：SQLite（简单可靠）
• 访问方式：HTTP + SSH
• 端口配置：通过 .env 文件灵活配置
• 数据存储：宿主机目录挂载
• 支持 Git LFS
• 镜像版本：固定版本（避免 latest）

技术选型

组件	选择	说明
Gitea 版本	1.25.4	当前最新稳定版
数据库	SQLite	零配置，适合小规模使用
容器镜像	gitea/gitea:1.25.4	官方镜像，固定版本

目录结构

gitea/
├── docker-compose.yml    # 容器编排配置
├── .env                  # 环境变量（端口等配置）
├── .gitignore            # 忽略数据目录和敏感文件
└── data/                 # Gitea 数据（挂载目录）
    ├── git/              # Git 仓库数据
    │   ├── repositories/ # 仓库存储
    │   └── lfs/          # LFS 文件存储
    ├── gitea/            # Gitea 配置和数据库
    │   ├── gitea.db      # SQLite 数据库（用户数据）
    │   └── conf/app.ini  # 配置文件
    └── ssh/              # SSH 密钥

配置文件

.env - 环境变量

# 镜像版本
GITEA_VERSION=1.25.4

# 端口配置
HTTP_PORT=3000
SSH_PORT=2222

# 时区
TZ=Asia/Shanghai

# Git LFS 配置
GITEA__lfs__START_SERVER=true
GITEA__lfs__PATH=/data/git/lfs

docker-compose.yml

• 镜像：gitea/gitea:${GITEA_VERSION}
• 端口映射：
  • ${HTTP_PORT}:3000 - Web 界面和 HTTP Git 操作
  • ${SSH_PORT}:22 - SSH Git 操作
• 数据卷挂载：./data:/data
• 环境变量：从 .env 文件读取
• 重启策略：always
• 网络：bridge 模式

.gitignore

忽略 data/ 目录和 .env 文件（避免敏感信息提交）

数据存储说明

数据类型	容器内路径	宿主机路径
用户账户、权限	/data/gitea/gitea.db	./data/gitea/gitea.db
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

使用方式

启动服务

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. 配置服务器域名等基本信息
3. 数据库已使用 SQLite，无需额外配置

备份

备份 ./data/ 目录即可，特别是：

• ./data/gitea/gitea.db - 用户和配置数据
• ./data/git/repositories/ - 仓库数据
• ./data/git/lfs/ - LFS 文件

文件清单

需要创建的文件：

1. docker-compose.yml - Docker Compose 配置
2. .env - 环境变量配置
3. .gitignore - Git 忽略规则
4. README.md - 使用说明文档