https://github.com/rice-awa/minecraft-wiki-fetch-api
一个用于抓取和转换 Minecraft 中文 Wiki 内容的 API 服务。可搜索或抓取minecraft wiki页面内容并将其转化为markdown格式
https://github.com/rice-awa/minecraft-wiki-fetch-api
fetch-api javascript json markdown mc mczhwiki minecraft nodejs wiki
Last synced: about 2 months ago
JSON representation
一个用于抓取和转换 Minecraft 中文 Wiki 内容的 API 服务。可搜索或抓取minecraft wiki页面内容并将其转化为markdown格式
- Host: GitHub
- URL: https://github.com/rice-awa/minecraft-wiki-fetch-api
- Owner: rice-awa
- License: mit
- Created: 2025-08-01T02:06:46.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2026-03-21T09:54:08.000Z (2 months ago)
- Last Synced: 2026-03-22T01:24:00.913Z (2 months ago)
- Topics: fetch-api, javascript, json, markdown, mc, mczhwiki, minecraft, nodejs, wiki
- Language: JavaScript
- Homepage: https://mcwiki.rice-awa.top
- Size: 669 KB
- Stars: 6
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Minecraft Wiki API
一个用于抓取、解析并转换中文 Minecraft Wiki 内容的 REST API，已适配 Vercel Serverless 部署。
## 功能特性
- **Web 控制台**：访问根路径 `/` 即可使用可视化的 API 测试控制台
- **API Key 认证**：支持静态 API Key 认证，保护敏感端点
- **分布式速率限制**：支持 Upstash Redis 分布式限流，区分认证/未认证用户配额
- Wiki 搜索：`GET /api/search`
- 页面获取：`GET /api/page/:pageName`
- 页面源代码（Wikitext）：`format=wikitext`
- 批量获取：`POST /api/pages`
- 健康检查：`GET /health`、`GET /health/detailed`
- JSON 美化输出：查询参数 `pretty=true`
## 快速部署到 Vercel
### 方式一：一键部署（推荐）
[](https://vercel.com/new/clone?repository-url=https://github.com/rice-awa/minecraft-wiki-fetch-api&env=WIKI_BASE_URL,REQUEST_TIMEOUT,RATE_LIMIT_MAX&envDescription=API%20Configuration&envLink=https://github.com/rice-awa/minecraft-wiki-fetch-api/blob/main/.env.vercel)
### 方式二：CLI 部署
```bash
git clone https://github.com/rice-awa/minecraft-wiki-fetch-api.git
cd minecraft-wiki-fetch-api
npm install
npm install -g vercel
vercel login
npm run deploy
```
## 部署后验证
将 `https://your-project.vercel.app` 替换为你的实际域名。
**Web 控制台**：直接访问 `https://your-project.vercel.app/`
**API 测试**：
```bash
curl https://your-project.vercel.app/health
curl "https://your-project.vercel.app/api/search?q=钻石&limit=5&pretty=true"
curl "https://your-project.vercel.app/api/page/钻石?format=markdown&pretty=true"
curl "https://your-project.vercel.app/api/page/工作台?format=wikitext&pretty=true"
```
## 环境变量（Vercel）
推荐至少配置以下变量：
| 变量名 | 默认值 | 说明 |
| --- | --- | --- |
| `NODE_ENV` | `production` | 运行环境 |
| `WIKI_BASE_URL` | `https://zh.minecraft.wiki` | Wiki 源站 |
| `REQUEST_TIMEOUT` | `15000` | 外部请求超时（毫秒） |
| `MAX_RETRIES` | `2` | 外部请求重试次数 |
| `RATE_LIMIT_ANONYMOUS` | `30` | 未认证用户每分钟请求数 |
| `RATE_LIMIT_AUTHENTICATED` | `100` | 认证用户每分钟请求数 |
| `RATE_LIMIT_STORE` | `upstash` | 限流存储方式 |
| `UPSTASH_REDIS_REST_URL` | - | Upstash Redis URL（分布式限流必需） |
| `UPSTASH_REDIS_REST_TOKEN` | - | Upstash Redis Token |
| `API_KEY` | - | API 密钥（支持多个，逗号分隔） |
| `SEARCH_MAX_LIMIT` | `30` | 搜索最大条数 |
| `ALLOWED_ORIGINS` | `*` | CORS 白名单（逗号分隔） |
| `LOG_FILE` | `false` | Serverless 建议关闭文件日志 |
完整示例见：`./.env.vercel`
### API Key 认证
设置 `API_KEY` 环境变量启用认证：
```bash
# Vercel CLI
vercel env add API_KEY --env production
# 或在 Vercel Dashboard 中设置
```
**使用方式**：
```bash
# 方式一：请求头
curl -H "X-API-Key: your-api-key" https://your-api.vercel.app/api/pages
# 方式二：查询参数
curl "https://your-api.vercel.app/api/pages?api_key=your-api-key"
```
**端点保护规则**：
| 端点 | 访问级别 | 说明 |
| --- | --- | --- |
| `/health/*` | 公开 | 无需认证，无限流 |
| `/api/search` | 公开 | 无需认证，低限流 |
| `/api/page/:name` | 公开 | 无需认证，低限流 |
| `/api/pages` (POST) | **需认证** | 批量获取，高限流 |
| `/api/page/:name/cache` (DELETE) | **需认证** | 清除缓存 |
### 速率限制
未配置 Upstash 时自动降级到内存存储（本地开发友好）。
**配置项**：
- `RATE_LIMIT_ANONYMOUS=30` - 未认证用户配额
- `RATE_LIMIT_AUTHENTICATED=100` - 认证用户配额
- `RATE_LIMIT_WINDOW=60000` - 时间窗口（毫秒）
## API 概览
### `GET /api/search`
参数：
- `q`（必填）：关键词
- `limit`（可选）：结果数量，默认 `10`，最大 `50`
- `pretty`（可选）：`true/false`
### `GET /api/page/:pageName`
参数：
- `format`（可选）：`html` / `markdown` / `both` / `wikitext`
- `pretty`（可选）：`true/false`
### `POST /api/pages`
```json
{
"pages": ["钻石", "铁锭"],
"format": "markdown",
"concurrency": 2
}
```
**format 可选值**：`html` / `markdown` / `both` / `wikitext`
### 健康检查
- `GET /health`
- `GET /health/detailed`
- `GET /health/ready`
- `GET /health/live`
## 本地开发
```bash
npm install
npm run dev
```
本地模拟 Serverless：
```bash
npm run dev:serverless
npm run test:serverless
```
## Vercel 适配说明
项目当前使用 `api/index.js` 作为 serverless 入口，配合 `vercel.json` 路由转发，支持：
- **根路径 `/`**：返回 `public/index.html` Web 控制台
- API 路径 `/api` 与 `/api/*`
- 健康检查 `/health` 与 `/health/*`
## 常见问题
### 1. 部署后访问 `/health` 返回 404
确认项目根目录的 `vercel.json` 已随代码部署，并且路由规则包含 `/health` 与 `/health/*`。
### 2. 请求超时
优先检查：
- `REQUEST_TIMEOUT` 是否过大
- 单次批量请求 `pages` 数量是否过多
- 是否触发了上游 Wiki 网络波动
### 3. CORS 报错
请在 Vercel 环境变量中正确设置 `ALLOWED_ORIGINS`，多个域名用逗号分隔。
### 4. 批量获取返回 401 未认证
`POST /api/pages` 端点需要有效的 API Key。请设置 `API_KEY` 环境变量，并在请求中通过 `X-API-Key` 请求头或 `api_key` 查询参数传递。
### 5. 速率限制返回 429
请求过于频繁，请检查响应头中的 `X-RateLimit-Reset` 了解限制重置时间。认证用户享有更高配额。
### 6. Upstash 配置
1. 访问 [Upstash Console](https://console.upstash.io) 创建 Redis 实例
2. 复制 `UPSTASH_REDIS_REST_URL` 和 `UPSTASH_REDIS_REST_TOKEN`
3. 在 Vercel 环境变量中添加这两个值
## 相关文档
- [部署详解](./deploy-vercel.md)
- [API 说明](./docs/API_DOCUMENTATION.md)
- [环境变量](./docs/environment-variables-guide.md)
## 许可证
- 项目代码：`MIT`（见 `./LICENSE`）
- Wiki 内容版权：遵循中文 Minecraft Wiki 所声明的许可条款