关联主题::
同级:: 2025-11-24_星期一
下一级::

该文档内容来源于：升级更新指南.md

简单来说就是这个信息源渠道表的网站，原来是需要在本地更新，本地更新完之后推送到GitHub，然后部署在Cloudflare，然后现在可以纯云端进行编辑添加修改，不需要先在本地操作了。

升级更新指南 - Cloudflare KV 云端编辑功能

🆕 最新更新

v2.0.1 - 2025-11-24

修复问题： 文件夹点击事件优化

问题描述：

点击文件夹文字时，会在新标签页打开链接，而不是展开/收起文件夹

修复内容：

将文件夹点击处理从单独绑定改为事件委托模式
在捕获阶段处理点击事件，确保优先级最高
支持动态添加的文件夹元素自动绑定事件

技术实现：

// 修改前：为每个文件夹单独添加事件监听器
folderLink.addEventListener('click', function(ev) { ... });
 
// 修改后：使用事件委托在 mainmenu 上统一处理
mainMenu.addEventListener('click', function(ev) {
    const clickedLink = ev.target.closest('a');
    if (clickedLink && isFolderLink(clickedLink)) {
        ev.preventDefault();
        ev.stopPropagation();
        toggleFolder(clickedLink);
    }
}, true); // 捕获阶段

受影响文件：

index.html (行 548-586)

提交记录：

Commit: aa060a5
日期: 2025-11-24

v2.0.0 - 2024-11-24

更新内容： 实现云端在线编辑功能，无需本地操作即可修改网站内容

📋 更新概述

本次更新引入了 Cloudflare KV 存储功能，实现了网站内容的云端实时编辑。更新后，你可以直接在浏览器中编辑网站内容，修改立即生效，无需再通过终端推送代码。

核心变化

项目	更新前	更新后
数据存储	HTML 文件	Cloudflare KV
编辑方式	本地 PHP + 推送代码	直接网页端编辑
生效时间	需等待部署（1-3分钟）	即时生效
依赖环境	需要本地 PHP 环境	只需浏览器

📁 新增/修改的文件

新增文件

文件路径	说明
`functions/api/get-data.js`	KV 数据读取 API
`functions/api/save-data.js`	KV 数据保存 API
`js/kv-adapter.js`	KV 存储适配器，处理数据加载
`js/unified-api.js`	统一保存接口，自动检测环境
`migrate-to-kv.js`	数据迁移脚本
`admin_config.json`	配置数据备份
`mainmenu_html.txt`	菜单数据备份
`KV_DEPLOY_GUIDE.md`	KV 部署技术指南
`纯网页操作教程.md`	小白操作手册
`小白操作手册.md`	详细操作步骤

修改文件

文件路径	修改内容
`wrangler.toml`	添加 KV 命名空间配置
`index.html`	添加 kv-adapter.js 和 unified-api.js 引用；更新 JS/CSS 版本号
`js/admin.js`	修改保存逻辑，使用统一 API 接口替代直接调用 save_html.php

🔧 技术实现细节

1. 数据存储结构

数据存储在 Cloudflare KV 中，使用以下 Key：

KV 命名空间: xxy (或 WEBSITE_DATA)
├── admin_config    → JSON 格式，存储弹窗、轮播、公告等配置
├── mainmenu_html   → 文本格式，存储菜单 HTML 内容
└── announcement_config → JSON 格式，存储公告配置

2. API 端点

端点	方法	功能
`/api/get-data?type=all`	GET	获取所有数据
`/api/get-data?type=config`	GET	仅获取配置
`/api/get-data?type=menu`	GET	仅获取菜单
`/api/save-data`	POST	保存数据

3. 环境自动检测

系统会自动检测当前运行环境：

// 本地环境判断条件
hostname === 'localhost' ||
hostname === '127.0.0.1' ||
hostname.startsWith('192.168.') ||
hostname.startsWith('10.') ||
hostname.startsWith('172.')

本地环境 → 使用 PHP (save_html.php) 保存到文件
云端环境 → 使用 KV API 保存到 Cloudflare

4. 数据加载流程

页面加载
    ↓
kv-adapter.js 执行
    ↓
检测是否为云端环境
    ↓ 是
等待 mainmenu 元素加载完成
    ↓
调用 initializeFromKV()
    ↓
从 /api/get-data 获取数据
    ↓
更新 window.ADMIN_CONFIG
    ↓
替换 mainmenu.innerHTML
    ↓
页面显示 KV 中的最新内容

5. 数据保存流程

用户点击保存
    ↓
admin.js 调用 saveToHTMLFile()
    ↓
unified-api.js 检测环境
    ↓ 云端环境
调用 saveMenu() / saveConfig()
    ↓
kv-adapter.js 发送 POST 请求到 /api/save-data
    ↓
Cloudflare Function 写入 KV
    ↓
返回成功响应
    ↓
显示"保存成功"提示

🔑 关键代码修改

admin.js - saveToHTMLFile 函数

修改前： 直接调用 save_html.php

const response = await fetch('save_html.php', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(requestData)
});

修改后： 使用统一 API

if (mainmenuHtml && announcementConfig) {
    const success = await saveMenuAndAnnouncement(mainmenuHtml, announcementConfig);
    if (!success) throw new Error('保存失败');
} else if (mainmenuHtml) {
    const success = await saveMenu(mainmenuHtml);
    if (!success) throw new Error('保存菜单失败');
}

admin.js - 配置保存

修改前：

fetch('save_html.php', {
    method: 'POST',
    body: JSON.stringify({
        config_type: configType,
        config_data: config
    })
})

修改后：

saveConfig(configType, config)
    .then(success => {
        if (success) {
            showMessage(`${configType}配置保存成功！`, 'success');
        }
    })

kv-adapter.js - 自动初始化

// 等待 DOM 完全加载后执行初始化
function waitForDOMAndInit() {
  const mainMenu = document.getElementById('mainmenu');
  if (mainMenu) {
    console.log('📄 mainmenu 已找到，开始加载 KV 数据...');
    initializeFromKV().catch(error => {
      console.error('初始化 KV 数据失败:', error);
    });
  } else {
    console.log('⏳ 等待 mainmenu 加载...');
    setTimeout(waitForDOMAndInit, 100);
  }
}

⚙️ 配置要求

Cloudflare Dashboard 配置

创建 KV 命名空间
- 名称：xxy（或自定义名称）
- 记录 ID：67b6ed9a5e464d60ac056c152aa7a536
绑定 KV 到 Pages 项目
- Settings → Functions → KV namespace bindings
- Variable name: WEBSITE_DATA
- KV namespace: 选择创建的命名空间
环境变量（已有，无需修改）
- ADMIN_USERNAME: 管理员用户名
- ADMIN_PASSWORD: 管理员密码

wrangler.toml 配置

[[kv_namespaces]]
binding = "WEBSITE_DATA"
id = "67b6ed9a5e464d60ac056c152aa7a536"
 
[[env.production.kv_namespaces]]
binding = "WEBSITE_DATA"
id = "67b6ed9a5e464d60ac056c152aa7a536"
 
[[env.preview.kv_namespaces]]
binding = "WEBSITE_DATA"
id = "67b6ed9a5e464d60ac056c152aa7a536"

📝 使用说明

云端编辑（推荐）

访问 https://xxy.brmys.cn/admin 或 https://xxy.brmys.cn#admin
使用管理员账号密码登录
进入编辑模式，修改内容
点击保存
退出编辑模式
刷新页面验证修改

本地开发（可选）

# 启动本地服务器
php -S localhost:8000
 
# 访问本地网站
open http://localhost:8000
 
# 编辑完成后推送
git add .
git commit -m "更新内容"
git push

🐛 问题排查

问题 1：保存时提示失败

检查项：

KV 命名空间是否正确绑定
Variable name 是否为 WEBSITE_DATA（注意大小写）
浏览器控制台错误信息

问题 2：刷新后数据丢失

检查项：

控制台是否显示 ✅ 菜单已从 KV 加载
如果没有，检查 kv-adapter.js 是否正确加载
尝试清空浏览器缓存

问题 3：加载旧版本 JS

解决方法：

更新 index.html 中的 JS 版本号
例如：admin.js?v=20251124 → admin.js?v=20251125

调试命令

在浏览器控制台执行：

// 检查环境
detectEnvironment()  // 应返回 'cloudflare'
 
// 检查函数是否加载
typeof saveMenu  // 应返回 'function'
typeof loadDataFromKV  // 应返回 'function'
 
// 手动加载 KV 数据
initializeFromKV()
 
// 查看当前配置
window.ADMIN_CONFIG

📊 性能与限制

Cloudflare KV 免费套餐限制

项目	限制
每日读取	100,000 次
每日写入	1,000 次
存储空间	1 GB
单个值大小	25 MB

对于个人网站完全够用。

延迟

KV 读取：通常 < 50ms
KV 写入：通常 < 100ms
全球 CDN 缓存，访问速度快

🔄 回滚方案

如需回滚到旧版本（使用 PHP 保存）：

在 index.html 中移除 kv-adapter.js 和 unified-api.js 的引用
恢复 admin.js 中的 save_html.php 调用
推送代码

或者直接使用 Git 回滚：

git log --oneline  # 查看提交历史
git revert <commit-hash>  # 回滚指定提交
git push

📞 技术支持

如遇问题：

检查浏览器控制台（F12）的错误信息
查看 Cloudflare Pages 的部署日志
参考本文档的问题排查部分

🎉 更新完成

现在你可以享受云端编辑的便利了！

✅ 直接在网页端编辑
✅ 修改即时生效
✅ 无需本地环境
✅ 无需终端操作
✅ 数据安全存储在云端

Happy Editing! 🚀

白日梦与诗

探索

【项目】信息源渠道表网站开发-2025.11.24