从零搭建企业内部知识库：VitePress + Cloudflare Pages + Access 实战指南

发布人：慈云数据-客服中心发布时间：4小时前阅读量：3

Cloudflare 企业知识库搭建｜附完整命令

在企业内部，知识库不仅是“文档集合”，更是组织经验沉淀、项目交接、流程规范、研发协作和新人培训的重要基础设施。一个好用的企业知识库通常需要具备以下能力：

访问速度快，国内外团队都能稳定打开；
支持 Markdown 编写，方便技术团队维护；
支持版本管理，文档变更可追溯；
支持权限控制，只允许公司成员访问；
部署成本低，维护简单；
可持续扩展，例如接入搜索、对象存储、自动化发布等。

Cloudflare 提供了非常适合搭建企业知识库的一整套能力，包括 Cloudflare Pages、Workers、Access、Zero Trust、R2、D1、KV 等。对于大多数企业来说，最推荐的方案是：

使用 VitePress / Docusaurus / MkDocs 构建静态知识库，托管到 Cloudflare Pages，再通过 Cloudflare Access 做企业成员访问控制。

本文将以 VitePress + Cloudflare Pages + Cloudflare Access 为例，完整演示如何搭建一个企业级知识库，并附上从初始化到部署的完整命令。

一、整体架构设计

本文采用的架构如下：

员工浏览器
   ↓
Cloudflare Access 权限验证
   ↓
Cloudflare Pages
   ↓
VitePress 静态知识库
   ↓
GitHub / GitLab 仓库管理文档

这个方案的优点非常明显：

部署简单
VitePress 构建出的内容是纯静态文件，Cloudflare Pages 原生支持静态站点托管。
访问速度快
Cloudflare 全球 CDN 会自动缓存静态资源，员工访问速度稳定。
权限可控
通过 Cloudflare Access，可以基于邮箱、企业域名、身份提供商进行访问控制。
维护成本低
文档用 Markdown 编写，版本管理交给 Git，发布交给 Cloudflare Pages 自动完成。
适合企业长期使用
后续可以继续扩展全文搜索、图片对象存储、API 文档、内部工具导航等能力。

二、准备工作

在开始之前，需要准备以下环境和账号：

1. 本地环境

建议使用以下版本：

node -v
npm -v
git --version

2. Cloudflare 账号

你需要准备：

一个 Cloudflare 账号；
一个已经接入 Cloudflare 的域名；
一个 GitHub 或 GitLab 仓库；
如果需要权限控制，建议开启 Cloudflare Zero Trust。

假设你的企业知识库域名为：

docs.example.com

三、初始化 VitePress 知识库项目

首先创建一个项目目录。

mkdir cloudflare-enterprise-kb
cd cloudflare-enterprise-kb

初始化 npm 项目：

npm init -y

安装 VitePress：

npm install vitepress --save-dev

创建文档目录：

mkdir docs

初始化 VitePress：

npx vitepress init docs

执行后，命令行会提示你选择一些配置。可以参考如下选择：

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./docs
│
◇  Site title:
│  企业知识库
│
◇  Site description:
│  企业内部文档、流程规范与技术沉淀
│
◇  Theme:
│  Default Theme
│
◇  Use TypeScript for config and theme files?
│  Yes
│
◇  Add VitePress npm scripts to package.json?
│  Yes

初始化完成后，项目结构大致如下：

cloudflare-enterprise-kb
├── docs
│   ├── .vitepress
│   │   └── config.mts
│   ├── api-examples.md
│   ├── index.md
│   └── markdown-examples.md
├── package.json
└── package-lock.json

四、配置知识库首页

编辑首页文件：

vim docs/index.md

也可以使用 VS Code：

code docs/index.md

将内容修改为：

---
layout: home

hero:
  name: 企业知识库
  text: Enterprise Knowledge Base
  tagline: 沉淀经验、规范流程、提升协作效率
  actions:
    - theme: brand
      text: 开始阅读
      link: /guide/
    - theme: alt
      text: 文档规范
      link: /standard/document-style

features:
  - title: 流程规范
    details: 收录企业内部管理流程、审批规范、交付标准和协作约定。
  - title: 技术文档
    details: 沉淀架构设计、研发规范、部署手册、故障复盘和最佳实践。
  - title: 新人手册
    details: 帮助新员工快速了解组织、系统、流程和常用工具。
---

五、创建企业知识库目录结构

一个企业知识库不要一开始就做得过于复杂，但目录设计一定要清晰。推荐如下结构：

mkdir -p docs/guide
mkdir -p docs/standard
mkdir -p docs/tech
mkdir -p docs/project
mkdir -p docs/onboarding
mkdir -p docs/ops

创建基础文档：

cat > docs/guide/index.md <<'EOF'
# 使用指南

欢迎使用企业知识库。

本知识库用于沉淀企业内部流程、技术规范、项目资料、运维手册和新人培训内容。

## 适用人群

- 公司管理人员
- 产品经理
- 研发工程师
- 测试工程师
- 运维工程师
- 新入职员工

## 编写原则

1. 文档应清晰、准确、可执行；
2. 标题层级应合理；
3. 操作类文档必须提供完整命令；
4. 重要决策应记录背景、方案、影响和结论；
5. 文档变更必须通过 Git 提交记录追踪。
EOF

cat > docs/standard/document-style.md <<'EOF'
# 文档编写规范

## 一、标题规范

文档标题应简洁明确，避免使用含糊表述。

推荐：

```text
用户服务部署手册
订单系统故障排查指南
研发分支管理规范

不推荐：

一些说明
临时记录
新文档

二、结构规范

建议操作类文档包含以下结构：

背景说明
适用范围
前置条件
操作步骤
验证方式
回滚方案
常见问题

三、命令规范

所有命令应使用代码块展示，并标明环境。

npm install
npm run build

EOF


```bash
cat > docs/tech/deploy-standard.md <<'EOF'
# 应用部署规范

本文用于规范企业内部应用部署流程。

## 部署前检查

部署前必须确认：

- 代码已合并到主分支；
- CI 流水线执行成功；
- 数据库变更已评审；
- 已准备回滚方案；
- 已通知相关业务方。

## 常用命令示例

```bash
git pull origin main
npm install
npm run build
npm run test

回滚原则

如部署后出现严重故障，应优先恢复业务，再进行问题定位。 EOF


```bash
cat > docs/onboarding/index.md <<'EOF'
# 新人入职手册

欢迎加入团队。

## 入职第一天

你需要完成：

1. 开通企业邮箱；
2. 加入企业 IM；
3. 申请 Git 仓库权限；
4. 阅读企业知识库；
5. 配置本地开发环境。

## 常用系统

| 系统 | 用途 |
| --- | --- |
| Git 平台 | 代码托管 |
| 企业知识库 | 文档沉淀 |
| 项目管理系统 | 需求与任务管理 |
| CI/CD 平台 | 自动构建与发布 |
EOF

六、配置 VitePress 导航和侧边栏

打开配置文件：

vim docs/.vitepress/config.mts

替换为以下内容：

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: '企业知识库',
  description: '企业内部文档、流程规范与技术沉淀',

  cleanUrls: true,

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

    nav: [
      { text: '首页', link: '/' },
      { text: '使用指南', link: '/guide/' },
      { text: '流程规范', link: '/standard/document-style' },
      { text: '技术文档', link: '/tech/deploy-standard' },
      { text: '新人手册', link: '/onboarding/' }
    ],

    sidebar: {
      '/guide/': [
        {
          text: '使用指南',
          items: [
            { text: '知识库说明', link: '/guide/' }
          ]
        }
      ],

      '/standard/': [
        {
          text: '流程规范',
          items: [
            { text: '文档编写规范', link: '/standard/document-style' }
          ]
        }
      ],

      '/tech/': [
        {
          text: '技术文档',
          items: [
            { text: '应用部署规范', link: '/tech/deploy-standard' }
          ]
        }
      ],

      '/onboarding/': [
        {
          text: '新人手册',
          items: [
            { text: '入职指南', link: '/onboarding/' }
          ]
        }
      ]
    },

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

    search: {
      provider: 'local'
    },

    footer: {
      message: '企业内部资料，请勿外传',
      copyright: 'Copyright © 2024 Enterprise'
    }
  }
})

如果你没有 logo，可以先移除：

logo: '/logo.svg',

或者创建一个简单的 SVG：

cat > docs/public/logo.svg <<'EOF'

EOF

如果 docs/public 目录不存在，先创建：

mkdir -p docs/public

七、本地启动知识库

执行：

npm run docs:dev

默认访问地址通常是：

http://localhost:5173

如果你想指定端口：

npm run docs:dev -- --host 0.0.0.0 --port 3000

构建生产版本：

npm run docs:build

预览生产构建结果：

npm run docs:preview

构建产物默认位于：

docs/.vitepress/dist

八、使用 Git 管理知识库文档

初始化 Git 仓库：

git init

创建 .gitignore：

cat > .gitignore <<'EOF'
node_modules
docs/.vitepress/cache
docs/.vitepress/dist
.DS_Store
.env
EOF

提交代码：

git add .
git commit -m "init enterprise knowledge base"

如果你使用 GitHub，先创建一个远程仓库，例如：

git@github.com:example/cloudflare-enterprise-kb.git

然后执行：

git branch -M main
git remote add origin git@github.com:example/cloudflare-enterprise-kb.git
git push -u origin main

如果你使用 HTTPS：

git remote add origin https://github.com/example/cloudflare-enterprise-kb.git
git push -u origin main

九、部署到 Cloudflare Pages

方式一：通过 Cloudflare 控制台部署

进入 Cloudflare 控制台：

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

选择你的 GitHub 或 GitLab 仓库。

构建配置填写：

Framework preset: VitePress
Build command: npm run docs:build
Build output directory: docs/.vitepress/dist
Root directory: /
Node.js version: 18 或 20

保存后，Cloudflare Pages 会自动拉取代码并构建。

部署成功后，你会得到一个类似这样的地址：

https://cloudflare-enterprise-kb.pages.dev

方式二：使用 Wrangler 命令行部署

如果你希望通过命令行完成部署，可以安装 Cloudflare Wrangler。

npm install -g wrangler

wrangler login

构建项目：

npm run docs:build

创建 Pages 项目：

wrangler pages project create cloudflare-enterprise-kb

部署到 Cloudflare Pages：

wrangler pages deploy docs/.vitepress/dist --project-name cloudflare-enterprise-kb

部署成功后，终端会输出访问地址。

如果需要指定分支：

wrangler pages deploy docs/.vitepress/dist \
  --project-name cloudflare-enterprise-kb \
  --branch main

十、绑定企业自定义域名

假设你的域名是：

example.com

知识库域名是：

docs.example.com

在 Cloudflare Pages 项目中：

Pages 项目
  → Custom domains
  → Set up a custom domain

填写：

docs.example.com

如果域名已经托管在 Cloudflare，系统会自动添加 DNS 记录，通常是：

Type: CNAME
Name: docs
Target: cloudflare-enterprise-kb.pages.dev
Proxy: Enabled

如果你需要手动添加 DNS，可以在 DNS 页面添加：

CNAME docs cloudflare-enterprise-kb.pages.dev

等待生效后访问：

https://docs.example.com

十一、使用 Cloudflare Access 保护企业知识库

企业知识库通常不应该公开访问，因此需要通过 Cloudflare Access 做身份认证。

进入 Cloudflare 控制台：

Zero Trust
  → Access
  → Applications
  → Add an application

选择：

Self-hosted

填写应用信息：

Application name: 企业知识库
Session duration: 24 hours
Application domain: docs.example.com

然后创建访问策略。

例如，只允许公司邮箱域名访问：

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

也可以指定具体邮箱：

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

如果企业使用 Google Workspace、Azure AD、Okta 等身份提供商，也可以在 Zero Trust 中接入 IdP，然后基于组织、用户组控制权限。

配置完成后，访问：

https://docs.example.com

用户会先进入 Cloudflare Access 登录页，通过验证后才能访问知识库。

十二、配置 GitHub Actions 自动构建检查

虽然 Cloudflare Pages 可以直接构建部署，但建议在仓库中增加 GitHub Actions，用于在 Pull Request 阶段提前检查文档是否能够正常构建。

创建工作流目录：

mkdir -p .github/workflows

创建 CI 文件：

cat > .github/workflows/docs-ci.yml <<'EOF'
name: Docs CI

on:
  pull_request:
    branches:
      - main
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

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

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

      - name: Install dependencies
        run: npm ci

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

提交：

git add .github/workflows/docs-ci.yml
git commit -m "add docs ci workflow"
git push

这样每次提交或合并请求都会自动验证知识库是否能正常构建，避免把有问题的文档发布到线上。

十三、推荐的企业文档协作流程

为了让知识库真正长期可用，建议建立一套文档协作规范。

1. 所有文档必须通过 Git 提交

不建议直接在线改生产内容。推荐流程：

新建分支 → 编写文档 → 提交 Pull Request → Review → 合并 main → 自动发布

示例命令：

git checkout -b docs/add-payment-runbook

编辑文档后：

git add docs/ops/payment-runbook.md
git commit -m "docs: add payment service runbook"
git push origin docs/add-payment-runbook

然后在 GitHub / GitLab 创建合并请求。

2. 重要文档必须有人 Review

以下类型文档建议强制 Review：

生产部署手册；
故障处理手册；
数据库变更说明；
安全规范；
权限申请流程；
对外接口文档；
项目复盘文档。

3. 文档需要定期归档

建议每季度检查一次知识库，处理以下内容：

已过期的流程；
不再维护的项目；
废弃系统的部署手册；
重复文档；
标题不规范的文档；
无负责人文档。

可以在每篇重要文档顶部增加维护信息：

# 用户服务部署手册

> 负责人：平台研发组  
> 最近更新：2024-06-01  
> 适用环境：生产环境、预发布环境

十四、可选增强：接入 Cloudflare R2 存储附件

如果企业知识库中包含大量图片、PDF、安装包或导出文件，不建议全部放到 Git 仓库中。更好的方式是使用 Cloudflare R2 存储附件，然后在文档中引用链接。

安装 Wrangler：

npm install -g wrangler

wrangler login

创建 R2 Bucket：

wrangler r2 bucket create enterprise-kb-assets

上传文件示例：

wrangler r2 object put enterprise-kb-assets/images/architecture.png --file ./architecture.png

查看对象：

wrangler r2 object get enterprise-kb-assets/images/architecture.png --file ./downloaded-architecture.png

在文档中引用：

![系统架构图](https://assets.example.com/images/architecture.png)

如果附件也需要权限控制，可以通过 Cloudflare Worker 代理访问，并结合 Access 或签名 URL 进行控制。

十五、可选增强：使用 Page Rules / Cache Rules 优化缓存

对于知识库这类静态站点，可以通过 Cloudflare Cache Rules 提升访问速度。

推荐缓存策略：

URL: https://docs.example.com/assets/*
Cache eligibility: Eligible for cache
Edge TTL: 1 month
Browser TTL: 1 day

对于 HTML 页面，可以保持较短缓存，以便文档更新后快速生效：

URL: https://docs.example.com/*
Edge TTL: 5 minutes
Browser TTL: 5 minutes

如果使用 Cloudflare Pages，通常已经具备较好的静态缓存策略，一般不需要过度配置。除非知识库访问量较大，或者跨地区团队较多，才建议进一步细化缓存规则。

十六、常见问题

1. 部署后页面 404 怎么办？

首先确认 Cloudflare Pages 的构建输出目录是否正确：

docs/.vitepress/dist

然后本地执行：

npm run docs:build
npm run docs:preview

如果本地预览正常，再检查 Pages 构建日志。

2. 自定义域名无法访问怎么办？

检查 DNS 记录：

CNAME docs cloudflare-enterprise-kb.pages.dev

确认代理状态开启：

Proxy status: Proxied

也可以用命令检查解析：

dig docs.example.com

或者：

nslookup docs.example.com

3. Cloudflare Access 配置后所有人都进不去怎么办？

检查 Access 策略是否配置正确，尤其是邮箱域名。

例如：

@example.com

不要误写成：

example.com

如果使用身份提供商，还需要确认 IdP 已经在 Zero Trust 中配置完成。

4. 文档更新后没有立即生效怎么办？

可以在 Cloudflare Pages 中查看最新部署是否成功。如果部署成功但浏览器仍看到旧内容，可以尝试：

npm run docs:build

确认构建内容无误后重新部署：

wrangler pages deploy docs/.vitepress/dist --project-name cloudflare-enterprise-kb

也可以在 Cloudflare 控制台清理缓存：

Caching
  → Configuration
  → Purge Cache

十七、完整命令汇总

下面是一套从零开始创建、构建、提交、部署的完整命令：

mkdir cloudflare-enterprise-kb
cd cloudflare-enterprise-kb

npm init -y
npm install vitepress --save-dev

mkdir docs
npx vitepress init docs

mkdir -p docs/guide docs/standard docs/tech docs/project docs/onboarding docs/ops docs/public

cat > .gitignore <<'EOF'
node_modules
docs/.vitepress/cache
docs/.vitepress/dist
.DS_Store
.env
EOF

npm run docs:dev
npm run docs:build
npm run docs:preview

git init
git add .
git commit -m "init enterprise knowledge base"

git branch -M main
git remote add origin git@github.com:example/cloudflare-enterprise-kb.git
git push -u origin main

npm install -g wrangler
wrangler login

npm run docs:build
wrangler pages project create cloudflare-enterprise-kb
wrangler pages deploy docs/.vitepress/dist --project-name cloudflare-enterprise-kb