docs: add LFS COS storage migration guide with DNS bucket lookup fix

Documents how to migrate Gitea LFS from local disk to Tencent Cloud COS,
including the required MINIO_BUCKET_LOOKUP_TYPE=dns setting for COS compatibility.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.env.example

@@ -17,3 +17,17 @@ 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：决定 Gitea UI 中的链接生成
+# 不使用 Caddy（仅 HTTP）：ROOT_URL=http://${DOMAIN}:${HTTP_PORT}/
+# 使用 Caddy（HTTP + HTTPS）：ROOT_URL=https://${DOMAIN}/
+ROOT_URL=http://${DOMAIN}:${HTTP_PORT}/

.gitignore

@@ -4,5 +4,12 @@ data/
 # 环境变量（可能包含敏感信息）
 .env
 
+# Caddy 数据
+caddy_data/
+caddy_config/
+
+# 备份
+backup/
+
 # macOS
 .DS_Store

Caddyfile

@@ -0,0 +1,7 @@
+http://{$DOMAIN} {
+	reverse_proxy gitea:3000
+}
+
+https://{$DOMAIN} {
+	reverse_proxy gitea:3000
+}

README.md

@@ -1,48 +1,98 @@
-# Gitea 局域网部署
+# Gitea Docker 部署
 
-使用 Docker Compose 部署的 Gitea Git 服务。
+使用 Docker Compose 部署 Gitea，支持两种模式：
+
+- **HTTP 模式**：Gitea 直接暴露端口，仅 HTTP
+- **Caddy 模式**：通过 Caddy 反向代理，同时支持 HTTP 和 HTTPS（自动证书）
+
+## 架构
+
+### HTTP 模式（默认）
+
+```
+Client → Gitea (HTTP_PORT, e.g. 3000)
+           ├─ PostgreSQL (5432, Docker 内部网络)
+           └─ Gitea SSH (22 → 宿主机 SSH_PORT)
+```
+
+### Caddy 模式（--profile caddy）
+
+```
+Client → Caddy (80/443, HTTP + HTTPS) → Gitea (3000, Docker 内部网络)
+                                         ├─ PostgreSQL (5432, Docker 内部网络)
+                                         └─ Gitea SSH (22 → 宿主机 SSH_PORT)
+```
 
 ## 快速开始
 
-### 1. 配置环境变量
+### 前提条件
 
-复制并编辑 `.env` 文件：
+- 服务器 `SSH_PORT`（默认 2222）端口可从外网访问
+- 如使用 Caddy 模式：域名已解析到服务器公网 IP，且 80、443 端口可从外网访问
+
+### 1. 配置环境变量
 
 ```bash
 cp .env.example .env
 ```
 
-修改端口等配置：
+编辑 `.env`，关键配置：
 
 ```env
-HTTP_PORT=3000    # Web 界面端口
+DOMAIN=git.example.com    # 你的域名
 SSH_PORT=2222             # SSH 端口（宿主机端口，容器内仍为 22）
+POSTGRES_PASSWORD=changeme  # PostgreSQL 密码（务必修改）
 ```
 
-> `GITEA__server__SSH_PORT` 已通过 `.env` 传递给容器，告知 Gitea 对外 SSH 端口为 `2222`，
+#### HTTP 模式
-> 使 Web 界面中的 SSH clone 地址正确显示端口号。
+
+```env
+ROOT_URL=http://git.example.com:3000/
+```
+
+#### Caddy 模式
+
+```env
+ROOT_URL=https://git.example.com/
+```
 
 ### 2. 启动服务
 
 ```bash
+# HTTP 模式（仅 Gitea + PostgreSQL，无 Caddy）
 docker compose up -d
+
+# Caddy 模式（HTTP + HTTPS，Caddy 反向代理）
+docker compose --profile caddy up -d
 ```
 
+> Caddy 会自动为 `DOMAIN` 申请 Let's Encrypt 证书，稍等片刻后即可通过 HTTPS 访问。
+
 ### 3. 初始配置
 
-首次访问 `http://<服务器IP>:3000` 会进入安装向导：
+首次访问会进入安装向导：
 
 1. 设置管理员账户
-2. 配置服务器域名（可选）
+2. 数据库已通过环境变量配置为 PostgreSQL，无需手动设置
-3. 数据库已默认使用 SQLite
 
 ## 访问方式
 
+### HTTP 模式
+
 | 方式 | 地址 |
 |-----|------|
-| Web 界面 | `http://<IP>:3000` |
+| Web 界面 | `http://<DOMAIN>:<HTTP_PORT>` |
-| HTTP 克隆 | `git clone http://<IP>:3000/<用户>/<仓库>.git` |
+| HTTP 克隆 | `git clone http://<DOMAIN>:<HTTP_PORT>/<用户>/<仓库>.git` |
-| SSH 克隆 | `git clone ssh://git@<IP>:2222/<用户>/<仓库>.git` |
+| SSH 克隆 | `git clone ssh://git@<DOMAIN>:<SSH_PORT>/<用户>/<仓库>.git` |
+
+### Caddy 模式
+
+| 方式 | 地址 |
+|-----|------|
+| Web 界面 | `https://<DOMAIN>` |
+| HTTP 克隆 | `git clone http://<DOMAIN>/<用户>/<仓库>.git` |
+| HTTPS 克隆 | `git clone https://<DOMAIN>/<用户>/<仓库>.git` |
+| SSH 克隆 | `git clone ssh://git@<DOMAIN>:<SSH_PORT>/<用户>/<仓库>.git` |
 
 ## Git LFS
 
@@ -58,37 +108,71 @@ git push
 
 ## 数据备份
 
-备份 `data/` 目录：
+### 备份 PostgreSQL 数据库
 
 ```bash
-# 备份
+docker exec postgres pg_dump -U gitea gitea > gitea-db-$(date +%Y%m%d).sql
-tar -czvf gitea-backup-$(date +%Y%m%d).tar.gz data/
+```
 
-# 恢复
+### 备份全部数据
-tar -xzvf gitea-backup-20260320.tar.gz
+
+```bash
+# 备份数据目录 + 数据库导出
+tar -czvf gitea-data-$(date +%Y%m%d).tar.gz data/
+docker exec postgres pg_dump -U gitea gitea > gitea-db-$(date +%Y%m%d).sql
+```
+
+> 如果当前生产服务仍在使用旧版 SQLite，请在迁移前停止 Gitea，并至少备份 `data/gitea/gitea.db` 和完整 `data/` 目录。完整流程见 [SQLite 迁移到 PostgreSQL](docs/sqlite-to-postgres-migration.md)。
+
+### 恢复数据库
+
+```bash
+cat gitea-db-20260327.sql | docker exec -i postgres psql -U gitea gitea
 ```
 
 重要文件：
-- `data/gitea/gitea.db` - 用户和配置数据
+
+- `data/postgres/` - PostgreSQL 数据
 - `data/git/repositories/` - 仓库数据
 - `data/git/lfs/` - LFS 文件
+- `data/gitea/conf/app.ini` - Gitea 配置
+
+## SQLite 迁移到 PostgreSQL
+
+如果已有生产 Gitea 仍在使用旧版 Docker Compose 和 SQLite，不要直接启动最新 compose 覆盖数据库配置，也不要把 `gitea migrate` 当作数据搬迁命令。
+
+推荐流程是：停止旧 Gitea，冷备份 `data/gitea/gitea.db` 和 `data/`，更新到包含 PostgreSQL 的最新 commit，只启动空 PostgreSQL，用 `pgloader` 导入 SQLite 数据，最后启动 Gitea 并验证。
+
+完整步骤见 [docs/sqlite-to-postgres-migration.md](docs/sqlite-to-postgres-migration.md)。
 
 ## 常用命令
 
 ```bash
-# 启动
+# 启动（HTTP 模式）
 docker compose up -d
 
+# 启动（Caddy 模式）
+docker compose --profile caddy up -d
+
 # 停止
 docker compose down
 
 # 查看日志
 docker compose logs -f
 
+# 查看 PostgreSQL 日志
+docker compose logs -f postgres
+
+# 查看 Caddy 日志
+docker compose logs -f caddy
+
 # 重启
 docker compose restart
 
 # 更新版本
 # 修改 .env 中的 GITEA_VERSION 后
 docker compose up -d
+
+# 连接 PostgreSQL
+docker exec -it postgres psql -U gitea
 ```

docker-compose.yml

@@ -4,16 +4,61 @@ services:
     container_name: gitea
     environment:
       - TZ=${TZ}
+      - GITEA__database__DB_TYPE=postgres
+      - GITEA__database__HOST=postgres:5432
+      - GITEA__database__NAME=${POSTGRES_DB}
+      - GITEA__database__USER=${POSTGRES_USER}
+      - GITEA__database__PASSWD=${POSTGRES_PASSWORD}
       - GITEA__lfs__START_SERVER=${GITEA__lfs__START_SERVER}
       - GITEA__lfs__PATH=${GITEA__lfs__PATH}
       - GITEA__service__DISABLE_REGISTRATION=${GITEA__service__DISABLE_REGISTRATION}
       - GITEA__server__SSH_PORT=${GITEA__server__SSH_PORT}
+      - GITEA__server__ROOT_URL=${ROOT_URL}
+      - GITEA__server__DOMAIN=${DOMAIN}
+      - GITEA__server__SSH_DOMAIN=${DOMAIN}
     restart: always
     volumes:
       - ./data:/data
     ports:
       - "${HTTP_PORT}:3000"
       - "${SSH_PORT}:22"
+    depends_on:
+      postgres:
+        condition: service_healthy
+
+  postgres:
+    image: postgres:${POSTGRES_VERSION}
+    container_name: postgres
+    environment:
+      POSTGRES_DB: ${POSTGRES_DB}
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+    restart: always
+    volumes:
+      - ./data/postgres:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD", "pg_isready", "-U", "${POSTGRES_USER}"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+  caddy:
+    image: caddy:2
+    container_name: caddy
+    profiles:
+      - caddy
+    environment:
+      - DOMAIN=${DOMAIN}
+    restart: always
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+      - ./caddy_data:/data
+      - ./caddy_config:/config
+    depends_on:
+      - gitea
 
 networks:
   default:

docs/lfs-cos-storage.md

@@ -0,0 +1,179 @@
+# Gitea LFS 对接腾讯云 COS
+
+本文档适用于已通过本项目 Docker Compose 部署 Gitea，希望将 LFS 存储从本地磁盘迁移到腾讯云 COS 对象存储的场景。
+
+腾讯云轻量应用服务器（Lighthouse）可以正常使用，COS 通过 HTTPS 公网端点访问，无需额外网络配置。
+
+---
+
+## 一、腾讯云侧准备
+
+### 1.1 创建 COS Bucket
+
+进入 [COS 控制台](https://console.cloud.tencent.com/cos) → 存储桶列表 → 创建存储桶：
+
+| 选项 | 建议值 |
+|------|--------|
+| 地域 | 与服务器相同地域（降低延迟） |
+| 访问权限 | **私有读写** |
+| 版本控制 | 关闭（LFS 对象不需要） |
+
+创建后记录完整的 Bucket 名称，格式为 `<name>-<appid>`，例如 `gitea-lfs-1234567890`。
+
+### 1.2 创建 CAM 子账号并授权
+
+进入 [CAM 控制台](https://console.cloud.tencent.com/cam) → 用户管理 → 新建用户：
+
+- 用户类型选**编程访问**（只需 API 密钥，无需登录控制台）
+- 直接关联策略：搜索并勾选 `QcloudCOSDataFullControl`
+
+> 如需最小权限，自定义策略只需包含：
+> `GetObject` `PutObject` `DeleteObject` `HeadObject` `ListBucket`
+
+创建完成后保存 **SecretId** 和 **SecretKey**，页面关闭后无法再次查看。
+
+### 1.3 地域 ID 参考
+
+| 地域 | ID |
+|------|----|
+| 广州 | `ap-guangzhou` |
+| 上海 | `ap-shanghai` |
+| 北京 | `ap-beijing` |
+| 深圳 | `ap-shenzhen` |
+| 成都 | `ap-chengdu` |
+| 中国香港 | `ap-hongkong` |
+| 新加坡 | `ap-singapore` |
+
+---
+
+## 二、修改项目配置
+
+### 2.1 修改 `.env`
+
+将原来的本地 LFS 配置：
+
+```bash
+GITEA__lfs__START_SERVER=true
+GITEA__lfs__PATH=/data/git/lfs
+```
+
+替换为：
+
+```bash
+# Git LFS 配置 - 腾讯云 COS
+GITEA__lfs__START_SERVER=true
+GITEA__lfs__STORAGE_TYPE=minio
+GITEA__lfs__MINIO_ENDPOINT=cos.ap-guangzhou.myqcloud.com   # 改为你的地域
+GITEA__lfs__MINIO_ACCESS_KEY_ID=AKIDxxxxxxxxxx              # CAM SecretId
+GITEA__lfs__MINIO_SECRET_ACCESS_KEY=xxxxxxxxxx              # CAM SecretKey
+GITEA__lfs__MINIO_BUCKET=gitea-lfs-1234567890               # Bucket 完整名称
+GITEA__lfs__MINIO_LOCATION=ap-guangzhou                     # 改为你的地域
+GITEA__lfs__MINIO_USE_SSL=true
+GITEA__lfs__MINIO_BASE_PATH=lfs/
+GITEA__lfs__MINIO_BUCKET_LOOKUP_TYPE=dns
+```
+
+> `GITEA__lfs__PATH` 仅在本地存储模式下生效，切换到 minio 后删除该行即可。
+
+### 2.2 修改 `docker-compose.yml`
+
+在 `gitea` 服务的 `environment` 下，将原来的 LFS 条目：
+
+```yaml
+- GITEA__lfs__START_SERVER=${GITEA__lfs__START_SERVER}
+- GITEA__lfs__PATH=${GITEA__lfs__PATH}
+```
+
+替换为：
+
+```yaml
+- GITEA__lfs__START_SERVER=${GITEA__lfs__START_SERVER}
+- GITEA__lfs__STORAGE_TYPE=${GITEA__lfs__STORAGE_TYPE}
+- GITEA__lfs__MINIO_ENDPOINT=${GITEA__lfs__MINIO_ENDPOINT}
+- GITEA__lfs__MINIO_ACCESS_KEY_ID=${GITEA__lfs__MINIO_ACCESS_KEY_ID}
+- GITEA__lfs__MINIO_SECRET_ACCESS_KEY=${GITEA__lfs__MINIO_SECRET_ACCESS_KEY}
+- GITEA__lfs__MINIO_BUCKET=${GITEA__lfs__MINIO_BUCKET}
+- GITEA__lfs__MINIO_LOCATION=${GITEA__lfs__MINIO_LOCATION}
+- GITEA__lfs__MINIO_USE_SSL=${GITEA__lfs__MINIO_USE_SSL}
+- GITEA__lfs__MINIO_BASE_PATH=${GITEA__lfs__MINIO_BASE_PATH}
+- GITEA__lfs__MINIO_BUCKET_LOOKUP_TYPE=${GITEA__lfs__MINIO_BUCKET_LOOKUP_TYPE}
+```
+
+### 2.3 同步更新 `.env.example`
+
+`.env.example` 是提交到 git 的模板，需同步更新（不填真实密钥）：
+
+```bash
+# Git LFS 配置 - 腾讯云 COS
+GITEA__lfs__START_SERVER=true
+GITEA__lfs__STORAGE_TYPE=minio
+GITEA__lfs__MINIO_ENDPOINT=cos.ap-guangzhou.myqcloud.com
+GITEA__lfs__MINIO_ACCESS_KEY_ID=AKIDxxxxxxxxxx
+GITEA__lfs__MINIO_SECRET_ACCESS_KEY=xxxxxxxxxx
+GITEA__lfs__MINIO_BUCKET=your-bucket-name
+GITEA__lfs__MINIO_LOCATION=ap-guangzhou
+GITEA__lfs__MINIO_USE_SSL=true
+GITEA__lfs__MINIO_BASE_PATH=lfs/
+GITEA__lfs__MINIO_BUCKET_LOOKUP_TYPE=dns
+```
+
+---
+
+## 三、迁移已有 LFS 数据（可选）
+
+如果切换前本地 `data/git/lfs/` 已有文件，需手动同步到 COS，否则历史 LFS 对象会返回 404。
+
+使用腾讯云官方 CLI 工具 [coscli](https://cloud.tencent.com/document/product/436/63143)：
+
+```bash
+# 安装 coscli（macOS 示例）
+curl -o coscli https://github.com/tencentyun/coscli/releases/latest/download/coscli-darwin
+
+chmod +x coscli
+
+# 配置认证（交互式）
+./coscli config init
+
+# 上传本地 LFS 目录到 COS（同步模式，不重复上传）
+./coscli sync ./data/git/lfs/ cos://gitea-lfs-1234567890/lfs/ --recursive
+```
+
+同步完成后再重启 Gitea，避免服务重启期间出现 LFS 对象丢失。
+
+---
+
+## 四、重启并验证
+
+```bash
+# 重启 Gitea 服务（Compose 会自动检测 .env 变更并重建容器）
+docker compose up -d gitea
+
+# 查看启动日志，确认无报错
+docker compose logs -f gitea
+```
+
+验证 COS 是否生效：推送一个包含 LFS 文件的提交，然后到 COS 控制台的 `lfs/` 路径下确认对象是否出现。
+
+```bash
+# 本地测试推送
+git lfs track "*.bin"
+git add .gitattributes largefile.bin
+git commit -m "test: lfs upload to cos"
+git push
+```
+
+---
+
+## 五、常见问题
+
+**Q：Bucket 名称填什么格式？**  
+填完整名称（含 AppId），例如 `gitea-lfs-1234567890`。不含 `.cos.ap-xxx.myqcloud.com` 后缀。
+
+**Q：轻量服务器能用 COS 内网端点吗？**  
+轻量服务器使用独立的轻量网络，不在标准 VPC 内，默认无法访问 COS 内网端点。直接使用公网端点 `cos.<region>.myqcloud.com` 即可。若已通过云联网（CCN）打通网络，可将端点改为 `cos-internal.<region>.myqcloud.com` 以节省公网流量费用。
+
+**Q：推送 LFS 报 `403 Forbidden`？**  
+检查 CAM 子账号的策略是否包含目标 Bucket 的操作权限，以及 SecretId / SecretKey 是否填写正确。
+
+**Q：推送 LFS 报 `SignatureDoesNotMatch`？**  
+确认 `MINIO_LOCATION` 与 Bucket 实际所在地域一致。

docs/sqlite-to-postgres-migration.md

@@ -0,0 +1,253 @@
+# SQLite 迁移到 PostgreSQL
+
+本文档适用于已有 Gitea 服务仍在使用旧版 Docker Compose 和 SQLite，尚未更新到引入 PostgreSQL 的最新 commit 的场景。
+
+迁移目标是把 `data/gitea/gitea.db` 中的业务数据导入到新的 PostgreSQL 数据库，同时继续复用现有的仓库、LFS、附件和配置目录。
+
+> `gitea migrate` 不是 SQLite 到 PostgreSQL 的数据搬迁工具。它只会对当前 Gitea 配置指向的数据库执行 Gitea schema migration。
+>
+> Gitea 自带的跨数据库导出入口是 `gitea dump --database postgres`。Gitea 没有对应的自动 `gitea restore` 命令，恢复或导入 PostgreSQL 时需要手动解压 dump 包，并用 `psql` 导入其中的 `gitea-db.sql`。
+
+## 迁移前准备
+
+- 预留维护窗口。迁移期间必须停止 Gitea，避免 SQLite 继续写入。
+- 保持 `GITEA_VERSION` 不变。不要在同一次操作中同时升级 Gitea 版本和切换数据库。
+- 准备 `.env` 中的 PostgreSQL 配置：
+
+```env
+POSTGRES_VERSION=16-alpine
+POSTGRES_DB=gitea
+POSTGRES_USER=gitea
+POSTGRES_PASSWORD=<强密码>
+```
+
+- 确认可以运行 `sqlite3`、`unzip`，并且 PostgreSQL 容器里可以运行 `psql`。
+- 本文档假设 `docker-compose.yml` 把宿主机 `./data` 挂载到 Gitea 容器内的 `/data`。因此 dump 输出到容器内 `/data/gitea-dump-postgres.zip` 时，宿主机对应文件是 `data/gitea-dump-postgres.zip`。
+
+## 1. 停止旧 Gitea
+
+在仍使用 SQLite 的旧版 compose 下停止 Gitea：
+
+```bash
+docker compose stop gitea
+```
+
+如果启用了 Caddy，可以保持 Caddy 运行显示维护页，也可以一起停止：
+
+```bash
+docker compose stop caddy
+```
+
+## 2. 冷备份 SQLite 和数据目录
+
+```bash
+ts=$(date +%Y%m%d-%H%M%S)
+mkdir -p backups/$ts
+cp data/gitea/gitea.db backups/$ts/gitea.db
+cp data/gitea/conf/app.ini backups/$ts/app.ini
+tar -czf backups/$ts/gitea-data.tar.gz data/git data/gitea
+```
+
+备份完成后，记录 SQLite 中的关键表数量，作为迁移后校验基线：
+
+```bash
+sqlite3 data/gitea/gitea.db "select 'user', count(*) from user union all select 'repository', count(*) from repository union all select 'lfs_meta_object', count(*) from lfs_meta_object union all select 'public_key', count(*) from public_key union all select 'issue', count(*) from issue union all select 'release', count(*) from release;"
+```
+
+## 3. 使用 Gitea dump 导出 PostgreSQL SQL
+
+在仍使用旧 SQLite 配置时运行 `gitea dump`。不要先把 Gitea 配置切到 PostgreSQL，否则 dump 会尝试读取新数据库。
+
+```bash
+docker compose run --rm --user git gitea \
+  gitea dump -c /data/gitea/conf/app.ini \
+  --database postgres \
+  --file /data/gitea-dump-postgres.zip
+```
+
+确认宿主机上已经生成 dump 包：
+
+```bash
+ls -lh data/gitea-dump-postgres.zip
+```
+
+如果当前镜像或环境不能识别 `git` 用户，可以改用官方镜像常见 UID/GID：
+
+```bash
+docker compose run --rm --user 1000:1000 gitea \
+  gitea dump -c /data/gitea/conf/app.ini \
+  --database postgres \
+  --file /data/gitea-dump-postgres.zip
+```
+
+解压 dump 包，得到 `gitea-db.sql`：
+
+```bash
+mkdir -p backups/gitea-dump-postgres
+unzip -o data/gitea-dump-postgres.zip -d backups/gitea-dump-postgres
+ls -lh backups/gitea-dump-postgres/gitea-db.sql
+```
+
+## 4. 更新代码并只启动 PostgreSQL
+
+更新到包含 PostgreSQL 服务的最新 commit，并补齐 `.env` 中的 PostgreSQL 配置。
+
+```bash
+git pull
+```
+
+先只启动 PostgreSQL，不要启动 Gitea：
+
+```bash
+docker compose up -d postgres
+```
+
+确认 PostgreSQL 可连接：
+
+```bash
+docker compose exec -T postgres psql -U gitea -d gitea -c "select version();"
+```
+
+## 5. 确认 PostgreSQL 是空库
+
+检查目标库是否已有表：
+
+```bash
+docker compose exec -T postgres psql -U gitea -d gitea -c '\dt'
+```
+
+如果已经有 Gitea 业务表，先确认这些表不是生产数据。确认可丢弃后，停止 PostgreSQL，备份并移走 `data/postgres/`，再重新启动空库：
+
+```bash
+docker compose stop postgres
+ts=$(date +%Y%m%d-%H%M%S)
+mv data/postgres data/postgres.before-migration-$ts
+docker compose up -d postgres
+```
+
+再次运行 `\dt`，确认目标库为空。
+
+## 6. 导入 dump SQL 到 PostgreSQL
+
+使用 `psql` 导入 `gitea-db.sql`：
+
+```bash
+docker compose exec -T postgres psql -U gitea -d gitea < backups/gitea-dump-postgres/gitea-db.sql
+```
+
+导入完成后，检查目标库关键表数量：
+
+```bash
+docker compose exec -T postgres psql -U gitea -d gitea -c "select 'user', count(*) from \"user\" union all select 'repository', count(*) from repository union all select 'lfs_meta_object', count(*) from lfs_meta_object union all select 'public_key', count(*) from public_key union all select 'issue', count(*) from issue union all select 'release', count(*) from release;"
+```
+
+这些数量应与第 2 步 SQLite 基线一致。
+
+## 7. 启动 Gitea
+
+确认 `docker-compose.yml` 已通过 `GITEA__database__*` 环境变量指向 PostgreSQL，然后启动 Gitea：
+
+```bash
+docker compose up -d gitea
+docker compose logs -f gitea
+```
+
+Gitea 启动时会对 PostgreSQL 执行必要的 schema migration。日志中不应出现数据库连接、类型转换、唯一约束或 migration 错误。
+
+如果使用 Caddy：
+
+```bash
+docker compose up -d caddy
+```
+
+## 8. 迁移后验证
+
+- 使用原管理员账号登录 Web UI。
+- 确认用户、组织、仓库、Issue、Release、SSH Key 等数据存在。
+- 执行一次 HTTP 或 HTTPS clone。
+- 执行一次 SSH clone。
+- 推送一个普通 commit。
+- 如果使用 Git LFS，执行一次 LFS push。
+- 检查日志：
+
+```bash
+docker compose logs gitea postgres
+```
+
+## 常见问题
+
+### Gitea is not supposed to be run as root
+
+`docker compose run` 默认可能以 root 用户启动一次性容器，但 Gitea 不允许以 root 运行。给 dump 命令加上 `--user git`：
+
+```bash
+docker compose run --rm --user git gitea \
+  gitea dump -c /data/gitea/conf/app.ini \
+  --database postgres \
+  --file /data/gitea-dump-postgres.zip
+```
+
+如果 `git` 用户不可用，改用：
+
+```bash
+docker compose run --rm --user 1000:1000 gitea \
+  gitea dump -c /data/gitea/conf/app.ini \
+  --database postgres \
+  --file /data/gitea-dump-postgres.zip
+```
+
+### Unable to create dump file "/gitea-dump-*.zip": permission denied
+
+`gitea dump` 默认会把文件写到容器当前目录。如果当前目录是 `/`，非 root 用户没有写权限。显式指定 `--file /data/gitea-dump-postgres.zip`，让 dump 写入已挂载且可持久化的 `/data` 目录。
+
+### pgloader 备选方案
+
+如果 `gitea dump --database postgres` 在当前版本或数据集上失败，可以把 `pgloader` 作为备选迁移工具。使用前仍然要停止 Gitea、完成冷备份，并确认 PostgreSQL 目标库为空。
+
+把 `<POSTGRES_PASSWORD>` 替换为 `.env` 中的真实密码：
+
+```bash
+docker run --rm \
+  --network gitea_default \
+  -v "$PWD/data/gitea:/data/gitea:ro" \
+  dimitri/pgloader:latest \
+  pgloader sqlite:///data/gitea/gitea.db postgresql://gitea:<POSTGRES_PASSWORD>@postgres:5432/gitea
+```
+
+如果 compose project 网络名不是 `gitea_default`，替换 `--network` 参数。
+
+## 回滚
+
+如果迁移后验证失败，先停止新 Gitea：
+
+```bash
+docker compose stop gitea
+```
+
+回滚到旧版 SQLite compose，或临时移除 `docker-compose.yml` 中的 `GITEA__database__*` 环境变量，避免它覆盖 `app.ini`。
+
+恢复备份：
+
+```bash
+cp backups/<备份时间>/gitea.db data/gitea/gitea.db
+cp backups/<备份时间>/app.ini data/gitea/conf/app.ini
+```
+
+再启动旧 SQLite 版本：
+
+```bash
+docker compose up -d gitea
+```
+
+在迁移完全确认前，不要删除 `data/gitea/gitea.db`、`backups/`、`data/gitea-dump-postgres.zip` 或迁移前的 `data/postgres.before-migration-*`。
+
+## 演练建议
+
+正式迁移前，建议在复制出来的目录中完整演练一次：
+
+```bash
+cp -a gitea gitea-migration-dry-run
+cd gitea-migration-dry-run
+```
+
+演练中也要验证 dump 导出、SQL 解压、空库检查、`psql` 导入、表数量对比、Gitea 启动和 Web/Git 操作。演练通过后，再在正式目录执行维护窗口迁移。

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` | 容器编排配置：镜像、端口、卷、环境变量 |
+| `docker-compose.yml` | 容器编排：Gitea + PostgreSQL + Caddy（可选） |
-| `.env` | 可配置参数：版本、端口、时区、LFS 配置 |
+| `.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 服务：通过 `GITEA__database__*` 环境变量连接 PostgreSQL
-  gitea:
+- PostgreSQL 服务：`postgres:16-alpine`，健康检查 `pg_isready`
-    image: gitea/gitea:${GITEA_VERSION}
+- Gitea `depends_on` PostgreSQL（健康检查通过后才启动）
-    container_name: gitea
+- Caddy 服务：`profiles: [caddy]`，可选启用
-    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 配置语法**
 
@@ -104,154 +105,44 @@ data/
 # 环境变量（可能包含敏感信息）
 .env
 
+# Caddy 数据
+caddy_data/
+caddy_config/
+
 # macOS
 .DS_Store
 ```
 
-- [ ] **Step 2: 验证文件创建成功**
-
-Run: `cat .gitignore`
-Expected: 显示上述内容
-
 ---
 
-### Task 4: 创建 README.md 使用说明
+### Task 4: 创建 .env.example
-
-**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 示例文件
 
 **Files:**
 - Create: `.env.example`
 
 - [ ] **Step 1: 创建 .env.example 文件**
 
-```env
+与 `.env` 结构相同，但密码使用占位值 `changeme`。
-# Gitea 版本
-GITEA_VERSION=1.25.4
 
-# 端口配置
+---
-HTTP_PORT=3000
-SSH_PORT=2222
 
-# 时区
+## Chunk 2: 文档和验证
-TZ=Asia/Shanghai
 
-# Git LFS 配置
+### Task 5: 创建 README.md 使用说明
-GITEA__lfs__START_SERVER=true
-GITEA__lfs__PATH=/data/git/lfs
-```
 
-- [ ] **Step 2: 验证文件创建成功**
+**Files:**
+- Create: `README.md`
 
-Run: `cat .env.example`
+- [ ] **Step 1: 创建 README.md 文件**
-Expected: 显示上述内容
+
+内容包含：
+- 架构说明（HTTP 模式 / Caddy 模式）
+- 快速开始（配置 → 启动 → 初始设置）
+- 访问方式
+- Git LFS 使用
+- 数据备份（PostgreSQL pg_dump + 数据目录）
+- SQLite 迁移到 PostgreSQL 的安全入口说明，链接到 `docs/sqlite-to-postgres-migration.md`
+- 常用命令
 
 ---
 
@@ -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）

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/            # Gitea 配置
-    │   ├── gitea.db      # SQLite 数据库（用户数据）
+    │   ├── 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. 配置服务器域名等基本信息
+2. 数据库已通过环境变量配置为 PostgreSQL，无需手动设置
-3. 数据库已使用 SQLite，无需额外配置
 
 ### 备份
 
-备份 `./data/` 目录即可，特别是：
+```bash
-- `./data/gitea/gitea.db` - 用户和配置数据
+# 导出数据库
-- `./data/git/repositories/` - 仓库数据
+docker exec postgres pg_dump -U gitea gitea > gitea-db-$(date +%Y%m%d).sql
-- `./data/git/lfs/` - LFS 文件
+
+# 备份数据目录
+tar -czvf gitea-data-$(date +%Y%m%d).tar.gz data/
+```
 
 ## 文件清单
 
-需要创建的文件：
+| 文件 | 职责 |
-1. `docker-compose.yml` - Docker Compose 配置
+|-----|------|
-2. `.env` - 环境变量配置
+| `docker-compose.yml` | 容器编排：Gitea + PostgreSQL + Caddy |
-3. `.gitignore` - Git 忽略规则
+| `.env` | 环境变量：版本、端口、数据库、域名 |
-4. `README.md` - 使用说明文档
+| `.env.example` | 环境变量示例 |
+| `.gitignore` | 忽略数据目录和敏感文件 |
+| `Caddyfile` | Caddy 反向代理配置 |
+| `README.md` | 使用说明文档 |