属于你自己的 Git 服务器。
仓库就是组织架构图。

从能解决你问题的最小方案开始，因为在它之上的每一层，都是一项你必须亲自运维的服务。通过 SSH 使用的裸仓库，在你已有的服务器上只需一条命令，就能给你一个具备身份验证、历史记录和推送权限的真正 Git 远程仓库。没有 Web 应用，没有数据库，没有没完没了的升级，除了 sshd 之外什么都不用打补丁。如果你只是一个人，只是想把提交从笔记本电脑和某个平台上搬出来，这就是一个完整的答案，你在读完步骤 02 之后就可以不用再往下看了。

# On the server, as an unprivileged user:
mkdir -p ~/git/project.git && cd ~/git/project.git
git init --bare

# On your laptop:
git remote add origin ssh://user@git.example.com/~/git/project.git
git push -u origin main

一旦有第二个人参与进来，或者你想要一堆裸仓库所在的目录完全做不到的那四件事——在浏览器里浏览历史记录、以拉取请求的形式审查改动、在代码旁边跟踪工单，以及把某一个仓库的访问权限单独授予某一个人——你就需要一个代码托管平台了。这在能力上是真正的提升，在运维负担上也是真正的提升。请慎重选择：

Forgejo 和 Gitea 师出同源，日常使用起来也几乎一模一样。Forgejo 于 2024 年初硬分叉而来，由 Codeberg e.V. 持有，这是一家总部位于柏林的非营利注册社团；Gitea 则由一家营利性公司开发，该公司拥有其商标，并要求贡献者转让版权。两者都是优秀的软件。但只有其中一个的托管方，其利益动机与你阅读这篇文章的初衷相符。

本指南接下来的部分都使用 Forgejo。步骤 02 到步骤 06 中的几乎所有内容，原封不动地套用到 Gitea 上也同样成立——变化的只是容器名称和少数几个环境变量，整体结构不变。

Forgejo、PostgreSQL 和 Caddy。Forgejo 保存仓库并提供界面服务，PostgreSQL 保存所有非 Git 对象的内容，Caddy 负责终结 TLS 并自动申请证书，无需你多说第二遍。PostgreSQL 被刻意设置为不对主机开放：它只能通过 Compose 网络、以服务名的方式，被那一个真正需要它的容器访问到。

/srv/forgejo/.env

FORGEJO_DOMAIN=git.example.com
FORGEJO_VERSION=15                             # the LTS line; 16 is current stable
POSTGRES_PASSWORD=$(openssl rand -base64 32)   # paste the value, do not leave the $( )

/srv/forgejo/docker-compose.yml

services:
  forgejo:
    image: codeberg.org/forgejo/forgejo:${FORGEJO_VERSION}
    container_name: forgejo
    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: ${POSTGRES_PASSWORD}
      FORGEJO__server__DOMAIN: ${FORGEJO_DOMAIN}
      FORGEJO__server__ROOT_URL: https://${FORGEJO_DOMAIN}/
      FORGEJO__server__SSH_DOMAIN: ${FORGEJO_DOMAIN}
      FORGEJO__server__SSH_PORT: "2222"          # what clones will say
      FORGEJO__server__SSH_LISTEN_PORT: "22"     # what the container listens on
      FORGEJO__service__DISABLE_REGISTRATION: "true"
      FORGEJO__repository__DEFAULT_PRIVATE: private
      FORGEJO__security__INSTALL_LOCK: "true"
    restart: unless-stopped
    volumes:
      - ./data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "127.0.0.1:3000:3000"    # web, reached only by Caddy
      - "2222:22"                # git over SSH, public
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    container_name: forgejo-db
    environment:
      POSTGRES_USER: forgejo
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: forgejo
    restart: unless-stopped
    volumes:
      - ./postgres:/var/lib/postgresql/data
    # No ports: block. This is the point.

  caddy:
    image: caddy:2-alpine
    container_name: forgejo-caddy
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - ./caddy-data:/data
      - ./caddy-config:/config

/srv/forgejo/Caddyfile

git.example.com {
    encode zstd gzip
    request_body {
        max_size 512MB          # raise it if you push large repositories
    }
    reverse_proxy 127.0.0.1:3000
}

这两行 SSH 配置是最容易出错的地方，值得多读一遍。SSH_LISTEN_PORT 是容器内部的端口，也就是 Forgejo 内置 SSH 服务器绑定的端口。SSH_PORT 则是 Forgejo 在展示给你的克隆地址中打印出来的端口——它必须和端口映射对外的那一侧保持一致。一旦这两者对不上，其他一切都能正常工作，唯独用户复制粘贴的那个地址会出问题。

启动它，然后通过命令行创建管理员。 不要使用 Web 安装程序。在一个全新的实例上，任何找到这个主机名的人都能访问到它，而通过它创建的第一个账户就会成为管理员——这是一场你完全没必要参与的竞速。上面文件中的 INSTALL_LOCK，会在容器启动之前就把这条路堵死。

docker compose up -d
docker compose logs -f forgejo        # wait for "Starting new Web server"

docker compose exec -u git forgejo forgejo admin user create \
  --admin --username you --email you@example.com --random-password

在浏览器中打开这个主机名，用打印出来的密码登录，然后修改密码。接下来逐一检查那些能把一个“能用”的实例变成一个“封闭”实例的设置——大部分在上面的环境变量区块里已经设置好了，但每一项都值得亲自确认，而不是想当然地认为它已经生效：

有一条路径值得记住：实际生效的配置文件，在主机上位于 ./data/gitea/conf/app.ini。Forgejo 保留了 gitea 这个目录名，是为了兼容已有的安装，这一点每个人都会被“惊到”一次，但也就那一次。形如 FORGEJO__section__KEY 的环境变量会在启动时被写入这个文件，所以你完全可以只通过 Compose 文件来管理整套配置——但如果你手动编辑了 app.ini，对应同一个键的环境变量会在下次重启时覆盖掉你的修改。这两种方式只能二选一，并保持前后一致。

Forgejo Actions 会从 .forgejo/workflows/ 中读取与 GitHub Actions 相同格式的工作流文件，并把它们交给一个叫做 Forgejo Runner 的独立程序去执行。这个运行器并不是代码托管平台的一部分，也不必和它运行在同一台机器上——这正是整个设计的用意所在，也是这一步要专门提出警告、而不是一带而过的原因。

在实例上启用 Actions，然后从管理面板中获取一个注册令牌——可以是整个实例通用的，也可以限定在某一个组织或某一个仓库范围内；如果你拿不准，后者是更稳妥的默认选择。运行器是主动向外连接到代码托管平台的，所以完全不需要任何入站端口，可以放在你喜欢的任何防火墙后面，哪怕是一台没有公网地址的机器上也没问题。

# In the Compose environment of the forge, or app.ini:
#   FORGEJO__actions__ENABLED: "true"
# Then: Site administration -> Actions -> Runners -> Create new runner

# On the runner machine:
forgejo-runner generate-config > config.yml

forgejo-runner register --no-interactive \
  --instance https://git.example.com \
  --token <REGISTRATION_TOKEN> \
  --name runner-01 \
  --labels docker:docker://node:22-bookworm,debian:docker://debian:12

forgejo-runner --config config.yml daemon

标签，就是工作流和运行器之间的契约：一个要求 runs-on: docker 的任务，会得到一个由右侧镜像构建出来的容器。只声明你真正准备好提供的那些标签，因为一个任务如果要求一个没人提供的标签，会永远等下去，而不是直接失败——在漫长的一天快结束时去排查这种问题，会让人相当抓狂。

.forgejo/workflows/ci.yml

on: [push, pull_request]

jobs:
  test:
    runs-on: docker
    container:
      image: node:22-bookworm
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test

用同样的方式限定密钥的作用范围。Forgejo 在仓库、组织和实例三个层级都能存放密钥；一个只有某一个仓库需要用到的部署密钥，就应该只存在于那一个仓库上，这样一个不相关项目里被攻破的工作流才无法读到它。只要目标支持，就优先使用短期令牌而不是长期令牌，并且永远不要把密钥直接写进工作流文件——工作流文件是仓库的一部分，而仓库是有历史记录的。

如果你的构建每次都要拉取相同的基础镜像，就把它们缓存起来。一个本地镜像仓库缓存，或者一个持久化的运行器缓存，能把两分钟的镜像拉取变成两秒钟，对你正在高频请求的上游镜像仓库来说，这也是种礼貌。另外要注意，整个设计本身鼓励的这种模式，正是本指南与智能体运行时指南放在一起的原因：运行器本质上是一个从你的代码托管平台拉取任务的通用工作节点，所以定时维护任务、数据管道和智能体负载，同样也该放在这里。

自建代码托管平台，确实真真切切地改变了谁掌握着你的成果，但这并不等于隐形。做完上面的一切之后，有四件事依然成立，认清它们，才是“真正的防御”和“自己讲给自己听的故事”之间的区别。

磁盘，在别人的楼里。 一台租来的服务器，运行在某个数据中心里的硬件上，那里有门、也有工作人员。NordBastion 不会检查客户的工作负载，透明度报告和预警金丝雀说明了如果我们被要求配合会发生什么——但架构层面的说法才是最诚实的：改变的是，不再有针对你仓库的产品级索引，不再有分析你提交记录的数据管道，也不再有一份可以被随时修改的隐私政策。不变的是，这台机器依然是实体的，也依然不在你自己家里。

证书一签发，主机名就立刻公开。 每一张受公众信任的证书，都会被记录进任何人都能搜索的证书透明度日志，所以即便你从未链接过它，git.yourproject.com 依然是可以被发现的。这泄露的不是你的代码，而是“这个项目存在，而且大致是什么时候开始的”这一事实。可以使用一个你已经公开的域名下的子域名，或者干脆完全跳过公开证书，改用 WireGuard 或洋葱服务来访问这个代码托管平台。

现在，你要负责给一个 Web 应用打补丁了。 这个代码托管平台是一个登录页面、一条处理不受信任标记内容的渲染管线、一个 SSH 服务器，还是一个 CI 引擎，而且全都能从互联网访问到。这比步骤 01 里的裸仓库，攻击面要大得多，而且你必须让它保持最新。订阅发布公告，把安全更新当成“这周就得处理”的事，而不是“这个季度找时间弄”的事。

联邦化还没到来。 Forgejo 在代码托管平台的联邦化上确实在做实事，也一直在公布进展，但截至目前，你还无法像在共享平台上那样，从自己的实例上向别人的实例发起拉取请求。这在实践中意味着：外部贡献者要么仍需要一个你这边的账户，要么你改为通过邮件接收补丁，要么你保留一个公开镜像，专门接收路过式的贡献。提前为符合你项目情况的那一种做好打算，而不是等它发生了才感到意外。

你确切买到的到底是什么：这份记录了你在构建什么、和谁一起构建、以及何时开始的带日期的记录，不再由一家把分析它写进商业模式里的公司掌握。这个说法很有限，但它是真实的。而它只有在步骤 06 真正完成之后，才配得上你为此付出的代价——一个从未测试过恢复的自建代码托管平台，算不上什么隐私上的进步，它只是一个包装得更好看的单点故障。