Astro + Decap CMS 从 GitHub 迁移到 Gitea 完整指南

本文记录了将 Twilight 博客项目从 GitHub 迁移到自托管 Gitea 的完整过程，以及遇到的常见问题和解决方案。

背景

Twilight 是一个基于 Astro 框架的博客项目，使用 Decap CMS（原 Netlify CMS）作为后台管理系统。出于数据自主可控的考虑，决定将代码仓库从 GitHub 迁移到自托管的 Gitea 服务器。

迁移步骤

1. 配置 Decap CMS 后端

修改 .decap.yml 配置文件，将后端从 GitHub 改为 Gitea：

1
backend:
2
  name: gitea
3
  repo: gowls/blog
4
  app_id: your-client-id  # Gitea OAuth 应用的 Client ID
5
  api_root: https://git.gowls.site/api/v1
6
  base_url: https://git.gowls.site
7
  auth_endpoint: https://git.gowls.site/login/oauth/authorize
8
  branch: main

关键配置说明：

字段	说明
`app_id`	Gitea OAuth 应用提供的 Client ID
`api_root`	Gitea API 地址，格式为 `/api/v1`
`base_url`	Gitea 实例的根地址
`auth_endpoint`	OAuth 授权端点地址

2. 创建 Gitea Actions 工作流

将 GitHub Actions 工作流迁移到 Gitea，创建 .gitea/workflows/deploy.yml：

1
name: Deploy to Pages
2

3
on:
4
  push:
5
    branches: [main]
6
  workflow_dispatch:
7

8
permissions:
9
  contents: read
10
  pages: write
11
  id-token: write
12

13
jobs:
14
  build:
15
    runs-on: ubuntu-latest
16
    steps:
17
      - name: Checkout
18
        uses: actions/checkout@v4
19

20
      - name: Setup pnpm
21
        uses: pnpm/action-setup@v4
22

23
      - name: Setup Node
24
        uses: actions/setup-node@v4
25
        with:
26
          node-version: 20
27
          cache: pnpm
28

29
      - name: Install dependencies
30
        run: pnpm install
31

32
      - name: Build
33
        run: pnpm run build
34
        env:
35
          GITHUB_ACTIONS: false
36

37
      - name: Upload artifact
38
        uses: actions/upload-pages-artifact@v3
39
        with:
40
          path: dist
41

42
  deploy:
43
    needs: build
44
    runs-on: ubuntu-latest
45
    permissions:
46
      pages: write
47
      id-token: write
48
    steps:
49
      - name: Deploy to Pages
50
        uses: actions/deploy-pages@v4

3. 禁用 GitHub OAuth 代理

由于 Gitea 支持 PKCE 认证，不需要额外的 OAuth 代理。在 astro.config.mjs 中禁用：

1
decapCmsOauth({
2
  configPath: "./.decap.yml",
3
  decapCMSVersion: "3.9.0",
4
  enable: false,  // Gitea 使用 PKCE，不需要 OAuth 代理
5
}),

4. 创建 Gitea OAuth 应用

在 Gitea 中创建 OAuth 应用：

登录 Gitea → 设置 → 应用
点击 创建 OAuth2 应用
填写以下信息：
- 应用名称：Twilight Blog
- 重定向 URI：
  - 本地开发：http://localhost:4321/admin/
  - 线上部署：https://blog.gowls.cn/admin/
重要：取消勾选 “Confidential Client”（机密客户端）

⚠️ 注意：Decap CMS 使用 PKCE 认证，必须取消 Confidential Client 选项，否则会报 “invalid empty client secret” 错误。

5. 配置 CORS

由于 Decap CMS 从博客域名向 Gitea API 发送请求，需要配置 CORS。

编辑 Gitea 的 custom/conf/app.ini：

1
[cors]
2
ENABLED = true
3
ALLOW_DOMAIN = blog.gowls.cn,localhost:4321
4
ALLOW_SUBDOMAIN = true
5
METHODS = GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS
6
ALLOW_CREDENTIALS = false
7
MAX_AGE = 30m

修改后重启 Gitea 服务。

6. 删除 GitHub 相关配置

删除 .github 目录及所有 GitHub 相关配置：

1
rm -rf .github

常见问题与解决方案

问题 1：Client ID not registered

原因：.decap.yml 中 app_id 未填写正确的 Client ID。

解决：确保 app_id 与 Gitea OAuth 应用提供的 Client ID 一致。

问题 2：Unregistered Redirect URI

原因：Gitea OAuth 应用中未配置正确的重定向 URI。

解决：在 Gitea OAuth 应用中添加：

本地开发：http://localhost:4321/admin/
线上部署：https://blog.gowls.cn/admin/

注意末尾的 / 是必需的。

问题 3：Failed to fetch

原因：CORS 跨域问题，浏览器阻止了跨域请求。

解决：在 Gitea 服务器配置 CORS（见上文第 5 步）。

问题 4：invalid empty client secret

原因：Gitea OAuth 应用勾选了 “Confidential Client”，但 PKCE 认证不需要 client secret。

解决：取消勾选 “Confidential Client” 选项。

问题 5：sha not found [main/content/posts]

原因：远程仓库中 src/content/posts 目录不存在或为空。

解决：创建一篇示例文章并推送到仓库：

1
mkdir -p src/content/posts
2
# 创建示例文章
3
git add src/content/posts
4
git commit -m "添加示例文章"
5
git push

总结

迁移完成后，配置清单如下：

配置项	文件/位置
后端配置	`.decap.yml`
CI/CD	`.gitea/workflows/deploy.yml`
OAuth 应用	Gitea 设置 → 应用
CORS	`custom/conf/app.ini`
博客地址	`twilight.config.yaml`

通过这次迁移，博客项目完全实现了自主可控，代码托管、后台管理、CI/CD 都可以在自己的服务器上运行，不再依赖第三方平台。

参考资料：