AutoRAG项目中使用CNAME文件配置GitHub Pages自定义域名指南

背景介绍

在开源项目AutoRAG的文档部署过程中，开发团队发现当使用GitHub Pages托管文档时，自定义域名设置会在每次部署后被重置。这是由于GitHub Pages的部署机制会覆盖原有的域名配置，导致文档URL回退到默认的github.io域名。本文将详细介绍如何通过添加CNAME文件来解决这一问题。

技术原理

CNAME文件的作用

CNAME（Canonical Name）文件是GitHub Pages识别自定义域名的关键配置文件。该文件需要满足以下要求：

1. 必须放置在网站根目录
2. 只能包含一行内容，即完整的自定义域名（如www.example.com）
3. 文件名为全大写的"CNAME"（无扩展名）

GitHub Pages的工作机制

当使用GitHub Actions自动部署时，GitHub Pages会：

1. 清空目标分支（通常是gh-pages）的所有内容
2. 将构建产物完全替换原有内容
3. 如果没有检测到CNAME文件，会自动使用github.io域名

解决方案实施

1. 创建CNAME文件

在项目文档源目录（docs/source/）下创建CNAME文件，内容为自定义域名：

www.yourdomain.com

2. 修改构建流程

在Sphinx文档构建过程中，需要确保CNAME文件被正确复制到输出目录。这可以通过两种方式实现：

方案一：手动复制 在GitHub Actions工作流中添加显式复制命令：

- name: Copy CNAME
  run: |
    cp docs/source/CNAME docs/build/html/CNAME

方案二：Sphinx配置 在conf.py中添加静态文件配置：

html_static_path = ['_static']
html_extra_path = ['CNAME']

3. 完整的工作流示例

以下是整合后的GitHub Actions工作流配置：

name: Documentation Deployment

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install -r docs/requirements.txt
      - run: sphinx-build -b html docs/source docs/build/html
      - run: cp docs/source/CNAME docs/build/html/CNAME
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: docs/build/html

注意事项

1. DNS配置需同步：确保域名服务商处已正确配置CNAME记录指向GitHub Pages
2. HTTPS强制启用：GitHub Pages会自动为自定义域名配置SSL证书，建议开启强制HTTPS
3. 缓存问题：域名更改后可能需要等待DNS缓存刷新（通常24小时内）

进阶技巧

对于需要支持多域名的场景，可以考虑：

1. 使用DNS的CNAME记录实现多域名指向
2. 通过GitHub Pages的Enforce HTTPS选项确保所有访问都通过安全连接
3. 在构建脚本中添加域名验证逻辑，防止配置错误

通过以上配置，AutoRAG项目的文档系统可以稳定地使用自定义域名，同时保持自动化部署的便利性。这种方案也适用于其他基于GitHub Pages的技术文档托管场景。