mirror of
https://github.com/34892002/edgeKey.git
synced 2026-05-06 15:22:43 +08:00
345 lines
15 KiB
Markdown
345 lines
15 KiB
Markdown
[](README-en.md)
|
||
[](README.md)
|
||
|
||
# EdgeKey
|
||
|
||
EdgeKey 是一套有vike框架开发，可直接部署到 Cloudflare 的一体化全栈卡密商城系统：同一套代码同时包含前端页面、SSR 渲染、后端 API / 数据变更入口，并由 Cloudflare Workers 运行。
|
||
|
||
## 功能特性
|
||
|
||
- 🚀 **真正的零成本** — 不用购买服务器和域名，基于 Cloudflare 全球边缘网络运行。一键部署，即刻上线。把钱花在刀刃上，把时间还给自己。
|
||
- 🌍 **零成本运维** — 基于 Workers + D1，免费额度足够满足日常运营，无需担心额外的账单扣费。
|
||
- 🛍️ **商品管理** — 支持分类、商品上下架、库存模式（有限/无限）、最小/最大购买数量。
|
||
- 🔑 **卡密管理** — 批量导入卡密，支付后自动发货，支持库存实时预警。
|
||
- 📦 **订单管理** — 包含订单列表、手动补发、自动关闭过期订单及详细的支付日志。
|
||
- 💳 **多支付网关** — 内置 BEpusdt (USDT)、Epay (聚合支付)，支持插件式扩展更多接口。
|
||
- 📧 **邮件通知** — 支持 SMTP / API / Cloudflare Email 三种通道，内置详细的邮件发送日志。
|
||
- ⚙️ **站点设置** — 灵活配置站点名称、Logo、公告及客服联系方式。
|
||
- 🔐 **管理后台** — 安全可靠的管理员账号体系。
|
||
|
||
> [!TIP]
|
||
> **关于 0 成本运行：** 在配合支付渠道（usdt、自建等）、个人邮箱 SMTP 以及免费图床的理想状态下，本项目可实现 **100% 零成本** 运营。
|
||
|
||
## 项目截图
|
||
|
||
|
||
|
||
|
||
|
||
|
||
## 快速开始
|
||
|
||
本项目支持三种部署方式，按推荐程度排序：
|
||
|
||
| 方式 | 适合场景 | 便捷程度 |
|
||
|---|---|---|
|
||
| **一键部署**（推荐） | 首次部署，无需本地环境 | ⭐⭐⭐ 最简单，点击按钮全自动完成 |
|
||
| **Git 自动部署** | 持续迭代，代码推送自动更新 | ⭐⭐ 配置一次后全自动 |
|
||
| **手动部署** | 二开需求，细节掌控 | ⭐ 需要本地环境和命令行操作 |
|
||
|
||
详细步骤见下方各章节说明。
|
||
|
||
### 一键部署到 Cloudflare Workers
|
||
|
||
[](https://deploy.workers.cloudflare.com/?url=https://github.com/34892002/edgeKey)
|
||
|
||
> **点击按钮后，会打开 Cloudflare Workers 部署向导，操作提示：**
|
||
> 1. 登录并授权 Git 账户(github、gitlab)，它会自动在你的git账号创建一个新仓库。
|
||
> 2. 为了增强安全性，请在向导中修改默认的密钥（ `AUTH_SECRET`）。
|
||
> 3. 如果你不绑定已有的D1数据库，它会自动完成新建数据库并初始化数据（管理员账号等）的操作，无需手动干预。
|
||
> 4. 部署成功之后在页面的日志里面可以找到 "Deployed edgekey triggers (0.38 sec) https://edgekey.你的账号.workers.dev" 这样的日志，其中 "https://edgekey.你的账号.workers.dev" 就是你的项目网址。
|
||
> 5. https://edgekey.你的账号.workers.dev/admin 为管理后台登陆地址，默认管理员账号:admin，密码:admin123456，切记登陆后立即修改密码！
|
||
|
||
### 通过 Git 连接 Cloudflare 自动部署
|
||
|
||
如果你使用 Cloudflare Workers 的 Git 集成（连接 GitHub/GitLab 仓库自动部署），需要先完成以下前置步骤：
|
||
|
||
**0. 前置：在 Cloudflare Dashboard 创建 D1 数据库**
|
||
|
||
1. 进入 [dash.cloudflare.com](https://dash.cloudflare.com) → **Storage & Databases** → **D1**
|
||
2. 点击 **Create** 创建数据库，名称填 `edgekey-db`
|
||
3. 记录数据库详情页中的 `database_id`，后续部署命令中需要用到
|
||
|
||
数据库表结构和种子数据会在首次部署时由 `deploy` 脚本自动完成初始化，无需手动操作。
|
||
|
||
**1. 部署命令**
|
||
|
||
由于 `wrangler.jsonc` 中的 `database_id` 需要与你的实际 D1 数据库绑定，Git 自动部署时请在 Cloudflare 的"构建配置"中将部署命令设置为：
|
||
|
||
```bash
|
||
sed -i 's/"database_name": "edgekey-db"/"database_name": "edgekey-db", "database_id": "你的database_id"/' wrangler.jsonc && bun run deploy
|
||
```
|
||
|
||
将 `你的database_id` 替换为你的实际 D1 数据库 ID（可在 Cloudflare Dashboard → D1 → 数据库详情页找到）。
|
||
|
||
**2. 配置 AUTH_SECRET 环境变量**
|
||
|
||
在 Cloudflare Workers Git 集成的"高级设置"中：
|
||
1. 添加变量名 `AUTH_SECRET`
|
||
2. 输入你的密钥字符串作为变量值
|
||
3. 勾选"加密"选项
|
||
|
||
### 构建与部署（手动）
|
||
|
||
首次部署到 Cloudflare 前，需要先在云端创建并初始化 D1 数据库：
|
||
|
||
1. **登录并创建数据库**
|
||
```bash
|
||
bunx wrangler login
|
||
bunx wrangler d1 create edgekey-db
|
||
```
|
||
|
||
2. **绑定 Database ID**
|
||
将上一步终端输出的 `database_id` 填入 `wrangler.jsonc`。
|
||
|
||
```jsonc
|
||
"d1_databases": [
|
||
{
|
||
"binding": "DB",
|
||
"database_name": "edgekey-db",
|
||
"database_id": "这里填入你刚创建数据库的UUID", // <-- 必须添加这一行
|
||
"migrations_dir": "prisma/migrations"
|
||
}
|
||
]
|
||
```
|
||
|
||
3. **按顺序初始化云端表结构**
|
||
```bash
|
||
bun run db:migrations:remote
|
||
```
|
||
|
||
4. **初始化管理员账号与初始化种子数据**
|
||
```bash
|
||
bun run db:seed:remote
|
||
```
|
||
|
||
5. **配置 AUTH_SECRET**
|
||
输入命令执行，根据命令行提示输入你要使用的密钥字符串。```bash
|
||
bunx wrangler secret put AUTH_SECRET
|
||
```
|
||
|
||
6. **生成 Prisma Client 并一键部署**
|
||
```bash
|
||
bun run db:generate
|
||
bun run up
|
||
```
|
||
|
||
`bun run up` 等价于先构建再发布：
|
||
- `vike build`
|
||
- `wrangler deploy`
|
||
|
||
部署配置见 `wrangler.jsonc`（其中 `main` 指向 Photon 的 Cloudflare server-entry 虚拟入口）。
|
||
|
||
## 安全性说明（重要）
|
||
|
||
当前项目使用管理员账号密码登录。用于生产环境前请务必：
|
||
- Cloudflare 生产环境必须配置 `AUTH_SECRET`，未配置会抛出异常并禁止管理员登录
|
||
- 配置方式详见上方"一键部署"、"通过 Git 连接 Cloudflare 自动部署"、"构建与部署（手动）"各章节说明
|
||
- 生产环境配置AUTH_SECRET命令 `wrangler secret put AUTH_SECRET`
|
||
- 默认管理员账号为 `admin / admin123456`，首次登录后请立即修改密码
|
||
|
||
### 忘记密码？
|
||
|
||
在 Cloudflare Dashboard 中通过 D1 Console 将密码重置为 `admin123456`：
|
||
|
||
1. 进入 [dash.cloudflare.com](https://dash.cloudflare.com) → **Storage & Databases** → **D1** → 点击 `edgekey-db`
|
||
2. 顶部 tab → **Console**
|
||
3. 执行以下 SQL：
|
||
|
||
```sql
|
||
UPDATE Admin SET passwordHash = '$2b$10$viMe8RgcpM30gmmF9OpOcuA/QgleSIUk5VRtqjOulfSIbgK5jQCI6' WHERE username = 'admin';
|
||
```
|
||
|
||
4. 登录后台后立即修改密码
|
||
|
||
## 本地开发
|
||
|
||
推荐使用 Bun（也可替换为 npm/pnpm/yarn）。
|
||
|
||
```bash
|
||
bun install
|
||
```
|
||
|
||
由于本项目使用了 Cloudflare D1 数据库，在首次启动本地开发服务器前，必须先初始化本地的 D1 模拟器表结构：
|
||
|
||
```bash
|
||
# 1. 生成 Prisma Client（首次安装依赖后必须执行）
|
||
bun run db:generate
|
||
|
||
# 2. 按顺序将所有迁移脚本应用到本地 Wrangler 模拟器
|
||
bun run db:migrations:local
|
||
|
||
# 3. 初始化管理员账号与初始化种子数据
|
||
bun run db:seed
|
||
|
||
# 4. 准备.env 文件
|
||
# 请在 `env.example` 中填写必要的环境变量，例如 `AUTH_SECRET`。
|
||
# 然后复制 `env.example` 到 `env` 文件。
|
||
|
||
# 5. 启动开发服务器
|
||
bun run dev
|
||
```
|
||
|
||
### Cloudflare D1 + Prisma 本地开发工作流
|
||
|
||
本项目使用了 Prisma ORM 与 Cloudflare D1 数据库，完全遵循 [官方 Prisma + Cloudflare D1 指南](https://www.prisma.io/docs/guides/deployment/cloudflare-d1) 的最佳实践。
|
||
|
||
### 当前运行方式
|
||
|
||
- `bun dev` 运行在 Cloudflare 风格的本地开发环境中，Prisma 会通过 `env.DB` 连接到**本地 D1 模拟器**。
|
||
- `bun run up` 部署后，Prisma 会通过同一个 `env.DB` 绑定连接到**远程 D1**。
|
||
- `.env` 中的 `DATABASE_URL` 仅用于 Prisma CLI / 配置层，不参与当前应用运行时的数据库连接。
|
||
- 当前 `prisma/schema.prisma` 仅保留 Cloudflare client generator，运行时统一使用 `generated/prisma/client`。
|
||
- 因此，本项目当前的数据库运行模式是：**开发环境用本地 D1，生产环境用远程 D1**。
|
||
|
||
### 正确的数据库开发工作流
|
||
|
||
当你需要修改数据库表结构时，请**严格按照以下流程执行**：
|
||
|
||
**第一步：修改 Schema 并生成 SQL 迁移脚本**
|
||
|
||
修改 `prisma/schema.prisma` 后，不要使用常规的 `migrate dev`，而是使用 `migrate diff` 生成 SQL 脚本：
|
||
|
||
```bash
|
||
# 由于 Cloudflare D1 和普通的 MySQL 完全不同。普通的 Prisma migrate dev 依赖于一个长期运行的数据库连接来比对状态、创建 shadow database 等等，而 D1 不支持这些操作。
|
||
# 后续增量迁移（修改现有表结构时）
|
||
# 新版 Prisma 已经废弃了 --from-local-d1，推荐使用 --from-migrations
|
||
bunx prisma migrate diff \
|
||
--from-migrations prisma/migrations \
|
||
--to-schema prisma/schema.prisma \
|
||
--script > prisma/migrations/0002_xxx.sql
|
||
```
|
||
|
||
说明：
|
||
- `0001_init.sql` 只用于第一次初始化，不应在后续迁移中反复覆盖。
|
||
- 后续迁移请按顺序新增文件，例如 `0002_add_foo.sql`、`0003_add_bar.sql`。
|
||
|
||
**第二步：将迁移同步到本地 D1 模拟器（用于本地开发/测试）**
|
||
|
||
```bash
|
||
bun run db:migrations:local
|
||
```
|
||
|
||
如果不执行这一步，运行 `bun dev` 访问页面时会报错 `no such table`。
|
||
|
||
**第三步：将迁移同步到 Cloudflare 线上（发布前）**
|
||
|
||
```bash
|
||
bun run db:migrations:remote
|
||
```
|
||
|
||
本地和线上需要分别执行一次。
|
||
|
||
### 日常开发命令
|
||
|
||
```bash
|
||
bun dev
|
||
```
|
||
|
||
上面的命令会启动本地开发服务器，并使用 `wrangler.jsonc` 中定义的 D1 绑定连接到**本地 D1 模拟器**。
|
||
|
||
### Telefunc 说明
|
||
|
||
- Telefunc 函数按约定放在对应页面目录下，以 `.telefunc.ts` 结尾。
|
||
- 当前 Windows + `bun dev` + `workerd` 组合下，Telefunc 的开发态命名/同目录检查会触发路径兼容问题，因此在 `server/telefunc-handler.ts` 中关闭了该检查。
|
||
- 这不会影响 Telefunc 的实际加载和调用，只是跳过开发态的命名约定校验。
|
||
|
||
**⚠️ 绝对不要做的操作：**
|
||
1. **不要**假设 `bun dev` 使用的是 `prisma/db.sqlite`；当前它实际使用的是本地 D1 模拟器。
|
||
2. **不要**使用 `prisma migrate dev`，这会偏离当前 D1 迁移工作流。
|
||
3. **不要**反复覆盖 `prisma/migrations/0001_init.sql`；初始化迁移和后续增量迁移应分开维护。
|
||
|
||
## 技术栈
|
||
|
||
- 框架与渲染
|
||
- Vike（文件路由 + SSR）
|
||
- Vue 3（前端组件）
|
||
- Server / 运行时
|
||
- Hono（服务端路由与中间件）
|
||
- Photon（将服务端入口适配到 Cloudflare）
|
||
- Wrangler（Cloudflare 部署与本地开发工具）
|
||
- 数据与变更
|
||
- Telefunc（前后端同构的数据变更 RPC）
|
||
- Prisma（ORM）
|
||
- D1（Cloudflare 原生 SQLite 数据库，本项目开发与部署统一使用）
|
||
- UI
|
||
- Tailwind CSS
|
||
- daisyUI（Tailwind 组件与主题）
|
||
- 认证
|
||
- Auth.js（管理员账号密码登录）
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
.
|
||
├─ assets/ # 静态资源
|
||
├─ components/ # 复用组件（非路由页面）
|
||
├─ pages/ # Vike 文件路由目录（页面就近放置组件/样式/类型）
|
||
│ ├─ +config.ts # 全局配置（例如 title、SSR 等）
|
||
│ ├─ +Layout.vue # 全局布局
|
||
│ ├─ +Head.vue # 全局 head 标签
|
||
│ ├─ tailwind.css # Tailwind + daisyUI 入口
|
||
│ ├─ index/+Page.vue # 前台首页（/）
|
||
│ ├─ product/+Page.vue # 商品详情页（/product/:slug）
|
||
│ ├─ query/+Page.vue # 订单查询页（/query）
|
||
│ ├─ order/+Page.vue # 订单详情页（/order/:orderNo）
|
||
│ ├─ admin/ # 管理后台（/admin）
|
||
│ └─ _error/+Page.vue # 错误页
|
||
├─ server/ # 服务端入口（Hono）与中间件
|
||
│ ├─ entry.ts # 服务端主入口
|
||
│ ├─ authjs-handler.ts # Auth.js handler + session middleware
|
||
│ ├─ prisma-middleware.ts # Prisma D1 注入中间件
|
||
│ └─ telefunc-handler.ts # Telefunc handler
|
||
├─ lib/ # 业务逻辑库（支付适配器、发货逻辑等）
|
||
├─ modules/ # 功能模块（支付通知、订单等）
|
||
├─ scripts/ # 辅助脚本（种子数据、验证脚本）
|
||
├─ prisma/ # Prisma Schema 与迁移 SQL
|
||
│ ├─ schema.prisma
|
||
│ └─ migrations/
|
||
│ ├─ 0001_init.sql
|
||
│ └─ 0002_xxx.sql
|
||
├─ vite.config.ts # Vite 插件配置（vike + vue + tailwind + telefunc）
|
||
├─ wrangler.jsonc # Cloudflare Workers 配置（入口为 Photon 虚拟模块）
|
||
└─ package.json # 脚本与依赖
|
||
```
|
||
|
||
### 关于 `+` 文件（Vike 约定）
|
||
|
||
`pages/` 目录下以 `+` 开头的文件是 Vike 的"约定接口文件"，用于声明页面、配置与数据加载等；不带 `+` 的文件会被当作普通模块（组件、样式、类型）处理，便于页面就近组织代码。
|
||
|
||
常见 `+` 文件：
|
||
- `+Page.vue`：页面组件
|
||
- `+data.ts`：页面数据获取（SSR/CSR 共享）
|
||
- `+Layout.vue`：布局（包裹页面）
|
||
- `+Head.vue`：head 标签
|
||
- `+config.ts`：页面/全局配置
|
||
|
||
## 日志排查
|
||
|
||
当邮件发送异常或支付回调出现问题时，可在 Cloudflare Dashboard 查看 Workers 运行日志：
|
||
|
||
1. 进入 [dash.cloudflare.com](https://dash.cloudflare.com)
|
||
2. 左侧菜单 → **Workers & Pages** → 点击 **edgekey**
|
||
3. 顶部 tab → **Observability**
|
||
4. 在搜索框输入关键词过滤日志，例如：
|
||
- `email.notify_order_paid.config_failed` — 支付后邮件配置获取失败
|
||
- `email.send.failed` — 邮件发送失败
|
||
- `email.order_paid.failed` — 支付成功后发送邮件通知失败
|
||
- `payment.notify.route_exception` — 支付回调路由异常
|
||
- `payment.notify.context_missing` — 支付回调缺少数据库上下文
|
||
- `payment.notify.diagnostic` — 支付回调校验异常诊断（签名错误、金额不匹配等）
|
||
- `bepusdt.verify_notify` — BEpusdt 回调原始 payload（info 级别）
|
||
|
||
## 鸣谢
|
||
|
||
感谢 [Linux.do](https://linux.do/) 、[NodeSeek](https://www.nodeseek.com/) 社区支持。
|
||
|
||
感谢下列开源项目
|
||
- [Ebpusdt](https://github.com/v03413/BEpusdt) — 加密货币交易支持
|
||
- [worker-mailer](https://github.com/zou-yu/worker-mailer) — Workers环境SMTP邮件支持
|
||
|
||
|
||
## 🏝️ 社区交流
|
||
- Telegram 群组：https://t.me/edgeKeyChannel
|
||
- Telegram 频道：https://t.me/edgeKeyGroup
|