opensource/AstrBot
3
0
Fork 0
mirror of https://github.com/AstrBotDevs/AstrBot.git synced 2026-10-16 15:06:04 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
f99c76ec106f9d47a909393e463197687eec4070
AstrBot/docs/zh/dev/openapi-scopes.md
T
Ruochen Pan f99c76ec10 fix(dashboard): bound upload memory and add resumable chunked uploads (#10123) 
* refactor(dashboard): consolidate upload saves into streaming helper

Five copies of the same upload-save logic existed: three file wrappers
(UploadFileAdapter, RequestUploadFile, PluginUploadFile) plus one
_save_upload() in each of BackupService and SkillsService. The backup
variant fell back to a full-body read() for raw FastAPI UploadFile,
buffering entire uploads in memory.

Introduce save_upload_stream() as the single streaming implementation
(1 MiB blocks, optional max_bytes with in-loop abort and partial-file
cleanup). The wrappers keep their public signatures and delegate to it;
skills/chat/config save paths call save() directly with max_bytes,
replacing their post-save size checks.

* fix(dashboard): bound backup upload size and harden chunked flow

Backup routes passed raw FastAPI UploadFile into the service layer,
hitting the full-body read() fallback: a single authenticated request
with an oversized chunk or whole-file upload could OOM-kill the
process (verified with a 512 MiB memory-limited container, exit 137).

- Wrap uploads in UploadFileAdapter so all saves stream to disk
- Enforce CHUNK_SIZE (1 MiB) per chunk and 128 MiB for whole-file
  uploads, aborting mid-stream with partial-file cleanup
- Cap chunked backup totals at 8 GiB and point larger backups at
  manual restore via the data directory
- Verify the merged backup size against the declared total

* fix(dashboard): enforce MAX_CONTENT_LENGTH with per-route overrides

The 128 MiB MAX_CONTENT_LENGTH value was written into the compat-layer
config dict but nothing read it, so the FastAPI/hypercorn path had no
request body limit at all.

Add a middleware that rejects oversized bodies with 413 before auth or
body parsing, using MAX_CONTENT_LENGTH as the default with per-route
overrides for legitimate large uploads (attachments 512 MiB, plugin
config files 500 MiB, knowledge bases 512 MiB) and a tight 2 MiB cap
on the backup chunk endpoint. Requests without a Content-Length header
pass through and remain bounded by per-endpoint max_bytes at save time.

* refactor(dashboard): extract generic chunked upload session service

Pull the chunk session machinery out of BackupService into a reusable
ChunkedUploadService owning session lifecycle, chunk storage, streaming
assembly and expiry cleanup, in preparation for webchat attachment
chunked uploads.

Sessions are now bound to an owner (the authenticated username) and a
purpose; chunk/complete/abort calls from another owner fail with the
same "not found or expired" error as unknown sessions, so upload IDs
cannot be probed or consumed cross-user. BackupService keeps business
concerns (zip validation, size caps, manifest marking) and delegates
the rest; API shapes and frontend flows are unchanged.

* feat(dashboard): add resumable upload status endpoint

Expose per-session progress (received chunk indexes, totals, expiry)
so clients can resume an interrupted chunked upload by sending only
the missing chunks instead of starting over.

Abuse considerations baked in: the lookup inherits owner binding and
answers "not found or expired" for both unknown sessions and sessions
owned by someone else (no probing), the response carries no filename
(minimal disclosure), and the query is strictly read-only — it never
touches last_activity, so polling it cannot anchor a session and its
on-disk chunks alive past expiry.

* fix(dashboard): bound file signature memory with chunked hashing

getFileSignature() read the entire file into browser memory via
arrayBuffer() before computing SHA-256, spiking renderer memory by the
full attachment size (up to the 512 MiB upload cap).

The signature is only used for in-session staging dedup and never
leaves the browser, so it does not need to be the canonical whole-file
SHA-256. Hash 8 MiB blocks individually and digest the concatenated
block digests instead; the prefix changes to sha256m: to mark the
algorithm change (old signatures vanish with the page session, so no
compatibility concern).

* feat(dashboard): resumable chunked upload UI for backup import

Extract the chunk scheduling logic from BackupDialog into a reusable
useChunkedUpload composable (5-way concurrency, per-chunk silent
retries, progress accounting) and add resume support on top of the
new upload status endpoint: a failed upload now offers a "Resume
Upload" action that queries received chunk indexes and sends only the
missing ones. Expired sessions transparently re-initialize and start
over; a failed complete() drops the poisoned session by design.

Wires the new /backups/upload/status endpoint through the OpenAPI
spec and regenerated client, and adds the resumeUpload label to all
four locales.

* feat(dashboard): chunked upload endpoints for webchat attachments

Mirror the backup chunked-upload flow for chat attachments so large
files (>128 MiB request-body default, up to the 512 MiB attachment
cap) can be uploaded in slices: POST /api/v1/files/upload/{init,
chunk,complete,abort,status}, owner-bound sessions, and a per-route
body limit on the chunk endpoint.

ChatService reuses the generic ChunkedUploadService with a new meta
passthrough carrying the client content_type through the session;
completion merges outside the chunk dir and feeds the result through
save_uploaded_file() unchanged via a move-based LocalUploadFile
adapter, keeping MIME sniffing, type classification and attachment
insertion in exactly one place.

Also repairs two pre-existing test stubs that predated the
max_bytes-aware save() contract and were already failing on this
branch.

* feat(dashboard): chunked upload with resume for webchat attachments

Route staged files >= 32 MiB through the new chunked upload endpoints
via useChunkedUpload; smaller files keep the single POST path so paste
and quick picks stay low-latency. The content_type travels through the
init payload so server-side attachment classification is unchanged.

A failed chunked upload is kept as an error chip in the input area
with a retry action that resumes from the last received chunk (and
transparently restarts when the session expired) plus a discard action
that aborts the session. Failed entries hold their uploader in a
shallowRef so Vue's deep ref unwrapping cannot strip the composable's
internal refs, and their signatures stay reserved to block duplicate
staging while a failed entry exists.

* docs: regenerate openapi artifacts for file upload endpoints

* fix(dashboard): harden chunk save and request body limits

Address review findings on the upload-hardening branch:

- save_chunk() now writes to a uniquely named temp file, verifies the
  save() byte count against the expected chunk length, and publishes
  via atomic rename. A failed or concurrent same-index retry can no
  longer truncate and delete an already-received chunk (previously
  left received_chunks claiming data that assemble() then failed to
  find), and short writes are rejected instead of published.
- Requests with multipart bodies but no Content-Length are rejected
  with 411: form parsing spools large bodies to disk before any
  per-file size check can run. This is a documented stopgap — other
  lengthless bodies still pass and are bounded only at save time;
  closing that fully requires counting bytes as they arrive.
- Whole-file upload overrides gain 1 MiB of multipart framing slack
  so a file exactly at the size cap is no longer rejected with 413.

The body-limit decision is extracted into a pure function for direct
unit tests; the assemble-time size recheck is now covered by an
out-of-band corruption test since chunk-level verification rejects
short writes earlier.

* fix(dashboard): drain upload pool and pin session on resume

A failed chunk made runPool() reject immediately while the remaining
in-flight requests kept writing; a resume could then race them on the
same chunk, stale retries read the mutable uploadId (potentially
writing into a re-initialized session), and late completions kept
counting progress (150% after resume).

The pool now stops scheduling on first failure but drains issued
requests via allSettled before surfacing the error, each request pins
the uploadId captured at run start, and a run-generation counter
(bumped on start/resume/cancel) blocks stale completions from the
progress accounting.

* fix(dashboard): close 411 bypass and temp-file residue on publish

Address the second round of review findings:

- The 411 media-type check used a raw startswith(), but the form
  parser strips surrounding whitespace, so a leading-space
  Content-Type was let through without a Content-Length while
  Starlette still parsed the body as multipart. Detection now uses
  the same parse_options_header the parser uses.
- A failing os.replace() during chunk publish left the uniquely
  named temp file behind; it is now covered by the same cleanup
  discipline as the save path.

Backup direct-upload routes deliberately get no framing slack: they
are legacy paths with no remaining callers, and the pre-existing
exact-limit 413 edge is answered by chunked upload.

* fix(dashboard): abort sessions created after a cancel

Cancelling while initUpload was still in flight cleared local state
before an upload id existed; when the delayed init returned, the run
flipped from idle to error and the freshly created server session was
never aborted. handleFailure now lets cancel win over any late
resolution and aborts the session id captured at that point.

* fix(dashboard): check cancel flag after completeUpload resolves

Cancelling while completeUpload was in flight let the late success
response flip the uploader from idle to done and hand the result to
the caller, which proceeded to the precheck. completeSession() now
re-checks the cancel flag after the response arrives and routes the
late success through the cancelled path instead.

* fix(dashboard): gate the 411 rule to body-capable methods

The 411 stopgap rejected GET /api/v1/logs/live: the SSE log client
sends a bogus "Content-Type: multipart/form-data" header on a GET
(copy-paste relic), and a GET with no Content-Length matched the
multipart-without-length rule. Body-less methods never trigger form
parsing, so no disk-spool risk exists for them — the 411 now applies
only to POST/PUT/PATCH. The junk header on the SSE client is removed
as well; the other two SSE consumers never had it.

* feat(dashboard): show in-progress chips for chunked attachments

Chunked uploads gave no feedback while in flight: the staged chip
only appeared after completion, leaving multi-minute uploads silent.
Track in-flight uploads alongside the failed ones and render progress
chips (filename, percent, thin progress bar) with a cancel action in
the input area; on success the chip hands off to the staged
attachment, on failure to the resumable error chip.

* fix(dashboard): type active upload chips upfront and align progress bar

The in-progress chip used a generic cloud icon even though the file
type is known locally before the upload starts; it now derives
icon/color/label from the filename via attachmentPresentation, same
as the staged chip. The progress bar's left edge is aligned with the
filename text instead of the card padding.

* fix(dashboard): keep active-chip progress bar inside the card

v-progress-linear ships width:100%, which wins over the right offset
in absolute positioning; the bar ran 52px past the card's right edge
and was clipped by overflow:hidden. Give it width:auto so the left/
right offsets determine the width.

* fix(dashboard): rework active-chip progress track and cancel button

Positioning a Vuetify component root directly proved fragile — the
progress bar drifted to the card's top edge. Wrap it in a plain track
div that owns the absolute positioning and let the component fill it.
Replace the corner tonal badge cancel with an inline text-variant
icon button after the percent label, and drop the padding reserved
for the badge.

* fix(dashboard): enforce session expiry and atomic save semantics

Address the third review round (sourcery-ai findings):

- get_session() now actually enforces the idle expiry it advertises
  in its "not found or expired" error; expired sessions stay
  abortable for cleanup, and backup upload_init starts the janitor
  just like chat's does, so chunk dirs cannot linger indefinitely.
- cleanup_session() only unregisters a session after rmtree()
  succeeds, letting the janitor retry on transient filesystem errors
  instead of permanently leaking the chunk directory.
- save_upload_stream() writes to a uniquely named temp sibling and
  atomically renames on success, so a failed or cancelled overwrite
  can no longer delete a pre-existing destination (e.g. re-uploading
  over an existing attachment), and all callers inherit the behavior.

The write()-return-value finding is a non-issue: BufferedWriter
writes fully or raises, and the chunk path already verifies byte
counts.

* fix(dashboard): guard failed-upload retry against double clicks

retryFailedUpload() ran resume() without any in-flight marker, so a
second click started a concurrent resume on the same session; the
loser hit "not found or expired" and left a failed chip next to the
successfully staged attachment. The entry now moves to activeUploads
while resuming, which blocks the second click and shows live
progress, and returns to failedUploads only if the resume errors.
2026-09-18 17:55:30 +08:00

14 KiB
Raw Blame History

outline
outline
deep

API Scope 与接口对照

本页由 openspec/openapi-v1.yaml 自动生成。每个接口的基础权限来自 x-astrbot-scope；敏感操作还会列出需要显式授予的子权限。

bot

管理机器人及平台配置。

方法 接口 条件性敏感子权限
GET /api/v1/bot-types —
GET /api/v1/bots —
POST /api/v1/bots —
GET /api/v1/bots/by-id —
PUT /api/v1/bots/by-id —
DELETE /api/v1/bots/by-id —
PATCH /api/v1/bots/enabled —
GET /api/v1/bots/stats —
POST /api/v1/bots/test —
GET /api/v1/bots/{bot_id} —
PUT /api/v1/bots/{bot_id} —
DELETE /api/v1/bots/{bot_id} —
PATCH /api/v1/bots/{bot_id}/enabled —
POST /api/v1/bots/{bot_id}/test —

provider

管理模型服务提供商和提供商源。

方法 接口 条件性敏感子权限
GET /api/v1/provider-sources —
POST /api/v1/provider-sources —
GET /api/v1/provider-sources/by-id —
PUT /api/v1/provider-sources/by-id —
DELETE /api/v1/provider-sources/by-id —
GET /api/v1/provider-sources/models —
GET /api/v1/provider-sources/providers —
POST /api/v1/provider-sources/providers —
GET /api/v1/provider-sources/{source_id} —
PUT /api/v1/provider-sources/{source_id} —
DELETE /api/v1/provider-sources/{source_id} —
GET /api/v1/provider-sources/{source_id}/models —
GET /api/v1/provider-sources/{source_id}/providers —
POST /api/v1/provider-sources/{source_id}/providers —
GET /api/v1/providers —
POST /api/v1/providers —
GET /api/v1/providers/by-id —
PUT /api/v1/providers/by-id —
DELETE /api/v1/providers/by-id —
POST /api/v1/providers/embedding-dimension —
PATCH /api/v1/providers/enabled —
GET /api/v1/providers/schema —
POST /api/v1/providers/test —
GET /api/v1/providers/{provider_id} —
PUT /api/v1/providers/{provider_id} —
DELETE /api/v1/providers/{provider_id} —
POST /api/v1/providers/{provider_id}/embedding-dimension —
PATCH /api/v1/providers/{provider_id}/enabled —
POST /api/v1/providers/{provider_id}/test —

persona

管理人格设定和人格文件夹。

方法 接口 条件性敏感子权限
GET /api/v1/persona-folders —
POST /api/v1/persona-folders —
PUT /api/v1/persona-folders/{folder_id} —
DELETE /api/v1/persona-folders/{folder_id} —
GET /api/v1/personas —
POST /api/v1/personas —
GET /api/v1/personas/by-id —
PUT /api/v1/personas/by-id —
DELETE /api/v1/personas/by-id —
POST /api/v1/personas/move —
POST /api/v1/personas/reorder —
GET /api/v1/personas/tree —
GET /api/v1/personas/{persona_id} —
PUT /api/v1/personas/{persona_id} —
DELETE /api/v1/personas/{persona_id} —

im

主动发送 IM 消息，并查询机器人或平台标识。

方法 接口 条件性敏感子权限
GET /api/v1/im/bots —
POST /api/v1/im/messages —

config

管理配置文件、系统配置和通用配置，但不包含修改 admins_id 的能力。

  • 包含权限: bot、provider

  • 敏感子权限 config:edit_admin: 允许具有 config 权限的 Key 修改 admins_id。该子权限必须显式授予。

方法 接口 条件性敏感子权限
POST /api/v1/bot-types/{bot_type}/registration —
GET /api/v1/config-profiles —
POST /api/v1/config-profiles config:edit_admin
GET /api/v1/config-profiles/schema —
GET /api/v1/config-profiles/{config_id} —
PUT /api/v1/config-profiles/{config_id} config:edit_admin
PATCH /api/v1/config-profiles/{config_id} —
DELETE /api/v1/config-profiles/{config_id} —
GET /api/v1/config-routes —
PUT /api/v1/config-routes —
PUT /api/v1/config-routes/{umo} —
DELETE /api/v1/config-routes/{umo} —
GET /api/v1/subagents/available-tools —
GET /api/v1/subagents/config —
PUT /api/v1/subagents/config —
GET /api/v1/system-config —
PUT /api/v1/system-config config:edit_admin
GET /api/v1/system-config/runtime —
GET /api/v1/system-config/schema —
GET /api/v1/t2i/templates —
POST /api/v1/t2i/templates —
GET /api/v1/t2i/templates/active —
PUT /api/v1/t2i/templates/active —
POST /api/v1/t2i/templates/default/reset —
GET /api/v1/t2i/templates/{name} —
PUT /api/v1/t2i/templates/{name} —
DELETE /api/v1/t2i/templates/{name} —

chat

调用对话能力，并管理 ChatUI 会话和项目。

  • 敏感子权限 chat:admin: 允许 username 使用 AstrBot 中已配置的管理员 ID。该子权限必须显式授予。
方法 接口 条件性敏感子权限
POST /api/v1/chat chat:admin
GET /api/v1/chat/configs —
GET /api/v1/chat/projects —
POST /api/v1/chat/projects —
DELETE /api/v1/chat/projects/sessions/{session_id} —
GET /api/v1/chat/projects/{project_id} —
PATCH /api/v1/chat/projects/{project_id} —
DELETE /api/v1/chat/projects/{project_id} —
GET /api/v1/chat/projects/{project_id}/sessions —
POST /api/v1/chat/projects/{project_id}/sessions/{session_id} —
GET /api/v1/chat/projects/{project_id}/workspace/file —
GET /api/v1/chat/projects/{project_id}/workspace/file/download —
GET /api/v1/chat/projects/{project_id}/workspace/files —
GET /api/v1/chat/runs/{run_id}/stream —
GET /api/v1/chat/sessions —
POST /api/v1/chat/sessions/batch-delete —
GET /api/v1/chat/sessions/new —
GET /api/v1/chat/sessions/{session_id} —
PATCH /api/v1/chat/sessions/{session_id} —
DELETE /api/v1/chat/sessions/{session_id} —
PATCH /api/v1/chat/sessions/{session_id}/messages/{message_id} —
POST /api/v1/chat/sessions/{session_id}/messages/{message_id}/regenerate —
POST /api/v1/chat/sessions/{session_id}/stop —
POST /api/v1/chat/threads —
GET /api/v1/chat/threads/{thread_id} —
DELETE /api/v1/chat/threads/{thread_id} —
POST /api/v1/chat/threads/{thread_id}/messages —
GET /api/v1/chat/ws chat:admin

data

管理对话记录和平台会话数据。

方法 接口 条件性敏感子权限
GET /api/v1/conversations —
POST /api/v1/conversations/batch-delete —
POST /api/v1/conversations/export —
GET /api/v1/conversations/filter-options —
GET /api/v1/conversations/{conversation_id} —
PATCH /api/v1/conversations/{conversation_id} —
DELETE /api/v1/conversations/{conversation_id} —
PUT /api/v1/conversations/{conversation_id}/messages —
GET /api/v1/session-groups —
POST /api/v1/session-groups —
PUT /api/v1/session-groups/{group_id} —
DELETE /api/v1/session-groups/{group_id} —
GET /api/v1/sessions —
GET /api/v1/sessions/active-umos —
PATCH /api/v1/sessions/provider —
GET /api/v1/sessions/rules —
POST /api/v1/sessions/rules —
POST /api/v1/sessions/rules/delete —
PATCH /api/v1/sessions/service —

file

上传和下载对话附件。

方法 接口 条件性敏感子权限
GET /api/v1/file —
POST /api/v1/file —
POST /api/v1/files —
GET /api/v1/files/content —
POST /api/v1/files/upload/abort —
POST /api/v1/files/upload/chunk —
POST /api/v1/files/upload/complete —
POST /api/v1/files/upload/init —
POST /api/v1/files/upload/status —
GET /api/v1/files/{attachment_id} —
DELETE /api/v1/files/{attachment_id} —
GET /api/v1/files/{attachment_id}/content —

plugin

管理插件、插件配置、插件源和插件市场数据。

方法 接口 条件性敏感子权限
GET /api/v1/plugin-sources —
POST /api/v1/plugin-sources —
PUT /api/v1/plugin-sources —
DELETE /api/v1/plugin-sources/by-id —
DELETE /api/v1/plugin-sources/{source_id} —
GET /api/v1/plugins —
GET /api/v1/plugins/by-id —
DELETE /api/v1/plugins/by-id —
GET /api/v1/plugins/changelog —
GET /api/v1/plugins/config —
PUT /api/v1/plugins/config —
GET /api/v1/plugins/config-files —
POST /api/v1/plugins/config-files —
DELETE /api/v1/plugins/config-files —
GET /api/v1/plugins/config/schema —
PATCH /api/v1/plugins/enabled —
GET /api/v1/plugins/extensions/{plugin_path} —
POST /api/v1/plugins/extensions/{plugin_path} —
PUT /api/v1/plugins/extensions/{plugin_path} —
PATCH /api/v1/plugins/extensions/{plugin_path} —
DELETE /api/v1/plugins/extensions/{plugin_path} —
GET /api/v1/plugins/failed —
DELETE /api/v1/plugins/failed/{plugin_id} —
POST /api/v1/plugins/failed/{plugin_id}/reload —
POST /api/v1/plugins/install/git —
POST /api/v1/plugins/install/github —
POST /api/v1/plugins/install/upload —
POST /api/v1/plugins/install/url —
GET /api/v1/plugins/market —
GET /api/v1/plugins/market/categories —
GET /api/v1/plugins/page —
GET /api/v1/plugins/page-bridge-sdk.js —
GET /api/v1/plugins/page/assets —
GET /api/v1/plugins/pages —
GET /api/v1/plugins/readme —
POST /api/v1/plugins/reload —
POST /api/v1/plugins/update —
POST /api/v1/plugins/validate/repo —
POST /api/v1/plugins/version-support/check —
GET /api/v1/plugins/{plugin_id} —
DELETE /api/v1/plugins/{plugin_id} —
GET /api/v1/plugins/{plugin_id}/changelog —
GET /api/v1/plugins/{plugin_id}/config —
PUT /api/v1/plugins/{plugin_id}/config —
DELETE /api/v1/plugins/{plugin_id}/config-files —
GET /api/v1/plugins/{plugin_id}/config-files/{config_key} —
POST /api/v1/plugins/{plugin_id}/config-files/{config_key} —
GET /api/v1/plugins/{plugin_id}/config/schema —
PATCH /api/v1/plugins/{plugin_id}/enabled —
PUT /api/v1/plugins/{plugin_id}/log-level —
GET /api/v1/plugins/{plugin_id}/pages —
GET /api/v1/plugins/{plugin_id}/pages/{page_name} —
GET /api/v1/plugins/{plugin_id}/pages/{page_name}/assets/{asset_path} —
GET /api/v1/plugins/{plugin_id}/readme —
POST /api/v1/plugins/{plugin_id}/reload —
POST /api/v1/plugins/{plugin_id}/source —
POST /api/v1/plugins/{plugin_id}/update —

mcp

管理 MCP 服务器配置和服务端同步。

方法 接口 条件性敏感子权限
POST /api/v1/mcp/providers/modelscope/sync —
GET /api/v1/mcp/servers —
POST /api/v1/mcp/servers —
PUT /api/v1/mcp/servers/by-name —
DELETE /api/v1/mcp/servers/by-name —
PATCH /api/v1/mcp/servers/enabled —
POST /api/v1/mcp/servers/test —
PUT /api/v1/mcp/servers/{server_name} —
DELETE /api/v1/mcp/servers/{server_name} —
PATCH /api/v1/mcp/servers/{server_name}/enabled —
POST /api/v1/mcp/servers/{server_name}/test —

skill

管理 Skills、Skill 压缩包、Skill 文件和 Shipyard Neo Skill 流程。

方法 接口 条件性敏感子权限
GET /api/v1/skills —
POST /api/v1/skills —
GET /api/v1/skills/archive —
POST /api/v1/skills/batch —
PATCH /api/v1/skills/by-name —
DELETE /api/v1/skills/by-name —
GET /api/v1/skills/file —
PUT /api/v1/skills/file —
GET /api/v1/skills/files —
GET /api/v1/skills/neo/candidates —
POST /api/v1/skills/neo/candidates/delete —
POST /api/v1/skills/neo/evaluate —
GET /api/v1/skills/neo/payload —
POST /api/v1/skills/neo/promote —
GET /api/v1/skills/neo/releases —
POST /api/v1/skills/neo/releases/delete —
POST /api/v1/skills/neo/rollback —
POST /api/v1/skills/neo/sync —
PATCH /api/v1/skills/{skill_name} —
DELETE /api/v1/skills/{skill_name} —
GET /api/v1/skills/{skill_name}/archive —
GET /api/v1/skills/{skill_name}/files —
GET /api/v1/skills/{skill_name}/files/{file_path} —
PUT /api/v1/skills/{skill_name}/files/{file_path} —
Reference in New Issue View Git Blame Copy Permalink