Cloudflare 部署指南

本指南将帮助您将 MITM Service 文档部署到 Cloudflare Pages。

准备工作

1. Cloudflare 账号

注册 Cloudflare 账号
创建或准备一个 Cloudflare Pages 项目

2. GitHub 仓库

确保您的项目已推送到 GitHub：

git add .
git commit -m "Add documentation"
git push origin main

方法一：通过 Cloudflare Pages 部署

1. 连接 GitHub

登录 Cloudflare Dashboard
进入 Pages 页面
点击 Create a project
选择 Connect to Git
授权 Cloudflare 访问您的 GitHub 仓库
选择 mitm-service 仓库

2. 配置构建设置

在构建配置页面填写：

Build settings:

Project name: mitm-service-docs
Production branch: main
Framework preset: None
Root directory (optional): document
Build command: npm install && npm install -g honkit && honkit build
Build output directory: _book

Environment variables:

NODE_VERSION=20

重要: Honkit 6.x 需要 Node.js 20+。

重要说明：

✅ Root directory 设置为 document 后，构建会在 document 目录下执行
✅ Build command 不需要包含 cd document
✅ Build output 只需要 _book（相对于 Root directory）
✅ 使用 Honkit 替代 GitBook，支持 Node.js 18+
❌ 不要使用 cd document && 开头的命令，会导致找不到目录

3. 保存并部署

点击 Save and Deploy，Cloudflare 将自动构建和部署您的文档。

4. 访问文档

部署完成后，您可以通过以下地址访问：

https://mitm-service-docs.pages.dev
或配置自定义域名

方法二：使用 GitBook + Cloudflare

1. GitBook 集成

注册 GitBook

访问 GitBook
注册并创建账号

导入 GitHub 仓库

在 GitBook 中创建新 Space
选择 Import from GitHub
授权并选择 mitm-service 仓库
设置文档根目录为 document

配置 GitBook

GitBook 会自动识别 SUMMARY.md 和 README.md。

2. 同步到 Cloudflare

方式 A: GitBook 直接发布

GitBook 会提供一个公开 URL，可以直接使用。

方式 B: 导出静态站点到 Cloudflare

在本地构建 GitBook：

cd document
npm install gitbook-cli -g
gitbook install
gitbook build

将 _book 目录推送到 GitHub
在 Cloudflare Pages 中部署静态文件

本地构建配置

创建构建脚本

在项目根目录创建 package.json（如果还没有）：

{
  "name": "mitm-service",
  "version": "1.0.0",
  "scripts": {
    "docs:install": "cd document && npm install",
    "docs:dev": "cd document && gitbook serve",
    "docs:build": "cd document && gitbook build",
    "build:docs": "npm run docs:install && npm run docs:build"
  }
}

在 document 目录创建 package.json:

{
  "name": "mitm-service-docs",
  "version": "1.0.0",
  "description": "MITM Service Documentation",
  "scripts": {
    "serve": "gitbook serve",
    "build": "gitbook build",
    "install": "gitbook install"
  },
  "dependencies": {
    "gitbook-cli": "^2.3.2"
  }
}

本地预览

# 安装 GitBook
cd document
npm install

# 本地预览
npm run serve

# 访问 http://localhost:4000

构建静态文件

cd document
npm run build

构建完成后，静态文件在 document/_book 目录。

Cloudflare Workers 集成（高级）

如果需要在 Cloudflare Workers 中添加自定义逻辑：

1. 创建 Worker

在项目根目录创建 workers/docs.js:

export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);

    // 重定向根路径到文档
    if (url.pathname === '/') {
      return Response.redirect('https://your-docs.pages.dev', 302);
    }

    // 添加安全头
    const response = await fetch(request);
    const newResponse = new Response(response.body, response);

    newResponse.headers.set('X-Content-Type-Options', 'nosniff');
    newResponse.headers.set('X-Frame-Options', 'DENY');
    newResponse.headers.set('X-XSS-Protection', '1; mode=block');

    return newResponse;
  }
};

2. 配置 wrangler.toml

name = "mitm-service-docs"
main = "workers/docs.js"
compatibility_date = "2024-01-01"

[site]
bucket = "./document/_book"

3. 部署 Worker

npm install -g wrangler
wrangler login
wrangler deploy

自定义域名

1. 添加自定义域名

在 Cloudflare Pages 项目设置中：

进入 Custom domains
点击 Set up a custom domain
输入域名（如 docs.yourdomain.com）
按提示配置 DNS

2. 配置 DNS

在 Cloudflare DNS 设置中添加 CNAME 记录：

Type: CNAME
Name: docs
Content: mitm-service-docs.pages.dev
Proxy status: Proxied (橙色云朵)

3. SSL/TLS 配置

在 Cloudflare SSL/TLS 设置中：

选择 Full 或 Full (strict) 模式
启用 Always Use HTTPS
启用 Automatic HTTPS Rewrites

持续部署

自动部署

Cloudflare Pages 会自动监听 GitHub 仓库的变更：

推送到 main 分支 → 部署到生产环境
推送到其他分支 → 部署到预览环境

手动部署

也可以通过 Wrangler CLI 手动部署：

wrangler pages publish document/_book --project-name=mitm-service-docs

性能优化

1. 启用缓存

Cloudflare 自动缓存静态资源。可以自定义缓存规则：

在 Cloudflare Dashboard 的 Caching 中：

设置合适的缓存 TTL
配置缓存规则

2. 启用 HTTP/3

在 Cloudflare 的 Network 设置中启用：

HTTP/3 (with QUIC)
0-RTT Connection Resumption

3. 压缩优化

在 Speed 设置中配置：

Auto Minify (HTML, CSS, JS)
Brotli compression

监控和分析

1. Web Analytics

在 Cloudflare Pages 项目中启用 Web Analytics：

访问统计
页面性能
用户行为

2. 日志查看

使用 Cloudflare Logs：

wrangler pages deployment tail

常见问题

构建失败

检查构建日志: 在 Cloudflare Pages 项目的 Deployments 页面查看详细日志。

常见原因:

Node.js 版本不兼容 → 设置 NODE_VERSION 环境变量
依赖安装失败 → 检查 package.json
构建命令错误 → 验证本地构建

404 错误

Single Page Application (SPA) 路由: 在 document 目录创建 _redirects 文件：

/*    /index.html   200

更新未生效

清除缓存: 在 Cloudflare Dashboard 的 Caching 中点击 Purge Everything。

安全配置

1. 访问控制

在 Cloudflare Pages 设置中配置：

Access Policies - 限制访问
Password Protection - 为预览部署设置密码

2. 安全头

通过 _headers 文件配置：

在 document 目录创建 _headers:

/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  X-XSS-Protection: 1; mode=block
  Referrer-Policy: strict-origin-when-cross-origin
  Permissions-Policy: camera=(), microphone=(), geolocation=()

下一步

查看 GitBook 官方文档
查看 Cloudflare Pages 文档
配置自定义主题和样式