{"id":29945194,"url":"https://github.com/rice-awa/minecraft-wiki-fetch-api","last_synced_at":"2026-04-16T10:02:02.983Z","repository":{"id":307648429,"uuid":"1030041410","full_name":"rice-awa/minecraft-wiki-fetch-api","owner":"rice-awa","description":"一个用于抓取和转换 Minecraft 中文 Wiki 内容的 API 服务。可搜索或抓取minecraft wiki页面内容并将其转化为markdown格式","archived":false,"fork":false,"pushed_at":"2026-03-21T09:54:08.000Z","size":685,"stargazers_count":6,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-22T01:24:00.913Z","etag":null,"topics":["fetch-api","javascript","json","markdown","mc","mczhwiki","minecraft","nodejs","wiki"],"latest_commit_sha":null,"homepage":"https://mcwiki.rice-awa.top","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rice-awa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-01T02:06:46.000Z","updated_at":"2026-03-21T09:54:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"eb32433e-3837-4338-ae30-83437454c30b","html_url":"https://github.com/rice-awa/minecraft-wiki-fetch-api","commit_stats":null,"previous_names":["rice-awa/minecraft-wiki-fetch-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rice-awa/minecraft-wiki-fetch-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rice-awa%2Fminecraft-wiki-fetch-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rice-awa%2Fminecraft-wiki-fetch-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rice-awa%2Fminecraft-wiki-fetch-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rice-awa%2Fminecraft-wiki-fetch-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rice-awa","download_url":"https://codeload.github.com/rice-awa/minecraft-wiki-fetch-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rice-awa%2Fminecraft-wiki-fetch-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31880882,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T09:23:21.276Z","status":"ssl_error","status_checked_at":"2026-04-16T09:23:15.028Z","response_time":69,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fetch-api","javascript","json","markdown","mc","mczhwiki","minecraft","nodejs","wiki"],"created_at":"2025-08-03T05:00:36.083Z","updated_at":"2026-04-16T10:02:02.978Z","avatar_url":"https://github.com/rice-awa.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Minecraft Wiki API\n\n一个用于抓取、解析并转换中文 Minecraft Wiki 内容的 REST API，已适配 Vercel Serverless 部署。\n\n## 功能特性\n\n- **Web 控制台**：访问根路径 `/` 即可使用可视化的 API 测试控制台\n- **API Key 认证**：支持静态 API Key 认证，保护敏感端点\n- **分布式速率限制**：支持 Upstash Redis 分布式限流，区分认证/未认证用户配额\n- Wiki 搜索：`GET /api/search`\n- 页面获取：`GET /api/page/:pageName`\n- 页面源代码（Wikitext）：`format=wikitext`\n- 批量获取：`POST /api/pages`\n- 健康检查：`GET /health`、`GET /health/detailed`\n- JSON 美化输出：查询参数 `pretty=true`\n\n## 快速部署到 Vercel\n\n### 方式一：一键部署（推荐）\n\n[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/rice-awa/minecraft-wiki-fetch-api\u0026env=WIKI_BASE_URL,REQUEST_TIMEOUT,RATE_LIMIT_MAX\u0026envDescription=API%20Configuration\u0026envLink=https://github.com/rice-awa/minecraft-wiki-fetch-api/blob/main/.env.vercel)\n\n### 方式二：CLI 部署\n\n```bash\ngit clone https://github.com/rice-awa/minecraft-wiki-fetch-api.git\ncd minecraft-wiki-fetch-api\nnpm install\nnpm install -g vercel\nvercel login\nnpm run deploy\n```\n\n## 部署后验证\n\n将 `https://your-project.vercel.app` 替换为你的实际域名。\n\n**Web 控制台**：直接访问 `https://your-project.vercel.app/`\n\n**API 测试**：\n\n```bash\ncurl https://your-project.vercel.app/health\ncurl \"https://your-project.vercel.app/api/search?q=钻石\u0026limit=5\u0026pretty=true\"\ncurl \"https://your-project.vercel.app/api/page/钻石?format=markdown\u0026pretty=true\"\ncurl \"https://your-project.vercel.app/api/page/工作台?format=wikitext\u0026pretty=true\"\n```\n\n## 环境变量（Vercel）\n\n推荐至少配置以下变量：\n\n| 变量名 | 默认值 | 说明 |\n| --- | --- | --- |\n| `NODE_ENV` | `production` | 运行环境 |\n| `WIKI_BASE_URL` | `https://zh.minecraft.wiki` | Wiki 源站 |\n| `REQUEST_TIMEOUT` | `15000` | 外部请求超时（毫秒） |\n| `MAX_RETRIES` | `2` | 外部请求重试次数 |\n| `RATE_LIMIT_ANONYMOUS` | `30` | 未认证用户每分钟请求数 |\n| `RATE_LIMIT_AUTHENTICATED` | `100` | 认证用户每分钟请求数 |\n| `RATE_LIMIT_STORE` | `upstash` | 限流存储方式 |\n| `UPSTASH_REDIS_REST_URL` | - | Upstash Redis URL（分布式限流必需） |\n| `UPSTASH_REDIS_REST_TOKEN` | - | Upstash Redis Token |\n| `API_KEY` | - | API 密钥（支持多个，逗号分隔） |\n| `SEARCH_MAX_LIMIT` | `30` | 搜索最大条数 |\n| `ALLOWED_ORIGINS` | `*` | CORS 白名单（逗号分隔） |\n| `LOG_FILE` | `false` | Serverless 建议关闭文件日志 |\n\n完整示例见：`./.env.vercel`\n\n### API Key 认证\n\n设置 `API_KEY` 环境变量启用认证：\n\n```bash\n# Vercel CLI\nvercel env add API_KEY --env production\n\n# 或在 Vercel Dashboard 中设置\n```\n\n**使用方式**：\n\n```bash\n# 方式一：请求头\ncurl -H \"X-API-Key: your-api-key\" https://your-api.vercel.app/api/pages\n\n# 方式二：查询参数\ncurl \"https://your-api.vercel.app/api/pages?api_key=your-api-key\"\n```\n\n**端点保护规则**：\n\n| 端点 | 访问级别 | 说明 |\n| --- | --- | --- |\n| `/health/*` | 公开 | 无需认证，无限流 |\n| `/api/search` | 公开 | 无需认证，低限流 |\n| `/api/page/:name` | 公开 | 无需认证，低限流 |\n| `/api/pages` (POST) | **需认证** | 批量获取，高限流 |\n| `/api/page/:name/cache` (DELETE) | **需认证** | 清除缓存 |\n\n### 速率限制\n\n未配置 Upstash 时自动降级到内存存储（本地开发友好）。\n\n**配置项**：\n- `RATE_LIMIT_ANONYMOUS=30` - 未认证用户配额\n- `RATE_LIMIT_AUTHENTICATED=100` - 认证用户配额\n- `RATE_LIMIT_WINDOW=60000` - 时间窗口（毫秒）\n\n## API 概览\n\n### `GET /api/search`\n\n参数：\n\n- `q`（必填）：关键词\n- `limit`（可选）：结果数量，默认 `10`，最大 `50`\n- `pretty`（可选）：`true/false`\n\n### `GET /api/page/:pageName`\n\n参数：\n\n- `format`（可选）：`html` / `markdown` / `both` / `wikitext`\n- `pretty`（可选）：`true/false`\n\n### `POST /api/pages`\n\n```json\n{\n  \"pages\": [\"钻石\", \"铁锭\"],\n  \"format\": \"markdown\",\n  \"concurrency\": 2\n}\n```\n\n**format 可选值**：`html` / `markdown` / `both` / `wikitext`\n\n### 健康检查\n\n- `GET /health`\n- `GET /health/detailed`\n- `GET /health/ready`\n- `GET /health/live`\n\n## 本地开发\n\n```bash\nnpm install\nnpm run dev\n```\n\n本地模拟 Serverless：\n\n```bash\nnpm run dev:serverless\nnpm run test:serverless\n```\n\n## Vercel 适配说明\n\n项目当前使用 `api/index.js` 作为 serverless 入口，配合 `vercel.json` 路由转发，支持：\n\n- **根路径 `/`**：返回 `public/index.html` Web 控制台\n- API 路径 `/api` 与 `/api/*`\n- 健康检查 `/health` 与 `/health/*`\n\n## 常见问题\n\n### 1. 部署后访问 `/health` 返回 404\n\n确认项目根目录的 `vercel.json` 已随代码部署，并且路由规则包含 `/health` 与 `/health/*`。\n\n### 2. 请求超时\n\n优先检查：\n\n- `REQUEST_TIMEOUT` 是否过大\n- 单次批量请求 `pages` 数量是否过多\n- 是否触发了上游 Wiki 网络波动\n\n### 3. CORS 报错\n\n请在 Vercel 环境变量中正确设置 `ALLOWED_ORIGINS`，多个域名用逗号分隔。\n\n### 4. 批量获取返回 401 未认证\n\n`POST /api/pages` 端点需要有效的 API Key。请设置 `API_KEY` 环境变量，并在请求中通过 `X-API-Key` 请求头或 `api_key` 查询参数传递。\n\n### 5. 速率限制返回 429\n\n请求过于频繁，请检查响应头中的 `X-RateLimit-Reset` 了解限制重置时间。认证用户享有更高配额。\n\n### 6. Upstash 配置\n\n1. 访问 [Upstash Console](https://console.upstash.io) 创建 Redis 实例\n2. 复制 `UPSTASH_REDIS_REST_URL` 和 `UPSTASH_REDIS_REST_TOKEN`\n3. 在 Vercel 环境变量中添加这两个值\n\n## 相关文档\n- [部署详解](./deploy-vercel.md)\n- [API 说明](./docs/API_DOCUMENTATION.md)\n- [环境变量](./docs/environment-variables-guide.md)\n\n## 许可证\n\n- 项目代码：`MIT`（见 `./LICENSE`）\n- Wiki 内容版权：遵循中文 Minecraft Wiki 所声明的许可条款\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frice-awa%2Fminecraft-wiki-fetch-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frice-awa%2Fminecraft-wiki-fetch-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frice-awa%2Fminecraft-wiki-fetch-api/lists"}