包管理器操作系统【免费下载链接】nixpkgsNix Packages collection NixOS项目地址https://gitcode.com/GitHub_Trending/ni/nixpkgs点击查看免费下载Forgejo 是 Gitea 的一个 soft-fork强调社区驱动、自托管与联邦federation特性Codeberg 为核心完整讲解在 NixOS 上声明式部署 Forgejo 的推荐方式、app.ini自由配置与密钥管理机制并给出从 Gitea 迁移含版本兼容性约束与两种迁移路径的实战方案。读完本文你将能够独立完成 Forgejo 的初始化部署、数据库与备份配置、基于 systemd 凭据的安全密钥注入以及在受版本约束的前提下从既有 Gitea 实例无损迁移。1. Forgejo 与 Gitea 的关系Forgejo 是 Gitea 的 soft-fork它继承 Gitea 的代码库但更强调社区驱动治理并将**自托管self-hosting与联邦federation**作为核心方向。官方文档原文指出Codeberg 正是从 Forgejo 部署而来的实例这侧面印证了其在大规模自托管场景下的成熟度。在 NixOS 中两者分别有独立模块services.forgejo 与 services.gitea。虽然两个模块共享了大量选项命名例如database.type、stateDir、dump.interval等但 NixOS 官方文档明确警告不再推荐使用services.gitea.package pkgs.forgejo这种方式运行 Forgejo。如果使用services.gitea运行遇到问题不要向services.gitea模块维护者报告而应报告给services.forgejo模块维护者。从模块源码看forgejo.nix 中大量重命名/移除选项的迁移声明都注明copied from services.gitea说明两模块正在逐步分化。因此新部署应直接使用services.forgejo。2. 推荐的部署方式services.forgejo 最小配置首选方式是启用services.forgejo模块。一个最简的配置如下{ pkgs, ... }: { services.forgejo.enable true; }该模块默认值设计得非常开箱即用详见 forgejo.nix 的选项定义选项默认值说明services.forgejo.packagepkgs.forgejo-ltsForgejo 软件包services.forgejo.useWizardfalse是否使用内置安装向导关闭时app.ini由 Nix 声明式生成services.forgejo.stateDir/var/lib/forgejoForgejo 数据目录services.forgejo.customDir${stateDir}/custom自定义模板与运行期配置目录services.forgejo.user/groupforgejo/forgejo运行用户与组services.forgejo.database.typesqlite3数据库引擎sqlite3 / mysql / postgresservices.forgejo.database.name/userforgejo数据库名与用户services.forgejo.repositoryRoot${stateDir}/repositoriesGit 仓库存储路径services.forgejo.lfs.enablefalse是否启用 git-lfsservices.forgejo.dump.enablefalse是否启用定时备份启用模块后NixOS 会自动完成创建系统用户/组forgejo、准备目录stateDir、customDir、repositoryRoot、data、log等权限 0750见模块中的systemd.tmpfiles.rules、生成 systemd 服务forgejo.service默认监听0.0.0.0:3000并在首次启动时自动执行数据库迁移与 hook 路径重建。3. 从 Gitea 迁移到 Forgejo3.1 为什么建议尽早迁移官方文档指出迁移虽然当前并非严格必要但强烈推荐——两个模块及其对应项目很可能随每个版本进一步分化越晚迁移工作量越大。3.2 版本兼容性硬约束务必先读迁移存在两条必须遵守的版本红线Forgejo 侧最后一个支持从 Gitea 迁移的 Forgejo 版本是10.0.x。不要在未先迁移到10.0.x的情况下直接把 Gitea 数据交给 Forgejo11.x或更高版本。Gitea 侧该迁移流程支持的最后一个 Gitea 版本是1.22。不要尝试从 Gitea 1.23 或更高版本直接迁移否则很可能导致数据丢失。3.3 第一步将 Forgejo 锁定到 10.0.x迁移前必须把 Forgejo 固定到10.0.x这要求使用 nixpkgs 提交3bb45b041e7147e2fd2daf689e26a1f970a55d65或更早的版本。做法是临时在configuration.nix中加入{ pkgs, ... }: let nixpkgs-forgejo-10 import (pkgs.fetchFromGitHub { owner NixOS; repo nixpkgs; rev 3bb45b041e7147e2fd2daf689e26a1f970a55d65; hash sha256-8JL5NI9eUcGzzbR/ARkrG81WLwndoxqI650mA/4rUGI; }) { }; in { services.forgejo.package nixpkgs-forgejo-10.forgejo; }该片段通过pkgs.fetchFromGitHub引入旧版 nixpkgs 快照再将其forgejo包覆盖到services.forgejo.package从而在迁移期间获得与 Gitea 1.22 兼容的 Forgejo 10.0.x。3.4 完整迁移Full-Migration完整迁移会执行三步迁移状态目录data、重命名并修改数据库属主、删除 gitea 用户。注意若使用主机自带的 openssh 服务默认而非 Forgejo 内置 SSH迁移后 git remote 的 SSH URL 用户将从gitea变为forgejo。以 PostgreSQL默认为例的迁移命令其他数据库请相应调整systemctl stop gitea mv /var/lib/gitea /var/lib/forgejo runuser -u postgres -- psql -c ALTER USER gitea RENAME TO forgejo; ALTER DATABASE gitea RENAME TO forgejo; nixos-rebuild switch systemctl stop forgejo chown -R forgejo:forgejo /var/lib/forgejo systemctl restart forgejo命令序列要点systemctl stop gitea先停掉旧服务保证数据一致mv /var/lib/gitea /var/lib/forgejo把状态目录整体搬移到新模块默认的stateDir在 PostgreSQL 中重命名用户与数据库ALTER USER/ALTER DATABASE使它们与services.forgejo模块默认的database.name/database.user均为forgejo一致nixos-rebuild switch应用新配置此时services.gitea被禁用、services.forgejo启用chown -R forgejo:forgejo /var/lib/forgejo修正目录属主数据此前属于gitea用户systemctl restart forgejo以新用户启动服务。迁移完成后即可把 Forgejo 版本切回想要的新版本如当前的 16.0.5见 pkgs/by-name/fo/forgejo/package.nix。3.5 替代方案保留 gitea 用户复用旧存储位置如果不想重命名数据库、复制状态目录、更换用户可以让services.forgejo模块直接复用旧存储位置与旧数据库。此时务必先禁用services.gitea{ services.gitea.enable false; services.forgejo { enable true; user gitea; group gitea; stateDir /var/lib/gitea; database.name gitea; database.user gitea; }; users.users.gitea { home /var/lib/gitea; useDefaultShell true; group gitea; isSystemUser true; }; users.groups.gitea { }; }该方案把 Forgejo 模块的user、group、stateDir以及数据库名/用户全部指回 Gitea 原有的值并手动声明gitea系统用户与组从而避免任何数据搬移。需要留意的是模块中有两条相关断言见 forgejo.nix若database.createDatabase为真则database.user必须等于services.forgejo.user自动建库场景下PostgreSQL 自动建库时数据库用户与数据库名必须相同。因此如果沿用旧数据库可能需要将services.forgejo.database.createDatabase显式设为false文档注释说明移除ensureUsers/ensureDatabases不会产生任何副作用。4. 模块配置深度解析4.1 应用与运行身份package / useWizard / user / grouppackage默认指向pkgs.forgejo-lts也可覆盖为其他版本。useWizard默认false表示完全由 Nix 声明式生成app.ini若设为true则改用内置安装向导此时customDir不再承载运行期配置见 forgejo.nix 的选项注释。user/group控制运行身份默认自动创建forgejo系统用户home 指向stateDir。4.2 数据库配置services.forgejo.database { type postgres; # sqlite3 | mysql | postgres host 127.0.0.1; name forgejo; user forgejo; passwordFile /run/keys/forgejo-dbpassword; # 推荐避免明文 # createDatabase true; # 自动创建本地数据库默认开启 };关键行为对应 forgejo.nixtype sqlite3时使用${stateDir}/data/forgejo.db由database.path指定作为数据库文件type postgres且开启createDatabase时模块自动启用 PostgreSQL 并创建同名用户/数据库ensureDatabases/ensureUsers用户拥有库所有权此时默认通过 Unix socket/run/postgresql认证SSL_MODE被设为disabletype mysql时默认使用pkgs.mariadb通过/run/mysqld/mysqld.socksocket 认证并授予该库全部权限密码禁止明文旧选项database.password已被移除必须使用database.passwordFile指向包含密码的文件。密码会通过 secrets 机制注入环境变量而不是写进app.ini。4.3 仓库存储与 LFSrepositoryRoot默认${stateDir}/repositories存放所有 Git 仓库对应app.ini中的repository.ROOT启用services.forgejo.lfs.enable true后模块自动设置server.LFS_START_SERVER true与lfs.PATH ${stateDir}/data/lfs并额外为 LFS 生成LFS_JWT_SECRET密钥见 forgejo.nix。4.4 定时备份dump 子模块services.forgejo.dump { enable true; interval 04:31; # 每天 04:31格式见 systemd.time(7) type tar.zst; # zip | tar | tar.sz | tar.gz | tar.xz | tar.bz2 | tar.br | tar.lz4 | tar.zst file forgejo-dump; # null 时由 forgejo 自动命名 backupDir /var/lib/forgejo/dump; age 4w; # 清理阈值格式见 tmpfiles.d(5) };启用后模块会生成forgejo-dump.serviceoneshot执行forgejo dump --type type [--file file]工作目录为backupDir与forgejo-dump.timer按interval触发见 forgejo.nix。backupDir同时通过tmpfiles规则按age自动清理过期归档。该机制在集成测试中有专门验证测试用type tar.zst、file dump.tar.zst的配置启动 dump 服务并用file命令确认产物为 Zstandard 压缩数据见 nixos/tests/forgejo.nix。5. 声明式配置settings 自由项与 secrets 密钥注入5.1 settings直接映射 app.iniservices.forgejo.settings是自由形式freeform选项键值直接写入app.ini。NixOS 会负责生成 INI 文件并在preStart阶段写入${customDir}/conf/app.ini。模块为常用小节log、server、session提供了类型化的子选项并带默认值其余内容可自由扩展。官方示例见 forgejo.nixservices.forgejo.settings { DEFAULT { RUN_MODE dev; }; cron.sync_external_users { RUN_AT_START true; SCHEDULE every 24h; UPDATE_EXISTING true; }; mailer { ENABLED true; PROTOCOL sendmail; FROM do-not-replyexample.org; SENDMAIL_PATH ${pkgs.system-sendmail}/bin/sendmail; }; other { SHOW_FOOTER_VERSION false; }; };常用内置默认值一览配置项默认值说明settings.server.PROTOCOLhttp监听协议http/https/fcgi/httpunix/fcgiunixsettings.server.HTTP_ADDR0.0.0.0unix 协议时为/run/forgejo/forgejo.sock监听地址settings.server.HTTP_PORT3000监听端口unix socket 时忽略settings.server.DOMAINlocalhost服务器域名settings.server.ROOT_URLhttp://${DOMAIN}:${HTTP_PORT}/对外完整 URLsettings.server.SSH_PORT22克隆 URL 中显示的 SSH 端口端口转发场景下需显式设置settings.server.DISABLE_SSHfalse禁用外部 SSH 功能settings.log.LEVELInfo日志级别Trace/Debug/Info/Warn/Error/Criticalsettings.log.ROOT_PATH${stateDir}/log日志根路径settings.session.COOKIE_SECUREfalseHTTPS 场景建议设为true模块还自动注入若干关键默认值见 forgejo.nixDEFAULT.RUN_MODE prod、RUN_USER、WORK_PATH stateDir、database.DB_TYPE、repository.ROOT、security.INSTALL_LOCK true锁定安装流程防止重复初始化等。5.2 secrets基于 systemd LoadCredential 的密钥管理services.forgejo.secrets是settings的文件版镜像键结构与settings相同但每个值是一个文件路径而不是字符串/布尔值。模块将其包装为 systemd 的LoadCredential文件内容经环境变量导出后再通过 Forgejo 自带的environment-to-ini工具回填进app.ini参见 forgejo.nix。优先级secrets中指定的键优先于settings中同名键。官方示例services.forgejo.secrets { metrics { TOKEN /run/keys/forgejo-metrics-token; }; camo { HMAC_KEY /run/keys/forgejo-camo-hmac; }; service { HCAPTCHA_SECRET /run/keys/forgejo-hcaptcha-secret; HCAPTCHA_SITEKEY /run/keys/forgejo-hcaptcha-sitekey; }; };模块自动为每个 secret 生成对应的环境变量形如FORGEJO__section__key__FILE.与-会被转义为_0X2E_/_0X2D_后大写并在 unit 中通过LoadCredential [ VAR:path ]与environment注入。同时模块内置一个forgejo-secrets.serviceoneshot引导服务首次启动时自动调用forgejo generate secret生成SECRET_KEY、INTERNAL_TOKEN、oauth2 JWT_SECRET及启用 LFS 时的LFS_JWT_SECRET并写入${customDir}/conf/保证高价值密钥持久化且不落入 Nix store见 forgejo.nix。forgejo.service通过Requires/After依赖该引导服务。6. 底层实现systemd 单元与安全加固forgejo.service的生成逻辑forgejo.nix体现了 NixOS 模块的工程细节启动流程preStart中依次执行——写入生成的app.ini并运行environment-to-ini回填密钥 →forgejo migrate初始化/迁移数据库→forgejo admin regenerate hooks更新各仓库 hook 的二进制路径→ 存在authorized_keys时执行admin regenerate keys更新命令选项进程模型Type notifyExecStart forgejo web --pid /run/forgejo/forgejo.pidRestart always环境变量设置USER、HOME stateDir、FORGEJO_WORK_DIR stateDir、FORGEJO_CUSTOM customDir安全加固ProtectSystem strict、ProtectHome、PrivateTmp、PrivateDevices、PrivateUsers、NoNewPrivileges、RestrictAddressFamilies仅 AF_UNIX/AF_INET/AF_INET6、SystemCallFilter排除cpu-emulation debug keyring mount obsolete privileged setuid等、UMask 0027ReadWritePaths仅放开customDir、backupDir、repositoryRoot、stateDir、lfs.contentDirSSH 集成当未启用 Forgejo 内置 SSH 服务时模块会在 OpenSSH 的AcceptEnv中加入GIT_PROTOCOL以便外部 SSH 支持 git 协议 v2集成测试专门验证了 SSH 下协商到 protocol version 2见 nixos/tests/forgejo.nix。此外模块还通过systemd.tmpfiles.rules管理目录创建并收紧stateDir、conf、data、log、repositoryRoot、backupDir的权限0750并把 Forgejo 的 locale 目录以符号链接方式固定到当前包版本L ... ${cfg.package.out}/locale避免升级后语言文件漂移。7. 集成测试三种数据库与核心功能验证NixOS 官方为 Forgejo 模块提供了完整的集成测试 nixos/tests/forgejo.nix同一套测试脚本针对mysql、sqlite3、postgres三种数据库分别运行。测试覆盖的核心场景包括服务启动、HTTP 端口3000与 SSH 端口22就绪首页可访问关闭注册后访问/user/sign_up应提示 Registration is disabled. Please contact your site administrator.通过 API 创建管理员用户、token、仓库与 SSH 公钥客户端完成git push与git clone全流程/metrics端点必须携带secrets.metrics.TOKEN中配置的 Bearer token 才能访问验证 secrets 注入链路通过特殊化specialisation切换 runner 配置验证gitea-actions-runnerdeprecated与forgejo-runner两种 Actions runner 的注册及工作流执行验证forgejo dump备份产物格式正确并可下载。这些测试同时印证了services.forgejo支持通过settings.service.DISABLE_REGISTRATION、settings.repository.signing.SIGNING_KEY、settings.actions.ENABLED、settings.metrics.ENABLED等自由项完成丰富的实例定制。8. 相关软件包与生态当前仓库中与 Forgejo 相关的包均位于pkgs/by-name/fo/pkgs/by-name/fo/forgejo/package.nixForgejo 主程序包当前版本16.0.5lts false即非 LTS 线模块默认使用的forgejo-lts则对应 LTS 版本线pkgs/by-name/fo/forgejo-runner/package.nixForgejo Actions 的官方 runner对应services.forgejo-runner模块pkgs/by-name/fo/forgejo-cli/package.nix 与 pkgs/by-name/fo/forgejo-mcp/package.nix命令行工具与 MCP 集成组件。如果你计划让 Forgejo 承载 CI/CD可以在配置中启用settings.actions.ENABLED true并搭配services.forgejo-runner注册 runner——这也是集成测试中验证过的成熟组合路径。9. 快速上手清单完成一次标准部署的推荐步骤在configuration.nix中启用services.forgejo.enable true并按需调整settings.server.DOMAIN、ROOT_URL、HTTP_PORT生产环境选择database.type postgres或 mysql通过database.passwordFile提供密码避免明文入 store开启services.forgejo.lfs.enable如需要大文件支持与services.forgejo.dump.enable建议type tar.zst;通过services.forgejo.secrets注入 metrics token、captcha 密钥等敏感配置nixos-rebuild switch后访问ROOT_URL完成初始化模块默认已锁定安装流程管理员账号可通过forgejo admin user create创建参见测试脚本 nixos/tests/forgejo.nix。若从 Gitea 迁移请严格遵循第 3 节的版本约束与操作序列先锁定 Forgejo 10.0.xnixpkgs 提交3bb45b041e7147e2fd2daf689e26a1f970a55d65或更早完成数据迁移再切回新版本。10. 结语services.forgejo是 NixOS 上运行 Forgejo 的唯一推荐方式它既提供了开箱即用的默认值sqlite3、系统用户、自动建库、密钥引导又通过 freeform 的settings与secrets保留了与上游app.ini完全对齐的灵活度同时以严格的 systemd 沙箱和断言保障安全与一致性。配合内置的 dump 定时备份与三数据库集成测试你可以放心地将 Forgejo 作为自托管代码托管平台长期运行。赞分享包管理器操作系统【免费下载链接】nixpkgsNix Packages collection NixOS项目地址https://gitcode.com/GitHub_Trending/ni/nixpkgs点击查看免费下载相关推荐PR Agent Gitea 集成部署指南搭建 Gitea/Forgejo Webhook 服务器完整教程PR Agent Gitea 集成部署指南搭建 Gitea/Forgejo Webhook 服务器完整教程 本文面向自托管 Gitea / Forgejo 实人工智能AI Agent代码智能体代码评审AI 应用NixOS 上部署 Apache Kafkaservices.apache-kafka 模块的 KRaft 配置与迁移实战NixOS 上部署 Apache Kafkaservices.apache kafka 模块的 KRaft 配置与迁移实战 Apache Kafka 是一个开包管理器操作系统NixOS 部署 GitLab 全指南services.gitlab 模块的架构、配置、备份、Registry 迁移与 CI Runner 实践NixOS 部署 GitLab 全指南services.gitlab 模块的架构、配置、备份、Registry 迁移与 CI Runner 实践 GitLab包管理器操作系统上一篇如何为你的 Rails 引擎或 gem 配置 Factory Bot Rails下一篇Admin.NET的实际应用案例创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考