PHLI API 接口插件

PHLI API 接口插件为 PHLI（原 Prain 清雨）博客系统提供完整的 RESTful API，覆盖全部后台管理功能，可用于开发移动端 APP、小程序、第三方客户端等。

快速开始

安装

1. 将 api 文件夹放入 ext/ 目录
2. 在 PHLI 后台 → 扩展管理 中安装「API接口」插件
3. 安装后系统自动生成 32 位随机 API Key
4. 在后台 → API设置 中查看和管理 API Key

URL 格式

API 地址取决于是否开启伪静态：

可通过 api/check 接口返回的 rewrite 字段判断伪静态状态。

认证方式

所有 API 请求（api/check 除外）均需携带 API Key，支持两种方式：

方式一：请求头（推荐）

X-API-Key: your_api_key_here

方式二：Bearer Token

Authorization: Bearer your_api_key_here

响应格式

所有接口统一返回 JSON 格式：

成功响应

{
  "error": false,
  "code": 0,
  "message": "操作成功",
  "data": { ... }
}

错误响应

{
  "error": true,
  "code": 401,
  "message": "API Key无效",
  "data": []
}

常见错误码

接口总览

1. 系统模块

1.1 连接检测 无需认证

用于检测 API 是否可用及获取站点基本信息。

{
  "error": false,
  "code": 0,
  "message": "操作成功",
  "data": {
    "title": "我的博客",
    "name": "PHLI",
    "intro": "一个简单的博客",
    "avatar": "https://blog.com/db/upload/202601/01_120000_123.jpg",
    "version": "1.3.2",
    "url": "https://blog.com",
    "rewrite": true
  }
}

1.2 获取系统信息

响应 data 字段

1.3 检查系统更新

1.4 执行系统更新

无参数，直接调用即执行更新。

1.5 数据库版本更新

无参数，同步数据库结构到最新版本。

2. 文章模块

2.1 文章列表

查询参数

响应 data 字段

2.2 文章详情

路径参数

响应包含文章列表所有字段，额外增加：

2.3 创建文章

请求参数（application/x-www-form-urlencoded）

{
  "error": false,
  "code": 0,
  "message": "创建成功",
  "data": { "id": "my-first-post" }
}

2.4 更新文章

2.5 删除文章

批量删除示例：id[0]=first-post&id[1]=second-post

2.6 移动文章

3. 分类模块

3.1 分类列表

3.2 添加分类

3.3 编辑分类

3.4 批量保存分类

用于后台管理页面的全量保存模式，参数为数组格式。

3.5 删除分类

删除分类后，该分类下的文章 cid 会被置空。

4. 标签模块

4.1 标签列表

5. 评论模块

5.1 文章评论列表

5.2 全部评论列表

聚合所有文章的评论，按时间倒序排列。

额外字段：

5.3 删除评论

6. 友情链接模块

6.1 链接列表

6.2 添加链接

6.3 编辑链接

6.4 批量保存链接

参数为数组格式，用于后台全量保存。

6.5 删除链接

7. 导航菜单模块

7.1 导航列表

7.2 添加导航

7.3 编辑导航

7.4 批量保存导航

参数格式同链接批量保存。

7.5 删除导航

8. 设置模块

8.1 获取设置

8.2 保存设置

只需传递需要修改的字段，未传递的字段保持原值。

9. 文件上传模块

9.1 上传文件

请求格式：multipart/form-data

允许的文件类型：jpg, jpeg, png, gif, bmp, webp, mp4, mp3, pdf, doc, docx, xls, xlsx, zip, rar, txt, md

请求示例（JavaScript）

const formData = new FormData();
formData.append('file', fileInput.files[0]);

fetch('https://blog.com/api/upload/upload', {
  method: 'POST',
  headers: { 'X-API-Key': 'your_api_key' },
  body: formData
})

10. 主题模块

10.1 主题列表

10.2 启用主题

10.3 删除主题

10.4 获取主题设置页

10.5 保存主题设置

11. 扩展模块

11.1 扩展列表

11.2 安装扩展

11.3 卸载扩展

11.4 删除扩展

11.5 获取扩展设置页

12. 日志模块

12.1 日志统计

12.2 获取日志开关

12.3 日志列表

12.4 清空日志

无参数。

12.5 修改日志开关

API 权限管理（api-auth 插件）

概述

api-auth 插件为 API 提供多 Key 权限分配功能。安装后，除原始 API Key（超级管理员）外，可创建多个子 Key，每个 Key 拥有独立的权限配置。

认证优先级

1. 原始 API Key → 超级管理员，拥有全部权限
2. api-auth 子 Key → 根据权限配置校验
3. 无匹配 Key → 401 错误

权限格式

权限模块列表

权限示例

{
  "permissions": [
    "article:read",
    "article:write",
    "category:read",
    "tag:read"
  ]
}

此配置允许查看和编辑文章、查看分类和标签，但不能删除文章或修改其他模块。

开发指南

伪静态自适应

开发客户端时，应先调用 api/check 接口获取 rewrite 字段，据此构建后续请求的 URL：

// 检测伪静态并构建基础URL
const checkRes = await fetch(blogUrl + '/?api/check');
const checkData = await checkRes.json();
const rewrite = checkData.data.rewrite;
const baseUrl = rewrite
  ? blogUrl + '/api/'
  : blogUrl + '/?api/';

// 后续请求
fetch(baseUrl + 'article/list/1', {
  headers: { 'X-API-Key': apiKey }
});

图片路径处理

• 读取：API 返回的图片路径（img、avatar、内容中的 src）均为完整 URL
• 写入：提交内容时，完整 URL 会自动转换为相对路径存储
• 上传：上传接口返回的 url 为完整 URL，path 为相对路径

内容编辑注意事项

• 文章 content 是解析后的 HTML，rawContent 是原始内容
• 编辑文章时应使用 rawContent 作为编辑器初始内容
• 保存时提交 content 字段即可

错误处理建议

async function apiRequest(url, options = {}) {
  const res = await fetch(url, {
    ...options,
    headers: {
      'X-API-Key': apiKey,
      'Content-Type': 'application/x-www-form-urlencoded',
      ...options.headers
    }
  });

  const data = await res.json();

  if (data.error) {
    switch (data.code) {
      case 401: // API Key 无效，跳转配置页
        break;
      case 403: // 权限不足
        break;
      case 404: // 接口不存在
        break;
      default:  // 其他错误
        break;
    }
    throw new Error(data.message);
  }

  return data;
}

CORS 支持

API 已内置 CORS 支持，响应头包含：

Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: X-API-Key, Authorization, Content-Type
Access-Control-Allow-Methods: GET, POST, OPTIONS

OPTIONS 预检请求会自动返回 200，无需额外处理。

常见问题

Q：API Key 在哪里获取？

A：在 PHLI 后台 → 扩展管理 → API接口 → 设置 中查看，支持重新生成。

Q：如何判断伪静态是否开启？

A：调用 GET /api/check 接口，返回的 rewrite 字段为 true 表示开启。

Q：文章的 id 是什么？

A：文章 ID 是 URL 名称（如 my-first-post），不是数字自增ID。创建时可自定义，留空则自动生成 T + 时间戳格式。

Q：分类的 id 是什么？

A：分类 ID 是分类别称（如 php、tech），是字符串类型，不是数字。

Q：上传文件时为什么返回 400？

A：请确保使用 multipart/form-data 格式提交，且不要手动设置 Content-Type 请求头。文件字段名必须为 file。

Q：保存设置后浏览量变成 0 了？

A：views 字段仅在明确传值时更新。保存设置时，如果不需修改浏览量，请不要传递 views 参数。

Q：如何实现多用户权限？

A：安装 api-auth 扩展插件，在后台创建多个 API Key 并分配不同权限。