基于Cloudflare部署在线客服系统

2026-09-18T20:52:26+08:00 | 5分钟阅读

Mizar

基于Cloudflare部署在线客服系统

简介

基于 Cloudflare Workers 的轻量在线客服系统：访客聊天（文字 + 图片）、管理后台、Telegram / 企业微信群机器人新消息通知、定时数据清理。原生 Hono + TypeScript 实现，无服务器、零运维。项目下载：livechat

功能特性

• 💬 访客聊天 — 文字 + 图片上传（存 R2），长轮询实时收发，链接自动可点击
• 👨‍💼 管理后台 — 客户列表 / 消息回复 / 标记已读 / 删除 / 系统设置 / 修改密码
• 🔐 安全认证 — PBKDF2-SHA256(100k) 密码哈希 + HMAC-SHA256 会话 Cookie（30 天），改密自动轮换会话密钥
• 📱 Telegram 通知 — 新消息实时推送到管理员（600 秒/客户端节流）
• 💼 企业微信通知 — 群机器人 webhook 推送（与 Telegram 并行、独立节流）
• 🧹 定时清理 — 每日 03:00 UTC：每客户端保留最新 20% 消息（最少 50 条），删除 90 天无消息的僵尸客户端
• 📦 零配置部署 — npm run setup 一键创建 D1 + R2、回填配置、执行迁移
• 📲 PWA 管理后台 — 可安装到桌面 / 手机主屏，离线可用，独立窗口运行

技术栈

目录结构

livechat-system-worker/
├── src/                 # Worker 源码
│   ├── index.ts         # 入口：路由 / 图片 / 定时清理
│   ├── chat.ts          # 客户端聊天 API（init/send/get_messages/check_new）
│   ├── admin.ts         # 管理后台 API（登录/客户/消息/设置）
│   ├── auth.ts          # PBKDF2 密码哈希 + HMAC 会话
│   ├── db.ts            # D1 访问与设置表工具
│   ├── telegram.ts      # Telegram 通知（节流）
│   ├── wecom.ts         # 企业微信机器人通知（节流）
│   ├── cleanup.ts       # 每日数据清理逻辑
│   └── util.ts          # 通用小工具
├── static/              # Workers Assets 静态页面
│   ├── index.html       # 访客聊天页
│   ├── admin.html       # 管理后台页（PWA 入口）
│   ├── manifest.webmanifest  # PWA 清单（安装到桌面/主屏）
│   ├── sw.js            # Service Worker（管理后台离线缓存）
│   └── icons/           # PWA 图标（SVG）
├── migrations/          # D1 迁移（幂等）
├── scripts/
│   ├── setup.mjs        # 一键初始化（建 D1/R2、回填 ID、迁移、生成密码）
│   ├── formal_secret_scan.mjs  # 敏感信息扫描（提交前运行）
│   └── validate-jsonc.mjs      # wrangler.jsonc 语法校验
├── reference/           # 原 PHP 版参考实现（仅参考；uploads/ 含真实数据不发布）
├── wrangler.jsonc       # Worker 配置（D1 / R2 / Assets / Cron）
├── AGENTS.md            # AI / 开发者部署指南（必读）
└── .dev.vars.example    # 本地环境变量示例

API 概览

定时清理

每日 03:00 UTC 自动执行（wrangler.jsonc → triggers.crons）：

• 每客户端消息超 50 条时，仅保留最新 20%，删除更旧记录
• 删除 90 天无消息且未活跃的僵尸客户端

reference/ 目录说明

reference/ 保留原 PHP 版实现（config.php / database.php / chat.php / admin.php / api/* 等），用于对照迁移逻辑。其中 config.php 等文件的敏感配置已替换为占位符；reference/uploads/ 含真实聊天数据，已通过 .gitignore 排除，不随本仓库发布。

开发命令

创建Cloudflare Token

Token 权限清单

在 Cloudflare 控制台 → My Profile → API Tokens → Create Token，选 Edit Cloudflare Workers 模板，并按下表勾选（权限必须 ≥ 下表的粒度，否则 setup/deploy 会失败）：

创建Token

• 令牌名称：ai-livechat
• 权限范围：整个账户
• 权限策略
  • Workers Scripts：Edit
  • D1：Edit
  • R2：Edit
  • Account Settings：Read
• 过期时间：无过期时间
• IP 过滤：留空

部署项目

拉取项目

执行命令：

git clone https://github.com/aibochinese001/livechat-system-worker.git
cd livechat-system-worker

设置 Token 环境变量

在powerShell中执行命令：

$env:CLOUDFLARE_API_TOKEN = "cf_你的TOKEN"

Token 权限需包含：Workers Scripts Edit 、D1 Edit 、R2 Edit （均为 Account 级），最好再加 Account Settings Read 。权限不够会在后面 setup/deploy 时报You do not have permission to perform this action 。

安装依赖

cd e:\Informations\MSB\technical_information\git\livechat\livechat
npm install

一键初始化

自动完成：创建 D1lc-db + R2lc-media → 回填 database_id → 执行 2 个迁移 → 生成并尝试写入ADMIN_PASSWORD

npm run setup

⚠️ 运行完 立即保存 终端里打印的 🔑 管理员初始密码（首次登录后台用）。

部署

npm run deploy

部署成功会输出地址：https://opcgrow-livechat.<你的子域>.workers.dev

登录后台

能打开后台后：

1. 用 setup 生成并让你保存的 初始密码 登录/admin
2. 进入「修改密码」改成自己的强密码（改密后自动写入数据库并轮换会话密钥）
3. 改完后，env 里的ADMIN_PASSWORD secret 就没用了，可顺手删掉（不删也不影响，登录时数据库里的密码优先）

如果登录时提示「未初始化管理员密码」 （setup 阶段写 secret 时 Worker 还不存在，可能没写进去），就补一条：

npx wrangler secret put ADMIN_PASSWORD

通知配置

npx wrangler secret put TELEGRAM_BOT_TOKEN   # Telegram 通知
npx wrangler secret put TELEGRAM_ADMIN_ID
npx wrangler secret put WECOM_WEBHOOK_URL	# 企业微信群机器人`

或在后台/admin → 系统设置 里填写（env secret 优先级更高）。

设置github action推送

自动化推送部署，实现本地推送到github后，使用github action自动部署到cloudflare worker。

工作流文件：.github\workflows\deploy.yml

在 GitHub 仓库配置 Secrets。

打开 https://github.com/DreamPathway/livechat/settings/secrets/actions → New repository secret，添加两个：