加油站、充电站数据 API 一站式接入 API 接口聚合分发平台

---

# 牡丹 API 平台 · 功能详细介绍

## 一、系统整体定位

这是一个 API 聚合分发平台，核心业务模式为：开发者注册账号，由管理员在后台为其充值积分，开发者创建 API Key 后，第三方调用方凭 Key 和签名调用平台上架的 API 产品，每次成功调用自动扣除相应积分。平台本身不实时转发上游数据，所有产品数据都预先落地到本地数据库，接口只查本地库，与上游系统完全解耦。

整个项目由三套独立应用组成：后端服务（提供全部接口）、管理后台（运营人员使用）、开发者控制台（含公开产品市场和文档站）。

## 二、开发者控制台功能（console 端）

### 2.1 公开产品市场（无需登录）

- 首页为产品市场，展示所有上架产品卡片，每张卡片显示产品名称、描述、单次调用价格、数据量，点击卡片进入产品详情页。

- 顶部提供"登录"和"注册"入口，已登录状态显示"进入控制台"按钮。

### 2.2 产品详情文档页（无需登录）

- 展示产品名称、编码、描述、单价、数据量，提供"开通调用"入口。

- 每个接口独立区块展示：接口方法、路径、名称、功能描述、请求参数表（参数名/类型/必填/说明）、响应示例。

- 每个接口提供 curl、Javascri-pt、Python 三种调用示例，支持一键复制。

- 页面底部有签名算法说明（HMAC-SHA256 签名串格式、时间戳 5 分钟有效、nonce 防重放），支持一键下载 Markdown 格式的完整接口文档。

### 2.3 登录与注册

- 登录使用手机号加密码；注册支持手机号、昵称（选填）、密码（至少 6 位），注册成功后自动登录。

- 市场页可带参数直达注册页。

### 2.4 控制台总览（需登录）

- 展示三个统计卡片：积分余额（带"创建 API Key"快捷按钮）、累计调用次数及消耗积分、API Key 数量。

- 下方展示最近 10 条调用记录（产品、状态、扣费、耗时、时间）。

### 2.5 API Key 管理（需登录）

- 列表展示每个 Key 的名称、API Key、QPS 上限、累计调用次数、累计消耗积分、状态（开关切换启用/停用）、最1后使用时间。

- 支持创建 Key：填写 Key 名称和 QPS 上限（1 到 1000），创建成功后弹出 API Key 与 API Secret 一对密钥，Secret 仅1此一次可见，关闭弹窗后不再显示，有明确警示提醒保存。

- 支持一键复制 API Key，支持删除 Key（二次确认）。

### 2.6 调用记录（需登录）

- 分页展示自己的调用日志：产品、状态（成功/失败类型标签）、扣费、耗时、调用 IP、时间。

## 三、管理后台功能（admin 端）

### 3.1 管理员登录

- 账号密码登录，密码校验失败或账号被禁用均无法登录，登录成功保存 Token 进入系统。

### 3.2 仪表盘

- 六个统计卡片：今日调用量、今日消耗积分、用户总数、今日新增用户、平台总积分、启用 Key 数。

- 今日各产品调用表格：按产品编码展示调用次数与消耗积分。

### 3.3 用户管理

- 列表展示用户 ID、手机号、昵称、积分余额、Key 数、调用次数、注册时间、状态（正常/禁用）。

- 支持按手机号或昵称关键字搜索、分页。

- 充值积分：弹窗展示用户当前余额，输入充值数量（1 到 100 万）和备注，确认后原子增加余额，同时写充值记录表和积分流水表，前端提示充值后最1新余额。

- 启用/禁用用户（二次确认）。

- 查看单用户调用记录弹窗（最近 20 条：产品、状态、扣费、耗时、时间）。

### 3.4 产品管理

- 列表展示产品编码、名称、单价（行内数字输入框直接改价，改动即保存）、描述、数据源类型、数据量、最1后同步时间。

- 上架/下架开关，切换即保存。

- 编辑接口文档：弹窗中直接编辑 Markdown 格式文档并保存，保存后写入数据库。

### 3.5 调用日志

- 全局日志分页查询，可按状态筛选（成功、无效 Key、余额不足、限流、产品异常等）和按手机号/请求 ID 搜索。

- 展示手机号、昵称、产品、状态、扣费、耗时、IP、请求 ID、时间。

### 3.6 Key 管理

- 全局查看所有用户的 Key 列表（所属用户手机号、昵称、Key 名称、API Key、QPS、状态、最1后使用、创建时间），只读查看，不做停用操作。

## 四、后端平台功能（server 端）

### 4.1 用户体系

- 注册：手机号格式校验（大陆手机号规则）、密码至少 6 位、手机号唯2一性检查、密码 bcrypt 加密存储、昵称缺省自动生成。

- 登录：校验手机号和密码、账号禁用拦截、签发 7 天有效期的用户 Token。

- 个人中心：返回资料、积分余额、会员等级（预留字段）、累计调用次数、累计消耗积分、启用 Key 数。

- 修改资料：昵称、头像。

- 积分流水查询：分页返回充值、扣费、退款、调整等所有余额变动记录（类型、金额、变动后余额、备注、时间）。

### 4.2 API Key 管理

- 创建：生成一对 API Key（公钥）与 API Secret（私钥），支持自定义名称、QPS 上限（最1大 1000）、IP 白名单（逗号分隔）。

- 列表：返回每个 Key 的调用统计（累计次数、累计消耗积分）和最1后使用时间。

- 更新：名称、QPS、IP 白名单、启停状态。

- 删除：物理删除，仅能操作自己的 Key。

### 4.3 开放接口网关（平台核心）

所有对外接口统一走网关，网关按固定顺序完成 10 步处理，业务产品只负责"查什么表、返回什么"：

1. Key 鉴权：校验请求头中的 X-Api-Key，不存在则返回 401；Key 被停用返回 403。

2. IP 白名单：Key 配置了白名单时，请求 IP 不在名单内返回 403。

3. 时间戳校验：X-Timestamp 与服务器时间差超过 5 分钟视为过期，返回 401。

4. Nonce 防重放：同一 Key 下相同 nonce 5 分钟内不可重复使用，防止重放攻击。

5. 签名校验：用 Key 的 Secret 对签名串做 HMAC-SHA256 计算并常数时间比对，失败返回 401。签名串格式为 请求方法、路径、时间戳、nonce、请求体哈希 五段换行拼接。

6. QPS 限流：按 Key 做 1 秒滑动窗口计数，超过 Key 的 QPS 上限返回 429。

7. 产品与余额预检：产品必须存在且上架，否则 404；用户必须存在且未被禁用，否则 403；余额低于产品单次价格返回 402。

8. 执行产品逻辑：调用对应产品的业务函数查询本地库。

9. 成功原子扣费：用条件更新（余额足够才扣）保证不超扣，成功后写积分流水（扣费记录，含变动后余额）并更新 Key 最1后使用时间。

10. 写调用日志：记录用户、Key、产品、请求 ID、扣费、状态、耗时、IP。

计费规则：仅成功调用扣费，鉴权失败、余额不足、限流、参数错误、产品异常均不扣费。每次请求都会生成唯2一请求 ID，方便排查。

### 4.4 开放产品接口（当前 2 个产品，各 2 积分/次）

加油站产品（gas-station）：

- 附近加油站：传入经纬度（可选半径默认 10 公里最1大 50、条数默认 20 最1大 50），按距离升序返回周边油站，含距离计算（公里数）；参数非法返回 400。

- 油站详情：传油站 ID，返回油站完整信息（名称、品牌、地址、电话、营业时间、优惠、省市县、坐标），并附带该站油价列表和油枪列表。

- 油站搜索：传关键字（匹配名称/地址/品牌）和可选城市过滤，分页返回结果及总数。

充电站产品（charging-station）：

- 附近充电站：传经纬度，按距离返回周边充电站，含快充桩数、慢充桩数。

- 充电站详情：传充电站 ID，返回完整信息。

所有查询均只查本地库，附近查询通过经纬度范围剪枝加距离公式排序实现，并在经纬度上建了复合索引。

### 4.5 公共接口（供产品市场与文档站）

- 上架产品列表：无需登录返回产品编码、名称、单价、描述、数据量、最1后同步时间。

- 产品详情：无需登录返回产品完整信息和后台维护的 Markdown 文档。

### 4.6 管理接口

- 管理员登录、仪表盘统计（今日调用/消耗/用户/新增用户/平台总积分/启用 Key 数/分产品统计）。

- 用户列表、搜索、启用禁用、充值（原子更新余额并联动写充值单和流水）、单用户调用记录。

- 产品列表、产品更新（名称、单价、描述、上下架、文档、图标、排序）。

- 全部调用日志查询（状态/产品/关键字筛选）、全部 Key 列表。

### 4.7 启动初始化

- 启动时先检测数据库连通，连不上直接退出并给出处理指引。

- 首次启动自动创建默认管理员账号（admin），无需手工建号。

- 启动时打印油站/充电站数据量，若数据为空提示运行数据导入命令。

## 五、数据工具功能（tools 与 server/data）

### 5.1 源库导出脚本

在现有项目数据库所在机器上运行，从源库导出油站、充电站、油价、油枪四类数据为 JSON 文件，导出时已做字段筛选（如油站仅导出有坐标的），油价和油枪通过联表取平台油站 ID。

### 5.2 数据导入器

读取导出的 JSON 文件导入本地库，按业务唯2一键做幂等覆盖（重复导入安全），500 条一批批量写入提升速度。导入完成后自动更新产品的同步状态、数据量、最1后同步时间，并写入数据同步日志表。

### 5.3 充电站拉取脚本

针对快电 API 只支持按位置查询、无全量接口的限制，按全国城市网格加 30 公里半径加分页方式扫描，按站 ID 去重，输出 JSON 供导入。支持单城市测试模式。

### 5.4 网关端到端自测脚本

自动执行完整流程：登录（失败则自动注册）→ 充值积分 → 创建 Key → 用签名调用附近加油站接口 → 验证余额扣减、调用日志、积分流水，用于回归验证网关全链路。

## 六、数据库功能（13 张表）

业务表 8 张：用户表、API Key 表、产品表（含单价、数据源类型、同步状态、文档）、调用日志表、积分流水表、充值记录表、管理员表、数据同步日志表。

产品数据表 4 张：加油站表（含油价 JSON 冗余字段）、油价明细表、油枪明细表、充电站表。产品数据表按产品独立前缀隔离，新增产品只需新建对应数据表。

种子数据：建库时自动插入加油站、充电站两个产品的初始记录。

## 七、当前实际数据规模与运行情况

- 加油站 18283 条、充电站 19461 条、油价 43625 条，两个产品同步状态均为正常。

- 附近查询实测 2 到 9 毫秒返回。

- 端到端链路已验证：注册登录、充值、建 Key、签名调用、成功扣费、日志与流水落库全流程可用。

- 管理后台地址 39003（默认账号 admin）、开发者控制台 39004、后端 39002。

## 八、已规划但尚未实现的内容

- 供应链商品 API：需用户提供别的项目商品表结构，建表后写导入器即可接入。

- Bingo18 实时开奖 API：需用户提供抓取逻辑，实现定时抓取器存库。

- 文档站域名占位符替换：示例代码中的域名目前是占位文本，正式上线需替换为实际域名。

---

## 一、平台整体定位类（适合开源仓库、项目主页推广）

1. 牡丹 API 平台：开箱即用的 API 聚合分发与积分计费系统源码

2. API 接口聚合分发平台，注册、后台充值、按次扣费一站式闭环

3. 独立部署的 API 开放平台源码，自带运营后台与开发者控制台

4. 可私有化部署的 API 售卖系统：建 Key、定价、计费、日志全自动

5. API 平台从零到上线完整实现，注册到调用全流程可跑通

## 二、数据产品卖点类（适合产品市场、数据服务推广）

6. 全国加油站数据查询 API，1.8 万油站周边搜索接口直接调用

7. 充电站数据接口上线：1.9 万充电站位置与快慢充数量随时查

8. 加油站、充电站数据 API 一站式接入，按次调用即买即用

9. 油站附近查询 API 实测毫秒级返回，覆盖全国 1.8 万站点

10. 油站详情接口一次返回油价与油枪信息，2 积分即可调用

## 三、开发者接入类（适合开发者社区、技术文档推广）

11. 三分钟接入指南：创建 API Key 并完成签名认证调用

12. 接口调用示例全覆盖：curl、Javascri-pt、Python 一键复制即用

13. 开发者友好的 API 文档站：示例可复制、Markdown 文档可下载

14. API 接入不再踩坑：时间戳、随机串、签名校验规则一文看懂

15. 一个 Key 管多个接口：QPS 上限与 IP 白名单随心配置

## 四、安全与计费机制类（适合技术博客、架构分享推广）

16. 接口调用如何防重放防篡改？API 签名鉴权实战方案详解

17. API 网关的限流、白名单、原子扣费是怎么实现的

18. 按次计费的 API 平台如何保证不超扣？余额校验设计思路

19. 仅成功才扣费：接口失败、余额不足、限流全部免费

20. 每次调用都有日志有流水，积分变动全程可追溯

## 五、运营管理类（适合商业运营方、SaaS 推广）

21. 运营 API 平台必备后台：用户充值、禁用、调用记录全掌控

22. API 产品运营后台：调价、上下架、文档维护一个页面搞定

23. 数据同步状态后台一目了然，产品数据量实时可见

24. 今日调用量、消耗积分、新增用户，仪表盘一屏掌握

25. 平台积分总账清晰，每笔充值扣费都有据可查

## 六、架构扩展类（适合技术选型、长期维护推广）

26. 可插拔的 API 产品架构：新增一个数据产品不改平台主流程

27. 数据落地本地库的 API 平台：查询更快、与上游完全解耦

28. 接口只查本地库：不依赖上游实时转发，服务稳定性更高

29. 一套系统两种数据模式：批量导入与定时抓取均可接入

30. API 平台的会员、在线充值已预留扩展，二次开发成本低

---

补充说明：上述标题中的"1.8 万油站""1.9 万充电站""2 积分/次""毫秒级返回"均来自代码与运行数据（加油站表 18283 条、充电站表 19461 条、产品单价 2 积分、附近查询实测 2-9 毫秒），作为真实数字锚点提升搜索与点击效果。若需要针对某个具体平台（如 GitHub 仓库名、站点 title 标签、文章 H1）做进一步裁剪或组合，告诉我目标渠道即可。

定制看需求，一般几小时内完成，也不贵。

【属性】

• 框架: vue
• 语言: 其他
• 数据库: Mysql
• 规格: 整站源码
• 授权: 免授权
• 源文件: 完全开源（含全部源文件）
• 大小: 1 MB
• 移动端: Wap、App、小程序、自适应、公众服务号
• 安装服务: 免费【要求说明】
• 主机类型: 独立主机（服务器、VPS、VM）
• 伪静态: 无需
• 操作系统: Linux
• 安装方式: 提供管理权限
• web服务: nginx