基础 URL:由配置 urls.apiBaseUrl 决定。
同时提供 /1/(已弃用)和 /v1/ 端点。建议新集成使用 /v1/。
完整 OpenAPI 3.1 规范见 openapi.yaml。
一条日志记录不再区分“正文”和“附件”,而是由一个 ID 下的若干文件组成:
- 新客户端上传时只提交
files;旧版content字段仍然兼容,会映射为latest.log,已有客户端不需要迁移。 - 单个文件大小不设上限;全部文件展开后合计不超过 20 MiB。
- 上传阶段逐文件脱敏,并在识别为 Minecraft 日志时执行 SpinYarn 反混淆。
- 全文 Codex 分析不在上传时执行,只在请求某个文件的分析接口时执行。
- 多文件日志直接访问
raw/{id}或insights/{id}会返回200+ 文件列表;客户端选择文件后再带文件名请求。
# 1. 上传文件列表
curl -X POST https://api.logshare.cn/v1/log \
-H 'Content-Type: application/json' \
-d '{
"files": [
{"name": "latest.log", "content": "<日志全文>"},
{"name": "crash-reports/crash-01.txt", "content": "<崩溃报告>"}
],
"source": "your-launcher/1.0.0"
}'
# 2. 列出文件
curl https://api.logshare.cn/v1/log/sAbCdEf
# 3. 多文件时先选择文件,再读取或分析
curl https://api.logshare.cn/v1/raw/sAbCdEf/latest.log
curl https://api.logshare.cn/v1/insights/sAbCdEf/latest.log上传响应的 token 是删除日志的唯一凭证,丢失后无法找回,请自行持久化保存。
- 一次上传完整现场:建议同时提交游戏主日志、崩溃报告与启动器日志,通过
files数组或 ZIP 压缩包提交。 - 多文件先让用户选择:调用
GET /v1/log/{id},若requiresFileSelection为true,展示files列表让用户选择,再使用所选文件的name请求 raw/insights。 - 注明来源:
source推荐格式为启动器标识/版本号,例如fcl/1.2.0、pojavlauncher/3.4.1。 - 保留删除凭证与分享链接:持久化
token,并提供url的一键复制或外跳。
POST /1/log (已弃用)
POST /v1/log
Content-Type: application/x-www-form-urlencoded 或 application/json。
Content-Encoding: 支持 br、gzip、x-gzip、deflate,最多 5 层;解压后请求体上限 32 MiB。
Accept-Encoding: 默认采用 br,未声明时回退 gzip、deflate。
请求字段:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
files |
array | 否* | 文件数组,每个元素 {name, content};文件数 ≤ 200,展开后合计 ≤ 20 MiB。与 content 至少提供一个 |
content |
string | 否* | 旧版单文件字段;不为空时映射为 latest.log,与 files 同时存在时作为主文件 |
metadata[] |
array | 否 | 分析核心输入,每项 {key, value, label?, visible?}。最多 100 条;key 去除首尾空白后必须为 1–64 字符,value 字符串最长 1024 字符、其他类型会 JSON 序列化,label 最长 128 字符;重复 key 以首次出现为准;visible=false 不公开。JSON 与 urlencoded 均支持 |
source |
string | 否 | 来源标识,最长 64 字符,格式如 fcl/1.2.0 |
files与content至少提供一个;两者同时提供时,content作为主文件latest.log(若重名则使用main.log),其余文件按files处理。旧客户端可以继续使用{"content": "...", "source": "..."}上传。
多文件与 ZIP:
{
"files": [
{ "name": "latest.log", "content": "..." },
{ "name": "crash-reports/crash-01.txt", "content": "..." },
{ "name": "server-logs.zip", "content": "<zip 二进制内容>" }
]
}.zip文件会自动展开,保留内部相对路径。- 展开后每个文件独立经过脱敏过滤链。
- 文件数上限 200;所有文件合计上限 20 MiB;不限制单个文件大小或行数。
- ZIP 条目名会做路径遍历防护(拒绝
../、绝对路径)。 - 同名文件会自动改名为
name (2).ext、name (3).ext。 - 内容去重按「按名称排序的文件集合 +
source」计算指纹;命中时直接返回既有 ID,deduplicated: true。
metadata 很重要,不是可选装饰。 请尽量提供
version、loader、launcher、modpack、崩溃上下文等结构化字段;GET /v1/log/{id}只展示客户端提交且visible=true的条目(visible=false除外)。后端从日志识别出的version/loader仅作为内部统计字段保存,不会回填到公开 metadata。
响应:
{
"success": true,
"message": "Log submitted successfully",
"id": "sAbCdEf",
"url": "https://logshare.cn/sAbCdEf",
"filesUrl": "https://api.logshare.cn/v1/log/sAbCdEf",
"raw": "https://api.logshare.cn/v1/raw/sAbCdEf",
"token": "3f9c1a7d...",
"deduplicated": false,
"fileCount": 2,
"requiresFileSelection": true,
"files": [
{
"name": "crash-reports/crash-01.txt",
"size": 2048,
"lines": 80,
"raw": "https://api.logshare.cn/v1/raw/sAbCdEf/crash-reports/crash-01.txt",
"insights": "https://api.logshare.cn/v1/insights/sAbCdEf/crash-reports/crash-01.txt"
}
]
}去重命中时的 token 语义:命中已有指纹时返回的
token是本次请求新生成的,并未写入存储,不能用于删除该日志;删除凭证仍属于首次上传者。
DELETE /1/log/{id} (已弃用)
DELETE /v1/log/{id}
鉴权: Authorization: Bearer <token>。
多 ID: 逗号分隔,如 DELETE /v1/log/id1,id2。
GET /1/log/{id} (已弃用)
GET /v1/log/{id}
返回日志元信息与全部文件。多文件时 requiresFileSelection 为 true:
{
"success": true,
"message": "Log metadata retrieved successfully",
"id": "sAbCdEf",
"fileCount": 2,
"requiresFileSelection": true,
"size": 4096,
"lines": 120,
"created": 1755200000,
"expires": 1755804800,
"metadata": [],
"source": "launcher/1.0.0",
"filesUrl": "https://api.logshare.cn/v1/log/sAbCdEf",
"files": [
{
"name": "latest.log",
"size": 2048,
"lines": 40,
"raw": "https://api.logshare.cn/v1/raw/sAbCdEf/latest.log",
"insights": "https://api.logshare.cn/v1/insights/sAbCdEf/latest.log"
}
]
}GET /1/raw/{id} (已弃用)
GET /v1/raw/{id}
GET /1/raw/{id}/{filename} (已弃用)
GET /v1/raw/{id}/{filename}
- 只有一个文件时,
GET /v1/raw/{id}直接返回text/plain内容。 - 多个文件时,
GET /v1/raw/{id}返回200+ 文件列表(结构同文件列表接口),不会擅自选择文件。 - 指定文件名后返回该文件原文,例如:
GET /v1/raw/sAbCdEf/crash-reports/crash-01.txt
{filename} 支持子路径,需 URL 编码。文件不存在返回 404。文件名只做数据库精确匹配,不做文件系统路径拼接。
GET /1/insights/{id} (已弃用)
GET /v1/insights/{id}
GET /1/insights/{id}/{filename} (已弃用)
GET /v1/insights/{id}/{filename}
- 只有一个文件时,
GET /v1/insights/{id}直接返回 Codex 分析 JSON。 - 多个文件时,返回
200+ 文件列表;客户端选择文件后请求:
GET /v1/insights/sAbCdEf/latest.log
返回 Codex 解析结果,包含类型、版本、错误信息与堆栈等:
{
"id": "vanilla/server",
"name": "Vanilla",
"type": "Server Log",
"version": "1.21.9",
"analysis": {
"problems": [
{ "message": "...", "counter": 1, "solutions": ["..."] }
],
"information": [
{ "message": "Minecraft version: 1.21.9", "counter": 1, "label": "Minecraft version", "value": "1.21.9" }
]
}
}分析结果按文件内容哈希做进程内 LRU 缓存;同一文件重复访问不会重复执行 Codex。
GET /1/limits (已弃用)
GET /v1/limits
{
"storageTime": 604800,
"maxFiles": 200,
"maxTotalBytes": 20971520,
"maxRequestBodyBytes": 33554432
}限流口径: 限流在边缘完成:nginx
limit_req按 IP 30 r/s(burst 60),OpenLiteWaf 再叠加 10 秒窗口 240 次的 CC 限流。CC 超限返回429并带Retry-After,limit_req超限返回503;两者都不封禁 IP(特征命中累计 3 次才会临时封禁)。应用层不再执行内容审核,边缘 WAF 仍负责基础探测拦截。
GET /
返回全部可用端点列表。
成功:
{
"success": true,
"message": "OK"
}错误:
{
"success": false,
"error": "错误描述",
"code": 400
}| 状态码 | 说明 |
|---|---|
| 200 | 请求成功;多文件列表也返回 200 |
| 400 | 请求参数错误 |
| 401 | 缺少认证信息 |
| 403 | 权限不足或 IP 被封禁 |
| 404 | 日志或文件不存在 |
| 405 | 请求方法不允许 |
| 413 | 请求体或文件总量过大 |
| 415 | 不支持的 Content-Type 或 Content-Encoding |
| 429 | 速率限制触发 |
| 500 | 服务器内部错误 |