REST API 接口文档
GEO Wiki Pro REST API 完整接口参考，包含认证、文档管理、分类、标签、媒体上传等所有端点
# REST API 接口文档
> GEO Wiki Pro 后端 REST API 完整接口参考手册
---
## 概述
GEO Wiki Pro 提供基于 RESTful 风格的 HTTP API，所有接口均在 `/api/v1/` 路径下。公开接口无需认证，管理接口需要 JWT 认证和管理员角色。
### 基础信息
| 项目 | 说明 |
|------|------|
| 基础 URL | `https://your-domain.com/api/v1` |
| 认证方式 | JWT（httpOnly cookie） |
| CSRF 保护 | Double-submit cookie HMAC |
| 内容类型 | `application/json` |
| 限流策略 | 全局 300 次/分钟，认证接口 10 次/分钟 |
### 响应格式
**成功响应：**
```json
{
"success": true,
"data": { ... }
}
```
**分页响应：**
```json
{
"success": true,
"data": [ ... ],
"pagination": {
"page": 1,
"limit": 20,
"total": 42,
"totalPages": 3
}
}
```
**错误响应：**
```json
{
"success": false,
"message": "Not found"
}
```
---
## 公开接口
以下接口无需认证，任何人都可以访问。
### 获取文档列表
```
GET /api/v1/docs
```
**查询参数：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `lang` | string | 否 | 语言代码（zh/en/jp），默认 zh |
| `category` | string | 否 | 分类 slug 筛选 |
| `page` | number | 否 | 页码，默认 1 |
| `limit` | number | 否 | 每页条数，默认 20 |
**示例：**
```bash
curl "https://geowiki.pro/api/v1/docs?lang=en&category=can-motion&page=1&limit=10"
```
**响应：**
```json
{
"success": true,
"data": [
{
"slug": "can-bus-protocol",
"title": "CAN Bus Protocol",
"category": "can-motion",
"tags": ["can-bus", "protocol"],
"author": "admin",
"sort": 1,
"description": "CAN bus communication protocol overview",
"updated_at": "2026-05-20T10:30:00Z"
}
],
"pagination": {
"page": 1,
"limit": 10,
"total": 25,
"totalPages": 3
}
}
```
### 获取单篇文档
```
GET /api/v1/docs/:slug
```
**路径参数：**
| 参数 | 类型 | 说明 |
|------|------|------|
| `slug` | string | 文档 slug |
**查询参数：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `lang` | string | 否 | 语言代码，默认 zh |
**示例：**
```bash
curl "https://geowiki.pro/api/v1/docs/can-bus-protocol?lang=en"
```
**响应：**
```json
{
"success": true,
"data": {
"slug": "can-bus-protocol",
"title": "CAN Bus Protocol",
"category": "can-motion",
"tags": ["can-bus", "protocol"],
"author": "admin",
"sort": 1,
"description": "CAN bus communication protocol overview",
"content": "# CAN Bus Protocol\n\nThe Controller Area Network (CAN)...",
"updated_at": "2026-05-20T10:30:00Z"
}
}
```
::: note
对于非默认语言的请求，系统会执行级联合并：先读取中文文档作为基础，再用目标语言文档覆盖匹配的 slug。因此即使某文档只有中文版本，英文请求也能返回内容。
:::
### 文档搜索
```
GET /api/v1/docs/search
```
**查询参数：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `q` | string | 是 | 搜索关键词 |
| `lang` | string | 否 | 语言代码 |
| `category` | string | 否 | 分类 slug |
| `page` | number | 否 | 页码 |
| `limit` | number | 否 | 每页条数 |
**示例：**
```bash
curl "https://geowiki.pro/api/v1/docs/search?q=can+bus&lang=en&category=can-motion"
```
**响应：**
```json
{
"success": true,
"data": [
{
"slug": "can-bus-protocol",
"title": "CAN Bus Protocol",
"description": "CAN bus communication protocol overview",
"score": 0.95
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 5,
"totalPages": 1
}
}
```
### 获取分类列表
```
GET /api/v1/categories
```
**响应：**
```json
{
"success": true,
"data": [
{
"slug": "can-motion",
"name": "CAN 运动控制",
"name_en": "CAN Motion Control",
"description": "CAN 总线运动控制产品文档"
}
]
}
```
### 获取标签列表
```
GET /api/v1/tags
```
**响应：**
```json
{
"success": true,
"data": [
{
"slug": "can-bus",
"name": "CAN 总线",
"name_en": "CAN Bus"
}
]
}
```
### 获取站点配置
```
GET /api/v1/config
```
**响应：**
```json
{
"success": true,
"data": {
"hero_title": "GEO Wiki Pro",
"hero_subtitle": "Technical Documentation Platform",
"featured_slugs": ["quick-start", "faq"],
"logo_url": "/media/logo.png",
"favicon_url": "/media/favicon.ico"
}
}
```
### 获取组合元数据
```
GET /api/v1/meta
```
返回分类、标签和通知信息的组合数据。
**响应：**
```json
{
"success": true,
"data": {
"categories": [ ... ],
"tags": [ ... ],
"notice": "Important announcement text"
}
}
```
### AI 爬虫 Feed
```
GET /api/v1/llms.txt
```
返回专为 AI 爬虫优化的文本内容。
### 站点地图
```
GET /api/v1/geo/sitemap.xml
```
返回 XML 格式的站点地图。
### 提交反馈
```
POST /api/v1/feedback
```
**请求体：**
```json
{
"slug": "can-bus-protocol",
"content": "Great documentation!",
"rating": 5
}
```
**响应：**
```json
{
"success": true,
"data": {
"id": "fb_123456"
}
}
```
---
## 认证接口
### 用户登录
```
POST /api/v1/auth/login
```
**请求体：**
```json
{
"username": "admin",
"password": "your-password"
}
```
**响应：**
```json
{
"success": true,
"data": {
"user": {
"username": "admin",
"role": "admin"
},
"mustChangePassword": false
}
}
```
::: warning
首次登录时，`mustChangePassword` 为 `true`，必须先调用修改密码接口才能访问管理功能。
:::
### 用户登出
```
POST /api/v1/auth/logout
```
### 获取当前用户信息
```
GET /api/v1/auth/me
```
**响应：**
```json
{
"success": true,
"data": {
"username": "admin",
"role": "admin",
"passwordChanged": true
}
}
```
### 修改密码
```
POST /api/v1/auth/change-password
```
**请求体：**
```json
{
"oldPassword": "current-password",
"newPassword": "new-password"
}
```
### 注册新用户
```
POST /api/v1/auth/register
```
::: warning
此接口仅管理员可用。
:::
**请求体：**
```json
{
"username": "newuser",
"password": "user-password",
"role": "editor"
}
```
---
## 管理接口
所有管理接口需要 JWT 认证和管理员/编辑者角色。
### 文档管理
#### 创建文档
```
POST /api/v1/admin/docs
```
**请求体：**
```json
{
"slug": "my-new-doc",
"title": "My New Document",
"category": "support",
"tags": ["guide", "tutorial"],
"author": "admin",
"sort": 5,
"description": "A helpful guide",
"content": "# My New Document\n\nContent here...",
"lang": "en"
}
```
::: tip
如果未提供 slug，系统会自动根据标题生成。创建文档时会检查 slug 是否重复。
:::
#### 更新文档
```
PUT /api/v1/admin/docs/:slug
```
更新文档时会自动同步共享字段（category、tags、author、sort）到其他语言版本。
#### 删除文档
```
DELETE /api/v1/admin/docs/:slug
```
#### 文档排序
```
PUT /api/v1/admin/docs/reorder
```
**请求体：**
```json
{
"slugs": ["doc-1", "doc-2", "doc-3"],
"category": "can-motion",
"lang": "zh"
}
```
::: note
此接口必须在 `PUT /api/v1/admin/docs/:slug` 之前定义，否则 Express 会将 `reorder` 匹配为 slug 参数。
:::
### 分类管理
#### 获取分类列表
```
GET /api/v1/admin/categories
```
#### 创建分类
```
POST /api/v1/admin/categories
```
**请求体：**
```json
{
"slug": "new-category",
"name": "新分类",
"name_en": "New Category",
"description": "Category description"
}
```
#### 更新分类
```
PUT /api/v1/admin/categories/:slug
```
#### 删除分类
```
DELETE /api/v1/admin/categories/:slug
```
### 标签管理
#### 获取标签列表
```
GET /api/v1/admin/tags
```
#### 创建标签
```
POST /api/v1/admin/tags
```
**请求体：**
```json
{
"slug": "new-tag",
"name": "新标签",
"name_en": "New Tag"
}
```
#### 删除标签
```
DELETE /api/v1/admin/tags/:slug
```
### 反馈管理
#### 获取反馈列表
```
GET /api/v1/admin/feedback
```
#### 删除反馈
```
DELETE /api/v1/admin/feedback/:id
```
### 媒体管理
#### 获取媒体列表
```
GET /api/v1/admin/media
```
#### 删除媒体文件
```
DELETE /api/v1/admin/media/:filename
```
### 上传文件
```
POST /api/v1/media/upload
```
**请求：** `multipart/form-data`
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file` | file | 是 | 上传的文件 |
::: warning
文件上传会通过 magic bytes 检测真实类型。文件名会进行 `encodeURIComponent` 编码。
:::
**示例：**
```bash
curl -X POST "https://geowiki.pro/api/v1/media/upload" \
-H "Cookie: jwt=your-token" \
-F "[email protected]"
```
### 站点配置管理
#### 获取完整配置
```
GET /api/v1/admin/config
```
#### 更新配置
```
PUT /api/v1/admin/config
```
**请求体：**
```json
{
"hero_title": "My Wiki",
"hero_subtitle": "Technical Documentation",
"featured_slugs": ["quick-start", "faq"],
"logo_url": "/media/logo.png",
"favicon_url": "/media/favicon.ico",
"customHeadHtml": "<meta name=\"theme-color\" content=\"#3b82f6\">"
}
```
::: note
`customHeadHtml` 字段会自动过滤 `<script>`、`<iframe>` 和 `on*` 事件属性，防止 XSS 攻击。
:::
### 草稿管理
#### 发布草稿
```
POST /api/v1/admin/drafts/:slug/publish
```
#### 拒绝草稿
```
DELETE /api/v1/admin/drafts/:slug
```
### 用户管理
#### 获取用户列表
```
GET /api/v1/admin/users
```
#### 创建用户
```
POST /api/v1/admin/users
```
#### 删除用户
```
DELETE /api/v1/admin/users/:username
```
### 统计信息
```
GET /api/v1/admin/stats
```
返回文档数量、分类统计、标签使用情况等仪表盘数据。
### 留言管理
#### 获取留言列表
```
GET /api/v1/admin/guestbook
```
#### 创建留言
```
POST /api/v1/admin/guestbook
```
#### 更新留言
```
PUT /api/v1/admin/guestbook/:id
```
#### 删除留言
```
DELETE /api/v1/admin/guestbook/:id
```
### GEO 分析
#### 获取 GEO 概览
```
GET /api/v1/admin/geo/overview
```
#### 重建 GEO 文件
```
POST /api/v1/admin/geo/rebuild
```
触发重新生成 `llms.txt` 和 `sitemap.xml`。
---
## 错误码
| HTTP 状态码 | 说明 |
|------------|------|
| 200 | 成功 |
| 201 | 创建成功 |
| 400 | 请求参数错误 |
| 401 | 未认证或 token 过期 |
| 403 | 无权限 |
| 404 | 资源不存在 |
| 409 | 资源冲突（如 slug 重复） |
| 429 | 请求过于频繁（限流） |
| 500 | 服务器内部错误 |
---
## 安全机制
| 机制 | 说明 |
|------|------|
| JWT 认证 | httpOnly cookie，2 小时过期 |
| CSRF 保护 | Double-submit cookie HMAC 验证 |
| 限流 | 全局 300 次/分钟，认证接口 10 次/分钟 |
| CSP | Helmet nonce-based Content Security Policy |
| 文件上传 | Magic bytes 类型检测 |
| Slug 验证 | 正则匹配 + 长度限制 + 去重检查 |
---
*最后更新: 2026-06-06 | 版本: v3.0.2*