Forgejo Docker 部署教程

#knowledge #post

Forgejo Docker 部署教程：使用独立 SSH 22 端口，实现 GitHub 风格 SSH 克隆地址

本文记录一次完整部署过程：
Docker Compose 部署 Forgejo + PostgreSQL，Caddy 反代 Web，独占公网 22 端口提供 Git SSH 服务，并配置 GitHub 风格 SSH URL。

最终效果：

网页：

https://git.zenroly.com

Git SSH：

git clone git@git.zenroly.com:bill/notes.git

无需：

-p 2222

与 GitHub 使用体验一致。

一、设计架构

服务器原本：

sshd
监听 51989

因为安全原因，没有使用默认 SSH 22：

sudo ss -tnlp | grep ssh

结果：

LISTEN 0 128 0.0.0.0:51989 sshd

所以 22 端口空闲，可以交给 Forgejo。

最终架构：

                Internet

                    |
                    |
          git.zenroly.com:22
                    |
                    |
              docker-proxy
                    |
                    |
             Forgejo SSH
                    |
              Git 用户认证


管理SSH:

          server-ip:51989
                    |
                  sshd
                    |
              管理服务器

这样：

互不干扰。

二、安装目录

创建：

mkdir ~/forgejo
cd ~/forgejo

目录：

forgejo/
├── docker-compose.yml
└── data/
    └── gitea/
        └── conf/
            └── app.ini

Forgejo 继承 Gitea 配置路径：

/data/gitea/conf/app.ini

三、docker-compose.yml

最终配置：

networks:
  forgejo_net:

services:
  forgejo:
    image: codeberg.org/forgejo/forgejo:15
    container_name: forgejo
    restart: unless-stopped

    networks:
      - forgejo_net

    depends_on:
      - forgejo-db

    environment:

      # 容器运行用户
      - USER_UID=1001
      - USER_GID=1001


      # PostgreSQL
      - FORGEJO__database__DB_TYPE=postgres
      - FORGEJO__database__HOST=forgejo-db:5432
      - FORGEJO__database__NAME=forgejo
      - FORGEJO__database__USER=forgejo
      - FORGEJO__database__PASSWD=密码


      # 网站
      - FORGEJO__server__ROOT_URL=https://git.zenroly.com/
      - FORGEJO__server__DOMAIN=git.zenroly.com


      # SSH
      - FORGEJO__server__SSH_DOMAIN=git.zenroly.com
      - FORGEJO__server__SSH_PORT=22

      # 注意：
      # 使用宿主机22映射，不使用Forgejo内置SSH
      - FORGEJO__server__SSH_LISTEN_PORT=0.0.0.0:22

      - FORGEJO__server__DISABLE_SSH=false

      # 关闭内置 SSH Server
      - FORGEJO__server__START_SSH_SERVER=false


      # GitHub 风格 SSH URL
      # false = git@host:user/repo.git
      # true  = ssh://git@host/user/repo.git
      - FORGEJO__repository__USE_COMPAT_SSH_URI=false


      # Actions
      - FORGEJO__actions__ENABLED=true
      - FORGEJO__actions__DEFAULT_ACTIONS_URL=https://code.forgejo.org


    volumes:
      - ./data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro


    ports:

      # Web 给 Caddy 反代
      - "127.0.0.1:3000:3000"

      # SSH
      - "22:22"



  forgejo-db:

    image: postgres:16-alpine
    container_name: forgejo-db
    restart: unless-stopped

    networks:
      - forgejo_net

    environment:
      - POSTGRES_DB=forgejo
      - POSTGRES_USER=forgejo
      - POSTGRES_PASSWORD=密码

    volumes:
      - postgres_data:/var/lib/postgresql/data



volumes:

  postgres_data:

四、关键配置说明

1. 不开启 Forgejo 内置 SSH

错误方案：

FORGEJO__server__START_SSH_SERVER=true

原因：

Forgejo 会自己监听：

:22

但是 Docker 已经映射：

宿主机22 -> 容器22

会冲突：

日志：

Failed to start SSH server:
listen tcp :22:
bind: address already in use

所以：

正确：

FORGEJO__server__START_SSH_SERVER=false

2. SSH URL 格式

Forgejo 配置：

FORGEJO__repository__USE_COMPAT_SSH_URI=false

注意：

不是：

FORGEJO__server__USE_COMPAT_SSH_URI

错误位置不会生效。

对应：

[repository]
USE_COMPAT_SSH_URI = false

效果：

false:

git@git.zenroly.com:bill/notes.git

GitHub 风格。

true:

ssh://git@git.zenroly.com/bill/notes.git

标准 SSH URI。

五、启动 Forgejo

首次：

docker compose up -d

修改配置后：

不要：

docker restart forgejo

因为环境变量需要重新创建。

使用：

docker compose down

docker compose up -d --force-recreate

检查：

docker compose ps

应该：

forgejo   Up
forgejo-db Up

六、检查端口

服务器：

sudo ss -tnlp | grep 22

正确：

LISTEN 0 4096 0.0.0.0:22 docker-proxy

说明：

Docker 已接管 22。

管理 SSH：

sudo ss -tnlp | grep ssh

保持：

0.0.0.0:51989 sshd

七、配置 Caddy 反代 Web

Caddy：

git.zenroly.com {

    reverse_proxy 127.0.0.1:3000

}

然后：

systemctl reload caddy

访问：

https://git.zenroly.com

八、SSH 测试

电脑：

ssh git@git.zenroly.com

第一次：

接受指纹。

成功：

Hi there, bill!
You've successfully authenticated with the key named xxx,
but Forgejo does not provide shell access.

说明：

SSH Key → Forgejo → 用户认证成功。

九、Git clone 测试

推荐：

git clone git@git.zenroly.com:bill/notes.git

成功：

正克隆到 'notes'...

提交：

echo hello > test.md

git add .

git commit -m "test"

git push

结果：

To git@git.zenroly.com:bill/notes.git
main -> main

十、最终配置总结

SSH

用途 端口 程序
Git仓库 22 Docker Forgejo
服务器管理 51989 sshd

Forgejo

项目 配置
Web Caddy → 3000
数据库 PostgreSQL 16
SSH 宿主机22映射
内置SSH 关闭
Clone格式 GitHub scp 风格

最终体验

和 GitHub 一样：

git clone git@git.zenroly.com:bill/notes.git

无需：

ssh://
-p 2222

整个架构已经比较接近 GitHub/GitLab 的部署方式。这个方案的优势是：Forgejo 不碰系统 sshd，Git 服务与服务器管理完全隔离。