使用 Caddy 容器和 Cgit 展示 Git 仓库

Nite

2025-07-20

前置教程

使用 Caddy 和容器轻松搭建你的私有 Git 服务器 (Git Over HTTPS)

简介

经过之前的教程，我们已经有了一个可以访问的 Git 服务器，现在我们想要通过 Web 页面展示这个 Git 服务器中的仓库列表。

实操步骤

1. 更新容器镜像

首先，我们需要在自定义的 Caddy 镜像中添加 cgit 和相关依赖。

重新编辑 custom-containerfile/Containerfile：

FROM docker.io/library/caddy:2-builder AS builder

RUN xcaddy build \
    --with github.com/aksdb/caddy-cgi/v2

FROM docker.io/library/caddy:latest

RUN apk update && apk add --no-cache git git-daemon cgit python3 py3-pygments py3-markdown py3-docutils groff

COPY --from=builder /usr/bin/caddy /usr/bin/caddy

2. 配置 Caddyfile

接下来，修改 Caddyfile 以处理 Git 的 HTTP 协议，并配置 cgit 的 CGI 服务。

git.your-domain.com {
 @git {
  header User-Agent git/*
 }

 route {
  # 启用基础认证保护整个服务
  basic_auth {
   # 使用 `caddy hash-password` 命令生成你的密码哈希
   # 将 "your_username" 替换为你的用户名
   # 将 "$2a$14$..." 替换为生成的哈希密码
   your_username $2a$14$ABC...
  }

  handle /cgit.* {
   root * /usr/share/webapps/cgit
   file_server
  }

  handle /favicon.ico {
   root * /usr/share/webapps/cgit
   file_server
  }

  handle @git {
   cgi * /usr/libexec/git-core/git-http-backend {
    env GIT_PROJECT_ROOT=/git-repos GIT_HTTP_EXPORT_ALL=1
   }
  }

  handle {
   cgi * /usr/share/webapps/cgit/cgit.cgi {
    env CGIT_CONFIG=/cgitrc
   }
  }
 }
}

3. 配置 cgit

创建一个 cgitrc 文件来配置 cgit 的外观和行为。这个文件定义了仓库的根目录、页面标题、Logo、CSS 样式等。

# https://man.archlinux.org/man/cgitrc.5

root-title=Your Git Repositories

root-desc=A collection of personal and experimental projects

css=/cgit.css

logo=/cgit.png

favicon=/favicon.ico

enable-index-owner=1

enable-http-clone=1

enable-index-links=1

enable-blame=1

enable-commit-graph=1

enable-log-filecount=1

enable-log-linecount=1

branch-sort=age

max-stats=quarter

snapshots=tar.gz zip

readme=:README.md

source-filter=/usr/lib/cgit/filters/syntax-highlighting.py
about-filter=/usr/lib/cgit/filters/about-formatting.sh

# scan-path 必须在文件的最后，不然前面设置的参数都会无效
scan-path=/git-repos

4. 检查目录结构

完成以上配置后，你的项目目录结构应该如下所示：

/my-caddy-git-server
├── Caddyfile
├── compose.yml
├── cgitrc
├── custom-containerfile/
│   └── Containerfile
├── git-repos/
│   └── (Git 仓库将存放在这里)
└── caddy_data/
    └── (Caddy 的证书和状态将存放在这里)

5. 更新 Compose 文件

为了让 cgit 能够读取到配置，我们需要修改 compose.yml 文件，将 cgitrc 文件挂载到容器中。

name: git-server
services:
  git-server:
    # 指定使用我们自定义的 Containerfile 进行构建
    build: ./custom-containerfile
    restart: unless-stopped
    ports:
      # 映射 HTTPS 和 HTTP 端口
      - "443:443"
      - "80:80"
    volumes:
      # 挂载 Caddyfile
      - ./Caddyfile:/etc/caddy/Caddyfile
      # 挂载存放 Git 仓库的目录
      - ./git-repos:/git-repos
      # 挂载 Caddy 数据卷，用于持久化 TLS 证书
      - ./caddy_data:/data
      # 挂载 cgitrc
      - ./cgitrc:/cgitrc

6. 启动并访问

一切就绪后，启动服务：

podman-compose up -d

启动成功后，访问 https://git.your-domain.com 即可看到 cgit 生成的 git 仓库列表页面。