{ "openapi": "3.1.0", "info": { "title": "RawMark API", "version": "1", "description": "RawMark单用户API。普通JSON统一{code,data,message}，code=0成功；保留HTTP语义。登录会话固定30天；API令牌保留read/write权限。受保护API只接受Bearer，不接受Cookie。文件、下载、事件、204与OpenAPI文档不包装。" }, "servers": [ { "url": "/api/v1" } ], "security": [ { "bearer": [] } ], "paths": { "/health": { "get": { "summary": "健康检查", "tags": [ "系统" ], "security": [ {} ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "$ref": "#/components/schemas/Ok" }, "message": { "type": "string" } } } } } } } } }, "/openapi.json": { "get": { "summary": "本文档", "tags": [ "系统" ], "security": [ {} ], "responses": { "200": { "description": "OpenAPI 文档", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/auth/state": { "get": { "summary": "是否已经初始化", "tags": [ "登录" ], "security": [ {} ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "type": "object", "required": [ "setUp" ], "properties": { "setUp": { "type": "boolean" } } }, "message": { "type": "string" } } } } } } } } }, "/auth/setup": { "post": { "summary": "首次设置密码并返回Bearer会话", "tags": [ "登录" ], "security": [ {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "password" ], "properties": { "password": { "type": "string" } } } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "type": "object", "required": [ "token", "expiresAt" ], "properties": { "token": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "message": { "type": "string" } } } } } }, "400": { "description": "密码过短", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "已初始化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "仅未初始化实例可设置密码；首次成功后自动登录，已初始化时返回 409。" } }, "/auth/login": { "post": { "summary": "验证码及密码登录，返回Bearer会话", "tags": [ "登录" ], "security": [ {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "password", "captchaId", "captchaCode" ], "properties": { "password": { "type": "string" }, "captchaId": { "type": "string" }, "captchaCode": { "type": "string" } } } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "type": "object", "required": [ "token", "expiresAt" ], "properties": { "token": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "message": { "type": "string" } } } } } }, "401": { "description": "密码错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "失败次数过多", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "验证码错误、已使用或过期（40001/40002）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/logout": { "post": { "summary": "退出登录", "tags": [ "登录" ], "security": [ { "bearer": [] } ], "responses": { "204": { "description": "服务端会话已撤销" } } } }, "/auth/password": { "post": { "summary": "修改登录密码；当前会话保留，其他设备需重新登录", "tags": [ "登录" ], "security": [ { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "current": { "type": "string" }, "next": { "type": "string" } }, "required": [ "current", "next" ] } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "$ref": "#/components/schemas/Ok" }, "message": { "type": "string" } } } } } }, "400": { "description": "新密码过短", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "当前密码错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "失败次数过多", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/settings": { "get": { "summary": "应用设置（全部设备共用的一份 JSON 对象）", "tags": [ "设置" ], "responses": { "200": { "description": "设置", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } } } } } } } }, "patch": { "summary": "合并修改设置", "tags": [ "设置" ], "security": [ { "bearer": [] } ], "description": "按顶层键合并：请求中的键覆盖原值，值为 null 的键被删除。成功后经 WebSocket 推送 settings 事件。 trashRetentionDays 为非负安全整数（默认30，0为永不自动删除），null恢复默认。期限适用于已有和新回收站条目，服务启动及每小时按原删除时间永久清理。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "trashRetentionDays": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991, "default": 30 } } } } } }, "responses": { "200": { "description": "合并后的设置", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } } } } } }, "400": { "description": "不是 JSON 对象，或自动删除期限无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "超过 1 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tree": { "get": { "summary": "全部笔记、图片与文件夹（含 .assets，不含隐藏条目或符号链接）", "tags": [ "笔记" ], "responses": { "200": { "description": "目录树", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/Entry" } } } }, "message": { "type": "string" } } } } } } } } }, "/files/{path}": { "parameters": [ { "name": "path", "in": "path", "required": true, "description": "仓库内的相对路径，如 `目录/笔记.md`（各段需 URL 编码）", "schema": { "type": "string" } } ], "get": { "summary": "读取笔记", "tags": [ "笔记" ], "responses": { "200": { "description": "Markdown 原文", "headers": { "ETag": { "description": "内容版本（rev），带双引号", "schema": { "type": "string" } } }, "content": { "text/markdown": { "schema": { "type": "string" } } } }, "404": { "description": "不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "写入笔记（不存在的上级目录会自动创建）", "tags": [ "笔记" ], "description": "请求体整体作为笔记内容。`If-Match: \"rev\"` 要求当前版本一致，否则返回 412 与最新 rev；`If-None-Match: *` 要求笔记尚不存在；都不带则直接覆盖。", "parameters": [ { "name": "If-Match", "in": "header", "schema": { "type": "string" } }, { "name": "If-None-Match", "in": "header", "schema": { "type": "string", "enum": [ "*" ] } } ], "requestBody": { "required": true, "content": { "text/markdown": { "schema": { "type": "string" } } } }, "responses": { "200": { "description": "已写入", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "type": "object", "properties": { "rev": { "type": "string" } } }, "message": { "type": "string" } } } } }, "headers": { "ETag": { "description": "内容版本（rev），带双引号", "schema": { "type": "string" } } } }, "400": { "description": "路径无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "If-None-Match 时已存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "版本冲突", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "type": "integer", "minimum": 1 }, "data": { "type": "object", "properties": { "error": { "type": "string" }, "rev": { "type": "string", "description": "服务器上的当前版本；为空表示已不存在" } } }, "message": { "type": "string" } } } } } }, "413": { "description": "超过 20 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "把笔记、图片或文件夹移入回收站（笔记连同 .assets）", "tags": [ "笔记" ], "responses": { "200": { "description": "回收站条目", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "$ref": "#/components/schemas/TrashItem" }, "message": { "type": "string" } } } } } }, "404": { "description": "不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/move": { "post": { "summary": "移动或重命名笔记、图片或文件夹", "tags": [ "笔记" ], "description": "笔记的 .assets 目录随之移动，改名时改写本篇图片目录链接；图片移动或改名保持扩展名，并更新仓库笔记中的本地引用。维护笔记中的本地入链及相对出链。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "$ref": "#/components/schemas/Ok" }, "message": { "type": "string" } } } } } }, "404": { "description": "源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "目标已存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/folders": { "post": { "summary": "新建文件夹", "tags": [ "笔记" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string" } }, "required": [ "path" ] } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "$ref": "#/components/schemas/Ok" }, "message": { "type": "string" } } } } } }, "409": { "description": "已存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/assets": { "post": { "summary": "上传图片到笔记的 .assets 目录", "tags": [ "图片" ], "parameters": [ { "name": "note", "in": "query", "required": false, "description": "所属笔记路径", "schema": { "type": "string" } }, { "name": "folder", "in": "query", "description": "文件夹图片管理上传目标，空字符串表示根目录；与 note 互斥", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } }, "required": [ "file" ] } } } }, "responses": { "200": { "description": "相对笔记所在目录的链接，可直接写入 Markdown", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "type": "object", "properties": { "link": { "type": "string" } } }, "message": { "type": "string" } } } } } }, "413": { "description": "超过 50 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "note 与 folder 必须且只能指定一个；note 上传到笔记附件目录，folder 上传到目录的 assets 子目录。" } }, "/assets/import": { "post": { "summary": "下载公网图片到笔记的 .assets 目录", "tags": [ "图片" ], "description": "仅接受公网 HTTP/HTTPS 地址，实际连接及重定向均校验；不携带登录凭据或使用环境代理。重定向链最多 5 个请求、2 次下载尝试，单次超时 10 秒；仅超时、429 和 5xx 重试。支持 PNG/JPEG/GIF/WebP，按文件签名识别，最大 50 MB。", "parameters": [ { "name": "note", "in": "query", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" } } } } } }, "responses": { "200": { "description": "相对笔记所在目录的图片链接", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "type": "object", "properties": { "link": { "type": "string" } } }, "message": { "type": "string" } } } } } }, "400": { "description": "来源地址或笔记路径无效，或目标不是公网", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "所属笔记不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "图片超过 50 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "不支持的图片类型", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "来源请求失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/raw/{path}": { "parameters": [ { "name": "path", "in": "path", "required": true, "description": "仓库内的相对路径，如 `目录/笔记.md`（各段需 URL 编码）", "schema": { "type": "string" } } ], "get": { "summary": "读取仓库中的原始文件（图片等）", "tags": [ "图片" ], "responses": { "200": { "description": "文件内容", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/search": { "get": { "summary": "全文搜索", "tags": [ "笔记" ], "description": "空格分隔多个词，全部命中才返回；最多 50 条。", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "结果", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } } } }, "message": { "type": "string" } } } } } } } } }, "/trash": { "get": { "summary": "回收站列表", "tags": [ "回收站" ], "responses": { "200": { "description": "条目", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TrashItem" } } } }, "message": { "type": "string" } } } } } } } }, "delete": { "summary": "清空回收站全部条目", "description": "永久删除，不可恢复；结果逐项报告，失败条目保留。只读令牌禁止。", "tags": [ "回收站" ], "responses": { "200": { "description": "包含成功及失败的逐项结果", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "$ref": "#/components/schemas/TrashPurgeResult" }, "message": { "type": "string" } } } } } } } } }, "/trash/{id}/restore": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "从回收站恢复", "tags": [ "回收站" ], "responses": { "200": { "description": "恢复的条目", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "$ref": "#/components/schemas/TrashItem" }, "message": { "type": "string" } } } } } }, "404": { "description": "不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "原位置已有同名文件", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trash/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "彻底删除回收站条目", "tags": [ "回收站" ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "$ref": "#/components/schemas/Ok" }, "message": { "type": "string" } } } } } }, "404": { "description": "不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/events": { "get": { "summary": "WebSocket：仓库变更推送", "tags": [ "笔记" ], "description": "升级为 WebSocket 后，服务器推送 JSON 数组，元素为 Event。客户端不发送消息。", "responses": { "101": { "description": "切换为 WebSocket" } } } }, "/tokens": { "get": { "summary": "API 令牌列表", "tags": [ "API 令牌" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "令牌", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "type": "object", "properties": { "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/APIToken" } } } }, "message": { "type": "string" } } } } } } } }, "post": { "summary": "创建 API 令牌", "tags": [ "API 令牌" ], "security": [ { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "scope": { "type": "string", "enum": [ "read", "write" ] } }, "required": [ "name", "scope" ] } } } }, "responses": { "200": { "description": "token 明文只返回这一次", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "type": "object", "properties": { "token": { "type": "string" }, "info": { "$ref": "#/components/schemas/APIToken" } } }, "message": { "type": "string" } } } } } }, "400": { "description": "名称或范围无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tokens/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "吊销 API 令牌", "tags": [ "API 令牌" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "$ref": "#/components/schemas/Ok" }, "message": { "type": "string" } } } } } }, "404": { "description": "不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/themes": { "get": { "summary": "列出主题（含内置默认主题）", "tags": [ "外观" ], "responses": { "200": { "description": "主题列表", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "type": "object", "properties": { "themes": { "type": "array", "items": { "$ref": "#/components/schemas/Theme" } } } }, "message": { "type": "string" } } } } } } } } }, "/themes/{id}": { "get": { "summary": "读取主题 CSS", "tags": [ "外观" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "主题信息与 CSS", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "allOf": [ { "$ref": "#/components/schemas/Theme" }, { "type": "object", "properties": { "css": { "type": "string" } } } ] }, "message": { "type": "string" } } } } } }, "404": { "description": "主题不存在或文件不完整" } } } }, "/plugins": { "get": { "summary": "列出已安装插件及启用状态", "tags": [ "插件" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "type": "object", "properties": { "plugins": { "type": "array", "items": { "$ref": "#/components/schemas/Plugin" } } } }, "message": { "type": "string" } } } } } }, "401": { "description": "需要登录会话" }, "400": { "description": "请求或插件包无效" }, "403": { "description": "不接受 API 令牌" } } }, "post": { "summary": "安装 ZIP 插件；安装后默认停用，同 id 拒绝覆盖", "tags": [ "插件" ], "security": [ { "bearer": [] } ], "responses": { "201": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "$ref": "#/components/schemas/Plugin" }, "message": { "type": "string" } } } } } }, "401": { "description": "需要登录会话" }, "400": { "description": "请求或插件包无效" }, "403": { "description": "不接受 API 令牌" }, "409": { "description": "同名插件已安装" }, "413": { "description": "ZIP 超过 10 MiB" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } } } }, "/plugins/{id}": { "patch": { "summary": "修改全设备插件启用偏好", "tags": [ "插件" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "$ref": "#/components/schemas/Plugin" }, "message": { "type": "string" } } } } } }, "401": { "description": "需要登录会话" }, "400": { "description": "请求或插件包无效" }, "403": { "description": "不接受 API 令牌" }, "404": { "description": "插件或指定版本的资源不存在" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } } } } } } }, "delete": { "summary": "停用并卸载插件包，保留插件私有数据", "tags": [ "插件" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "$ref": "#/components/schemas/Ok" }, "message": { "type": "string" } } } } } }, "401": { "description": "需要登录会话" }, "400": { "description": "请求或插件包无效" }, "403": { "description": "不接受 API 令牌" }, "404": { "description": "插件或指定版本的资源不存在" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/plugins/{id}/data": { "get": { "summary": "读取插件私有 JSON，无数据时为 null", "tags": [ "插件" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "type": "object", "required": [ "data" ], "properties": { "data": {} } }, "message": { "type": "string" } } } } } }, "401": { "description": "需要登录会话" }, "400": { "description": "请求或插件包无效" }, "403": { "description": "不接受 API 令牌" }, "404": { "description": "插件或指定版本的资源不存在" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "put": { "summary": "替换插件私有 JSON，最多 1 MiB", "tags": [ "插件" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "type": "object", "required": [ "data" ], "properties": { "data": {} } }, "message": { "type": "string" } } } } } }, "401": { "description": "需要登录会话" }, "400": { "description": "请求或插件包无效" }, "403": { "description": "不接受 API 令牌" }, "404": { "description": "插件或指定版本的资源不存在" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": {} } } } } } } }, "/plugins/{id}/assets/{revision}/{path}": { "get": { "summary": "鉴权读取指定安装版本的包内资源", "tags": [ "插件" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "成功" }, "401": { "description": "需要登录会话" }, "400": { "description": "请求或插件包无效" }, "403": { "description": "不接受 API 令牌" }, "404": { "description": "插件或指定版本的资源不存在" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "revision", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/import": { "post": { "summary": "导入 Markdown 文件或 ZIP 知识库", "tags": [ "文件" ], "description": "多选 .md 或单个 ZIP，总上传不超过 100 MB；ZIP 必须指定新建文件夹名称。目标目录必须存在，冲突不覆盖。解压及整理后上限 512 MiB、10,000 项，单篇笔记 20 MiB、附件 50 MiB。Markdown 与 ZIP 文件名须为 UTF-8。ZIP 层级保留，本地图片生成笔记独立附件，原附件保留；外部链接不下载，缺失本地目标以警告返回。", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "files" ], "properties": { "dir": { "type": "string", "description": "目标目录，空字符串为根目录" }, "folder": { "type": "string", "description": "ZIP 的新建文件夹名称；普通 Markdown 留空" }, "files": { "type": "array", "items": { "type": "string", "format": "binary" } } } } } } }, "responses": { "201": { "description": "导入成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "type": "object", "required": [ "paths", "notes", "assets", "warnings" ], "properties": { "paths": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "integer" }, "assets": { "type": "integer", "description": "附件文件总数，包含原始附件和独立副本" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "message": { "type": "string" } } } } } }, "400": { "description": "格式、路径或编码无效" }, "401": { "description": "未登录或令牌无效" }, "403": { "description": "只读令牌不能导入" }, "404": { "description": "目标目录不存在" }, "409": { "description": "目标已存在，不覆盖" }, "413": { "description": "超过上传、解压、文件数量或单文件大小限制" } } } }, "/assets/{path}": { "put": { "summary": "原位替换已有图片，保留路径和引用", "tags": [ "图片" ], "parameters": [ { "name": "path", "in": "path", "required": true, "description": "仓库中的图片路径", "schema": { "type": "string" } } ], "description": "multipart file 字段的扩展名须与目标图片一致；不创建新文件，最大 50 MB。旧图片不会进入回收站。", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } }, "required": [ "file" ] } } } }, "responses": { "200": { "description": "替换成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "$ref": "#/components/schemas/Ok" }, "message": { "type": "string" } } } } } }, "400": { "description": "非法路径、空文件或扩展名不一致" }, "404": { "description": "目标图片不存在" }, "413": { "description": "超过 50 MB" } } } }, "/export": { "post": { "summary": "导出原始 Markdown 和本地附件", "description": "接收非空路径列表；单篇无附件返回 .md，目录、多选或含附件返回 ZIP。ZIP 保留仓库相对路径；不下载外部资源，不跟随其他未选中笔记。缺失附件或非法路径返回错误。此 POST 接口不修改数据，只读令牌可调用。", "tags": [ "文件" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "paths" ], "properties": { "paths": { "type": "array", "minItems": 1, "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "原始 Markdown 或 ZIP 附件", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "路径无效" }, "404": { "description": "文件或附件不存在" } } } }, "/metadata": { "get": { "summary": "读取笔记关系、标签与资源引用索引", "security": [ { "bearer": [] } ], "responses": { "200": { "description": "索引就绪状态与元数据列表，不含笔记正文", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "type": "object", "required": [ "notes", "ready" ], "properties": { "notes": { "type": "array", "items": { "$ref": "#/components/schemas/NoteMetadata" } }, "ready": { "type": "boolean" } } }, "message": { "type": "string" } } } } } } } } }, "/assets/cleanup": { "post": { "summary": "重新核对全库引用后，将孤立图片移入回收站", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "paths" ], "properties": { "paths": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "已移入回收站的图片及跳过原因", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "$ref": "#/components/schemas/CleanupImagesResult" }, "message": { "type": "string" } } } } } }, "400": { "description": "请求无效，或笔记元数据异常，无法确认引用" } } } }, "/tree-icon": { "put": { "summary": "设置单个文件或目录的图标，null 恢复默认", "tags": [ "文件" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "path", "icon" ], "properties": { "path": { "type": "string" }, "icon": { "oneOf": [ { "$ref": "#/components/schemas/TreeIcon" }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "$ref": "#/components/schemas/Ok" }, "message": { "type": "string" } } } } } }, "400": { "description": "非法路径或图标" }, "404": { "description": "文件不存在" } } } }, "/fonts": { "get": { "summary": "列出已导入字体", "tags": [ "设置" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "type": "object", "required": [ "fonts" ], "properties": { "fonts": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFont" } } } }, "message": { "type": "string" } } } } } }, "401": { "description": "未登录" }, "403": { "description": "只接受登录会话" } } }, "post": { "summary": "导入字体，按内容去重（TTF/OTF/WOFF/WOFF2，上限30 MB）", "tags": [ "设置" ], "security": [ { "bearer": [] } ], "responses": { "201": { "description": "新字体已导入", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "$ref": "#/components/schemas/CustomFont" }, "message": { "type": "string" } } } } } }, "401": { "description": "未登录" }, "403": { "description": "只接受登录会话" }, "200": { "description": "相同内容的字体已存在，返回原字体", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "$ref": "#/components/schemas/CustomFont" }, "message": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } } } }, "/fonts/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "删除导入字体，将使用它的界面、正文和代码字体恢复Maple；Maple不可删除", "tags": [ "设置" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "$ref": "#/components/schemas/Ok" }, "message": { "type": "string" } } } } } }, "401": { "description": "未登录" }, "403": { "description": "只接受登录会话" } } } }, "/fonts/{id}/file": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "读取导入字体文件", "tags": [ "设置" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "成功" }, "401": { "description": "未登录" }, "403": { "description": "只接受登录会话" } } } }, "/storage": { "get": { "summary": "按需统计存储空间", "description": "只接受登录会话。统计数据目录和实际笔记库的普通文件字节，嵌套去重，不跟随内部符号链接；附件/回收站是笔记库的子项，totalSize不重复累加。calculatedAt为统计完成时间（Unix毫秒）。扫描失败返回错误，不返回部分结果。", "tags": [ "设置" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "统计结果", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "$ref": "#/components/schemas/StorageUsage" }, "message": { "type": "string" } } } } } }, "403": { "description": "只接受登录会话" }, "500": { "description": "扫描失败" } } } }, "/maintenance/status": { "get": { "summary": "维护状态", "tags": [ "维护" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "$ref": "#/components/schemas/MaintenanceStatus" }, "message": { "type": "string" } } } } } }, "401": { "description": "未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "不接受API令牌", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/maintenance/export/{kind}": { "post": { "summary": "导出完整实例或设置包", "tags": [ "维护" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "ZIP下载", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "操作或输入无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "不接受API令牌", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "正在维护、磁盘空间不足或当前服务不支持此操作", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "文件系统、数据库或其他内部故障", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "kind", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/maintenance/notes/export": { "post": { "summary": "导出普通 Markdown 笔记库", "tags": [ "维护" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "ZIP下载", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "操作或输入无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "不接受API令牌", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "正在维护、磁盘空间不足或当前服务不支持此操作", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "文件系统、数据库或其他内部故障", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/maintenance/uploads": { "post": { "summary": "创建备份上传，压缩上限2GiB，分块上限8MiB", "tags": [ "维护" ], "security": [ { "bearer": [] } ], "responses": { "400": { "description": "操作或输入无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "不接受API令牌", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "正在维护、磁盘空间不足或当前服务不支持此操作", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "返回上传id", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } } }, "message": { "type": "string" } } } } } }, "500": { "description": "文件系统、数据库或其他内部故障", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "kind", "size" ], "properties": { "kind": { "type": "string", "enum": [ "full", "settings" ] }, "size": { "type": "integer", "minimum": 1, "maximum": 2147483648 } } } } } } } }, "/maintenance/uploads/{id}": { "put": { "summary": "顺序追加备份分块", "tags": [ "维护" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "type": "object", "required": [ "offset" ], "properties": { "offset": { "type": "integer" } } }, "message": { "type": "string" } } } } } }, "400": { "description": "操作或输入无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "不接受API令牌", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "正在维护、磁盘空间不足或当前服务不支持此操作", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "文件系统、数据库或其他内部故障", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Upload-Offset", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 0 } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } }, "delete": { "summary": "取消当前会话的上传", "tags": [ "维护" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "$ref": "#/components/schemas/Ok" }, "message": { "type": "string" } } } } } }, "400": { "description": "操作或输入无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "不接受API令牌", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "正在维护、磁盘空间不足或当前服务不支持此操作", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "文件系统、数据库或其他内部故障", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/maintenance/uploads/{id}/validate": { "post": { "summary": "校验归档并生成摘要，展开上限8GiB/100000项", "tags": [ "维护" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "$ref": "#/components/schemas/BackupSummary" }, "message": { "type": "string" } } } } } }, "400": { "description": "操作或输入无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "不接受API令牌", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "正在维护、磁盘空间不足或当前服务不支持此操作", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "文件系统、数据库或其他内部故障", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/maintenance/settings/import": { "post": { "summary": "确认后导入设置和资源，操作前备份", "tags": [ "维护" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "$ref": "#/components/schemas/Ok" }, "message": { "type": "string" } } } } } }, "400": { "description": "操作或输入无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "不接受API令牌", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "正在维护、磁盘空间不足或当前服务不支持此操作", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "文件系统、数据库或其他内部故障", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "confirmed", "id" ], "properties": { "confirmed": { "type": "boolean", "const": true }, "id": { "type": "string" } } } } } } } }, "/maintenance/settings/reset": { "post": { "summary": "确认后重置偏好，保留插件存储", "tags": [ "维护" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "$ref": "#/components/schemas/Ok" }, "message": { "type": "string" } } } } } }, "400": { "description": "操作或输入无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "不接受API令牌", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "正在维护、磁盘空间不足或当前服务不支持此操作", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "文件系统、数据库或其他内部故障", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "confirmed" ], "properties": { "confirmed": { "type": "boolean", "const": true } } } } } } } }, "/maintenance/restore": { "post": { "summary": "确认后恢复完整实例，操作前备份并重新登录", "tags": [ "维护" ], "security": [ { "bearer": [] } ], "responses": { "400": { "description": "操作或输入无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "不接受API令牌", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "正在维护、磁盘空间不足或当前服务不支持此操作", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "已提交恢复；服务将短暂维护并要求重新登录", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "type": "object", "required": [ "restarting" ], "properties": { "restarting": { "type": "boolean" } } }, "message": { "type": "string" } } } } } }, "500": { "description": "文件系统、数据库或其他内部故障", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "confirmed", "id" ], "properties": { "confirmed": { "type": "boolean", "const": true }, "id": { "type": "string" } } } } } } } }, "/maintenance/index/{operation}": { "post": { "summary": "优化或重建索引", "tags": [ "维护" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "$ref": "#/components/schemas/Ok" }, "message": { "type": "string" } } } } } }, "400": { "description": "操作或输入无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "不接受API令牌", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "正在维护、磁盘空间不足或当前服务不支持此操作", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "文件系统、数据库或其他内部故障", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "operation", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/maintenance/temp/clear": { "post": { "summary": "清理本程序未使用临时文件", "tags": [ "维护" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "$ref": "#/components/schemas/ClearTempResult" }, "message": { "type": "string" } } } } } }, "400": { "description": "操作或输入无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "不接受API令牌", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "正在维护、磁盘空间不足或当前服务不支持此操作", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "文件系统、数据库或其他内部故障", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/maintenance/logs/export": { "post": { "summary": "导出应用日志和运行摘要", "tags": [ "维护" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "ZIP下载", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "操作或输入无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "未登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "不接受API令牌", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "正在维护、磁盘空间不足或当前服务不支持此操作", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "文件系统、数据库或其他内部故障", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/me": { "get": { "summary": "恢复登录会话身份与权限", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "type": "object", "required": [ "permissions", "expiresAt" ], "properties": { "permissions": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": "string", "format": "date-time" } } }, "message": { "type": "string" } } } } } }, "401": { "description": "登录凭据无效或过期", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "需要登录会话，API令牌无权调用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/captcha": { "post": { "summary": "签发5分钟、单次登录验证码", "security": [ {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "replaceId": { "type": "string" } } } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "type": "object", "required": [ "captchaId", "imageDataUrl", "expiresAt" ], "properties": { "captchaId": { "type": "string" }, "imageDataUrl": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "message": { "type": "string" } } } } } }, "429": { "description": "验证码签发频率或容量限制", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/tickets": { "post": { "summary": "签发绑定当前会话的资源读取或一次性事件票据", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "enum": [ "images", "fonts", "plugin", "events" ] }, "pluginId": { "type": "string" }, "revision": { "type": "string" } } } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "const": 0 }, "data": { "type": "object", "required": [ "url", "expiresAt" ], "properties": { "url": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "message": { "type": "string" } } } } } }, "401": { "description": "登录凭据无效或过期", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "需要登录会话，API令牌无权调用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/resources/{ticket}/{kind}/{path}": { "get": { "summary": "受限原生资源；事件票据60秒一次性，其余跟随父会话到期，每次检查父会话", "security": [ {} ], "parameters": [ { "name": "ticket", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "对应资源原始内容" }, "101": { "description": "WebSocket事件升级" } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "API 令牌（rm_ 开头）" } }, "schemas": { "Error": { "type": "object", "required": [ "code", "data", "message" ], "properties": { "code": { "type": "integer", "minimum": 1 }, "data": { "type": [ "object", "null" ] }, "message": { "type": "string" } } }, "Ok": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] }, "Entry": { "type": "object", "properties": { "path": { "type": "string" }, "dir": { "type": "boolean" }, "size": { "type": "integer" }, "mtime": { "type": "integer", "description": "修改时间（Unix 毫秒）" }, "icon": { "$ref": "#/components/schemas/TreeIcon" } } }, "TrashItem": { "type": "object", "properties": { "id": { "type": "string" }, "path": { "type": "string", "description": "原路径" }, "dir": { "type": "boolean" }, "deletedAt": { "type": "integer", "description": "Unix 毫秒" }, "assets": { "type": "string", "description": "随条目保存的旧图片目录，可省略" } }, "required": [ "id", "path", "dir", "deletedAt" ] }, "SearchResult": { "type": "object", "properties": { "path": { "type": "string" }, "line": { "type": "integer", "description": "第一处匹配所在行（从 1 开始）；只有路径匹配时为 0" }, "snippet": { "type": "string" } } }, "Event": { "type": "object", "description": "tree：目录结构变化；changed：内容变化（rev 为新版本）；deleted：删除；moved：移动（from → path）；settings：设置变化", "properties": { "type": { "type": "string", "enum": [ "tree", "changed", "deleted", "moved", "settings" ] }, "path": { "type": "string" }, "from": { "type": "string" }, "rev": { "type": "string" } } }, "APIToken": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "scope": { "type": "string", "enum": [ "read", "write" ] }, "createdAt": { "type": "integer" }, "lastUsedAt": { "type": "integer", "description": "Unix 毫秒，0 为从未使用" } } }, "Theme": { "type": "object", "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "Plugin": { "type": "object", "required": [ "id", "name", "version", "apiVersion", "revision", "enabled" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "revision": { "type": "string" }, "apiVersion": { "type": "integer", "const": 1 }, "enabled": { "type": "boolean" } } }, "TreeIcon": { "type": "object", "required": [ "kind", "value" ], "properties": { "kind": { "type": "string", "enum": [ "emoji", "builtin" ] }, "value": { "type": "string", "description": "Emoji 字符或内置线性图标名称，最多64字节" } } }, "TrashPurgeResult": { "type": "object", "required": [ "deleted", "failed" ], "properties": { "deleted": { "type": "array", "items": { "type": "string" } }, "failed": { "type": "array", "items": { "type": "object", "required": [ "id", "error" ], "properties": { "id": { "type": "string" }, "error": { "type": "string" } } } } } }, "StorageUsage": { "type": "object", "required": [ "totalSize", "categories", "assetsSize", "trashSize", "calculatedAt", "builtinFontsSize", "customFontsSize" ], "properties": { "totalSize": { "type": "integer", "minimum": 0 }, "assetsSize": { "type": "integer", "minimum": 0 }, "trashSize": { "type": "integer", "minimum": 0 }, "calculatedAt": { "type": "integer", "minimum": 0 }, "categories": { "type": "array", "items": { "type": "object", "required": [ "id", "size" ], "properties": { "id": { "type": "string", "enum": [ "vault", "databases", "fonts", "themes", "plugins", "other" ] }, "size": { "type": "integer", "minimum": 0 } } } }, "builtinFontsSize": { "type": "integer", "minimum": 0 }, "customFontsSize": { "type": "integer", "minimum": 0 } } }, "NoteReference": { "type": "object", "required": [ "target", "line" ], "properties": { "target": { "type": "string" }, "line": { "type": "integer" } } }, "NoteMetadata": { "type": "object", "required": [ "path", "rev", "title", "tags", "links", "assets", "warnings" ], "properties": { "path": { "type": "string" }, "rev": { "type": "string" }, "title": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/NoteReference" } }, "assets": { "type": "array", "items": { "$ref": "#/components/schemas/NoteReference" } }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "CleanupImagesResult": { "type": "object", "required": [ "deleted", "skipped" ], "properties": { "deleted": { "type": "array", "items": { "$ref": "#/components/schemas/TrashItem" } }, "skipped": { "type": "array", "items": { "type": "object", "required": [ "path", "reason" ], "properties": { "path": { "type": "string" }, "reason": { "type": "string" } } } } } }, "CustomFont": { "type": "object", "required": [ "id", "name", "format" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "format": { "type": "string", "enum": [ "ttf", "otf", "woff", "woff2" ] } } }, "MaintenanceStatus": { "type": "object", "required": [ "busy", "operation", "error", "finishedAt" ], "properties": { "busy": { "type": "boolean" }, "operation": { "type": "string" }, "error": { "type": "string" }, "finishedAt": { "type": "integer" }, "backup": { "type": "string" } } }, "BackupSummary": { "type": "object", "required": [ "kind", "createdAt", "entries", "size" ], "properties": { "kind": { "type": "string", "enum": [ "full", "settings" ] }, "createdAt": { "type": "integer" }, "entries": { "type": "integer" }, "size": { "type": "integer" } } }, "ClearTempResult": { "type": "object", "required": [ "files", "bytes", "failed" ], "properties": { "files": { "type": "integer" }, "bytes": { "type": "integer" }, "failed": { "type": "array", "items": { "type": "string" } } } } } }, "x-business-codes": { "0": "成功", "40000": "参数无效", "40001": "验证码错误或已使用", "40002": "验证码过期", "40003": "当前密码错误", "40100": "认证无效", "40101": "登录密码错误", "40300": "权限不足", "40400": "资源不存在", "40900": "资源冲突", "41200": "文档版本冲突，data.rev为最新版本", "41300": "超过大小上限", "42900": "请求过于频繁", "50000": "服务端错误", "50300": "维护中" } }