Forgejo 部署教程：私有 Git 仓库、HTTPS 推送与备份

开始前

个人脚本、站点配置和未公开的项目，放在自己能管理的 Git 服务里，查历史和迁移都会方便一些。Forgejo 可以提供仓库、议题和代码协作界面。真正需要提前安排的，是谁能创建账号、仓库默认是否私有，以及服务器出问题后如何恢复。

先把目标缩小：这次只部署一个私有代码站，验证网页、HTTPS 推送和仓库恢复。Actions Runner、包仓库、邮件通知可以等基础数据和访问正常后再加，避免一开始同时排查代码服务、构建环境和通知链路。

部署前先确认 VPS 的磁盘、内存和公网访问条件，也可以查看雨云云服务器；注册时填写优惠码 `KuZhuJi`。

先用 HTTPS，暂时不开放第二个 SSH 入口

Git 服务的网页入口和系统 SSH 是两回事。本文保留服务器原有 SSH 管理方式，仅把 Forgejo 的 3000 端口绑定回环地址，由反向代理提供 HTTPS。仓库先通过 HTTPS 克隆和推送，因此不用额外暴露容器的 22 端口。

HTTPS 入口负责网页和 Git 请求，`/data` 保存应用的持久内容。电脑上的仓库副本能保住一部分代码历史，但不能完整替代服务端的用户、议题、附件和配置。

安装时应已有 Docker Compose，并准备一个独立域名。以下镜像主版本 `16` 对应官方当前 Docker 文档。它会跟随这个主版本的更新；正式运行后记录实际镜像摘要，升级前核对发行说明，跨主版本升级不当作普通拉取镜像处理。

mkdir -p ~/services/forgejo/data
cd ~/services/forgejo
sudo chown -R 1000:1000 data

`1000:1000` 对应下面设置的应用 UID/GID。它并不要求宿主机一定有同名用户，但目录所有权必须和容器里运行服务的身份匹配。不要为了省事改成所有人可写。

保存 `compose.yaml`：

services:
  forgejo:
    image: codeberg.org/forgejo/forgejo:16
    environment:
      USER_UID: "1000"
      USER_GID: "1000"
      FORGEJO__server__DOMAIN: git.example.com
      FORGEJO__server__ROOT_URL: https://git.example.com/
      FORGEJO__server__DISABLE_SSH: "true"
      FORGEJO__service__DISABLE_REGISTRATION: "true"
    ports:
      - "127.0.0.1:3004:3000"
    volumes:
      - ./data:/data
    restart: unless-stopped

把域名替换成实际入口。Forgejo 支持按 `FORGEJO__章节__字段` 映射配置；这里提前关闭公开注册，并让应用给出的仓库地址使用正式 HTTPS 域名。仅设置 `ROOT_URL` 不会自动生成 DNS 或证书，反向代理仍需另行配置。

docker compose config --quiet
docker compose up -d
docker compose logs --tail=100 forgejo

若 Codeberg 镜像仓库在当前网络不可达，官方文档提供 `data.forgejo.org` 作为镜像地址替代。先确认网络和官方说明，不从搜索结果里随便拿一个同名第三方镜像。

安装界面里的 SQLite 适合从小实例起步

用 SSH 先进入安装页：

ssh -L 13004:127.0.0.1:3004 user@your-server

本机打开 `http://127.0.0.1:13004`。首次安装可选择 SQLite，并保持数据库文件位于持久的 `/data` 路径中。仓库目录、应用配置和日志路径也应留在持久区域；不要把重要文件配置到容器临时层。

填写站点名称、服务器域名和基础 URL，核对它们与 Compose 一致。通过安装界面设置首个管理员，使用独立密码；如果部署后看不到预期安装入口，先读日志和已有数据，不要删除整个目录反复重试。

反向代理接到宿主机 `127.0.0.1:3004`。HTTPS 生效后，用正式域名登录，创建一个私有仓库，再从另一个未登录窗口访问它。预期无权限的访问应被挡住，公开首页可以展示的内容则根据自己的设置决定。

准备独立实例时，可在雨云选择适合的云服务器配置，优惠码 `KuZhuJi`。配置按实际任务选择，数据库和附件另做备份。

一次真实推送比只看首页更有用

创建测试仓库时，把可见性明确设为私有，并添加 README。先通过网页写入一小段内容，再使用页面给出的 HTTPS 地址克隆。根据实例的认证设置，Git 操作可能需要个人访问令牌；为令牌选择完成当前任务所需的范围，不在仓库 URL 中直接嵌入令牌。

git clone https://git.example.com/owner/test-repo.git
cd test-repo
printf '\nDeployment check\n' >> README.md
git add README.md
git commit -m 'Check HTTPS push'
git push

将 `owner/test-repo` 换成实际仓库。命令需要本机已安装 Git、设置提交身份，并能完成该实例的认证。提交后回网页检查新提交、差异和作者信息；再在另一目录克隆，确认新内容真的来自服务端。

遇到推送失败，记录 HTTP 状态、时间和客户端报错。网页能登录但 Git 失败，可能涉及令牌、权限、代理请求大小或超时；不要直接把仓库改为公开来绕过认证。大文件传输与普通小文本的验证也不同，需要时再单独检查 Git LFS。

私有仓库仍然需要团队权限管理

管理员负责实例维护，日常写代码的账号尽量只拿需要的仓库权限。协作者可以按仓库或组织授权，临时外包只进入有关项目，不共享管理员账号。账号离开后，撤销成员权限及相关令牌，检查是否还保留部署密钥和 Webhook。

代码里出现密码后，仅删除当前文件通常不够，因为历史提交中可能仍然存在。先轮换已经泄露的凭据，再处理仓库历史和其他副本。私有仓库可以控制访问范围，但不能替代密钥管理，也不能保证所有协作者的电脑一直安全。

另一个常见误区是把服务器配置文件整体提交。Compose 可以进入仓库，含有实际密码的 `.env` 应留在受保护的部署位置；提供 `.env.example` 说明所需字段。忽略文件只能避免未来误提交，已经进入历史的敏感值仍需要处理。

需要增加服务器时，可以打开雨云选购页面，填写优惠码 `KuZhuJi`；迁移前保留数据与原有部署配置。

备份范围比 Git 仓库目录更大

一个 Git 仓库的镜像副本主要保护代码与引用。实例的用户、议题、评论、附件、应用配置和数据库，需要按实际部署一起保存。这里采用 SQLite 且持久内容放在 `data` 下，暂停应用后复制整个目录，可以把备份边界说明得比较清楚。

mkdir -p backups
docker compose stop forgejo
tar -czf "backups/forgejo-$(date +%F-%H%M%S).tar.gz" data compose.yaml
docker compose start forgejo

文件含有内部数据和可能的敏感配置，限制权限并转移到服务器之外。若以后改为 PostgreSQL，以上目录复制不包含外部数据库，必须增加一致的数据库导出。插件、对象存储或其他独立服务也不能默认已经被打包。

恢复演练在独立目录使用原镜像，映射另一个回环端口。首先检查管理员能登录，然后检查私有仓库、测试提交、议题和附件。最后使用新测试地址克隆仓库；如果只看网页上仓库名还在，就无法确认实际 Git 对象可读。

升级前记录可以回退到哪一份数据

固定版本不是永久不升级。定期查看维护公告、发行说明和当前主版本的支持情况，把升级安排在有完整备份、能做验收的时间。涉及迁移时，先在副本上验证升级路径，读清是否要求中间版本。

回退需要旧镜像和升级前数据一起保存。数据库一旦被新版本迁移，只把容器镜像改回旧版本可能仍然打不开。把备份时间、对应镜像和恢复步骤放在一份服务器之外的维护记录中；这份记录应能让你在代码站无法访问时仍找到恢复入口。