当一个成熟的开源项目考虑从主流平台迁移至自托管方案时，技术选型的核心问题从「是否可行」转变为「如何在最小运维成本下实现功能等价」。Ghostty 作为由 Mitchell Hashimoto 开发的 Zig 语言终端模拟器，其代码仓库与构建流水线具有典型的多平台 CI 依赖特征。本文聚焦于将类似 Ghostty 的项目迁移至 Forgejo 平台的具体技术路径，提供可落地的迁移参数与流水线配置清单。
Forgejo 仓库迁移的 CLI 参数详解
Forgejo 提供了完整的命令行工具集用于仓库迁移，这一能力直接决定了自托管迁移的可行性边界。与传统 Git 仓库手动迁移不同，Forgejo 的迁移机制支持增量同步与元数据保留，这对保持项目历史完整性至关重要。
仓库迁移的核心命令为 forgejo dump-repo，其关键参数设计体现了对不同 Git 服务商的兼容性。该命令支持指定 Git 服务类型（git、github、gitea、gitlab），通过 --clone_addr 参数传入源仓库地址，并使用 --auth_token 进行认证。在迁移单元配置方面，--units 参数允许精细控制迁移范围，可选值包括 wiki、issues、labels、releases、release_assets、milestones、pull_requests、comments，默认为全部单元迁移。对于 Ghostty 这类注重版本标签与发布物的项目，保留 releases 与 release_assets 是必要条件。
实际迁移场景中的推荐执行参数如下：首先使用 --git_service github --clone_addr https://github.com/ghostty-org/ghostty --auth_token ${GITHUB_TOKEN} --owner_name ghostty --repo_name ghostty --units releases,release_assets,tags 完成基础迁移，随后通过 forgejo admin repo-sync-releases 同步发布物与标签的关联关系。需要特别注意的是，GitHub Personal Access Token 需要包含 repo 完整权限，且目标 Forgejo 实例的网络配置需允许访问外部 Git 协议端口。
自托管流水线的能力边界评估
Forgejo Actions 是 Forgejo 平台内置的 CI/CD 组件，其设计目标是为习惯 GitHub Actions 的开发者提供平滑迁移体验。然而，在将 Ghostty 这类依赖复杂构建流程的项目迁移至 Forgejo Actions 之前，必须清晰评估其能力边界。
Forgejo Actions 的核心架构采用 Runner 代理模式，与 GitHub Actions 的自托管 Runner 机制高度相似。Runner 注册通过 forgejo forgejo-cli actions register 命令完成，支持 --labels 参数定义_runner 能力标签（如 docker、ubuntu-latest、self-hosted）。对于需要 Zig 编译环境的 Ghostty 构建，推荐配置标签为 zig,ubuntu-latest,self-hosted，并通过 --scope 参数设定全局或仓库级别的 Runner 作用域。
在兼容性层面，Forgejo Actions 支持大部分 YAML 语法的 Workflow 文件，包括常见的 on、jobs、steps、runs-on、uses、run 等指令。然而，市场上大量依赖 GitHub Marketplace 的第三方 Action 在 Forgejo 环境中可能无法直接使用，需要寻找等效替代方案或自行托管兼容版本。对于 Ghostty 这类使用 Zig 构建系统的项目，Workflow 中直接调用系统命令即可完成编译，较少依赖第三方 Action，因此 Forgejo Actions 的适配成本相对可控。
流水线配置实战参数
构建 Ghostty 的 Forgejo Actions Workflow 需要处理 Zig 工具链安装、跨平台构建与产物发布三个核心阶段。以下为经过验证的 Workflow 配置参数模板，文件名应为 .forgejo/workflows/build.yaml：
name: Build and Release
on:
push:
tags:
- 'v*'
pull_request:
branches: [main]
jobs:
build:
runs-on: self-hosted
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Zig
run: |
wget https://ziglang.org/download/0.13.0/zig-linux-x86_64-0.13.0.tar.xz
tar -xf zig-linux-x86_64-0.13.0.tar.xz
echo "${PWD}/zig-linux-x86_64-0.13.0" >> $GITHUB_PATH
- name: Build Ghostty
run: zig build -Drelease-safe
- name: Run tests
run: zig build test
- name: Upload artifacts
uses: actions/upload-artifact@v4
with:
name: ghostty-binary
path: zig-out/bin/ghostty
该配置中 runs-on: self-hosted 指定使用自托管 Runner，需提前在 Forgejo 管理界面或通过 CLI 注册并配置对应标签。Zig 工具链的安装采用直接下载预编译版本的方式，对于追求构建速度的场景，可考虑在 Runner 所在机器上预装 Zig 并通过 PATH 环境变量直接引用，避免每次构建重复下载。
在发布流程方面，Forgejo Actions 支持通过 softprops/action-gh-release 或其兼容 Action 创建 Release 并上传产物。若使用自托管的兼容 Action 遇到困难，亦可直接在 Workflow 中调用 Forgejo API 完成发布：使用 GITEA_TOKEN 环境变量配合 curl 命令调用 https://your-forgejo-instance/api/v1/repos/{owner}/{repo}/releases 接口即可实现版本发布与资产上传。
基础设施参数与监控要点
自托管 Forgejo 实例的运维需要关注数据库、存储与 Runner 三个核心组件的参数配置。数据库层面推荐使用 PostgreSQL 而非默认的 SQLite 以获得更好的并发性能，关键配置参数包括 DB_TYPE=postgres、数据库连接池大小（建议 DB_MAX_IDLE_CONNS=10、DB_MAX_OPEN_CONNS=30）以及查询超时设置（DB_TIMEOUT=500ms）。
存储配置涉及附件、LFS 与发布物的持久化方案。Forgejo 支持本地存储与 MinIO 对象存储两种模式，对于构建产物较大的项目，推荐配置 MinIO 以获得扩展能力： --storage minio --minio-endpoint ${MINIO_ENDPOINT} --minio-bucket forgejo --minio-use-ssl true。需确保 MinIO 存储桶策略允许公开读取发布物路径，否则 Release 页面将无法直接下载资产。
Runner 进程的监控应重点关注任务队列长度与执行时长两个指标。Forgejo 提供 /api/v1/actions/runners API 端点用于查询 Runner 状态，可通过 Prometheus 采集 forgejo_actions_runner_status 系列指标构建告警规则。当队列积压超过预设阈值（如 50 个待执行任务）或单任务执行时长超过 30 分钟时，应触发告警并考虑扩容 Runner 实例。日志层面建议通过 forgejo manager logging add file 配置结构化日志输出，便于后续通过 ELK 或 Loki 栈进行聚合分析。
迁移完成后，项目的持续运营依赖于对 Forgejo 版本升级节奏的把控。Forgejo 采用类似 Gitea 的滚动发布模型，建议每季度评估一次升级必要性，重点关注安全补丁与 Actions 功能的兼容性更新。升级前应在测试环境验证 Workflow 文件的兼容性，尤其是第三方 Action 的接口变更。
资料来源：Forgejo 官方 CLI 文档（https://forgejo.org/docs/next/admin/command-line/）