Cloudflare 企业知识库搭建｜附配置文件

在企业数字化协作中，知识库已经不再只是“文档存放处”，而是团队经验沉淀、流程标准化、客户支持、研发协作和内部培训的重要基础设施。一个优秀的企业知识库，应该具备访问速度快、权限可控、部署稳定、维护成本低、支持版本管理、易于搜索和可持续扩展等特点。

传统企业知识库通常部署在自建服务器、内部 NAS、Confluence、语雀、飞书文档或 Notion 等平台上。它们各有优势，但也常见一些问题：访问速度受地域影响明显、权限体系复杂、外部协作成本高、私有化部署维护压力大、数据备份和安全策略不统一等。

Cloudflare 提供了一整套边缘网络与零信任安全能力，非常适合搭建企业级知识库。通过 Cloudflare Pages、Workers、Zero Trust Access、R2、D1、Turnstile、WAF 等产品，可以构建一个高可用、全球加速、安全可控、低成本的企业知识库系统。

本文将以实战视角介绍如何基于 Cloudflare 搭建企业知识库，并附上常用配置文件示例。

一、为什么选择 Cloudflare 搭建企业知识库？

Cloudflare 的优势并不只是 CDN。对于企业知识库而言，它更像是一套轻量级云原生基础设施。

1. 全球边缘加速

Cloudflare 拥有覆盖全球的边缘节点。知识库部署到 Cloudflare Pages 后，静态资源可以直接在边缘节点缓存和分发。无论员工在国内、海外办公室，还是远程办公，都能获得较快的访问速度。

对于 Markdown 文档、图片、CSS、JavaScript、字体文件等静态资源，Cloudflare Pages 的分发效率非常高。

2. 部署简单，维护成本低

相比自建 Nginx、服务器、数据库、证书和备份系统，Cloudflare Pages 的部署流程更加轻量。通常只需要将知识库项目托管到 GitHub 或 GitLab，再连接 Cloudflare Pages，即可实现自动构建和自动发布。

每次提交代码，Cloudflare 会自动触发构建，生成新的知识库站点。

3. 支持企业级权限控制

企业知识库通常不能完全公开，尤其是包含内部流程、技术文档、客户资料、运维手册、财务制度等内容时，必须做好访问控制。

Cloudflare Zero Trust Access 可以实现：

• 邮箱域名登录限制；
• Google Workspace、Microsoft Entra ID、Okta 等身份源集成；
• 指定用户、用户组访问；
• 一次性 PIN 邮箱验证；
• 多因素认证；
• 按路径设置权限；
• 登录审计记录。

这使得知识库既可以部署在公网，又不会裸露给未授权用户。

4. 易于结合 Git 做版本管理

企业知识库最怕“文档不可追踪”。如果文档直接写在在线编辑器里，虽然方便，但版本管理、变更审计、多人协作规范常常不够清晰。

使用 Markdown + Git 的方式，可以做到：

• 文档修改有提交记录；
• 支持代码评审流程；
• 可以回滚历史版本；
• 可以通过分支管理不同阶段内容；
• 适合研发、运维、安全、产品等团队协作。

5. 成本可控

对于中小团队甚至很多大型企业部门级知识库而言，Cloudflare Pages 免费额度已经足够使用。若配合 R2 存储附件、Workers 实现接口、D1 存储结构化数据，也可以按需扩展，成本通常低于传统服务器方案。

二、推荐架构方案

本文推荐的企业知识库架构如下：

用户浏览器
   │
   ▼
Cloudflare DNS
   │
   ▼
Cloudflare Zero Trust Access
   │
   ▼
Cloudflare Pages
   │
   ├── 静态知识库页面
   ├── Markdown 文档
   ├── 图片与前端资源
   │
   └── 可选：Workers API
          ├── R2：附件与大文件存储
          ├── D1：搜索索引或反馈数据
          └── Turnstile：防机器人验证

在这个架构中：

• Cloudflare DNS 负责域名解析；
• Cloudflare Access 负责访问认证；
• Cloudflare Pages 负责部署知识库前端；
• GitHub/GitLab 负责源码和文档管理；
• R2 用于存放图片、PDF、压缩包等附件；
• Workers 可用于扩展搜索、反馈、统计、鉴权逻辑；
• D1 可用于保存用户反馈、搜索记录或结构化数据。

三、技术选型建议

搭建企业知识库时，前端框架可以有多种选择。常见方案包括：

本文以 VitePress + Cloudflare Pages + Access 为例。VitePress 基于 Vue 和 Vite，构建速度快，页面体验好，特别适合技术团队搭建企业知识库。

四、目录结构设计

一个比较规范的企业知识库目录结构可以如下：

company-kb/
├── docs/
│   ├── .vitepress/
│   │   └── config.ts
│   ├── guide/
│   │   ├── index.md
│   │   ├── onboarding.md
│   │   └── workflow.md
│   ├── engineering/
│   │   ├── index.md
│   │   ├── frontend.md
│   │   ├── backend.md
│   │   └── devops.md
│   ├── security/
│   │   ├── index.md
│   │   ├── access-control.md
│   │   └── incident-response.md
│   ├── operation/
│   │   ├── index.md
│   │   └── customer-support.md
│   └── index.md
├── package.json
├── wrangler.toml
├── _headers
├── _redirects
└── README.md

建议按照企业部门或知识类型划分目录，例如：

• guide：新人指南、制度说明、通用流程；
• engineering：研发规范、接口文档、部署文档；
• security：安全制度、权限申请、应急响应；
• operation：运营流程、客户支持、SOP；
• product：产品说明、需求模板、Roadmap；
• sales：销售资料、报价流程、客户问答。

需要注意的是，企业知识库不是目录越多越好。目录结构应该保持清晰，避免一开始就设计得过于复杂。可以先从核心部门文档开始，再逐渐扩展。

五、初始化 VitePress 项目

首先创建项目：

mkdir company-kb
cd company-kb

npm init -y
npm install vitepress -D

修改 package.json：

{
  "name": "company-kb",
  "version": "1.0.0",
  "description": "Enterprise knowledge base powered by Cloudflare Pages and VitePress",
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  },
  "devDependencies": {
    "vitepress": "^1.5.0"
  }
}

创建首页文件：

mkdir -p docs/.vitepress
touch docs/index.md
touch docs/.vitepress/config.ts

docs/index.md 示例：

---
layout: home

hero:
  name: 企业知识库
  text: Company Knowledge Base
  tagline: 沉淀经验、统一标准、提升协作效率
  actions:
    - theme: brand
      text: 开始阅读
      link: /guide/
    - theme: alt
      text: 研发文档
      link: /engineering/

features:
  - title: 统一标准
    details: 汇总企业制度、流程、规范和模板，减少重复沟通。
  - title: 安全可控
    details: 结合 Cloudflare Access 实现企业级访问控制。
  - title: 版本管理
    details: 使用 Git 管理文档变更，支持审查、回滚和协作。
---

六、VitePress 配置文件

下面是一个适合企业知识库的 docs/.vitepress/config.ts 示例：

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: '企业知识库',
  description: 'Company Knowledge Base powered by Cloudflare',
  lang: 'zh-CN',
  cleanUrls: true,
  lastUpdated: true,

  head: [
    ['meta', { name: 'theme-color', content: '#2563eb' }],
    ['meta', { name: 'robots', content: 'noindex,nofollow' }],
    ['link', { rel: 'icon', href: '/favicon.ico' }]
  ],

  themeConfig: {
    logo: '/logo.svg',

    nav: [
      { text: '首页', link: '/' },
      { text: '新人指南', link: '/guide/' },
      { text: '研发文档', link: '/engineering/' },
      { text: '安全合规', link: '/security/' },
      { text: '运营支持', link: '/operation/' }
    ],

    sidebar: {
      '/guide/': [
        {
          text: '新人指南',
          items: [
            { text: '概览', link: '/guide/' },
            { text: '入职流程', link: '/guide/onboarding' },
            { text: '协作流程', link: '/guide/workflow' }
          ]
        }
      ],

      '/engineering/': [
        {
          text: '研发文档',
          items: [
            { text: '概览', link: '/engineering/' },
            { text: '前端规范', link: '/engineering/frontend' },
            { text: '后端规范', link: '/engineering/backend' },
            { text: 'DevOps 规范', link: '/engineering/devops' }
          ]
        }
      ],

      '/security/': [
        {
          text: '安全合规',
          items: [
            { text: '概览', link: '/security/' },
            { text: '访问控制', link: '/security/access-control' },
            { text: '应急响应', link: '/security/incident-response' }
          ]
        }
      ],

      '/operation/': [
        {
          text: '运营支持',
          items: [
            { text: '概览', link: '/operation/' },
            { text: '客户支持流程', link: '/operation/customer-support' }
          ]
        }
      ]
    },

    search: {
      provider: 'local'
    },

    socialLinks: [
      { icon: 'github', link: 'https://github.com/example/company-kb' }
    ],

    footer: {
      message: 'Internal use only. Powered by Cloudflare Pages.',
      copyright: 'Copyright © 2025 Company'
    }
  }
})

这里需要重点关注：

['meta', { name: 'robots', content: 'noindex,nofollow' }]

企业内部知识库不建议被搜索引擎收录，因此建议加上 noindex,nofollow。即使已经使用 Cloudflare Access 做了访问控制，也应该在页面层面禁止搜索引擎抓取。

七、Cloudflare Pages 部署配置

1. 连接代码仓库

将项目推送到 GitHub：

git init
git add .
git commit -m "init company knowledge base"
git branch -M main
git remote add origin git@github.com:example/company-kb.git
git push -u origin main

进入 Cloudflare Dashboard：

Workers & Pages → Create application → Pages → Connect to Git

选择对应仓库后，填写构建配置：

Project name: company-kb
Production branch: main
Framework preset: None
Build command: npm run docs:build
Build output directory: docs/.vitepress/dist
Root directory: /

如果使用 pnpm，则配置为：

Build command: pnpm docs:build
Build output directory: docs/.vitepress/dist

八、wrangler.toml 配置文件

虽然 Cloudflare Pages 可以直接在控制台配置，但建议项目中保留 wrangler.toml，方便后续通过 CLI 部署、绑定 R2、D1 或 Workers。

示例：

name = "company-kb"
compatibility_date = "2025-01-01"

pages_build_output_dir = "docs/.vitepress/dist"

[vars]
ENVIRONMENT = "production"
APP_NAME = "Company Knowledge Base"

# 如果后续使用 D1，可以打开以下配置
# [[d1_databases]]
# binding = "KB_DB"
# database_name = "company-kb-db"
# database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# 如果后续使用 R2，可以打开以下配置
# [[r2_buckets]]
# binding = "KB_ASSETS"
# bucket_name = "company-kb-assets"

如果采用 Wrangler 部署，可以安装 CLI：

npm install wrangler -D

然后在 package.json 中添加：

{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs",
    "deploy": "wrangler pages deploy docs/.vitepress/dist --project-name company-kb"
  }
}

部署命令：

npm run docs:build
npm run deploy

九、Cloudflare Pages Headers 配置

为了提高安全性，可以添加 _headers 文件。注意：Cloudflare Pages 的 _headers 文件需要放到最终构建产物目录中。对于 VitePress，可以把它放在 docs/public/_headers，构建时会自动复制到输出目录。

创建：

mkdir -p docs/public
touch docs/public/_headers

docs/public/_headers 示例：

/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  Referrer-Policy: strict-origin-when-cross-origin
  Permissions-Policy: camera=(), microphone=(), geolocation=()
  Content-Security-Policy: default-src 'self'; img-src 'self' data: https:; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; font-src 'self' data:; connect-src 'self'; frame-ancestors 'none';
  Cache-Control: public, max-age=3600

说明：

• X-Frame-Options: DENY：禁止页面被 iframe 嵌套，降低点击劫持风险；
• X-Content-Type-Options: nosniff：防止浏览器错误解析 MIME 类型；
• Referrer-Policy：减少外部站点获取来源路径；
• Permissions-Policy：禁用不必要的浏览器权限；
• Content-Security-Policy：限制资源加载来源；
• Cache-Control：设置基础缓存策略。

如果你的知识库中使用了第三方搜索、评论或统计工具，需要相应调整 CSP，否则可能导致资源被浏览器拦截。

十、Cloudflare Pages Redirects 配置

有时企业知识库迁移后，旧路径需要跳转到新路径。可以使用 _redirects 文件。

创建 docs/public/_redirects：

/old-guide               /guide/                  301
/docs/onboarding         /guide/onboarding        301
/devops                  /engineering/devops      302
/security-policy         /security/access-control 301

如果需要为单页应用兜底，可以添加：

/* /index.html 200

不过 VitePress 通常不需要全局 SPA fallback，除非你有特殊前端路由需求。

十一、配置 Cloudflare Access 保护知识库

企业知识库最重要的一步是访问控制。部署完成后，Pages 会生成一个类似下面的域名：

https://company-kb.pages.dev

建议绑定企业自有域名，例如：

https://kb.example.com

然后在 Cloudflare Zero Trust 中配置 Access。

1. 创建 Access Application

进入：

Cloudflare Dashboard → Zero Trust → Access → Applications → Add an application

选择：

Self-hosted

填写：

Application name: Company Knowledge Base
Application domain: kb.example.com
Session duration: 24h

2. 设置访问策略

例如只允许企业邮箱访问：

Policy name: Allow company employees
Action: Allow
Include:
  Emails ending in: @example.com

如果要指定用户组：

Include:
  Emails:
    alice@example.com
    bob@example.com
    devops@example.com

也可以接入身份提供商，例如 Google Workspace、Microsoft Entra ID、Okta 等，再按组织架构授权。

3. 按路径细分权限

如果安全文档只允许安全团队访问，可以额外创建一个 Application 或使用 Access policy 对路径做限制：

Application domain:
kb.example.com/security/*

策略：

Allow security team only
Include:
  Emails:
    security-lead@example.com
    secops@example.com

这样，普通员工可以访问常规知识库，但无法访问安全应急、漏洞响应、权限策略等敏感内容。

十二、使用 R2 存储附件

知识库中经常会包含 PDF、培训视频、流程图、客户案例、压缩包等大文件。如果全部放在 Git 仓库中，会导致仓库越来越大，不利于维护。

推荐将大文件放入 Cloudflare R2。

1. 创建 R2 Bucket

Cloudflare Dashboard → R2 → Create bucket

名称示例：

company-kb-assets

2. 通过 Wrangler 上传文件

安装 Wrangler：

npm install wrangler -D

上传文件：

npx wrangler r2 object put company-kb-assets/training/onboarding.pdf --file ./assets/onboarding.pdf

如果需要公开访问，可以配置自定义域名，例如：

assets-kb.example.com

然后在 Markdown 中引用：

[下载入职培训 PDF](https://assets-kb.example.com/training/onboarding.pdf)

但要注意，如果附件也属于内部资料，不建议直接公开 R2 域名。更稳妥的方式是通过 Workers 代理，并结合 Access 或签名 URL 控制访问。

十三、Workers 代理 R2 附件示例

下面是一个简单的 Workers 示例，用于读取 R2 中的附件。

src/worker.ts：

export interface Env {
  KB_ASSETS: R2Bucket
}

export default {
  async fetch(request: Request, env: Env): Promise {
    const url = new URL(request.url)
    const key = url.pathname.replace(/^\/files\//, '')

    if (!key || key.includes('..')) {
      return new Response('Invalid file path', { status: 400 })
    }

    const object = await env.KB_ASSETS.get(key)

    if (!object) {
      return new Response('File not found', { status: 404 })
    }

    const headers = new Headers()
    object.writeHttpMetadata(headers)
    headers.set('Cache-Control', 'private, max-age=3600')

    return new Response(object.body, {
      headers
    })
  }
}

对应 wrangler.toml：

name = "company-kb-assets-worker"
main = "src/worker.ts"
compatibility_date = "2025-01-01"

[[r2_buckets]]
binding = "KB_ASSETS"
bucket_name = "company-kb-assets"

部署：

npx wrangler deploy

然后将 Worker 路由绑定到：

kb.example.com/files/*

这样知识库页面和附件可以处在同一个主域名下，再通过 Cloudflare Access 统一保护。

十四、文档编写规范

企业知识库能否长期有效，不取决于部署工具，而取决于内容治理。建议制定统一的文档规范。

1. 每篇文档应包含基本信息

例如：

# 生产环境发布流程

| 字段 | 内容 |
|---|---|
| 负责人 | DevOps Team |
| 适用范围 | 后端服务、前端应用 |
| 更新时间 | 2025-01-01 |
| 文档状态 | 生效中 |

## 一、适用场景

本文用于说明生产环境发布前检查、发布步骤和回滚流程。

2. 文档状态建议标准化

可使用以下状态：

• 草稿；
• 评审中；
• 生效中；
• 已废弃；
• 待更新。

3. 内容要面向读者

不要只记录“我知道什么”，而要说明“读者如何完成任务”。企业知识库的好文档通常具备：

• 目标明确；
• 步骤清晰；
• 示例完整；
• 风险提示充分；
• 有负责人；
• 有更新时间；
• 有相关链接。

4. 避免把敏感信息写入知识库

不要将以下内容直接写入 Markdown：

• 密码；
• Token；
• API Key；
• 私钥；
• 数据库连接串；
• 客户敏感信息；
• 内部安全漏洞细节；
• 未脱敏日志。

如果确实需要记录凭据获取方式，应写成：

生产数据库账号请通过权限申请系统提交申请。
审批通过后，可在企业密码管理器中查看。

而不是直接粘贴账号密码。

十五、GitHub Actions 自动构建示例

Cloudflare Pages 已经支持连接 Git 自动构建。如果希望使用 GitHub Actions 完成构建和部署，也可以配置。

.github/workflows/deploy.yml：

name: Deploy Knowledge Base to Cloudflare Pages

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    permissions:
      contents: read
      deployments: write

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: npm ci

      - name: Build docs
        run: npm run docs:build

      - name: Deploy to Cloudflare Pages
        uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          projectName: company-kb
          directory: docs/.vitepress/dist
          gitHubToken: ${{ secrets.GITHUB_TOKEN }}

需要在 GitHub Secrets 中配置：

CLOUDFLARE_API_TOKEN
CLOUDFLARE_ACCOUNT_ID

API Token 建议只授予必要权限，例如 Cloudflare Pages 编辑权限，不要使用全局 API Key。

十六、缓存策略建议

知识库页面通常以静态资源为主。推荐策略：

HTML

HTML 文件不要缓存过久，否则更新后用户可能看到旧页面。可以设置：

Cache-Control: public, max-age=300

JS、CSS、图片

构建产物一般带 hash，可以缓存更久：

Cache-Control: public, max-age=31536000, immutable

可以在 Cloudflare Cache Rules 中针对路径设置规则：

if path contains "/assets/"
then Cache TTL = 1 year

同时，企业知识库使用 Access 后，很多内容会被视为受保护资源。缓存策略应避免敏感内容被错误公开缓存。对于高度敏感文档，建议使用：

Cache-Control: private, no-store

十七、上线前检查清单

上线企业知识库前，建议逐项检查：

• [ ] 是否绑定企业自有域名；
• [ ] 是否开启 HTTPS；
• [ ] 是否配置 Cloudflare Access；
• [ ] 是否禁止搜索引擎收录；
• [ ] 是否配置安全响应头；
• [ ] 是否设置合理的缓存策略；
• [ ] 是否删除测试账号和测试文档；
• [ ] 是否检查 Markdown 中的敏感信息；
• [ ] 是否配置 Git 分支保护；
• [ ] 是否配置自动构建；
• [ ] 是否明确文档负责人；
• [ ] 是否建立文档更新流程；
• [ ] 是否准备备份和导出方案。

十八、常见问题

1. Cloudflare Pages 适合私有知识库吗？

适合。Pages 负责静态站点托管，Access 负责访问控制。只要 Access 配置正确，未授权用户无法访问知识库内容。

2. 能不能多人在线编辑？

VitePress + Git 更偏向工程化协作，而不是实时协同编辑。如果企业成员不熟悉 Git，可以设计流程：普通成员通过表单或 Issue 提交内容，由文档维护者整理合并。也可以结合 CMS 或内部编辑器扩展。

3. 文档搜索如何实现？

VitePress 提供本地搜索，适合中小型知识库。如果文档量很大，可以接入 Algolia、Pagefind 或自建搜索服务。企业内部知识库如果涉及敏感内容，应避免将索引上传到外部第三方服务，除非完成合规评估。

4. 能否按部门展示不同内容？

可以。最简单方式是通过 Cloudflare Access 按路径限制访问，例如 /security/*、/finance/*。如果需要页面级动态权限，需要引入 Workers 或服务端逻辑。

5. 国内访问速度如何？

Cloudflare 在不同地区的访问体验会受到网络环境影响。如果企业用户主要在国内，需要结合实际线路测试。对于跨国团队、海外办公和远程协作场景，Cloudflare 的优势会更明显。

十九、维护建议

知识库上线只是第一步，长期维护更重要。建议建立以下机制：

1. 文档负责人制度
   每个栏目指定负责人，避免文档无人维护。

2. 定期审查机制
   每季度检查关键文档是否过期。

3. 变更评审流程
   重要流程、制度、安全文档修改前需要评审。

4. 归档机制
   废弃文档不要直接删除，可以移动到归档目录，并标记废弃原因。

5. 反馈入口
   每篇文档底部提供反馈方式，例如 Issue 链接、表单或企业 IM 群。

6. 模板化写作
   为 SOP、故障复盘、接口文档、需求文档制定统一模板。

二十、总结

基于 Cloudflare 搭建企业知识库，是一种兼顾速度、安全、成本和可维护性的方案。通过 VitePress 可以快速生成结构清晰、体验良好的静态文档站；通过 Cloudflare Pages 可以实现自动部署和全球分发；通过 Zero Trust Access 可以实现企业级访问控制；通过 R2、Workers、D1 等能力，还可以进一步扩展附件管理、搜索、反馈和权限逻辑。

本文提供的核心配置包括：

• package.json：项目构建脚本；
• docs/.vitepress/config.ts：知识库站点配置；
• wrangler.toml：Cloudflare 部署和资源绑定配置；
• _headers：安全响应头配置；
• _redirects：路径跳转配置；
• GitHub Actions：自动化部署配置；
• Workers + R2：附件访问扩展示例。

如果企业希望快速搭建一个轻量、安全、可持续维护的内部知识库，Cloudflare Pages + Access + VitePress 是一个非常值得考虑的组合。它既保留了 Markdown 与 Git 的工程化优势，又具备 Cloudflare 边缘网络和零信任安全体系的基础能力，适合从小团队逐步扩展到企业级知识管理平台。