Gitea with PostgreSQL

生产 Gitea —— 开箱即用连接到 PostgreSQL。

Service #git#repository#postgresql#devops#code

Gitea（轻量级自托管 Git 服务）与专用 PostgreSQL 后端配对用于生产用途。Gitea 默认 SQLite 对小团队还行；PostgreSQL 是推荐的后端，一旦你超过少数并发用户、想要 HA 备份或以任何量运行 Gitea Actions。

使用 Pier 部署

1 打开 Pier 控制台，点击 Add service。
2 从模板列表中选择 Gitea with PostgreSQL。
3 选择版本、设置服务名称，Pier 会自动配置容器、存储和端口。
4 如需 HTTPS，请绑定域名。Traefik 会自动签发 Let's Encrypt 证书。

什么是 Gitea with PostgreSQL？

Gitea 是一个轻量级、自托管 Git 服务 —— 仓库、问题、PR、代码审查、发布、包注册表、Gitea Actions（与 GitHub Actions 兼容的 CI）。它默认为 SQLite 以简化，但一旦你有多个活跃用户、高 webhook 量或以任何量运行 Gitea Actions， Postgres 就是推荐的后端。

本模板在一个 Pier 栈中运行 Gitea 加专用 PostgreSQL，env 连线已正确。你登录并像独立模板一样使用 Gitea —— 代码、问题、PR、包 —— 后端只是在并发负载下性能更好。

Pier 如何部署它

Pier 使用官方 gitea/gitea 镜像和 postgres:17-alpine 用于后端。默认端口 —— Gitea web 在 3000，Gitea SSH 在 22（重新映射到高外部端口如 222）。PostgreSQL 保留在内部 Docker 网络上（不公开）。

持久卷 —— /data 用于 Gitea（仓库、上传、配置）和 /var/lib/postgresql/data 用于 Postgres。两者跨容器重启和版本升级幸存。

首次设置是首次访问时的标准 Gitea 安装屏幕：选择数据库（预填以指向捆绑的 Postgres），设置管理员用户，保存。在 Pier 中附加自定义域名以通过 Traefik 获得 HTTPS。

何时不要使用本模板

对于 1-3 个用户和小仓库数，独立 Gitea (SQLite) 模板更简单。对于完整的 DevOps 平台（Wiki、Pages、内置容器注册表、高级安全扫描），GitLab CE 功能更完整但对资源更重。对于社区治理的治理，Forgejo 是值得考虑的 Gitea 分叉。本模板是”在我自己的 VPS 上的生产 Gitea”的正确答案。

核心功能

生产就绪 Gitea

Web Git 托管、问题、PR、代码审查、发布、包、Actions —— 所有 Gitea，连接到 Postgres 用于并发写入可靠性。

预连线 DB 配置

Pier 将 Gitea 数据库类型设置为 postgres，加上 host/db/user/password env vars。Gitea 在首次启动时直接启动到 Postgres。

相同的 Gitea UI

仓库、问题、PR、镜像、actions、包注册表 (npm/pypi/maven/docker/...)、webhooks、SSH 访问 —— 全部与独立 Gitea 相同。

Gitea Actions

与 GitHub Actions 语法兼容的内置 CI/CD。在每个仓库的沙箱中运行；runners 单独部署。

通过 PostgreSQL 备份

pg_dump 捕获整个 Gitea 状态。加上仓库卷。比 SQLite 的"停止世界并复制"更干净的备份故事。

多租户友好

组织、团队、细粒度 ACL 随 Postgres 舒适扩展。通过 OAuth2/OIDC/LDAP/SAML 的 SSO。

应用场景

团队的自托管 GitHub

5-500 个团队每天使用 Gitea 进行代码审查、问题、发布。PostgreSQL 平滑处理并发问题/PR 写入负载。

生产内部 Git + CI

添加 Gitea Actions runners，将 CI 指向 PR，发布到你自己的注册表 —— 全部在你的 VPS 上，无 GitHub Actions 分钟账单。

公共 OSS 托管

一些项目在自己的 Gitea 上托管公共仓库而非 GitHub。Postgres 处理可见性/并发读取负载。

GitHub / GitLab 的镜像

自动将上游仓库的镜像拉入你的 Gitea 用于离线访问或备份。Webhook 驱动，无手动同步。

包注册表中心

与 Git 仓库一起的内部 npm / PyPI / Maven / Docker / Helm 注册表。一个身份验证表面，一个备份目标。

代码示例

通过 SSH 克隆 bash

# SSH 端口由 Pier 公开（默认 222 → 映射到内部 22）
git clone ssh://[email protected]:222/alice/myrepo.git

创建 Gitea Action 工作流 yaml

# .gitea/workflows/build.yml
name: build
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: go test ./...

镜像 GitHub 仓库 text

UI 中的迁移页面：
  类型：镜像
  URL: https://github.com/orgs/orgname/repo
  Auth: PAT（如果私有）
  间隔: 1h

将 Docker 镜像推送到 Gitea 的注册表 bash

docker login gitea.example.com -u alice -p $PAT
docker tag myapp gitea.example.com/alice/myapp:1.0
docker push gitea.example.com/alice/myapp:1.0

对比

vs 带 SQLite 的 Gitea（独立模板）	SQLite Gitea 对 1-3 个用户和小仓库数还行。Postgres 支持的 Gitea 是推荐设置，一旦你有并发写入、想要 HA 或以任何量运行 Actions。
vs GitLab CE	GitLab 更强大（完整 DevOps 平台）但重型（实际最小 8 GB RAM）。Gitea 是轻量级（约 500 MB RAM）；按可用资源选择。
vs Forgejo	Forgejo 是由社区治理的 Gitea 硬分叉（Codeberg）。相同功能集，大部分插入兼容。基于首选治理选择。
vs GitHub Enterprise	SaaS 或自托管，企业定价。Gitea 是零按席位成本的开放替代。

常见问题

为什么 PostgreSQL 而不是 SQLite？

在并发写入（问题评论、PR 更新、webhooks、Actions 运行）下，SQLite 成为瓶颈。PostgreSQL 干净地处理数千个并发连接。

我可以从 SQLite Gitea 迁移吗？

是 —— Gitea 提供 `gitea dump` / `gitea migrate` 流程。在 SQLite Gitea 上运行 dump，部署 Postgres 模板，将 dump 还原指向 Postgres。

我需要 Gitea Actions 的单独 runner 吗？

是 —— act_runner 作为连接到 Gitea 并执行工作流的单独容器/二进制运行。Pier 不捆绑它（尚）；手动部署 runner。

SSH 访问？

Pier 在高端口（例如 222）上公开 SSH。配置你的 `git remote` 以使用该端口，或设置 SSH 配置别名。

包注册表如何工作？

Gitea 的注册表支持 npm、PyPI、Maven、Composer、NuGet、Cargo、RubyGems、Docker、Helm、container、Conan、generic。使用个人访问 token 进行身份验证。

备份？

`gitea dump` 加 Postgres 后端的 pg_dump 覆盖一切。加上包含仓库 + 上传文件的数据卷。

SSO / LDAP / SAML？

是 —— 全部在站点管理 → 身份验证源中配置。Gitea 支持 OAuth2、OIDC、LDAP、SAML 和基本身份验证。

在你的 VPS 上部署

部署此服务 →