部署指南
2025-07-07
概述
本指南介绍如何将 OpenEarable 2.0 文档网站部署到各种平台,包括 GitHub Pages、Netlify、Vercel 等。
构建生产版本
在部署之前,需要构建生产版本的文档:
# 进入项目目录
cd my_site
# 构建文档
teedoc build
# 构建完成后,静态文件位于 out/ 目录
GitHub Pages 部署
方法一:GitHub Actions 自动部署
创建 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
配置 GitHub Pages
- 进入 GitHub 仓库设置
- 找到 "Pages" 选项
- 选择 "Deploy from a branch"
- 选择 "gh-pages" 分支
方法二:手动部署
构建文档
cd docs/my_site teedoc build
推送到 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 集成部署
连接 GitHub 仓库
- 登录 Netlify
- 选择 "New site from Git"
- 连接 GitHub 仓库
配置构建设置
- Build command:
cd docs && pip install -r requirements.txt && cd my_site && teedoc build
- Publish directory:
docs/my_site/out
- Base directory:
/
- Build command:
创建 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"
方法二:手动部署
构建文档
cd docs/my_site teedoc build
上传到 Netlify
- 将
out/
目录打包为 zip 文件 - 在 Netlify 控制台手动上传
- 将
Vercel 部署
创建 vercel.json
{ "version": 2, "builds": [ { "src": "docs/my_site/build.py", "use": "@vercel/python" } ], "routes": [ { "src": "/(.*)", "dest": "/docs/my_site/out/$1" } ] }
创建构建脚本
# 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
添加 CNAME 文件
# 在 out/ 目录创建 CNAME 文件 echo "docs.openearable.com" > docs/my_site/out/CNAME
配置 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 版本和依赖包版本
问题:样式丢失
解决:检查静态文件路径配置
问题:搜索不工作
解决:确保搜索索引文件已正确生成
调试技巧
本地测试
# 本地构建测试 teedoc build teedoc serve
检查日志
# 查看构建日志 teedoc build --verbose
验证配置
# 验证配置文件 python -m json.tool site_config.json
备份和恢复
备份策略
- 源码备份:定期推送到 Git 仓库
- 构建备份:保存构建产物
- 配置备份:备份重要配置文件
恢复流程
从 Git 恢复
git clone <repository> cd docs pip install -r requirements.txt cd my_site teedoc build
重新部署
# 根据选择的部署方式重新部署