# Cloudflare Pages 部署说明

当前项目已经支持两种模式：

1. 纯静态模式：直接部署即可
2. Supabase CMS 模式：前台部署到 Cloudflare Pages，内容走 Supabase
3. Cloudflare Functions 在线保存模式：管理员点击保存后直接更新远程文档

## 本地预览

在当前目录运行：

```bash
python3 -m http.server 5173
```

浏览器打开：

```text
http://localhost:5173/
```

## 方案 A：纯静态模式

适合内容不频繁修改时使用。

### Cloudflare Pages 直接上传

1. 登录 Cloudflare 控制台。
2. 进入 `Workers & Pages`。
3. 选择 `Create application`。
4. 选择 `Pages`。
5. 选择 `Direct Upload`。
6. 上传整个 `feishu-docs-site` 目录中的文件。
7. 部署完成后绑定域名，例如 `docs.your-domain.com`。

## 方案 B：Supabase CMS 模式

适合内容需要频繁更新时使用。

### 部署结构

- 前台：Cloudflare Pages
- 内容库：Supabase
- 图片/PDF：Supabase Storage
- 后台：`admin.html`
- 目录导航：Supabase `nav_items`

### 启用步骤

1. 在 Supabase 创建项目。
2. 执行 [supabase/schema.sql](./supabase/schema.sql)。
3. 填写 [data/cms.config.json](./data/cms.config.json)。
4. 重新部署站点。
5. 可用后台或命令行批量导入核心页面。

导入后可远程维护两部分：

- 页面正文：`pages` + `page_blocks`
- 首页/目录入口：`nav_items`

详细步骤见：

- [SUPABASE_SETUP.md](./SUPABASE_SETUP.md)

## 方案 C：Cloudflare Functions 在线保存

适合你现在这种“管理员直接编辑，点击保存后客户刷新就看到更新”的场景。

### 部署结构

- 前台：Cloudflare Pages
- 在线接口：Cloudflare Pages Functions
- 内容库：Supabase
- 管理入口：前台 `?edit=1`

### 你需要配置

1. 在 Supabase 执行：

```text
supabase/schema.sql
```

2. 把 [data/cms.config.json](./data/cms.config.json) 改为启用：

```json
{
  "enabled": true,
  "provider": "supabase",
  "projectUrl": "https://your-project.supabase.co",
  "anonKey": "your-anon-key"
}
```

3. 在 Cloudflare Pages 项目里配置环境变量：

```text
SUPABASE_URL
SUPABASE_ANON_KEY
SUPABASE_SERVICE_ROLE_KEY
SUPABASE_STORAGE_BUCKET
ADMIN_PASSWORD_HASH
ADMIN_PASSWORD_FALLBACK
PUBLIC_SITE_NAME
```

### 在线保存逻辑

- 前台访问时：优先请求 `/api/docs`
- 管理员登录时：请求 `/api/admin/login`
- 管理员点击“保存更新”时：请求 `/api/admin/save`
- 管理员上传图片/PDF/附件时：请求 `/api/admin/upload`
- 保存成功后：远程 Supabase 立即更新
- 保存失败时：自动回退到浏览器本地草稿

### 上传附件配置

在 Supabase Storage 创建公开 bucket：

```text
docs-assets
```

然后在 Cloudflare Pages 环境变量中添加：

```text
SUPABASE_STORAGE_BUCKET=docs-assets
```

图片上传后会直接显示在文档中；PDF、ZIP、Word、Excel 等附件会以文件按钮形式插入，客户点击即可查看或下载。

### 当前已接入的接口骨架

```text
functions/api/docs.js
functions/api/admin/login.js
functions/api/admin/save.js
functions/api/admin/upload.js
functions/api/admin/version.js
functions/api/admin/rollback.js
```

### 当前状态说明

这一版已经完成：

- 前台优先读取远程 `/api/docs`
- 编辑模式点击“保存更新”会优先走远程保存
- 远程失败时自动降级到本地草稿
- 每次保存会先写入 `page_versions`
- 已提供回滚接口 `/api/admin/rollback`
- 已提供上传接口 `/api/admin/upload`

这一版暂未完成：

- 单文档增量保存
- 多管理员冲突检测

## 后续导入飞书内容

推荐把真实飞书导出的 Markdown、HTML 或 TXT 放入：

```text
imports/
```

然后运行：

```bash
node tools/import-docs.mjs
node tools/build-preview.mjs
```

脚本会把导出文件写入：

```text
data/docs.json
```

保持字段结构不变即可：

```json
{
  "categories": [
    {
      "title": "分类名称",
      "items": [
        {
          "id": "unique-doc-id",
          "title": "文档标题",
          "updatedAt": "2026-07-03",
          "tags": ["标签"],
          "content": []
        }
      ]
    }
  ]
}
```

当前前台规则：

- 已经处理成站内页的，继续站内展示
- 还没处理成站内页的，继续跳飞书原链接
- 启用 Supabase 后，远程有的数据优先，远程没有的自动回退本地文档
- 启用 Supabase 后，首页关键入口也可由 `nav_items` 远程覆盖

## 腾讯云部署是否收费

腾讯云 COS 静态网站一般按量计费，可能涉及存储、请求、外网下行流量、CDN 等费用。访问量小的时候费用通常很低，但不是完全免费的长期托管。若国内访问是核心诉求，可以先用 Cloudflare Pages 验证，再按访问量决定是否迁移或加一份腾讯云 COS/CDN。