Forgejo/Gitea: 自托管轻量 Git 服务¶

为什么要学 Forgejo¶

GitHub 是好的，但有些场景需要自托管 Git 服务： - 公司内部代码不能放在外部平台 - 需要完全控制数据和基础设施 - 对 GitHub/GitLab 的定价不满意 - 想要在私有网络中运行 - 研究数据有合规要求（如医疗、政府）

GitLab 自托管虽然功能全面，但资源消耗巨大（推荐 8GB+ 内存）。Forgejo（Gitea 的社区分叉）用极少的资源提供了核心的 Git 托管能力。

维度	GitHub	GitLab 自托管	Forgejo/Gitea
部署方式	SaaS	自托管	自托管
最低内存	N/A	8GB+	256MB
语言	未知	Ruby/Go	Go
启动时间	N/A	分钟级	秒级
CI/CD	GitHub Actions	GitLab CI	Forgejo Actions/Woodpecker
包注册表	有	有	有
费用	免费(受限)/付费	免费/付费	完全免费
治理	微软	GitLab Inc	社区非营利

Forgejo vs Gitea¶

Forgejo 是 Gitea 的社区分叉（2022 年），两者 API 和功能高度兼容。主要区别： - Forgejo：非营利组织治理，社区优先，不接受风投 - Gitea：公司治理（Gitea Ltd），可能走商业化路线 - 功能上几乎一致，本教程的内容适用于两者

核心概念¶

白话解释¶

Forgejo 就是一个"迷你 GitHub"。安装后你会得到一个 Web 界面，能做以下事情： - 创建和管理 Git 仓库 - Pull Request 和代码审查 - Issue 跟踪 - CI/CD（通过 Forgejo Actions 或集成 Woodpecker CI） - 包注册表（npm、Docker、PyPI 等） - OAuth2 登录

核心概念表¶

概念	说明	GitHub 等价物
Organization	组织，用于分组管理仓库和成员	Organization
Repository	Git 仓库	Repository
Pull Request	代码合并请求	Pull Request
Issue	问题跟踪	Issue
Action	CI/CD 工作流（兼容 GitHub Actions 语法）	GitHub Actions
Package Registry	包存储（Docker/npm/PyPI 等）	GitHub Packages
Webhook	事件通知回调	Webhook
OAuth2 Provider	作为 OAuth2 身份提供者	GitHub OAuth
Migration	从其他平台导入仓库	GitHub Importer

安装配置¶

方式一：Docker Compose（推荐）¶

# docker-compose.yml
version: '3'

services:
  forgejo:
    image: codeberg.org/forgejo/forgejo:9
    container_name: forgejo
    environment:
      - USER_UID=1000
      - USER_GID=1000
    restart: always
    volumes:
      - ./forgejo-data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - '3000:3000'   # Web UI
      - '2222:22'     # SSH

docker compose up -d
# 访问 http://localhost:3000 进行初始配置

方式二：直接安装¶

# 下载二进制
wget -O forgejo https://codeberg.org/forgejo/forgejo/releases/download/v9.0.0/forgejo-9.0.0-linux-amd64
chmod +x forgejo
sudo mv forgejo /usr/local/bin/

# 创建用户
sudo adduser --system --group --disabled-password --shell /bin/bash --home /home/git git

# 创建必要目录
sudo mkdir -p /var/lib/forgejo/{custom,data,log}
sudo chown -R git:git /var/lib/forgejo
sudo chmod -R 750 /var/lib/forgejo

# 创建 systemd 服务
sudo cat > /etc/systemd/system/forgejo.service << 'EOF'
[Unit]
Description=Forgejo
After=syslog.target network.target

[Service]
RestartSec=2s
Type=simple
User=git
Group=git
WorkingDirectory=/var/lib/forgejo
ExecStart=/usr/local/bin/forgejo web --config /etc/forgejo/app.ini
Restart=always
Environment=USER=git HOME=/home/git FORGEJO_WORK_DIR=/var/lib/forgejo

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable --now forgejo

初始配置¶

首次访问 http://your-server:3000 会进入安装向导：

配置项	推荐值	说明
数据库类型	SQLite3 (小团队) / PostgreSQL (大团队)	SQLite 零配置
站点名称	你的组织名	显示在页面标题
仓库根目录	`/data/gitea-repositories`	Git 仓库存储路径
服务器域名	`git.example.com`	对外访问域名
SSH 端口	22 或 2222	SSH 克隆端口
注册模式	禁用自注册 (内部使用)	安全考虑

配置文件详解¶

# /etc/forgejo/app.ini (或 /data/gitea/conf/app.ini)

[server]
DOMAIN = git.example.com
HTTP_PORT = 3000
ROOT_URL = https://git.example.com/
SSH_PORT = 2222
START_SSH_SERVER = true
LFS_START_SERVER = true  # 启用 Git LFS

[database]
DB_TYPE = sqlite3
PATH = /data/forgejo/forgejo.db

[repository]
ROOT = /data/gitea-repositories
DEFAULT_BRANCH = main

[service]
DISABLE_REGISTRATION = true  # 禁用公开注册
REQUIRE_SIGNIN_VIEW = true   # 需要登录才能查看
DEFAULT_ALLOW_CREATE_ORGANIZATION = true

[mailer]
ENABLED = true
PROTOCOL = smtps
SMTP_ADDR = smtp.example.com
SMTP_PORT = 465
USER = noreply@example.com
PASSWD = your-password
FROM = "Forgejo" <noreply@example.com>

[actions]
ENABLED = true  # 启用 Forgejo Actions

[packages]
ENABLED = true  # 启用包注册表

反向代理（Caddy）¶

# Caddyfile
git.example.com {
    reverse_proxy localhost:3000
}

# 或 Nginx
server {
    listen 443 ssl;
    server_name git.example.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

快速上手¶

创建仓库¶

# Web UI 创建：点击 "+" → "New Repository"

# 或使用 API
curl -X POST "http://localhost:3000/api/v1/user/repos" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project", "private": true, "auto_init": true}'

Git 操作¶

# 克隆仓库
git clone http://localhost:3000/user/my-project.git
# 或 SSH
git clone ssh://git@localhost:2222/user/my-project.git

# 推送代码
cd my-project
echo "# My Project" > README.md
git add .
git commit -m "Initial commit"
git push origin main

从 GitHub 迁移¶

Forgejo 内置了仓库迁移功能：

Web UI → "+" → "New Migration"
选择来源（GitHub、GitLab、Bitbucket 等）
输入仓库 URL 和认证信息
选择要迁移的内容（Issues、Labels、Milestones、Releases 等）

# 或使用 API 迁移
curl -X POST "http://localhost:3000/api/v1/repos/migrate" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clone_addr": "https://github.com/user/repo.git",
    "repo_name": "repo",
    "repo_owner": "your-org",
    "service": "github",
    "auth_token": "ghp_...",
    "mirror": false,
    "issues": true,
    "labels": true,
    "milestones": true,
    "releases": true
  }'

Webhook 配置¶

# 在仓库 Settings → Webhooks 中配置
# 或使用 API

curl -X POST "http://localhost:3000/api/v1/repos/user/repo/hooks" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "slack",
    "config": {
      "url": "https://hooks.slack.com/services/...",
      "content_type": "json"
    },
    "events": ["push", "pull_request"],
    "active": true
  }'

进阶用法¶

Forgejo Actions（CI/CD）¶

Forgejo Actions 兼容 GitHub Actions 语法：

# .forgejo/workflows/ci.yml
name: CI
on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.22'
      - run: go test ./...

  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: golangci/golangci-lint-action@v6

设置 Runner

# 下载 Forgejo Runner
wget https://code.forgejo.org/forgejo/runner/releases/download/v3.5.0/forgejo-runner-linux-amd64
chmod +x forgejo-runner-linux-amd64
sudo mv forgejo-runner-linux-amd64 /usr/local/bin/forgejo-runner

# 注册 Runner
forgejo-runner register \
  --instance https://git.example.com \
  --token YOUR_RUNNER_TOKEN \
  --name my-runner

# 启动 Runner（使用 Docker 执行任务）
forgejo-runner daemon

包注册表¶

Forgejo 支持多种包格式：

# Docker Registry
docker login git.example.com
docker tag myapp git.example.com/user/myapp:latest
docker push git.example.com/user/myapp:latest

# npm
npm login --registry=https://git.example.com/api/packages/user/npm/
npm publish --registry=https://git.example.com/api/packages/user/npm/

# PyPI
pip install twine
twine upload --repository-url https://git.example.com/api/packages/user/pypi \
  -u your-username -p your-token dist/*

# Go Proxy
GOPROXY=https://git.example.com/api/packages/user/go go get example.com/pkg

OAuth2 / SSO¶

将 Forgejo 作为 OAuth2 身份提供者，或接入外部 SSO：

# app.ini — 接入 LDAP
[authentication]
ENABLE_OAUTH2_INTROSPECTION = true

# 接入 Keycloak/OIDC
# 在 Web UI → Site Administration → Authentication Sources 中配置
# 类型：OAuth2
# Provider：OpenID Connect
# Client ID/Secret：从 Keycloak 获取
# Discovery URL：https://keycloak.example.com/realms/myrealm/.well-known/openid-configuration

备份与恢复¶

# 备份
forgejo dump -c /etc/forgejo/app.ini
# 生成 forgejo-dump-xxx.zip，包含：
# - 数据库
# - 仓库
# - 配置
# - 日志

# Docker 环境备份
docker exec forgejo forgejo dump -c /data/gitea/conf/app.ini

# 恢复
forgejo restore --from forgejo-dump-xxx.zip

API 使用¶

Forgejo 提供完整的 REST API（兼容 Gitea API）：

# 创建 API Token
# Web UI → Settings → Applications → Generate Token

# 列出仓库
curl -H "Authorization: token YOUR_TOKEN" \
  http://localhost:3000/api/v1/repos/search

# 创建 Issue
curl -X POST "http://localhost:3000/api/v1/repos/user/repo/issues" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Bug report", "body": "Description..."}'

# API 文档
# 访问 http://localhost:3000/api/swagger

常见问题¶

Q1: Forgejo 和 Gitea 我该选哪个？¶

功能上几乎一致。选择依据： - Forgejo：偏好社区治理、非营利、长期稳定性 - Gitea：偏好公司维护、可能有更多商业功能

两者的配置和 API 兼容，迁移成本极低。

Q2: 小团队（5-10人）需要多少资源？¶

CPU：1 核心足够
内存：512MB-1GB
磁盘：取决于仓库大小，起步 10GB
数据库：SQLite 足够（<50 用户），更大规模用 PostgreSQL

Q3: 可以和 GitHub 双向同步吗？¶

可以设置镜像仓库： - 在 Forgejo 中创建仓库时选择 "Mirror" - 支持从 GitHub 拉取（pull mirror） - 也支持推送到 GitHub（push mirror）

Q4: HTTPS 怎么配置？¶

推荐用 Caddy 或 Nginx 反向代理处理 TLS，不在 Forgejo 中直接配置 HTTPS。

Q5: 如何升级 Forgejo？¶

# Docker
docker compose pull
docker compose up -d

# 二进制
# 下载新版本替换旧版本，重启服务
sudo systemctl stop forgejo
sudo cp forgejo-new /usr/local/bin/forgejo
sudo systemctl start forgejo

升级前务必备份。

参考资源¶

资源	链接
Forgejo 官网	https://forgejo.org
Forgejo 文档	https://forgejo.org/docs
Codeberg (Forgejo 的旗舰实例)	https://codeberg.org
Gitea 官网	https://about.gitea.com
Gitea 文档	https://docs.gitea.com
API 文档	你的实例地址 /api/swagger
Forgejo Runner	https://code.forgejo.org/forgejo/runner

总结：Forgejo/Gitea 是自托管 Git 服务的最佳轻量选择。只需要一个 Docker 容器和 256MB 内存，你就能拥有一个功能完整的代码托管平台。它特别适合小团队、内部项目、和对数据主权有要求的场景。与 GitLab 的重量级方案相比，Forgejo 的维护成本几乎可以忽略。