跳转至

部署指南

访问架构

用户/Agent 访问
    ↓
https://wave-knowledge.pages.dev/ + Bearer Token
    ↓
Worker 验证 Token
    ├─ 有效 → 返回知识库内容
    └─ 无效 → 401 Unauthorized

访问方式

Agent 访问（推荐）

# 使用 Bearer Token
curl https://wave-knowledge.pages.dev/ \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# 示例
curl https://wave-knowledge.pages.dev/ \
  -H "Authorization: Bearer sk-knowledge-abc123"

浏览器访问

直接在浏览器打开 URL，系统会提示输入 Token。

部署顺序

1. 准备阶段

# 配置 GitHub Secrets:
# - CLOUDFLARE_API_TOKEN: Cloudflare API Token
# - CLOUDFLARE_ACCOUNT_ID: 账户 ID
# - API_TOKEN: Bearer Token (自定义，建议 32+ 字符)

2. Cloudflare 控制台配置

  1. 创建 Pages 项目 

    npx wrangler pages project create wave-knowledge --production-branch=main

  2. 确认 Worker 已部署

  3. 访问 https://dash.cloudflare.com/workers-and-pages

  4. 确认 wave-knowledge-auth Worker 存在

  5. 配置 Worker 路由（可选）

  6. 如需通过自定义域名访问，在 Worker 设置中添加路由
  7. 域名需绑定到此 Worker

环境变量

GitHub Secrets

变量名 说明 示例
CLOUDFLARE_API_TOKEN Cloudflare API Token cfk_xxx
CLOUDFLARE_ACCOUNT_ID Cloudflare 账户 ID ef9cd986c28831a3f85041a8cf08990a
API_TOKEN Bearer Token sk-knowledge-abc123...

本地开发 (.env)

CLOUDFLARE_API_TOKEN=cfk_xxx
CLOUDFLARE_ACCOUNT_ID=ef9cd986c28831a3f85041a8cf08990a
API_TOKEN=sk-knowledge-abc123

工作流流程

Push/Merge to main
    ↓
Checkout Code
    ↓
Setup Python 3.11
    ↓
mkdocs build --clean  →  生成 site/
    ↓
wrangler pages deploy  →  部署到 Cloudflare Pages
    ↓
wrangler deploy (Worker)  →  部署认证 Worker
    ↓
wrangler secret put API_TOKEN  →  设置 Token
    ↓
部署完成

关键文件

文件 说明
mkdocs.yml MkDocs 站点配置
worker/index.js Worker 认证脚本 (Bearer Token)
wrangler.jsonc Worker 配置
.github/workflows/deploy.yml GitHub Actions 工作流

故障排查

常见错误

错误 原因 解决方案
401 Unauthorized Token 无效或缺失 检查 Authorization 请求头
522 自定义域名无法连接 检查 DNS 配置或放弃自定义域名
Project not found Token 账户与项目不在同一账户 确认 Token 权限和账户

验证部署

# 检查 Pages 项目
npx wrangler pages project list

# 检查 Worker 状态
npx wrangler deployments list --config wrangler.jsonc

# 本地测试
npx wrangler dev --config wrangler.jsonc

# 测试认证
curl https://wave-knowledge.pages.dev/ \
  -H "Authorization: Bearer YOUR_API_TOKEN"

安全建议

  1. Token 管理
  2. 使用强随机 Token（建议 32+ 字符）
  3. 定期轮换

  4. 不要提交到 Git

  5. 权限控制

  6. Token 仅用于读取知识库
  7. 不需要写入权限