Git 服务器搭建完全指南 / 第 5 章 - Forgejo 社区分支

第 5 章 - Forgejo 社区分支

Forgejo（发音：for-DJEH-yo，世界语中"铁匠"）是从 Gitea 社区分叉（fork）出来的自托管 Git 服务。2022 年 Gitea Ltd. 公司成立后，社区开发者担心商业公司对开源项目的控制，于 2022 年 12 月创建了 Forgejo 项目。

5.1 为什么选择 Forgejo

5.1.1 Forgejo vs Gitea

维度	Gitea	Forgejo
项目治理	Gitea Ltd.（商业公司）主导	Codeberg e.V.（非营利协会）主导
开源许可	MIT	MIT（加上 GPL v3 签名）
代码同步	独立发展	持续从 Gitea 上游合并
额外功能	标准功能集	新增 W3C ActivityPub、邮件通知等
发布周期	与 Gitea 对齐	通常在 Gitea 发布后数天内跟进
社区规模	较大	增长迅速
商业支持	有	无官方商业支持

5.1.2 选择 Forgejo 的理由

场景一：认同社区治理

团队希望使用的开源工具由非营利组织而非商业公司控制，确保长期开放性。

场景二：Codeberg 生态

团队已在 Codeberg.org 上托管部分开源项目，希望内部部署与之兼容。

场景三：联邦化特性

对 Forgejo 的 ActivityPub 联邦化特性感兴趣，未来可能实现跨实例协作。

5.2 安装部署

5.2.1 二进制安装

# 下载最新版本
FORGEJO_VERSION="9.0.0"
wget -O /usr/local/bin/forgejo \
  "https://codeberg.org/forgejo/forgejo/releases/download/v${FORGEJO_VERSION}/forgejo-${FORGEJO_VERSION}-linux-amd64"

chmod +x /usr/local/bin/forgejo

# 验证
forgejo --version

5.2.2 创建系统用户和目录

sudo adduser \
  --system \
  --shell /bin/bash \
  --group \
  --home /home/git \
  --disabled-password \
  git

sudo mkdir -p /var/lib/forgejo/{custom,data,log}
sudo mkdir -p /etc/forgejo

sudo chown -R git:git /var/lib/forgejo/
sudo chown root:git /etc/forgejo
sudo chmod 750 /etc/forgejo

5.2.3 Systemd 服务

sudo tee /etc/systemd/system/forgejo.service << 'EOF'
[Unit]
Description=Forgejo (Beyond coding. We forge.)
After=syslog.target
After=network.target
After=postgresql.service

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

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable forgejo
sudo systemctl start forgejo

5.2.4 Docker Compose 部署

# docker-compose.yml
version: "3"

services:
  forgejo:
    image: codeberg.org/forgejo/forgejo:9
    container_name: forgejo
    restart: always
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - FORGEJO__database__DB_TYPE=postgres
      - FORGEJO__database__HOST=db:5432
      - FORGEJO__database__NAME=forgejo
      - FORGEJO__database__USER=forgejo
      - FORGEJO__database__PASSWD=forgejo_password
    volumes:
      - ./forgejo/data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "2222:22"
    networks:
      - forgejo-network
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    container_name: forgejo-db
    restart: always
    environment:
      - POSTGRES_USER=forgejo
      - POSTGRES_PASSWORD=forgejo_password
      - POSTGRES_DB=forgejo
    volumes:
      - ./postgres/data:/var/lib/postgresql/data
    networks:
      - forgejo-network

networks:
  forgejo-network:
    driver: bridge

注意: 从 Docker Hub 拉取 Forgejo 镜像更稳定：image: codeberg.org/forgejo/forgejo:9 可替换为检查最新镜像源。部分环境中可能需要使用 codeberg.org/forgejo/forgejo 镜像仓库地址。

5.3 配置文件

# /etc/forgejo/app.ini

[server]
DOMAIN           = git.example.com
HTTP_PORT        = 3000
ROOT_URL         = https://git.example.com/
SSH_DOMAIN       = git.example.com
SSH_PORT         = 22
START_SSH_SERVER = false
LFS_START_SERVER = true
LFS_CONTENT_PATH = /var/lib/forgejo/data/lfs
OFFLINE_MODE     = true
DISABLE_SSH      = false

[database]
DB_TYPE  = postgres
HOST     = 127.0.0.1:5432
NAME     = forgejo
USER     = forgejo
PASSWD   = forgejo_password
SSL_MODE = disable

[repository]
ROOT                     = /var/lib/forgejo/data/repositories
DEFAULT_BRANCH           = main
ENABLE_PUSH_CREATE_USER  = true
ENABLE_PUSH_CREATE_ORG   = true

[service]
DISABLE_REGISTRATION              = false
REQUIRE_SIGNIN_VIEW               = false
ENABLE_NOTIFY_MAIL                = true

[security]
INSTALL_LOCK     = true
SECRET_KEY       = change_me_to_random_string
INTERNAL_TOKEN   = change_me_to_another_random_string
PASSWORD_COMPLEX = spec

[log]
MODE      = file
LEVEL     = Info
ROOT_PATH = /var/lib/forgejo/log

[cache]
ADAPTER = redis
HOST    = redis://127.0.0.1:6379/0

[queue]
TYPE     = redis
CONN_STR = redis://127.0.0.1:6379/1

[metrics]
ENABLED = true

5.4 Forgejo Actions

Forgejo Actions 是 Forgejo 的 CI/CD 功能，兼容 GitHub Actions 语法，并在此基础上增加了自己的扩展。

5.4.1 启用 Actions

# /etc/forgejo/app.ini
[actions]
ENABLED        = true
DEFAULT_ACTIONS_URL = https://github.com

5.4.2 安装 Runner

# 下载 Runner
RUNNER_VERSION="0.2.11"
wget "https://codeberg.org/forgejo/act_runner/releases/download/v${RUNNER_VERSION}/act_runner-${RUNNER_VERSION}-linux-amd64"
chmod +x act_runner-*
sudo mv act_runner-* /usr/local/bin/act_runner

# 生成配置文件
act_runner generate-config > config.yaml

# 获取注册 Token
# 在 Web 界面: Site Administration → Actions → Runners → Create New Runner
# 或通过 API:
TOKEN=$(curl -s -X GET \
  -H "Authorization: token YOUR_ADMIN_TOKEN" \
  "https://git.example.com/api/v1/admin/runners/registration-token" | jq -r '.token')

# 注册 Runner
act_runner register \
  --instance https://git.example.com \
  --token "$TOKEN" \
  --config config.yaml

5.4.3 Runner Systemd 服务

sudo tee /etc/systemd/system/forgejo-runner.service << 'EOF'
[Unit]
Description=Forgejo Actions Runner
After=network.target forgejo.service

[Service]
Type=simple
User=git
ExecStart=/usr/local/bin/act_runner daemon --config /home/git/runner/config.yaml
Restart=always
RestartSec=5s

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable forgejo-runner
sudo systemctl start forgejo-runner

5.4.4 编写工作流

# .forgejo/workflows/ci.yml
name: CI Pipeline

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

env:
  REGISTRY: git.example.com:5000

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run linter
        run: |
          echo "Running linter..."
          # 示例：使用 eslint
          # npm ci && npx eslint .

  test:
    runs-on: ubuntu-latest
    needs: lint
    strategy:
      matrix:
        node-version: [18, 20, 22]
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci
      - run: npm test

  build:
    runs-on: ubuntu-latest
    needs: test
    steps:
      - uses: actions/checkout@v4
      - name: Build application
        run: |
          npm ci
          npm run build
      - name: Upload build artifact
        uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/

  deploy:
    runs-on: ubuntu-latest
    needs: build
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist/
      - name: Deploy to server
        run: |
          echo "Deploying..."
          # scp -r dist/ deploy@server:/var/www/app/

5.4.5 使用 Forgejo Container Registry

# .forgejo/workflows/publish-image.yml
name: Publish Docker Image

on:
  push:
    tags:
      - 'v*'

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Login to Forgejo Container Registry
        run: |
          echo "${{ secrets.REGISTRY_TOKEN }}" | \
            docker login git.example.com -u "${{ github.actor }}" --password-stdin
      
      - name: Build and push
        run: |
          IMAGE=git.example.com/${{ github.repository }}:latest
          docker build -t "$IMAGE" .
          docker push "$IMAGE"

5.5 从 Gitea 迁移到 Forgejo

5.5.1 迁移策略

由于 Forgejo 基于 Gitea 的代码库，迁移相对简单：

数据	迁移方式
仓库（Git 数据）	直接复制 repositories 目录
数据库	直接导入（兼容 PostgreSQL/MySQL/SQLite）
附件/LFS	复制 data 目录
配置文件	大部分兼容，少量键名可能不同
Webhooks	数据库中，自动迁移
Actions	可能需要重新注册 Runner

5.5.2 迁移步骤

# 1. 停止 Gitea 服务
sudo systemctl stop gitea

# 2. 备份所有数据
sudo tar czf /var/backups/gitea-backup-$(date +%Y%m%d).tar.gz \
  /var/lib/gitea/ /etc/gitea/

# 3. 安装 Forgejo 二进制
sudo cp forgejo /usr/local/bin/forgejo
sudo chmod +x /usr/local/bin/forgejo

# 4. 复制数据目录（如果路径不同）
sudo cp -a /var/lib/gitea/* /var/lib/forgejo/

# 5. 复制配置文件
sudo cp /etc/gitea/app.ini /etc/forgejo/app.ini
# 根据 Forgejo 文档调整配置差异

# 6. 修改 Systemd 服务
sudo systemctl disable gitea
sudo systemctl enable forgejo

# 7. 启动 Forgejo
sudo systemctl start forgejo

# 8. 检查日志
sudo journalctl -u forgejo -f

重要: 迁移前务必备份，建议在测试环境先验证。

5.6 联邦化特性（实验性）

Forgejo 支持 W3C ActivityPub 协议，这是 Forgejo 独有的实验性特性。

# 启用 ActivityPub
[ federation ]
ENABLED = true

启用后，不同 Forgejo 实例之间可以：

关注其他实例上的用户
跨实例查看和评论 Issue
跨实例协作（未来计划）

注意: 联邦化功能仍在积极开发中，生产环境使用需谨慎评估。

5.7 Forgejo 专属功能

5.7.1 邮件通知增强

Forgejo 对邮件通知功能做了改进：

[mailer]
ENABLED        = true
FROM           = git@example.com
MAILER_TYPE    = smtp
SMTP_ADDR      = smtp.example.com
SMTP_PORT      = 587
IS_TLS_ENABLED = true
USER           = noreply@example.com
PASSWD         = smtp_password

5.7.2 更严格的安全默认值

Forgejo 默认启用了更严格的安全策略：

[security]
; 密码复杂度要求
PASSWORD_COMPLEX = spec
; 最小密码长度
MIN_PASSWORD_LENGTH = 10
; 两步验证策略
TWO_FACTOR_AUTH = true

5.8 日常运维

# 查看服务状态
sudo systemctl status forgejo

# 重启服务
sudo systemctl restart forgejo

# 查看日志
sudo journalctl -u forgejo -f
tail -f /var/lib/forgejo/log/forgejo.log

# 数据库维护（SQLite）
sudo -u git sqlite3 /var/lib/forgejo/data/forgejo.db "VACUUM;"

# 清理旧数据
sudo -u git forgejo manager flush-queues
sudo -u git forgejo doctor --run gc-repos

# 版本升级
# 1. 下载新版本
# 2. 停止服务
# 3. 替换二进制
# 4. 启动服务
# 5. 在 Web 界面完成数据库迁移（如需要）

5.9 扩展阅读

本章小结

学到了什么	关键要点
定位	Gitea 的社区驱动分支，由非营利组织治理
安装	二进制/ Docker，配置与 Gitea 高度兼容
Actions	兼容 GitHub Actions 语法，独立 Runner
迁移	从 Gitea 迁移简单，数据目录和数据库直接复用
特色	联邦化（ActivityPub）、更严格的安全默认值、社区治理

下一章：第 6 章 - GitLab CE 企业方案 — 搭建 GitLab Community Edition，构建一体化 DevOps 平台。