add PostgreSQL to replace SQLite for better LFS upload concurrency

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

@@ -2,13 +2,13 @@
 
 ## 概述
 
-使用 Docker Compose 在局域网中部署 Gitea Git 服务，支持 HTTP 和 SSH 访问，启用 Git LFS 支持。
+使用 Docker Compose 在局域网中部署 Gitea Git 服务，支持 HTTP 和 SSH 访问，启用 Git LFS 支持。使用 PostgreSQL 替代 SQLite 以获得更好的并发性能（尤其是 LFS 大文件上传）。
 
 ## 需求
 
 - 仅局域网使用
 - Docker Compose 容器化部署
-- 数据库：SQLite（简单可靠）
+- 数据库：PostgreSQL（解决 SQLite 文件锁导致的 LFS 上传瓶颈）
 - 访问方式：HTTP + SSH
 - 端口配置：通过 `.env` 文件灵活配置
 - 数据存储：宿主机目录挂载
@@ -18,10 +18,15 @@
 ## 技术选型
 
 | 组件 | 选择 | 说明 |
-|-----|------|-----|
+|-----|------|------|
 | Gitea 版本 | 1.25.4 | 当前最新稳定版 |
-| 数据库 | SQLite | 零配置，适合小规模使用 |
+| 数据库 | PostgreSQL 16 | 并发写入性能好，解决 SQLite 文件锁瓶颈 |
 | 容器镜像 | gitea/gitea:1.25.4 | 官方镜像，固定版本 |
+| 数据库镜像 | postgres:16-alpine | 轻量 PostgreSQL，~80MB |
+
+### 为什么从 SQLite 迁移到 PostgreSQL
+
+SQLite 使用文件级写锁，在 LFS 大文件上传时，元数据写入被串行化，导致上传速度被限制在约 1.7 MB/s。PostgreSQL 支持并发写入，消除了这个瓶颈。
 
 ## 目录结构
 
@@ -29,14 +34,18 @@
 gitea/
 ├── docker-compose.yml    # 容器编排配置
 ├── .env                  # 环境变量（端口等配置）
+├── .env.example          # 环境变量示例
 ├── .gitignore            # 忽略数据目录和敏感文件
+├── Caddyfile             # Caddy 反向代理配置（可选）
+├── README.md             # 使用说明
 └── data/                 # Gitea 数据（挂载目录）
     ├── git/              # Git 仓库数据
     │   ├── repositories/ # 仓库存储
     │   └── lfs/          # LFS 文件存储
-    ├── gitea/            # Gitea 配置和数据库
-    │   ├── gitea.db      # SQLite 数据库（用户数据）
+    ├── gitea/            # Gitea 配置
+    │   ├── gitea.db      # SQLite 数据库（迁移后保留作备份）
     │   └── conf/app.ini  # 配置文件
+    ├── postgres/         # PostgreSQL 数据
     └── ssh/              # SSH 密钥
 ```
 
@@ -55,31 +64,73 @@ SSH_PORT=2222
 # 时区
 TZ=Asia/Shanghai
 
+# PostgreSQL 配置
+POSTGRES_VERSION=16-alpine
+POSTGRES_DB=gitea
+POSTGRES_USER=gitea
+POSTGRES_PASSWORD=changeme
+
 # Git LFS 配置
 GITEA__lfs__START_SERVER=true
 GITEA__lfs__PATH=/data/git/lfs
+
+# 禁用公开注册
+GITEA__service__DISABLE_REGISTRATION=true
+
+# 域名配置
+DOMAIN=git.example.com
+ROOT_URL=http://${DOMAIN}:${HTTP_PORT}/
 ```
 
 ### docker-compose.yml
 
+#### Gitea 服务
+
 - 镜像：`gitea/gitea:${GITEA_VERSION}`
 - 端口映射：
   - `${HTTP_PORT}:3000` - Web 界面和 HTTP Git 操作
   - `${SSH_PORT}:22` - SSH Git 操作
 - 数据卷挂载：`./data:/data`
-- 环境变量：从 `.env` 文件读取
+- 环境变量：从 `.env` 文件读取（数据库连接通过 `GITEA__database__*` 环境变量覆盖 app.ini）
+- 依赖：`postgres`（健康检查通过后启动）
 - 重启策略：`always`
-- 网络：bridge 模式
+
+#### PostgreSQL 服务
+
+- 镜像：`postgres:${POSTGRES_VERSION}`（默认 16-alpine）
+- 环境变量：`POSTGRES_DB`、`POSTGRES_USER`、`POSTGRES_PASSWORD`
+- 数据卷挂载：`./data/postgres:/var/lib/postgresql/data`
+- 健康检查：`pg_isready`，5 秒间隔，3 秒超时，5 次重试
+- 重启策略：`always`
+
+#### Caddy 服务（可选，--profile caddy）
+
+- 镜像：`caddy:2`
+- 端口：80、443
+- 配置：`./Caddyfile` 只读挂载
+- 依赖：`gitea`
 
 ### .gitignore
 
-忽略 `data/` 目录和 `.env` 文件（避免敏感信息提交）
+忽略 `data/` 目录、`.env` 文件、Caddy 数据目录（避免敏感信息提交）
+
+## 数据库配置说明
+
+数据库配置通过 docker-compose.yml 中的 `GITEA__database__*` 环境变量设置，优先级高于 `app.ini`：
+
+| 环境变量 | 值 | 说明 |
+|---------|---|------|
+| `GITEA__database__DB_TYPE` | `postgres` | 数据库类型 |
+| `GITEA__database__HOST` | `postgres:5432` | Docker 内部网络连接 |
+| `GITEA__database__NAME` | `${POSTGRES_DB}` | 数据库名 |
+| `GITEA__database__USER` | `${POSTGRES_USER}` | 用户名 |
+| `GITEA__database__PASSWD` | `${POSTGRES_PASSWORD}` | 密码 |
 
 ## 数据存储说明
 
 | 数据类型 | 容器内路径 | 宿主机路径 |
 |---------|-----------|-----------|
-| 用户账户、权限 | /data/gitea/gitea.db | ./data/gitea/gitea.db |
+| PostgreSQL 数据 | /var/lib/postgresql/data | ./data/postgres/ |
 | Git 仓库 | /data/git/repositories/ | ./data/git/repositories/ |
 | SSH 密钥 | /data/git/.ssh/ | ./data/git/.ssh/ |
 | LFS 文件 | /data/git/lfs/ | ./data/git/lfs/ |
@@ -103,20 +154,25 @@ docker compose up -d
 
 首次访问 Web 界面会进入安装向导，需要：
 1. 设置管理员账户
-2. 配置服务器域名等基本信息
-3. 数据库已使用 SQLite，无需额外配置
+2. 数据库已通过环境变量配置为 PostgreSQL，无需手动设置
 
 ### 备份
 
-备份 `./data/` 目录即可，特别是：
-- `./data/gitea/gitea.db` - 用户和配置数据
-- `./data/git/repositories/` - 仓库数据
-- `./data/git/lfs/` - LFS 文件
+```bash
+# 导出数据库
+docker exec postgres pg_dump -U gitea gitea > gitea-db-$(date +%Y%m%d).sql
+
+# 备份数据目录
+tar -czvf gitea-data-$(date +%Y%m%d).tar.gz data/
+```
 
 ## 文件清单
 
-需要创建的文件：
-1. `docker-compose.yml` - Docker Compose 配置
-2. `.env` - 环境变量配置
-3. `.gitignore` - Git 忽略规则
-4. `README.md` - 使用说明文档
+| 文件 | 职责 |
+|-----|------|
+| `docker-compose.yml` | 容器编排：Gitea + PostgreSQL + Caddy |
+| `.env` | 环境变量：版本、端口、数据库、域名 |
+| `.env.example` | 环境变量示例 |
+| `.gitignore` | 忽略数据目录和敏感文件 |
+| `Caddyfile` | Caddy 反向代理配置 |
+| `README.md` | 使用说明文档 |