Gitea 本身是一个轻量级的 Git 服务，但官方暂未提供类似 GitHub Pages 的原生静态站点托管功能。如果你需要在 Gitea 环境中实现自动化部署并托管静态文档或前端构建产物，可以引入开源项目kekxv/gitea-pages 作为解决方案。

本文将介绍该项目的工作机制，并重点解析服务端的 Docker 部署方式，以及如何通过 Gitea Actions 编写 CI/CD 工作流，实现代码提交后的全自动构建与部署。

1. 架构简述：kekxv/gitea-pages 如何工作？

kekxv/gitea-pages 的定位是一个适配 Gitea 的无状态（Actionless）静态站点托管服务。其底层运行逻辑如下：

1. Webhook 驱动：通过在 Gitea 中配置全局或仓库级的 Webhook，监听 push 事件。
2. 分支同步：当检测到代码被推送到约定的分支（如 gh-pages）时，服务会通过浅克隆（Shallow Clone）将该分支的内容拉取到服务器本地。
3. Nginx 路由分发：结合泛域名解析（如 *.pages.example.com），内置的 Nginx 容器会将请求路由到对应仓库的克隆目录中，实现类似 username.pages.example.com/repo 的访问效果。
4. 权限校验：针对私有仓库，它支持通过 Gitea 的 OAuth2 机制或 Access Token 进行访问鉴权。

2. 服务端部署：Docker Compose 配置

kekxv/gitea-pages 的服务端架构解耦为两个核心容器：负责处理 Webhook 和拉取代码的 deployer，以及负责解析泛域名和托管静态文件的 pages-nginx。

你可以通过以下 docker-compose.yaml 文件快速拉起服务：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

services:
  deployer:
    image: ghcr.io/kekxv/gitea-pages/deployer:latest
    restart: unless-stopped
    environment:
      
      - DOMAIN=${DOMAIN:-}
      
      - WEBHOOK_SECRET=${WEBHOOK_SECRET:-}

      
      - GITEA_API_URL=${GITEA_API_URL:-}

      
      
      - OAUTH_CLIENT_ID=${OAUTH_CLIENT_ID:-}
      - OAUTH_CLIENT_SECRET=${OAUTH_CLIENT_SECRET:-}
      - OAUTH_REDIRECT_URL=${OAUTH_REDIRECT_URL:-}

      
      
    volumes:
      
      - ./pages/webroot:/var/www/pages
      
      - ./pages/deployer:/var/lib/deployer:rw
    ports:
      - "8080:8080" 

  pages-nginx:
    image: ghcr.io/kekxv/gitea-pages/nginx:latest
    restart: unless-stopped
    volumes:
      
      - ./pages/webroot:/var/www/pages:ro
    ports:
      - "8888:80" 

核心配置解析：

• **数据卷共享 (Volumes)**：deployer 将拉取的静态文件写入 ./pages/webroot，而 pages-nginx 以只读 (ro) 模式挂载该目录，实现了构建产物写入与对外发布的安全隔离。
• **端口映射 (Ports)**：
  • 8080 端口用于接收 Gitea 侧发出的 Webhook 请求，需确保 Gitea 实例能够访问该端口。
  • 8888 端口为 Nginx 服务的暴露端口，生产环境中通常需要在外层再配置一层反向代理（如 Nginx 或 Traefik），将泛域名 *.pages.example.com 指向此端口。
• 私有仓库鉴权：环境变量中提供了 OAuth2 和 GITEA_ACCESS_TOKEN 两种方式，供拉取私有仓库内容时进行身份认证。

3. CI/CD 配置：使用 Gitea Actions 自动部署

在服务端配置完成并成功运行后，开发者端的任务是将构建产物自动化地推送到 gh-pages 分支。由于 Gitea Actions 兼容 GitHub Actions 的语法和生态，我们可以直接利用现有的 Actions 插件。

以下是在 Gitea 仓库中实现自动打包并推送到 gh-pages 分支的标准 workflow 配置文件（保存路径：.gitea/workflows/deploy.yml）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

name: Deploy to gh-pages

on:
  push:
    branches:
      - main  
  workflow_dispatch: 

jobs:
  build:
    runs-on: ubuntu-latest
    
    
    permissions:
      contents: write 

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Deploy to gh-pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist          
          publish_branch: gh-pages     
          force_orphan: true           
          
          
          user_name: 'github-actions[bot]'
          user_email: 'github-actions[bot]@users.noreply.github.com'

4. Workflow 核心配置解析

上述 YAML 文件中有几个针对 Gitea Actions 环境的必要配置，需要特别注意：

• permissions: contents: write (写入权限声明)
  在默认的安全策略下，Runner 分配的 GITHUB_TOKEN 可能是只读权限。部署步骤需要向仓库的 gh-pages 分支执行 git push 操作，因此必须显式声明 contents: write 提升 Token 权限，否则会在部署阶段触发 HTTP 403 权限拒绝异常。
• github_token: ${{ secrets.GITHUB_TOKEN }} (免密认证)
  Gitea 在执行 Action 时，会在当前上下文中自动注入临时 Token。直接使用该内置 Token 即可完成仓库级的读写认证，无需手动生成并维护 Personal Access Token (PAT)，降低了密钥泄漏的风险。
• force_orphan: true (重置提交历史)
  开启该参数后，每次部署都会在 gh-pages 分支创建一个无父节点的新提交（Orphan Commit），丢弃历史记录。静态资源分支通常只需要保留最新版本的产物，此举可避免 Git 仓库因累积大量构建产物历史（如无用的 Source Map）而导致存储体积急剧膨胀。

5. 执行链路总结

完成全部配置后，整体的工程发布链路如下：

1. 开发者将源码 push 到项目的 main 分支。
2. 触发 Gitea Actions，Runner 执行环境初始化、拉取源码、安装依赖并执行 npm run build 生成 dist 目录。
3. actions-gh-pages 插件将 dist 目录作为根节点，强推至当前仓库的 gh-pages 分支。
4. 推送行为触发 Gitea Webhook，通过预设密钥将事件推送至 deployer 的 8080 端口。
5. deployer 验证 Webhook 请求合法后，通过浅克隆拉取 gh-pages 分支内容，写入共享数据卷。
6. pages-nginx 实时读取挂载目录的最新静态文件，外部通过泛域名即可访问最新发布的站点。