# FEERAPI

**Repository Path**: xunjinlu/feer-api

## Basic Information

- **Project Name**: FEERAPI
- **Description**: 一个小白写的，api官网程序，功能不多但是可以正常使用，以后的版本就随性开源喽,当前更新7.8.0版本,
- **Primary Language**: PHP
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-04-09
- **Last Updated**: 2026-07-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: API, PHP, MySQL

## README

<div align="center">
  <h1>FeerApi（PHP + MySQL）免费 API 接口管理/发布系统</h1>
</div>

> 当前版本：v7.8.0（以 `config/config.php` 为准）
> 运行模式：MySQL（`core/JsonDB.php` 为兼容层，底层仅使用 MySQL）

FeerApi 是一个面向开发者的 API 接口聚合与发布系统，包含前台展示、在线测试、接口中转代理、用户投稿与审核、后台管理、调用统计与实时日志等功能，并提供 **Web 一键安装向导**，适合快速部署到服务器并开源发布。

---

## 演示地址

- **线上演示**：[https://api.xunjinlu.fun](https://api.xunjinlu.fun)
## 主要功能

### 前台（官网）
- **API 列表/搜索/分类**：`index.php`、`apis.php`
  - 首页底部「在线调试」选择接口弹窗中，列表项展示与卡片相同的 **免费 / 积分·次 / KEY / 维护中** 标签
- **API 详情页**：`api-detail.php`
  - 请求参数展示（JSON 美化）
  - 响应示例展示（自动 JSON 格式化）
  - 在线测试（通过 `api-proxy.php` 规避 CORS）
  - **需密钥接口**：已登录且存在可用密钥时，在线测试区可自动随机填入一条密钥并提示；无密钥或未登录时给出简短说明（样式随明暗主题变量适配）
  - 接口反馈功能（支持填写联系方式）
- **文章/页面**：`articles.php`、`article.php`、`about.php`、`pages.php`
  - 文章评论支持配图上传（后台可配置图床；默认 521.im）
  - 评论内图片点击灯箱预览，关闭后保持原滚动位置（无页顶滑回）
- **友链**：`links.php`、`apply-link.php`
- **首页合作伙伴**：首页底部新增响应式合作伙伴 Logo 网格，支持后台启用/关闭与可选跳转
- **首页公告横幅**：滚动公告条 + 自动弹窗；横幅不含图片；弹窗正文由 JS 从 `application/json` 注入（减少爬虫把长公告当摘要；`meta`/`og:description` 仍为后台站点描述）；首页 DOM 先 `main` 后公告块、CSS `order` 保持原视觉顺序；弹窗内 Markdown 由 `core/Parsedown.php` 解析（**围栏代码按行闭合**、可选 **` ```html` / ` ```h5` 白名单 HTML**、**输出消毒** 避免异常内容破坏整页；**`![](url)` 空 alt**、表格、引用 `>`、`.mp4/.webm` 视频等）；首页额外加载 `markdown-content.css`；自动弹窗 **「不再提示」** / **「我知道了」** 行为同前；横幅点击查看仅 **「我知道了」**
- **赞助我们**：`donate.php`（赞助榜单置顶展示，收款码区域位于下方）

### 用户后台（开发者）
- **注册/登录**：`user/register.php`、`user/login.php`
  - 滑块人机验证 + IP 错误限流（登录/注册/找回密码分场景独立计数）
  - 可选「注册邮箱域名白名单」（后台配置，留空不限制）
  - 未完成滑块时点击登录会提示「请先完成滑块验证」（按钮保持可点击，非 disabled）
  - 前端 MD5 加密传输：登录 `MD5(MD5(明文)+nonce)` 防重放；注册/重置 `MD5(明文)`
  - 邮箱验证码发信限流（防轰炸）：单 IP/单邮箱多维度配额 + 超限锁定
  - 用户密码存储为 MD5，登录成功后自动将历史 BCrypt 哈希升级为 MD5
  - 登录成功自动回跳来源页（`?redirect=`）；已登录访问登录页自动跳转控制台
- **用户权限分级**：注册时可选择"普通用户 / 开发者"
  - 普通用户：更聚焦密钥、积分与调用消费，不显示开发者投稿管理视图
  - 开发者：保留原有投稿与接口管理全功能
- **第三方登录（可选）**：QQ / Gitee（见后台设置页）
  - OAuth 发起改为 POST + 一次性 Session 令牌，client_id 仅服务端拼接，前端不暴露
- **控制台/概览**：`user/index.php`（统计图表 + 实时调用日志；自动轮询刷新，无手动刷新按钮；列表滚动至底部时提示「仅展示最近的 100 条记录」）
- **投稿 API / 编辑 API**：`user/api-add.php`、`user/api-edit.php`
  - 投稿后默认进入 **待审核**（`review_status=0`）
  - 二次编辑会触发重新审核
  - API 详细文档使用内置简易 Markdown 工具栏（GFM 预览由 marked 统一配置）

### 用户后台（普通用户）
- **密钥管理**：`user/api-keys.php`
  - 支持生成多个 API 密钥（最多 5 个）
  - 密钥明文展示，一键复制
  - 查看调用次数和最后调用时间
  - 密钥禁用/重置功能
- **积分充值**：`user/points.php`
  - 支持套餐充值和自定义积分充值
  - 码支付/易支付多网关支持
  - 支付二维码弹窗展示，扫码支付
  - 取消订单后自动清除支付横幅与 URL 参数（仅更新本平台订单状态）
  - 充值成功后自动更新积分余额
  - 支持多种支付方式（支付宝/微信/QQ）
  - 用户可取消待支付订单（仅更新本平台数据库状态为「已取消」，不向支付平台发起撤销）
- **积分记录**：`user/points-logs.php`
  - 查看积分变动明细（充值/调用扣费/签到奖励/分成收入）
  - 显示关联订单号，点击可复制
  - 实时展示积分余额
  - 接口调用类型显示 API 名称
- **每日签到**：`user/checkin.php`
  - 每日签到随机赠送积分
  - 连续签到奖励机制
  - 无刷新签到体验
- **接口反馈**：`user/feedbacks.php`
  - 查看自己提交的接口收到的用户反馈
  - 反馈处理状态跟踪
  - 管理员回复邮件通知

### 管理员后台
- **安全登录**：`admin/login.php`
  - 滑块人机验证（Session 令牌 + 客户端拖动交互）
  - 未完成滑块时点击登录会提示「请先完成滑块验证」
  - 错误次数限制：连续 5 次密码错误 → 锁定 IP 15 分钟
  - 锁定期间前端实时倒计时提示
  - 首次安装设置密码时无需验证码和限流
- **控制台**：`admin/index.php`（趋势图 + 实时调用日志）
  - 多维度用户统计图表
  - 实时调用日志筛选；列表滚动至底部时提示「仅展示最近的 100 条记录」（与接口返回条数上限一致）
  - 统计卡片显示（API总数/活跃API/分类数量/总调用次数/开发者/普通用户）
- **API 管理**：`admin/apis.php`
  - 审核与运行状态分离（`review_status` 与 `runtime_status`）
  - 批量启用/禁用/维护（已避免与审核状态冲突）
  - 支持配置访问鉴权三档（`require_api_key`：**开放访问 / 密钥必传 / 密钥可选**；积分扣费仍强制密钥必传）
  - 请求参数类型支持内置扩展项 + 自定义类型；表格内 combobox 选择器（`param-type-picker`）
  - 支持配置每分钟请求上限（`qps_limit`，滑动 60 秒窗口）
  - 列表卡片/表格展示限流标签（与用户后台一致：「N 次/分」或「不限」）
  - 支持配置积分扣费（`points_cost`）
  - API 详细文档编辑为简易 Markdown 工具栏
- **待审核/已拒绝**：`admin/pending-apis.php`、`admin/rejected-apis.php`
- **调用统计**：`admin/stats.php`
  - 多维度用户统计（全部用户/密钥用户/积分用户/游客用户）
  - 图表筛选功能，灵活查看不同类型数据
  - 统计数据接口性能优化（文件缓存 + HTTP 缓存头）
- **调用日志**：`admin/api-call-logs.php`
  - 详细调用记录（API/请求方法/用户/密钥/IP/**来源域**/时间）
  - 无搜索时分页采用 `MAX(id)` 估算 + `id` 上限，减轻大表 COUNT/OFFSET 压力
  - 支持按用户类型筛选（全部/密钥/积分/游客）
  - 综合搜索框（支持搜索 API 名称/用户名/密钥/URL/IP/来源域名等）
- **积分变动**：`admin/points-logs.php`
  - 全站用户积分流水记录
  - 变动类型标签（充值/接口调用/签到/接口分成等）
  - 支持搜索和筛选功能
- **订单管理**：`admin/orders.php`
  - 充值订单查看与管理
  - 订单状态跟踪（待支付/已支付/已取消/已退款）
  - 中文标签化显示
  - 支持分页和搜索功能
- **系统设置**：`admin/settings.php`
  - 中转代理基础路径 `api_proxy_base_path`
  - 站点标题/Logo/域名等基础配置
  - **调用日志 IP 归属地**：完整 GET 链接（含 `{ip}` 与 key），可选 JSON 点号路径；URL 自动规范化 `&amp;` → `&`
  - **评论配图图床**：可配置 POST 上传接口（默认 521；支持自定义 URL/参数名/Token/JSON 路径）；密钥明文展示
  - **AI 文档**：OpenAI Chat Completions 兼容（API URL / 模型 / 密钥）
  - 支付网关配置（码支付/易支付）
  - **用户注册**：允许注册的邮箱域名白名单（逗号/换行分隔，留空不限制）
  - 积分比例与签到配置
  - 首页合作伙伴/公告开关
  - 赞助收款码配置
- **合作伙伴管理**：`admin/partners.php`
  - 支持合作伙伴名称、Logo、跳转链接、显示状态与排序管理
  - 电脑端侧边栏与手机端"更多"页均可直达
- **公告管理**：`admin/announcements.php`
  - 支持公告发布、编辑、置顶、启用/关闭、**首页自动弹窗**（`fa_announcements.popup_enabled`）；列表与卡片上提供 **开弹窗 / 关弹窗** 快捷按钮（无需进编辑页）
  - 公告内容编辑为简易 Markdown 工具栏（弹窗内支持图片语法）
  - 支持直接置顶/取消置顶快捷操作
  - 多置顶冲突处理（默认展示最新发布的置顶公告）
- **赞助管理**：`admin/sponsors.php`
  - 管理员手动登记赞助者头像/名称/链接/赞助内容
  - 支持 QQ 自动头像 与自定义头像链接
  - 支持多条"固定最后"并保持其余随机排序
  - 赞助榜单排序规则优化
- **用户管理**：`admin/users.php`
  - 用户类型切换（普通用户/开发者）
  - 管理员积分直充能力
  - 用户详情弹窗（包含调用记录/积分流水/密钥记录）
- **反馈/评论/文章/友链**：`admin/feedback.php`、`admin/comments.php`、`admin/articles.php`、`admin/links.php`
  - 文章管理卡片/表格可抽屉查看该文专属评论（参考订单详情抽屉）
- **友链审核**：`admin/pending-links.php`
  - 三态滑动切换：待审核 / 已拒绝 / 已通过（与用户后台图表模式切换同款 thumb 滑动效果）
  - 拒绝申请标记 status=2 保留记录，可恢复待审；已通过列表读取正式友链表
  - 桌面端表格 + 手机端卡片双布局
- **Markdown 编辑**：`admin/apis.php`、`admin/articles.php`、`admin/pages.php`、`admin/announcements.php`、`user/api-add.php`、`user/api-edit.php` 使用 `core/markdown-editor` 简易工具栏 + `assets/js/markdown-config.js`（marked GFM/表格等）；工具栏含「视频」（插入 `![](*.mp4|webm|ogg)` 模板），`markdown-editor.css` 随后台明暗主题白底/面板底自适应

### 代理与在线测试
- **API 中转代理**：`proxy.php`
  - 路由格式：`/{api_proxy_base_path}/{proxy_path}?参数...`
  - 上游可为公网或内网/本机（由你在后台配置的 `endpoint` 决定；生产环境请自行做好网络与权限隔离）
  - 传递真实客户端 IP（`X-Forwarded-For` / `X-Real-IP`，多段时取链首合法地址写入 `fa_api_call_logs`）
  - 记录调用统计（见下方统计）
  - 支持 API 密钥验证（密钥必传或积分接口时强制；**密钥可选**模式下不传 key 亦可调用，传 key 则识别用户）
  - 支持每分钟请求上限（滑动 60 秒窗口）
  - 支持积分扣费和分成
- **在线测试跨域代理**：`api-proxy.php`
  - 高仿浏览器请求头、自动解压（`CURLOPT_ENCODING`）
  - 来源检查、简单频控；测试目标可为内网/本机 URL（与 `proxy.php` 一致，由部署环境自担风险）
  - 向中转 `proxy.php` 传递规范化后的单一客户端 IP，保证首页/详情页在线测试写入调用日志的 IP 正确

### 调用统计
- 统计写入：`core/ApiCallLogger.php`
  - `fa_apis.call_count / last_call / heat` 更新
  - `fa_api_call_logs` 记录每次调用（含密钥上下文、请求来源等详细信息）
  - 积分扣费链路修复与小数支持
- 统计入口：
  - 后台统计页：`admin/stats.php`
  - 后台控制台趋势与实时日志：`admin/index.php`（依赖 Chart.js 与 `chart-line-tooltip.js` 多系列 tooltip 对齐；实时日志列表最多 100 条，滑到底部可见提示）
  - 用户后台统计：`user/index.php`（同上）

### 本地接口统计
- 目录：`api/`
- `api/index.php` 不再提供全站「按 IP / 小时」聚合限流；与 `record.php` 守卫一致的频控为各接口 **`qps_limit`（每分钟）**。
- 实现方式：通过手动引入 `record.php` 文件
- 使用方法：在本地接口文件中先调用 `api_record_guard_or_exit($apiId)` 进行校验，再调用 `api_record_send_async($apiId)` 进行统计
- 直接请求：可通过 `api/record.php?id=API_ID&key=API_KEY` 直接进行统计
- 示例代码：
  ```php
  // ==================== 统计功能 ====================
  $statsId = 14; // 对应后台配置的API ID
  require_once __DIR__ . '/../record.php';
  api_record_guard_or_exit($statsId);
  api_record_send_async($statsId);
  // ==================== 统计功能结束 ====================
  ```

---

## 目录结构（核心）

- `config/`
  - `config.php`：系统入口配置、安装检测、资产加载策略、站点配置、注入前端数据
  - `database.php`：**不再随仓库提供**，由安装向导自动生成
- `core/`
  - `MySQLDB.php`：MySQL 连接与基础 CRUD
  - `JsonDB.php`：兼容层（保留旧类名/方法名，底层仅用 MySQL）
  - `UserAuth.php`：用户认证/第三方登录/绑定/验证码发信
  - `UserAuthGuard.php`：用户端滑块验证 + 发信前校验
  - `Auth.php`：管理员认证
  - `LoginRateLimiter.php`：登录/IP 限流（管理员 + 用户多场景）
  - `EmailSendRateLimiter.php`：邮箱验证码发信限流
  - `OAuthHelper.php`：OAuth 发起 POST 安全
  - `ApiCallLogger.php`：调用统计统一写入（`proxy.php` 与 `api/record.php` 共用）
  - `Security.php`：CSRF、密码哈希（MD5/BCrypt 兼容）、传输层校验
  - `Mailer.php`：邮件发送（评论通知、反馈通知等）
  - `pay_notify.php`：支付回调处理
  - `core/markdown-editor/`：`loader.php` 与 `assets/js/markdown-editor.js`、`markdown-config.js`、`assets/css/markdown-content.css` 等
- `install/`
  - `index.php`：Web 安装向导（5 步）
  - `database.sql`：建表结构（安装时自动跳过 INSERT，保证空白库）
  - `install.lock`：安装锁（安装完成自动生成；重装需删除）
  - `upgrade_*.sql`：各版本增量升级脚本
- `admin/`：后台管理
- `user/`：用户后台
- `assets/`：前端静态资源与本地 vendor
- `docs/`：部署与伪静态文档
- `api/`：本地接口目录
  - `.user.ini`：自动统计钩子配置
  - `auto-stats-prepend.php`：自动统计前置脚本

---

## 环境要求

- PHP：建议 **7.4+ / 8.x**
- MySQL：建议 **5.7+ / 8.0**
- 扩展：PDO MySQL、cURL、mbstring、openssl（建议）
- Web 服务器：Nginx / Apache 均可

---

## 一键安装（推荐）

1. 上传源码到站点目录（建议网站根目录）。
2. 访问域名首页：
   - 若未安装（不存在 `install/install.lock`），会自动跳转到 `/install/`
3. 按向导完成 5 步：
   - 服务器检测
   - 数据库信息填写（默认 `localhost:3306`，其它为空）
   - 检测连接
   - 创建数据库表结构（同时生成 `config/database.php`）
   - 创建管理员账号
4. 完成后进入后台登录：`/admin/login.php`

更详细说明见：`docs/install-deploy.md`

---

## 版本号规则

版本号采用 `主.中.小`（SemVer）规范，升级规则见：`docs/versioning.md`

---

## 伪静态 / 重写

FeerApi 采用"通用伪静态 + API 代理路径分离"方案：

### Nginx（推荐）

精简 28 行配置（完整说明见 `nginx.conf.example`）：

```nginx
# ────── 通用伪静态（隐藏 .php 后缀，保留 PATH_INFO）──────
location / {
    try_files $uri $uri/ @php;
}
location @php {
    rewrite ^(/[^/]+)(/.*)?$ $1.php$2 last;
}

# ────── API 代理路径（默认 /apis/）──────
# 自定义代理路径时需同步修改此 location 路径
location /apis/ {
    try_files $uri $uri/ @api_proxy;
}
location @api_proxy {
    rewrite ^ /proxy.php last;
}

# ────── 执行 PHP ──────
location ~ \.php$ {
    fastcgi_pass   unix:/tmp/php-cgi.sock;
    fastcgi_index  index.php;
    fastcgi_param  SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include        fastcgi_params;
}
```

> **注意**：如果在后台自定义了 API 代理基础路径（默认 `apis`），需同步修改 nginx 中 `location /apis/` 的路径。

### Apache

仅需在网站根目录 `.htaccess` 中添加一行（Apache 2.2.16+ 原生支持，无需 mod_rewrite）：

```
FallbackResource /proxy.php
```

### 无伪静态备用

如果以上两种方案都不可用，系统还支持 PATH_INFO 直连模式：

```
https://你的域名/proxy.php/apis/接口路径?参数
```

---

## 中转代理使用方式

1. 后台设置 `API 中转代理基础路径`（默认 `apis`）
   - 该值对应 `settings.api_proxy_base_path`
2. 为某个 API 设置 `proxy_path`（如 `weather`）
3. 外部访问：
   - `https://你的域名/{api_proxy_base_path}/{proxy_path}?city=beijing`
   - 例如：`https://example.com/apis/weather?city=beijing`

`proxy.php` 会：
- 根据 `proxy_path` 查找真实 `endpoint`
- 透传请求方法/部分头/请求体
- 记录调用统计
- 处理 API 密钥验证
- 执行每分钟请求上限（滑动 60 秒窗口）
- 处理积分扣费和分成

---

## 审核状态与运行状态（重要）

系统将 **审核状态** 与 **运行状态** 分离：
- `review_status`：审核状态（1通过 / 0待审 / -1拒绝）
- `runtime_status`：运行状态（1启用 / 0禁用）
- `maintenance`：维护状态（1维护 / 0正常）

前台展示默认只显示：
- `review_status = 1` 且 `runtime_status = 1` 的接口（见 `core/JsonDB.php` 的 `getApis()`）

---

## 数据库说明

安装时会导入 `install/database.sql` 的表结构。

核心表（节选）：
- `fa_admins`：管理员
- `fa_users`：用户（含 `user_type` 区分普通/开发者、`points_balance` 积分余额等）
- `fa_apis`：API 主表（包含 `proxy_path`、审核/运行/维护状态、统计字段、`require_api_key`、`qps_limit`（每分钟上限）、`points_cost` 等）
- `fa_api_call_logs`：调用日志
- `fa_settings`：系统设置
- `fa_categories`：分类
- `fa_articles`：文章
- `fa_links`：友链
- `fa_feedback`：反馈
- `fa_user_api_keys`：用户 API 密钥
- `fa_points_orders`：积分充值订单
- `fa_user_points_logs`：积分流水
- `fa_announcements`：公告（含 `popup_enabled` 首页自动弹窗）
- `fa_partners`：合作伙伴
- `fa_sponsors`：赞助记录
- `fa_points_packages`：积分充值套餐

---

## 本地资源与加载策略

为提升访问速度与稳定性，系统对前端关键依赖采用：
- **本地优先**
- **远程兜底**
- **并行预热**

本地资源位于：`assets/vendor/`
说明见：`assets/vendor/README.md`

---

## 常见问题（FAQ）

### 1. 重新安装怎么做？
- 删除 `install/install.lock`，再访问 `/install/`

### 2. 为什么在线测试/代理会失败？
- 目标接口可能禁止跨域/校验 Referer/Origin（在线测试已尽量模拟浏览器头）
- 频控限制：`api-proxy.php` 默认 2 秒内限制同 IP 重复请求
- Nginx/PHP 对 `proxy.php` 的 `client_max_body_size` 过小会导致大文件 POST 失败

### 3. 为什么某些接口不在前台显示？
检查 `fa_apis`：
- `review_status` 是否为 1
- `runtime_status` 是否为 1
- `maintenance` 是否为 1（维护中会提示不可用）

### 4. 如何配置积分功能？
- 在后台 `系统设置` 中配置支付网关（码支付或易支付）
- 设置积分充值套餐和比例
- 在 API 管理中为接口配置 `points_cost`（积分扣费）
- 系统会自动处理积分扣费、分成和流水记录

### 5. 如何使用 API 密钥？
- 用户在 `user/api-keys.php` 中生成密钥
- 调用接口时在 URL 中添加 `key=你的密钥` 参数
- 或在请求头中添加 `X-API-Key: 你的密钥`

### 6. 如何配置支付功能？
- 在后台 `系统设置` 中选择支付网关（码支付或易支付）
- 填写相应的支付网关配置信息
- 码支付支持两种支付模式：跳转支付和直接扫码
- 易支付固定使用跳转支付模式

### 7. 如何管理积分充值套餐？
- 在后台 `系统设置` 中配置积分充值套餐
- 支持设置多个充值套餐，用户可选择适合的套餐进行充值
- 也支持自定义积分充值

---

## 安全说明（请务必阅读）

- 系统提供代理与在线测试能力，请务必在生产环境开启必要的访问控制策略。
- `proxy.php` / `api-proxy.php` 允许访问内网上游（便于本地联调）；公网暴露时请用 WAF、内网隔离或限制 `api-proxy.php` 访问来源，避免被滥用扫描内网。
- 建议使用 HTTPS 部署，以保证复制、登录等浏览器能力正常。
- 支付密钥等敏感信息请妥善保管，不要泄露。
- **管理员登录**：滑块验证 + IP 限流（`core/LoginRateLimiter.php`）；密码 MD5+Nonce 传输（`assets/js/pages/auth-password-transport.js`）。
- **用户登录/注册/找回密码**：滑块验证 + 分场景 IP 限流（`core/UserAuthGuard.php`）；密码 MD5 传输；邮箱验证码发信限流（`core/EmailSendRateLimiter.php`）。
- **OAuth 发起**：须 POST + 一次性令牌（`core/OAuthHelper.php`），避免 client_id 泄露与 GET 重放。
- 限流运行时文件位于 `config/.admin_login_fails.json`、`config/.login_fails_*.json`、`config/.email_send_rate.json`（已加入 `.gitignore`）。

---

## License / 开源协议

本项目为开源免费项目。首次进入安装向导会弹出"开源部署协议"，请在开源发布前根据你的需求补充仓库 LICENSE 文件与协议内容。