# 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 文件**

```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 文件**

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