部署指南

概述

本指南介绍如何将 OpenEarable 2.0 文档网站部署到各种平台,包括 GitHub Pages、Netlify、Vercel 等。

构建生产版本

在部署之前,需要构建生产版本的文档:

# 进入项目目录
cd my_site

# 构建文档
teedoc build

# 构建完成后,静态文件位于 out/ 目录

GitHub Pages 部署

方法一:GitHub Actions 自动部署

  1. 创建 GitHub Actions 工作流

    在项目根目录创建 .github/workflows/deploy.yml

    name: Deploy to GitHub Pages
    
    on:
      push:
        branches: [ main ]
      pull_request:
        branches: [ main ]
    
    jobs:
      build-and-deploy:
        runs-on: ubuntu-latest
        steps:
        - uses: actions/checkout@v3
    
        - name: Setup Python
          uses: actions/setup-python@v4
          with:
            python-version: '3.9'
    
        - name: Install dependencies
          run: |
            cd docs
            pip install -r requirements.txt
    
        - name: Build documentation
          run: |
            cd docs/my_site
            teedoc build
    
        - name: Deploy to GitHub Pages
          uses: peaceiris/actions-gh-pages@v3
          with:
            github_token: ${{ secrets.GITHUB_TOKEN }}
            publish_dir: ./docs/my_site/out
    
  2. 配置 GitHub Pages

    • 进入 GitHub 仓库设置
    • 找到 "Pages" 选项
    • 选择 "Deploy from a branch"
    • 选择 "gh-pages" 分支

方法二:手动部署

  1. 构建文档

    cd docs/my_site
    teedoc build
    
  2. 推送到 gh-pages 分支

    # 创建并切换到 gh-pages 分支
    git checkout --orphan gh-pages
    
    # 复制构建文件
    cp -r docs/my_site/out/* .
    
    # 提交并推送
    git add .
    git commit -m "Deploy documentation"
    git push origin gh-pages
    

Netlify 部署

方法一:Git 集成部署

  1. 连接 GitHub 仓库

    • 登录 Netlify
    • 选择 "New site from Git"
    • 连接 GitHub 仓库
  2. 配置构建设置

    • Build command: cd docs && pip install -r requirements.txt && cd my_site && teedoc build
    • Publish directory: docs/my_site/out
    • Base directory: /
  3. 创建 netlify.toml

    [build]
      command = "cd docs && pip install -r requirements.txt && cd my_site && teedoc build"
      publish = "docs/my_site/out"
    
    [build.environment]
      PYTHON_VERSION = "3.9"
    

方法二:手动部署

  1. 构建文档

    cd docs/my_site
    teedoc build
    
  2. 上传到 Netlify

    • out/ 目录打包为 zip 文件
    • 在 Netlify 控制台手动上传

Vercel 部署

  1. 创建 vercel.json

    {
      "version": 2,
      "builds": [
        {
          "src": "docs/my_site/build.py",
          "use": "@vercel/python"
        }
      ],
      "routes": [
        {
          "src": "/(.*)",
          "dest": "/docs/my_site/out/$1"
        }
      ]
    }
    
  2. 创建构建脚本

    # docs/my_site/build.py
    import subprocess
    import os
    
    os.chdir('docs')
    subprocess.run(['pip', 'install', '-r', 'requirements.txt'])
    os.chdir('my_site')
    subprocess.run(['teedoc', 'build'])
    

自定义域名

配置 CNAME

  1. 添加 CNAME 文件

    # 在 out/ 目录创建 CNAME 文件
    echo "docs.openearable.com" > docs/my_site/out/CNAME
    
  2. 配置 DNS

    • 在域名服务商添加 CNAME 记录
    • 指向 GitHub Pages 或部署平台的域名

更新配置

修改 site_config.json

{
  "site_domain": "docs.openearable.com",
  "site_protocol": "https",
  "site_root_url": "/"
}

性能优化

启用压缩

大多数托管平台都支持 Gzip 压缩,确保已启用:

// netlify.toml
[[headers]]
  for = "/*"
  [headers.values]
    Content-Encoding = "gzip"

CDN 加速

使用 CDN 加速静态资源:

// site_config.json
{
  "plugins": {
    "teedoc-plugin-assets": {
      "config": {
        "header_items": [
          "<link rel=\"preload\" href=\"/static/css/main.css\" as=\"style\">",
          "<link rel=\"dns-prefetch\" href=\"//fonts.googleapis.com\">"
        ]
      }
    }
  }
}

监控和维护

构建状态监控

  • 设置 GitHub Actions 通知
  • 监控部署状态
  • 配置错误报告

定期更新

# 更新依赖
pip install --upgrade teedoc

# 重新构建
teedoc build

故障排除

常见问题

问题:构建失败
解决:检查 Python 版本和依赖包版本

问题:样式丢失
解决:检查静态文件路径配置

问题:搜索不工作
解决:确保搜索索引文件已正确生成

调试技巧

  1. 本地测试

    # 本地构建测试
    teedoc build
    teedoc serve
    
  2. 检查日志

    # 查看构建日志
    teedoc build --verbose
    
  3. 验证配置

    # 验证配置文件
    python -m json.tool site_config.json
    

备份和恢复

备份策略

  1. 源码备份:定期推送到 Git 仓库
  2. 构建备份:保存构建产物
  3. 配置备份:备份重要配置文件

恢复流程

  1. 从 Git 恢复

    git clone <repository>
    cd docs
    pip install -r requirements.txt
    cd my_site
    teedoc build
    
  2. 重新部署

    # 根据选择的部署方式重新部署
    

参考资源