121 lines
6.0 KiB
Markdown
121 lines
6.0 KiB
Markdown
# modelping · 萌芽Ping
|
||
|
||
在 Cloudflare Workers 上运行的大模型 API **流式首字延迟**与**可用性**监控面板：React + Vite 前端（Static Assets CDN）+ D1 存储（默认保留 30 天探测记录）+ 每分钟 Cron 调度。
|
||
|
||
## 目录结构
|
||
|
||
- [`frontend/`](frontend/)：React 前端（入口 [`frontend/index.html`](frontend/index.html)、源码 [`frontend/src/`](frontend/src/)）；根目录 [`vite.config.ts`](vite.config.ts) 将 `root` 指向此处，[`public/`](public/) 仍为静态资源目录。
|
||
- [`worker/`](worker/)：Cloudflare Worker — Hono API、D1、加密与定时探测调度；入口见 [`wrangler.json`](wrangler.json) 的 `main` 字段。
|
||
|
||
## 功能概要
|
||
|
||
- 管理端配置：API 根地址、API Key、模型名、协议（**OpenAI Chat Completions 经典** / **OpenAI Responses 新版** / Claude Anthropic）。
|
||
- 探测间隔：1、5、10、30、60、360（分钟）。
|
||
- 公开仪表盘：24h / 30d 可用率、按日时间条、最近状态码与首字延迟。
|
||
- 管理员入口：访问 **`/admin?token=<ADMIN_TOKEN>`**（与 `.dev.vars` / Secrets 中 `ADMIN_TOKEN` 一致即可，示例 `shumengya520`）。校验通过后 token 写入当前浏览器 `sessionStorage`，并自动 **`replace` 到 `/admin`**（从地址栏去掉 token，减少泄露）。
|
||
- 一键部署：`npm run build && wrangler deploy`（Cloudflare Vite 插件会自动使用 `dist/modelping` 构建产物与资源目录）。
|
||
|
||
## 前置条件
|
||
|
||
- Node.js 20+
|
||
- Cloudflare 账号与 [Wrangler](https://developers.cloudflare.com/workers/wrangler/) 登录（`npx wrangler login`）
|
||
|
||
## 初始化 D1
|
||
|
||
```bash
|
||
npx wrangler d1 create modelping
|
||
```
|
||
|
||
将输出中的 `database_id` 写入根目录 [`wrangler.json`](wrangler.json) 里 `d1_databases[0].database_id`（替换 `replace-with-your-d1-database-id`）。
|
||
|
||
应用迁移（本地与远程各执行一次按你开发需要；升级含「OpenAI 新版 Responses」协议时请确保已执行最新 SQL）：
|
||
|
||
```bash
|
||
npx wrangler d1 migrations apply modelping --local
|
||
npx wrangler d1 migrations apply modelping --remote
|
||
```
|
||
|
||
## 密钥与环境变量
|
||
|
||
| 变量 | 说明 |
|
||
|------|------|
|
||
| `ADMIN_TOKEN` | 管理 API Bearer Token；本地可复制 [`.dev.vars.example`](.dev.vars.example) 为 `.dev.vars`。生产务必执行 `npx wrangler secret put ADMIN_TOKEN`。 |
|
||
| `ENCRYPTION_KEY` | 可选。32 字节 Base64，或任意字符串（将做哈希派生）。不设时，用 `ADMIN_TOKEN` 派生加密密钥（仅建议用于内网/演示）。 |
|
||
|
||
本地开发：
|
||
|
||
```bash
|
||
cp .dev.vars.example .dev.vars
|
||
# 编辑 .dev.vars
|
||
```
|
||
|
||
## 开发与部署
|
||
|
||
```bash
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
生产构建与部署：
|
||
|
||
```bash
|
||
npm run deploy
|
||
```
|
||
|
||
等价于 `tsc -b && vite build && wrangler deploy`。Wrangler 会使用重定向后的 `dist/modelping/wrangler.json` 上传 Worker 与 `dist/client` 静态资源。
|
||
|
||
## 出现「服务端未配置 ADMIN_TOKEN」（503）怎么修
|
||
|
||
含义：当前运行的 Worker **读不到** `ADMIN_TOKEN`（既不是 Secret，本地也没从 `.dev.vars` 注入）。
|
||
|
||
**线上（你已 `wrangler deploy` 的网站）**
|
||
|
||
`.dev.vars` **只对本地 dev 有效**，不会跟着部署上去。在项目目录执行：
|
||
|
||
```bash
|
||
npx wrangler secret put ADMIN_TOKEN
|
||
```
|
||
|
||
按提示粘贴与 URL 里一致的口令（例如 `shumengya520`）。成功后无需改代码，再访问 `/admin?token=...` 即可。
|
||
|
||
也可使用快捷脚本：`npm run secret:admin`（同上，仍是交互式输入 Secret）。
|
||
|
||
**本地（`npm run dev`）**
|
||
|
||
1. 项目根目录必须有 **`.dev.vars`**，且**第一行**建议直接写：`ADMIN_TOKEN=你的口令`（不要先写一大段注释，部分环境解析更稳）。
|
||
2. 保存后 **关掉 dev 再重新执行** `npm run dev`。
|
||
3. 浏览器访问的必须是 dev 打印出的地址（如 `http://localhost:5173/admin?token=你的口令`），不要误用线上域名或 `vite preview` 的静态站（可能没有 Worker）。
|
||
|
||
## 管理员登录排障（`/admin?token=...` 进不去）
|
||
|
||
1. 打开浏览器 **开发者工具 → Network**，访问 `/admin?token=你的口令`，查看 **`/api/admin/ping`**：
|
||
- **（失败 / 无记录）**：当前页面没有打到本项目的 Worker。本地请使用 **`npm run dev`**（Cloudflare Vite 插件会同时起前端与 Worker）；不要只用纯静态预览访问，否则没有 `/api/*`。
|
||
- **503 + `admin_token_not_configured`**：Worker 上 **没有可用的 `ADMIN_TOKEN`**。本地检查项目根目录 **`.dev.vars`** 并重启 dev；已部署环境必须执行 **`npx wrangler secret put ADMIN_TOKEN`**（`.dev.vars` **不会**随 `deploy` 传到线上）。
|
||
- **401**：请求里的 token 与 `ADMIN_TOKEN` **不一致**（含多余空格时，服务端与 URL 两侧已做 trim，但仍需内容一致）。
|
||
- **200**：校验已通过；若仍停在说明页，请看 **Application → Session Storage** 是否写入 `modelping_admin_token`，并尝试硬性刷新或排除扩展拦截。
|
||
|
||
2. 未登录页面上方如显示 **红色提示条**，即为本次 URL 校验失败原因（此前固定文案下不会显示，容易造成「后台没做」的误解）。
|
||
|
||
## 默认内网口令（仅示例）
|
||
|
||
本地示例默认 Admin Token 为 `shumengya520`。**线上环境请在 Dashboard 或 `wrangler secret put` 修改为强随机字符串。**
|
||
|
||
## API 摘要
|
||
|
||
| 方法 | 路径 | 认证 | 说明 |
|
||
|------|-----|------|------|
|
||
| GET | `/api/monitors` | 无 | 公开列表与聚合统计 |
|
||
| GET | `/api/monitors/:id` | 无 | 单条详情 |
|
||
| GET | `/api/admin/ping` | `Authorization: Bearer <ADMIN_TOKEN>` | 校验 Token |
|
||
| GET/POST/PUT/DELETE | `/api/admin/monitors`… | Bearer | 增删改监控；`POST .../:id/run` 立即探测一次 |
|
||
|
||
## 备注
|
||
|
||
- Cron 表达式为每分钟 `* * * * *`，在 Worker 内根据 `next_run_at` 与 `interval_minutes` 决定是否真正发起外呼。
|
||
- 探测使用 `stream: true`，以**首个内容增量**到达时间作为首字延迟。
|
||
- Worker 脚本体积请保持精简；前端由 CDN 提供，整体符合常见 Workers 体积限制实践。
|
||
|
||
## 许可证
|
||
|
||
MIT（若需其他许可证请自行替换。）
|