我的笔记

Appearance

Cloudflare Pages + Cloudflare Access 私有文档部署详细步骤 ​

目标:把本地 Markdown 项目部署到云端,私有访问、绑定自己的域名、经常更新,手机可随时查看。

前提:注册了 Cloudflare 账号,域名已托管到 Cloudflare,已安装 Node.js(npm)。

核心思路 ​

组件作用
Cloudflare Pages免费托管静态站(由 Markdown 渲染而来)
Cloudflare Access在域名前加"登录墙",没通过登录一律拦截,实现私有
私有 Git 仓库存放源码,每次 push 自动触发重新构建部署
自有域名绑定到 Pages,支持 HTTPS

第一步:构建你的静态站 ​

这里以 Vitepress 为例(好看、带搜索/目录导航),也可以换成 MkDocs、Docsify 等,原理相同。

bash
# 在 Windows 上打开终端(PowerShell / CMD / Git Bash)

# 1. 创建项目
npm create vitepress@latest my-docs

# 2. 进入目录
cd my-docs

# 3. 本地预览(可选,确认效果)
npm run docs:dev

# 4. 构建静态文件(生产产物)
npm run docs:build

构建产物默认输出到:

my-docs/docs/.vitepress/dist

记住这个输出目录,后面 Pages 配置会用到。

第二步:上传到私有 Git 仓库 ​

  1. 到 GitHub(或 Gitee/GitLab)新建一个仓库
  2. 务必选择 Private(私有),这是隐私的关键
  3. 本地关联并推送:
bash
git init
git add .
git commit -m "init"
git remote add origin git@github.com:你的用户名/my-docs.git
git branch -M main
git push -u origin main

之后每次修改,只要 git add . && git commit -m "..." && git push,就会自动触发重新部署(见第六步)。

第三步:创建 Cloudflare Pages 项目 ​

  1. 登录 Cloudflare 控制台
  2. 左侧菜单 → Workers & Pages → Create application → 选 Pages
  3. 点 Connect to Git,授权你的 GitHub 账号并选择 my-docs 仓库
  4. 填写构建设置:
    • Framework preset: 选 VitePress
    • Build command: npm run docs:build
    • Build output directory: docs/.vitepress/dist
  5. 点 Save and Deploy
  6. 首次部署完成后,你会获得一个 xxxx.pages.dev 的临时域名(先不要对外公开)

注意:Cloudflare Pages 支持 GitHub 和 GitLab。如果仓库在 Gitee,Pages 无法直连,需要用 CLI 手动上传,见文末"附录:Gitee 用户"。

第四步:绑定你自己的域名 ​

  1. 在 Pages 项目页面,进入 Custom domains 标签
  2. 点 Add custom domain,输入你的子域名,例如 docs.example.com
  3. Cloudflare 会要求你在 DNS 中添加一条记录,通常是一条 CNAME,指向 你的项目.pages.dev
  4. 确认添加后,等待 DNS 生效(通常几分钟)
  5. Cloudflare 会自动为该域名签发 HTTPS 证书

前提:你的域名 example.com 已经托管在 Cloudflare(即 DNS 使用 Cloudflare 的服务器)。

第五步:加 Cloudflare Access 登录墙(实现私有) ​

这是让"只有你能看"的关键步骤。

  1. 进入 Access → Applications → Add an application
  2. 选 Self-hosted(自托管应用)
  3. 填写:
    • Application name: 任意,如 my-docs
    • Application domain: 填 docs.example.com
  4. Authentication 登录方式,个人用推荐 One-time PIN(OTP):
    • 访问者输入邮箱 → Cloudflare 发送一次性验证码 → 输入后放行
    • 无需额外配置第三方身份服务,最省事
  5. Policies(策略) → Add a policy:
    • 名称任意
    • 规则默认设为 Include → Everyone(先通过邮箱验证码放行所有人,挡住未登录者)
  6. 点击 Save 保存

生效后效果:任何人访问 docs.example.com,都会先看到 Cloudflare 登录页,输入邮箱收到验证码并提交后,才能进入你的文档站。未通过验证的一律无法查看内容,实现私有。

进一步收紧(可选):在策略里改为只允许你个人邮箱,例如 Include → Emails → 你的邮箱,这样只有你一人能登录,其他人即使有验证码也进不来。

第六步:实现"经常更新" ​

  • Git 仓库方式(推荐):每次 git push,Cloudflare Pages 自动检测变更并重新构建部署,手机/电脑上改完即发布,零手工操作。
  • 手动部署方式(Gitee 用户):用 wrangler CLI 手动上传产物。
bash
# 安装 wrangler(全局)
npm install -g wrangler

# 登录
wrangler login

# 上传构建产物到 Pages 项目
wrangler pages deploy docs/.vitepress/dist --project-name my-docs

手机端使用 ​

  • 手机浏览器直接访问 docs.example.com
  • 首次访问会跳 Cloudflare 登录页,输邮箱收验证码即可
  • 后续访问在已登录状态下直接打开文档,支持移动端自适应

常见问题 ​

Q: Cloudflare 在国内访问慢/打不开? A: Cloudflare 的 Pages/CDN/Access 在国内不稳定,有时慢或无法访问,这是该方案最大的缺点。若要求国内稳定快速,建议改用国内服务器自托管方案(如腾讯云/阿里云轻量服务器 + nginx 密码认证 + 国内 CDN)。

Q: 可以免费吗? A: 可以。Pages 有免费额度,Access 免费额度够个人使用(每个用户可免费设置 50 个 Access 用户)。

Q: 需要懂服务器运维吗? A: 不需要,全部在 Cloudflare 网页控制台完成,无需购买服务器,也没有 nginx/Linux 运维负担。

方案优缺点总结 ​

优点

  • 免费、零服务器
  • 全程网页操作,无需运维
  • 私有性由 Cloudflare Access 保证
  • Git push 即自动更新
  • 绑定自己域名 + 自动 HTTPS

缺点

  • 国内访问速度/稳定性不佳(硬伤)
  • 依赖第三方平台(Cloudflare)
  • 登录体验依赖邮箱验证码

附录:Gitee 用户(Cloudflare 不支持直连) ​

  1. 本地构建产物后,安装 wrangler 并登录
  2. 手动部署:
bash
npm install -g wrangler
wrangler login
wrangler pages deploy docs/.vitepress/dist --project-name my-docs
  1. 每次更新都要手动执行这条命令(也可写成脚本一键执行)
  2. 私有性依然由 Access 登录墙保证(与 Git 仓库是否私有无关)

附录:若改为国内服务器方案(备选) ​

如果你最终决定要国内稳定快速,改为自托管:

  1. 买一台腾讯云/阿里云轻量应用服务器(约 ¥30-60/月)
  2. 服务器装 Nginx,把静态产物放到网站目录
  3. Nginx 加 auth_basic 用户名密码认证实现私有
  4. 域名解析(阿里云/腾讯云 DNS)指向服务器 IP,并开 CDN 加速
  5. 用 webhook + 私有 Git 仓库实现 push 自动拉取重建

这样私有性、国内速度、经常更新三者都满足,代价是花钱 + 要懂点 Linux/nginx。

附:Vitepress 项目目录结构(参考) ​

my-docs/
├── docs/
│   ├── .vitepress/
│   │   └── config.mjs      # 站点配置(标题、导航、搜索等)
│   ├── index.md            # 首页
│   └── 其他.md              # 你的文章
├── package.json
└── ...