add PostgreSQL to replace SQLite for better LFS upload concurrency

2026-04-27 15:35:34 +08:00
parent ff0929dc02
commit b68c715f6b
5 changed files with 244 additions and 194 deletions
--- a/docs/superpowers/plans/2026-03-20-gitea-lan-deployment.md
+++ b/docs/superpowers/plans/2026-03-20-gitea-lan-deployment.md
@@ -2,11 +2,11 @@

 > **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
+**Goal:** 使用 Docker Compose 部署 Gitea Git 服务，支持 HTTP/SSH 访问、Git LFS 和 PostgreSQL 数据库

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

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

 ---

@@ -14,14 +14,16 @@

 | 文件 | 职责 |
 |-----|------|
-| `docker-compose.yml` | 容器编排配置：镜像、端口、卷、环境变量 |
-| `.env` | 可配置参数：版本、端口、时区、LFS 配置 |
+| `docker-compose.yml` | 容器编排：Gitea + PostgreSQL + Caddy（可选） |
+| `.env` | 可配置参数：版本、端口、时区、数据库、域名 |
+| `.env.example` | 环境变量示例（无敏感信息） |
+| `Caddyfile` | Caddy 反向代理配置 |
 | `.gitignore` | 忽略数据目录和环境变量文件 |
-| `README.md` | 使用说明：启动、访问、备份 |
+| `README.md` | 使用说明：启动、访问、备份、迁移 |

 ---

-## Chunk 1: 基础配置文件
+## Chunk 1: 核心配置文件

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

@@ -41,9 +43,25 @@ 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: 验证文件创建成功**
@@ -60,28 +78,11 @@ Expected: 显示上述内容

 - [ ] **Step 1: 创建 docker-compose.yml 文件**

-```yaml
-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
-```
+关键配置：
+- Gitea 服务：通过 `GITEA__database__*` 环境变量连接 PostgreSQL
+- PostgreSQL 服务：`postgres:16-alpine`，健康检查 `pg_isready`
+- Gitea `depends_on` PostgreSQL（健康检查通过后才启动）
+- Caddy 服务：`profiles: [caddy]`，可选启用

 - [ ] **Step 2: 验证 Docker Compose 配置语法**

@@ -104,154 +105,44 @@ data/
 # 环境变量（可能包含敏感信息）
 .env

+# Caddy 数据
+caddy_data/
+caddy_config/
+
 # macOS
 .DS_Store
 ```

- [ ] **Step 2: 验证文件创建成功**
-
-Run: `cat .gitignore`
-Expected: 显示上述内容
-
 ---

-### Task 4: 创建 README.md 使用说明
-
-**Files:**
- Create: `README.md`
-
- [ ] **Step 1: 创建 README.md 文件**
-
-```markdown
-# Gitea 局域网部署
-
-使用 Docker Compose 部署的 Gitea Git 服务。
-
-## 快速开始
-
-### 1. 配置环境变量
-
-复制并编辑 `.env` 文件：
-
-```bash
-cp .env.example .env
-```
-
-修改端口等配置：
-
-```env
-HTTP_PORT=3000    # Web 界面端口
-SSH_PORT=2222     # SSH 端口
-```
-
-### 2. 启动服务
-
-```bash
-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 支持，使用方法：
-
-```bash
-git lfs install
-git lfs track "*.psd"
-git add .gitattributes
-git commit -m "Track PSD files with LFS"
-git push
-```
-
-## 数据备份
-
-备份 `data/` 目录：
-
-```bash
-# 备份
-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 文件
-
-## 常用命令
-
-```bash
-# 启动
-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 示例文件
+### Task 4: 创建 .env.example

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

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

-```env
-# Gitea 版本
-GITEA_VERSION=1.25.4
+与 `.env` 结构相同，但密码使用占位值 `changeme`。

-# 端口配置
-HTTP_PORT=3000
-SSH_PORT=2222
+---

-# 时区
-TZ=Asia/Shanghai
+## Chunk 2: 文档和验证

-# Git LFS 配置
-GITEA__lfs__START_SERVER=true
-GITEA__lfs__PATH=/data/git/lfs
-```
+### Task 5: 创建 README.md 使用说明

- [ ] **Step 2: 验证文件创建成功**
+**Files:**
+- Create: `README.md`

-Run: `cat .env.example`
-Expected: 显示上述内容
+- [ ] **Step 1: 创建 README.md 文件**
+
+内容包含：
+- 架构说明（HTTP 模式 / Caddy 模式）
+- 快速开始（配置 → 启动 → 初始设置）
+- 访问方式
+- Git LFS 使用
+- 数据备份（PostgreSQL pg_dump + 数据目录）
+- SQLite 迁移到 PostgreSQL 步骤
+- 常用命令

 ---

@@ -265,12 +156,12 @@ Expected: 显示 `docker-compose.yml`, `.env`, `.env.example`, `.gitignore`, `RE
 - [ ] **Step 2: 验证 Docker Compose 配置**

 Run: `docker compose config`
-Expected: 无错误输出，显示完整配置
+Expected: 无错误输出，显示完整配置（包含 gitea、postgres、caddy 服务）

 - [ ] **Step 3: （可选）启动服务测试**

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

 ---

@@ -278,5 +169,6 @@ Expected: 容器启动成功

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