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

Gitea 局域网部署实现计划

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

Architecture: 单容器部署，SQLite 数据库，宿主机目录挂载持久化数据，通过 .env 文件配置端口和环境变量

Tech Stack: Docker Compose, Gitea 1.25.4, SQLite

---

文件结构

文件	职责
docker-compose.yml	容器编排配置：镜像、端口、卷、环境变量
.env	可配置参数：版本、端口、时区、LFS 配置
.gitignore	忽略数据目录和环境变量文件
README.md	使用说明：启动、访问、备份

---

Chunk 1: 基础配置文件

Task 1: 创建 .env 环境变量文件

Files:

• Create: .env

• Step 1: 创建 .env 文件

# Gitea 版本
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

• Step 2: 验证文件创建成功

Run: cat .env Expected: 显示上述内容

---

Task 2: 创建 docker-compose.yml

Files:

• Create: docker-compose.yml

• Step 1: 创建 docker-compose.yml 文件

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

• Step 2: 验证 Docker Compose 配置语法

Run: docker compose config Expected: 无错误，显示解析后的配置

---

Task 3: 创建 .gitignore

Files:

• Create: .gitignore

• Step 1: 创建 .gitignore 文件

# 数据目录
data/

# 环境变量（可能包含敏感信息）
.env

# macOS
.DS_Store

• Step 2: 验证文件创建成功

Run: cat .gitignore Expected: 显示上述内容

---

Task 4: 创建 README.md 使用说明

Files:

• Create: README.md

• Step 1: 创建 README.md 文件

# Gitea 局域网部署

使用 Docker Compose 部署的 Gitea Git 服务。

## 快速开始

### 1. 配置环境变量

复制并编辑 `.env` 文件：

```bash
cp .env.example .env

修改端口等配置：

HTTP_PORT=3000    # Web 界面端口
SSH_PORT=2222     # SSH 端口

2. 启动服务

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 支持，使用方法：

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

数据备份

备份 data/ 目录：

# 备份
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 文件

常用命令

# 启动
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 示例文件

**Files:**
- Create: `.env.example`

- [ ] **Step 1: 创建 .env.example 文件**

```env
# Gitea 版本
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

• Step 2: 验证文件创建成功

Run: cat .env.example Expected: 显示上述内容

---

Task 6: 最终验证

• Step 1: 检查所有文件已创建

Run: ls -la Expected: 显示 docker-compose.yml, .env, .env.example, .gitignore, README.md

• Step 2: 验证 Docker Compose 配置

Run: docker compose config Expected: 无错误输出，显示完整配置

• Step 3: （可选）启动服务测试

Run: docker compose up -d Expected: 容器启动成功

---

完成标准

• 所有配置文件已创建
• docker compose config 验证通过
• 服务可以正常启动
• 可以通过 Web 界面访问安装向导