用 Gitea Pages 搭建静态站点托管服务：从选型到实战

前言

团队内部有大量静态 HTML 站点需要托管——原型设计、项目文档、自动化报表等。虽然市面上有 GitHub Pages、GitLab Pages 等成熟方案，但对于自托管 Gitea 的团队来说，直接在 Gitea 生态内解决显然更合理。

本文将分享我对比两个 Gitea Pages 开源项目后的选型思考，以及使用 deadnews/gitea-pages 的完整搭建过程。

项目选型

目前市面上有两个主流的 Gitea Pages 实现：

1. deadnews/gitea-pages

• 仓库: github.com/deadnews/gitea-pages
• 定位: 轻量级独立静态页面服务器
• 语言: Go（单二进制，镜像仅 10MB）
• 许可: MIT
• 配置: 4 个环境变量即可运行

2. d7z-project/gitea-pages

• 仓库: github.com/d7z-project/gitea-pages
• 定位: 全功能 Pages 服务器（Caddy 模块的继任者）
• 特色: 支持 JS 路由处理器（Goja）、反向代理、OAuth 鉴权、WebSocket/SSE

选型结论

对比项	deadnews/gitea-pages	d7z-project/gitea-pages
配置复杂度	⭐ 极简（4 个环境变量）	⭐⭐⭐ 中等（YAML 配置）
缓存机制	无缓存，实时读取	有缓存，需重启刷新
核心功能	静态文件托管	静态托管 + JS 路由 + 反向代理 + OAuth
适用场景	简单静态站	需要高级路由/鉴权的复杂场景

我的建议：如果你的需求就是"发布静态 HTML + 自动化更新"，deadnews/gitea-pages 是最佳选择——配置极简、实时更新、镜像小巧。等需要更复杂的功能时再迁移到 d7z 项目也不迟。

核心概念

deadnews/gitea-pages 的工作原理非常简单：

1. 它是一个 Go 语言写的 HTTP 服务
2. 每次收到请求，实时通过 Gitea API 读取仓库指定分支的文件
3. 返回给客户端，就像普通的 Web 服务器一样

URL 映射规则：

http://your-server:8000/{owner}/{repo}/{path}

快速开始

前提条件

• Docker 环境
• 一个可访问的 Gitea 实例（如自托管的 git.company.com）
• Gitea API Token（需要 read:repository 权限）

第一步：创建 Gitea API Token

登录 Gitea → 右上角头像 → 设置 → 应用 → 管理访问令牌：

• 名称：gitea-pages
• 权限：勾选 读取仓库
• 点击生成，复制 Token 值

第二步：启动服务

创建 docker-compose.yml：

services:
  gitea-pages:
    image: ghcr.io/deadnews/gitea-pages:latest
    container_name: gitea-pages
    ports:
      - "8000:8000"
    environment:
      - GITEA_PAGES_SERVER=https://git.company.com
      - GITEA_PAGES_TOKEN=你的Token
      - GITEA_PAGES_BRANCH=gh-pages
      - GITEA_PAGES_ADDR=:8000
    restart: unless-stopped

配置项说明：

变量	默认值	说明
GITEA_PAGES_SERVER	（必填）	Gitea 服务器地址
GITEA_PAGES_TOKEN	（必填）	Gitea API Token
GITEA_PAGES_BRANCH	gh-pages	提供 pages 服务所用分支
GITEA_PAGES_ADDR	:8000	监听地址

启动服务：

docker compose up -d

验证是否运行成功：

# 健康检查
curl http://localhost:8000/health

# 访问你的站点
curl http://localhost:8000/myteam/myproject/

第三步：准备静态文件

在你的 Gitea 仓库中创建一个 gh-pages 分支，放入静态 HTML 文件：

myproject/
├── index.html
├── style.css
├── about.html
├── data/
│   └── report.json
└── images/
    └── logo.png

第四步：推送并验证

git checkout -b gh-pages
git add .
git commit -m "初始化静态站点"
git push origin gh-pages

打开浏览器访问 http://localhost:8000/myteam/myproject/，如果看到你的页面，说明搭建成功！

实现自动化更新

由于 deadnews/gitea-pages 没有缓存，每次请求都实时从 Gitea 拉取文件，所以更新非常简单：

只需往 pages 分支推送新文件，立即可见，无需重启服务。

手动更新

git add .
git commit -m "更新报表数据"
git push origin gh-pages

CI/CD 自动更新

结合 Gitea Actions 或其他 CI 工具：

# .gitea/workflows/deploy-pages.yml
name: Deploy Pages
on:
  push:
    branches: [main]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: |
          npm install
          npm run build
      - run: |
          git checkout -b gh-pages
          cp -r dist/* .
          git add .
          git commit -m "自动部署 $(date)"
          git push origin gh-pages --force

实用技巧

1. 健康检查

curl http://localhost:8000/health

2. 自定义端口

environment:
  - GITEA_PAGES_ADDR=:8080

3. 多分支多实例

services:
  gitea-pages-stable:
    image: ghcr.io/deadnews/gitea-pages:latest
    ports: ["8001:8000"]
    environment:
      - GITEA_PAGES_BRANCH=stable

  gitea-pages-develop:
    image: ghcr.io/deadnews/gitea-pages:latest
    ports: ["8002:8000"]
    environment:
      - GITEA_PAGES_BRANCH=develop

4. Nginx 反向代理

server {
    listen 80;
    server_name pages.company.com;
    location / {
        proxy_pass http://127.0.0.1:8000;
    }
}

安全性说明

deadnews/gitea-pages 本身没有访问控制——Token 能读到的仓库，任何人都能通过 gitea-pages 访问。

部署位置	安全风险
localhost	✅ 安全
内网服务器	⚠️ 内网用户可访问
公网	❌ 不推荐

建议：Token 权限最小化，服务不要直接暴露在公网。

日志排查

docker compose logs -f

常见日志：

INFO  "Starting server" address=:8000
WARN  request url=/team/project/file.html status=404

总结

deadnews/gitea-pages 的核心优势：

1. ✅ 极简部署 — 4 个环境变量，一行 docker compose up
2. ✅ 实时更新 — 无缓存，推送即生效
3. ✅ 镜像小巧 — 仅 10MB
4. ✅ 双架构 — 支持 amd64 和 arm64

---

本文中使用的镜像版本：ghcr.io/deadnews/gitea-pages:latest