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 和 PostgreSQL 数据库

Architecture: Gitea + PostgreSQL 双容器部署，宿主机目录挂载持久化数据，通过 .env 文件配置端口和环境变量，Caddy 可选反向代理

Tech Stack: Docker Compose, Gitea 1.25.4, PostgreSQL 16 (alpine), Caddy 2 (可选)

---

文件结构

文件	职责
docker-compose.yml	容器编排：Gitea + PostgreSQL + Caddy（可选）
.env	可配置参数：版本、端口、时区、数据库、域名
.env.example	环境变量示例（无敏感信息）
Caddyfile	Caddy 反向代理配置
.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

# 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: 验证文件创建成功

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

---

Task 2: 创建 docker-compose.yml

Files:

• Create: docker-compose.yml

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

关键配置：

• Gitea 服务：通过 GITEA__database__* 环境变量连接 PostgreSQL

• PostgreSQL 服务：postgres:16-alpine，健康检查 pg_isready

• Gitea depends_on PostgreSQL（健康检查通过后才启动）

• Caddy 服务：profiles: [caddy]，可选启用

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

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

---

Task 3: 创建 .gitignore

Files:

• Create: .gitignore

• Step 1: 创建 .gitignore 文件

# 数据目录
data/

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

# Caddy 数据
caddy_data/
caddy_config/

# macOS
.DS_Store

---

Task 4: 创建 .env.example

Files:

• Create: .env.example

• Step 1: 创建 .env.example 文件

与 .env 结构相同，但密码使用占位值 changeme。

---

Chunk 2: 文档和验证

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

Files:

• Create: README.md

• Step 1: 创建 README.md 文件

内容包含：

• 架构说明（HTTP 模式 / Caddy 模式）
• 快速开始（配置 → 启动 → 初始设置）
• 访问方式
• Git LFS 使用
• 数据备份（PostgreSQL pg_dump + 数据目录）
• SQLite 迁移到 PostgreSQL 的安全入口说明，链接到 docs/sqlite-to-postgres-migration.md
• 常用命令

---

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: 无错误输出，显示完整配置（包含 gitea、postgres、caddy 服务）

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

Run: docker compose up -d Expected: postgres 和 gitea 容器均启动成功

---

完成标准

• 所有配置文件已创建
• docker compose config 验证通过
• 服务可以正常启动（Gitea + PostgreSQL）
• 可以通过 Web 界面访问安装向导
• 数据库连接正常（安装向导中数据库类型显示为 PostgreSQL）