475 行
34 KiB
Markdown
475 行
34 KiB
Markdown
# A7 · main.py 插件入口 + backend/routes 路由层 + 权限矩阵
|
||
|
||
> 审计范围(实际逐行读过的文件):
|
||
> `main.py`、`backend/route_registry.py`、`adapters/astrbot_adapter.py`、`core/identity.py`、`core/security.py`、`core/media_proxy.py`、
|
||
> `backend/routes/`(`common.py` `params.py` `profile_routes.py` `workflow_routes.py` `node_routes.py` `round_routes.py` `job_routes.py`
|
||
> `image_routes.py` `media_routes.py` `log_routes.py` `history_routes.py` `settings_routes.py` `data_backup_routes.py` `wardrobe_routes.py`
|
||
> `integration_routes.py` `advanced_material_routes.py` `prompt_routes.py` `event_routes.py`,其余 17 个文件通过脚本提取 def+guard 全量比对)、
|
||
> `backend/dto/common.py`、`backend/dto/job_dto.py`、`backend/dto/workflow_round_dto.py`、
|
||
> `backend/services/profile_service.py`、`workflow_service.py`、`workflow_round_service.py`、`resource_access_service.py`、`image_service.py`、
|
||
> `queue_service.py`、`media_service.py`、`generation_service.py`(权限相关片段)、`prompt_governance_service.py`、`wardrobe_service.py`、
|
||
> `profile_document_import_service.py`、`model_provider_bootstrap.py`、`database/db_helper.py`(Database 构造)、
|
||
> `frontend/shared/api/client.ts`、`frontend/shared/api/endpoints.ts`
|
||
>
|
||
> 已按要求忽略 `.tmp/`、`release/`、`node_modules/`、`__pycache__/`、`web/assets/`、`pages/imagestudio/assets/`。
|
||
|
||
## 摘要
|
||
|
||
`PERMISSION_MATRIX` 只是一张**声明式清单**——`dispatch_extension_request()` 从头到尾没有读过 `RouteMatch.permission`,真正的鉴权全靠每个 handler 里手写的 `require_*(ctx)`。我用脚本把 169 条 `RouteSpec` 与 handler 内实际调用的 `require_*` 逐条比对,**声明与实现在权限"类别"上基本对得上**(这点做得不错),但矩阵本身在运行时被上游架空:`main.py` 的桥接层给任何登录用户无条件发放 `can_write / can_manage_config / can_manage_materials / can_retry_tasks` 全部四项,于是六级权限矩阵在生产路径上塌缩成"登录 / 未登录"两级。
|
||
|
||
更严重的是**归属校验的覆盖不完整**:profile 与 round 两条链路正确接入了 owner 校验(`ProfileService._require_owner` / `ResourceAccessService.require_node`),而 workflow / node / image / job / history 五条链路的 service 方法**根本不接收 ctx**,任何登录用户凭 ID 即可读写他人的工作流、节点、图片与任务队列(`GET jobs` 甚至直接返回他人完整的生成请求体)。
|
||
|
||
此外还有三个结构性问题:客户端可自带 `content_permissions` / `entrypoint` 绕过成人内容路由闸门;所有 service 构造都发生在 `require_*` 之前(未授权请求即可触发重型 provider 初始化 + DB 写入,且构造期异常逃出 `handle_request` 直接 500);157 个 handler 是完全同构的三行样板 + 22 个各自为政的 `_create_*_service()` 工厂。
|
||
|
||
---
|
||
|
||
## 发现
|
||
|
||
### [P0-致命] 桥接层给所有登录用户发放全部权限,PERMISSION_MATRIX 在运行时被架空
|
||
|
||
- **位置**:`main.py:104`、`main.py:2337`
|
||
- **问题**:`_request_context_from_astrbot_request()` 只要能取到 username/user_id,就把 `BRIDGE_PERMISSIONS`(四项全部)塞进 `RequestContext.permissions`。而 AstrBot Plugin Page 桥接(`register_bridge_api` → `_make_bridge_handler`)是前端真正走的通路。结果 `config`(改配置、导入配置、回滚快照、恢复备份、轮换 private-companion token)、`materials`、`retry` 三档权限与 `read` 完全等价。
|
||
- **代码**:
|
||
```python
|
||
# main.py:104
|
||
BRIDGE_PERMISSIONS = frozenset(
|
||
{"can_write", "can_manage_config", "can_manage_materials", "can_retry_tasks"}
|
||
)
|
||
|
||
# main.py:2333-2344
|
||
# AstrBot authenticates extension routes before invoking the plugin, but
|
||
# PluginRequest currently exposes only the authenticated username. Grant
|
||
# the capabilities that exist today explicitly instead of a wildcard so a
|
||
# future permission cannot become enabled accidentally.
|
||
permissions = BRIDGE_PERMISSIONS if username or user_id else frozenset()
|
||
return RequestContext.from_astrbot(
|
||
username=username,
|
||
user_id=user_id,
|
||
client_ip=_client_ip(request),
|
||
source="astrbot_plugin_page",
|
||
permissions=permissions,
|
||
)
|
||
```
|
||
- **影响**:任意一个 AstrBot WebUI 普通登录用户可以:`POST settings/save` 改数据库后端/模型密钥环境变量名、`POST settings/rollback`、`POST backups/{id}/restore` 覆盖全量数据、`POST integrations/private-companion/token/rotate` 轮换外部集成令牌、`POST jobs/failed/clear` 清空他人失败队列。`route_registry.py` 里 `config`(22 条)、`materials`(38 条)、`retry`(8 条)三档共 68 条路由的权限边界形同虚设。同时因为没人拥有 `can_manage_all_profiles`,`ResourceAccessService._can_access` 的管理员分支是死代码。
|
||
- **修复建议**:
|
||
1. 从 AstrBot 请求上下文里真正解析角色/权限(`_attr(request, "roles")` / `request.user.permissions` 等,按 AstrBot 版本探测),映射成 ImageStudio 的四项能力;探测不到时**降级为最小集** `frozenset()`(只读),而不是最大集。
|
||
2. 在 `config.yaml` 增加显式的管理员白名单(`security.admin_usernames` / `security.material_managers`),`_request_context_from_astrbot_request` 据此授予 `can_manage_config` / `can_manage_materials` / `can_manage_all_profiles`。
|
||
3. 把 `permission` 真正接进分发器(见下一条),让矩阵成为强制点而非注释。
|
||
|
||
---
|
||
|
||
### [P0-致命] `dispatch_extension_request` 从不检查 `RouteMatch.permission`,矩阵与实现只靠人工同步
|
||
|
||
- **位置**:`adapters/astrbot_adapter.py:171-187`
|
||
- **问题**:分发器解析出 `match.permission` 后直接丢弃,立刻 `match.handler(...)`。鉴权 100% 依赖每个 handler 内部手写 `require_*`。仓库里没有任何测试或启动断言校验"`RouteSpec.permission` == handler 实际 guard",`runtime_health()` 只校验路由唯一性与权限名已知,不校验一致性。
|
||
- **代码**:
|
||
```python
|
||
def dispatch_extension_request(ctx, method, path, *, query=None, payload=None) -> dict[str, Any]:
|
||
match = resolve_route(method, path)
|
||
if match is None:
|
||
return error_response(...)
|
||
return match.handler(*_handler_args(match, ctx, query or {}, payload or {}))
|
||
# ↑ match.permission 从未被使用
|
||
```
|
||
对照 `route_registry.py:365-377`:
|
||
```python
|
||
def assert_unique_routes() -> None: ... # 只查重复
|
||
def assert_known_permissions() -> None: ... # 只查权限名拼写
|
||
```
|
||
- **影响**:新增一条路由时只要忘写 `require_write(ctx)`,就是一个静默的未授权写接口,CI 与 `runtime_health()` 都不会报警。当前 169 条路由靠人工维持一致(我逐条比对确认目前没有漏挂),但这是**一次疏忽即破防**的结构。同时 `_register_route()` 虽然把 `permission=` 传给 AstrBot,但真正生效的桥接注册 `_bridge_registration_routes()` 是 `<path:endpoint>` 通配符,**不携带任何权限元数据**(`main.py:1753-1758`)。
|
||
- **修复建议**:在分发器里做集中式强制:
|
||
```python
|
||
from backend.route_registry import permission_requirement
|
||
from backend.dto.common import ErrorCode, error_response
|
||
|
||
def dispatch_extension_request(ctx, method, path, *, query=None, payload=None):
|
||
match = resolve_route(method, path)
|
||
if match is None: ...
|
||
rule = permission_requirement(match.permission)
|
||
if rule["auth_required"] and not ctx.is_authenticated:
|
||
return error_response(error_code=ErrorCode.UNAUTHORIZED, message="...", request_id=ctx.request_id)
|
||
required = rule.get("required_permissions") or ([rule["required_permission"]] if rule["required_permission"] else [])
|
||
missing = [p for p in required if not ctx.has_permission(p)]
|
||
if missing:
|
||
return error_response(error_code=ErrorCode.FORBIDDEN, message="...", details={"permissions": missing}, request_id=ctx.request_id)
|
||
return match.handler(...)
|
||
```
|
||
handler 内的 `require_*` 保留为纵深防御,并补一个测试:遍历 `ROUTES`,用 AST 断言每个 handler 体内存在与声明等价的 guard。
|
||
|
||
---
|
||
|
||
### [P0-致命] workflow / node / image / job / history 五条链路无归属校验(IDOR)
|
||
|
||
- **位置**:`backend/routes/workflow_routes.py:21-32`、`50-61`、`backend/routes/node_routes.py:81-92`、`backend/routes/job_routes.py:19-41`、`backend/routes/image_routes.py:22-52`、`backend/routes/history_routes.py:36-50`
|
||
- **问题**:profile 路由(`ProfileService.get_profile(profile_id, ctx)` → `_require_owner`)和 round 路由(`WorkflowRoundService._node_and_workflow(node_id, ctx)` → `ResourceAccessService.require_node`)都做了归属校验;但 workflow / node / image / job / history 的 service 方法**签名里根本没有 ctx**,路由层也没有额外校验。
|
||
- **代码**:
|
||
```python
|
||
# backend/routes/workflow_routes.py:50-61 —— 只校验"已登录"
|
||
def get_workflow(ctx, workflow_id, service=None) -> dict:
|
||
workflow_service = service or _create_workflow_service()
|
||
def action() -> dict[str, Any]:
|
||
require_authenticated(ctx)
|
||
return workflow_service.get_workflow(workflow_id).to_dict() # ← 无 ctx
|
||
return handle_request(ctx, action)
|
||
|
||
# backend/services/workflow_service.py:146-150
|
||
def list_workflows(self, profile_id: str) -> list[ProfileWorkflow]: # ← 无 ctx
|
||
self._ensure_profile_exists(profile_id) # 只判存在,不判归属
|
||
return self.workflow_repository.list_workflows(profile_id)
|
||
|
||
def get_workflow(self, workflow_id: str) -> WorkflowDetail: # ← 无 ctx
|
||
workflow = self.workflow_repository.get_workflow(workflow_id)
|
||
|
||
# backend/services/workflow_service.py:650-654
|
||
def get_node(self, node_id: str) -> WorkflowNode: # ← 无 ctx
|
||
|
||
# backend/routes/job_routes.py:29-35 —— 列表参数里没有任何 owner 维度
|
||
result = queue_service.list_jobs(
|
||
status=..., workflow_id=..., profile_id=..., page=..., page_size=...
|
||
).to_dict()
|
||
|
||
# backend/routes/image_routes.py:34-40 —— 同样没有 owner 维度
|
||
result = image_service.list_images(profile_id=..., workflow_id=..., ...)
|
||
```
|
||
对照做对了的那条链路:
|
||
```python
|
||
# backend/services/workflow_round_service.py:1108-1114
|
||
node = (
|
||
self.resource_access_service.require_node(node_id, ctx)
|
||
if ctx is not None
|
||
else self.workflow_repository.get_node(node_id)
|
||
)
|
||
```
|
||
- **影响**:任意登录用户可枚举/读取/**修改**他人资源:
|
||
- `GET profiles/{他人profile_id}/workflows`、`GET workflows/{id}`、`PUT workflows/{id}`、`POST workflows/{id}/start|cancel|archive|execute-character`(execute-character 直接花对方的模型额度出图);
|
||
- `POST profiles/{他人profile_id}/workflows` 在他人档案下建工作流(`create_workflow` 只调 `_ensure_profile_exists`);
|
||
- `GET nodes/{id}`、`PUT nodes/{id}`、`POST nodes/{id}/generate`;
|
||
- `GET jobs`(无任何过滤,`GenerationTask.to_dict()` 含 `request` 全量生成请求,即他人的完整提示词、参考图 URI、模型路由,见 `backend/dto/job_dto.py:38`);
|
||
- `GET images`(无 owner 过滤,仅按 `metadata.quarantined` 过滤受限图)。
|
||
|
||
行为还自相矛盾:`GET nodes/{id}` 能读到他人节点,而 `GET nodes/{id}/rounds` 会正确 404——同一个节点两种答案。
|
||
- **修复建议**:把已存在的 `ResourceAccessService` 推广到这五条链路,而不是每处重造:
|
||
1. `WorkflowService.list_workflows/get_workflow/get_node/list_nodes` 增加 `ctx: RequestContext | None = None`,非 None 时走 `ResourceAccessService.require_workflow/require_node`;
|
||
2. `QueueService.list_jobs` / `ImageService.list_images` 增加 `owner_user_id` 过滤参数,路由层传 `ctx.actor_id`(拥有 `can_manage_all_profiles` 时传 `None`);
|
||
3. `HistoryService.list_workflow_history/save_workflow_snapshot` 前置 `require_workflow(workflow_id, ctx)`;
|
||
4. 补一个"越权矩阵"测试:用户 A 建资源,用户 B 对 169 条路由逐条请求,断言全部 404/403。
|
||
|
||
---
|
||
|
||
### [P1-严重] 客户端自带 `content_permissions` / `entrypoint`,可绕过成人内容路由闸门
|
||
|
||
- **位置**:`backend/services/generation_service.py:2366-2375`、`2352-2353`、`1497-1504`;入口 `backend/routes/node_routes.py:132-146`
|
||
- **问题**:`POST nodes/{node_id}/generate` 的 payload 原样透传给 `GenerationService.generate_node`,而路由裁决所依赖的"用户是否被允许成人内容"直接从**请求体**里取,从未与 `ctx` 校验。
|
||
- **代码**:
|
||
```python
|
||
# backend/services/generation_service.py:2366-2375
|
||
def _permission_context(payload: dict[str, Any]) -> dict[str, Any]:
|
||
configured = payload.get("content_permissions") if isinstance(payload.get("content_permissions"), dict) else {}
|
||
result = {
|
||
**configured,
|
||
"adult_user_allowed": bool(configured.get("adult_user_allowed", payload.get("adult_user_allowed", False))),
|
||
"quota_allowed": bool(configured.get("quota_allowed", payload.get("quota_allowed", True))),
|
||
}
|
||
...
|
||
|
||
# backend/services/generation_service.py:2352-2353
|
||
def _entrypoint(payload: dict[str, Any]) -> str:
|
||
value = _optional_text(payload.get("entrypoint") or payload.get("platform") or payload.get("source")) or "web"
|
||
|
||
# backend/services/prompt_governance_service.py:262-267 —— 消费点
|
||
entry_allowed = bool((self.config.get("entrypoints") or {}).get(entrypoint, False))
|
||
user_allowed = bool(permissions.get("adult_user_allowed", False))
|
||
group_allowed = bool(permissions.get("adult_group_allowed", group_id is None))
|
||
quota_allowed = bool(permissions.get("quota_allowed", True))
|
||
if not all((enabled, entry_allowed, user_allowed, group_allowed, quota_allowed)):
|
||
return self._decision(..., "adult_route_permission_denied", ...)
|
||
```
|
||
- **影响**:只要服务端 `prompt_governance.routing.adult_auto_route_enabled` 为 true,任意登录用户 POST
|
||
`{"content_permissions": {"adult_user_allowed": true, "adult_group_allowed": true, "quota_allowed": true}, "entrypoint": "<配置里放行的任一入口>"}`
|
||
即可让 `adult_allowed` 级别的提示词自动路由到 nsfw_route,同时 `quota_allowed: true` 还能绕过配额判定。聊天侧是对的(`chat_workflow_service.py:70/686/761` 由服务端 `_content_permissions(config, chat)` 生成),唯独 Web 路由这条缺失。
|
||
- **修复建议**:在路由层剥离客户端提供的这两个字段,由服务端重建:
|
||
```python
|
||
# node_routes.generate_node / round_routes 内
|
||
sanitized = {k: v for k, v in request_payload.items()
|
||
if k not in {"content_permissions", "adult_user_allowed", "adult_group_allowed",
|
||
"quota_allowed", "entrypoint", "platform", "source"}}
|
||
sanitized["entrypoint"] = "web"
|
||
sanitized["content_permissions"] = build_content_permissions(load_config_payload(), ctx)
|
||
```
|
||
`build_content_permissions` 复用 `chat_workflow_service._content_permissions` 的逻辑,按 `ctx.actor_id` 查配置白名单。
|
||
|
||
---
|
||
|
||
### [P1-严重] 所有 service 在 `require_*` 之前构造:未授权即可触发重型初始化 + DB 写入,且构造期异常逃出 `handle_request`
|
||
|
||
- **位置**:`backend/routes/node_routes.py:139-140`、`backend/routes/round_routes.py:28`、`137-162`、`backend/routes/node_routes.py:315-390`、`backend/routes/common.py:12-16`
|
||
- **问题**:每个 handler 的固定写法是"先在函数体里造 service,再把 `require_*` 放进闭包 `action`"。于是**鉴权发生在最贵的操作之后**。`_create_generation_service()` 会:读 `load_config_payload()`、建 `Database`、调 `sync_generation_provider_from_config()`(**向数据库 upsert provider/route 行**)、构造 provider runtime 与多个 governance service。
|
||
- **代码**:
|
||
```python
|
||
# backend/routes/node_routes.py:132-146
|
||
def generate_node(ctx, node_id, payload=None, service=None, generation_service=None) -> dict:
|
||
workflow_service = service or _create_workflow_service()
|
||
resolved_generation_service = generation_service or (None if service else _create_generation_service()) # ← 鉴权之前
|
||
request_payload = payload or {}
|
||
|
||
def action() -> dict[str, Any]:
|
||
require_write(ctx) # ← 鉴权在这里,已经太晚
|
||
|
||
# backend/routes/round_routes.py:21-33 —— 一个只读接口也走全量 provider 初始化
|
||
def list_node_rounds(ctx, node_id, query=None, service=None, media_service=None) -> dict:
|
||
round_service = service or _create_round_service() # → create_generation_service() → sync_..._from_config()
|
||
...
|
||
def action(): require_authenticated(ctx)
|
||
|
||
# backend/routes/node_routes.py:327-328
|
||
config_payload = load_config_payload()
|
||
sync_generation_provider_from_config(model_provider_service, config_payload) # 写库
|
||
```
|
||
而 `handle_request` 的 try 只包住 `callback`:
|
||
```python
|
||
# backend/routes/common.py:12-16
|
||
def handle_request(ctx, callback):
|
||
try:
|
||
return success_response(callback(), request_id=ctx.request_id)
|
||
except Exception as exc:
|
||
return response_from_exception(exc, request_id=ctx.request_id)
|
||
```
|
||
- **影响**:
|
||
1. **未授权资源消耗**:未登录/无权限用户狂刷 `GET nodes/x/rounds` 或 `POST nodes/x/generate`,每次请求都触发一轮配置解析 + provider 表写入,SQLite 写锁争用(`db_helper.py:166` timeout=30s)会拖垮整个插件;
|
||
2. **500 泄漏**:service 构造发生在 try 之外,配置损坏/数据库锁死/provider 参数非法时异常直接穿透 `dispatch_extension_request`(该函数也无 try)→ `dispatch_bridge_request` → AstrBot Quart,返回带 traceback 的 500,而不是规范的 `{"ok": false, ...}`;
|
||
3. 只读接口产生写副作用,违反 HTTP 语义。
|
||
- **修复建议**:
|
||
1. 把 service 构造挪进 `action` 闭包(最小改动,一行位置调整 × 157 处,可脚本化);
|
||
2. 或按下面 P2「样板代码」条目引入 `@route(permission=...)` 装饰器,由装饰器统一"先鉴权 → 再懒构造 service → 再统一异常包装";
|
||
3. `sync_generation_provider_from_config` 从请求路径移出,改为启动时执行一次 + 配置变更事件触发(`initialize_runtime_database` 已经调过一次);
|
||
4. `dispatch_extension_request` 外层加兜底 try,任何逃逸异常也转成 `UNKNOWN_ERROR` 响应。
|
||
|
||
---
|
||
|
||
### [P1-严重] `POST profiles/{profile_id}/archive` 实际执行的是删除
|
||
|
||
- **位置**:`backend/routes/profile_routes.py:109-114`,注册于 `backend/route_registry.py:69`
|
||
- **问题**:`archive_profile` 直接把调用转给 `delete_profile`,语义与端点名、与前端 `profileArchive` 按钮的用户预期完全不符。
|
||
- **代码**:
|
||
```python
|
||
# backend/routes/profile_routes.py:101-114
|
||
def delete_profile_via_post(ctx, profile_id, payload=None, service=None) -> dict:
|
||
return delete_profile(ctx, profile_id, service)
|
||
|
||
def archive_profile(ctx, profile_id, service=None) -> dict:
|
||
return delete_profile(ctx, profile_id, service) # ← "归档" == "删除"
|
||
```
|
||
对照 workflow 侧是真归档(`workflow_routes.py:106-111` → `_set_workflow_status(..., "archived", ...)`)。
|
||
- **影响**:前端 `profileArchive`(`frontend/shared/api/endpoints.ts:11`)标注为"归档",用户点击后档案被 `repository.soft_delete()` 置为 `status="deleted"`,随后 `get_profile` 会对 `status == "deleted"` 抛 404 —— 该档案及其下所有工作流从 UI 彻底消失且无归档列表可恢复。归档与删除是两种不同的用户意图,被合并成一种破坏性操作。
|
||
- **修复建议**:
|
||
```python
|
||
def archive_profile(ctx, profile_id, service=None) -> dict:
|
||
profile_service = service or _create_profile_service()
|
||
def action() -> dict:
|
||
require_write(ctx)
|
||
return profile_service.update_profile(profile_id, {"status": "archived"}, ctx).to_dict()
|
||
return handle_request(ctx, action)
|
||
```
|
||
并确认 `ProfileService.get_profile` / `ProfileRepository.list` 对 `archived` 状态可查(`list_profiles` 已支持 `status` 参数)。
|
||
|
||
---
|
||
|
||
### [P2-中等] 所有错误一律 HTTP 200,UNAUTHORIZED/FORBIDDEN/NOT_FOUND 无法被 HTTP 层识别
|
||
|
||
- **位置**:`backend/dto/common.py:58-72`、`main.py:2439-2452`
|
||
- **问题**:`error_response()` 返回普通 dict,`_to_bridge_response()` 也只是把它包成 `{"status": "error", ...}`,全程没有任何 HTTP 状态码映射。
|
||
- **代码**:
|
||
```python
|
||
# main.py:2439-2452
|
||
def _to_bridge_response(response: dict[str, Any]) -> dict[str, Any]:
|
||
if response.get("ok"):
|
||
return {"status": "ok", "message": "", "data": response.get("data"), "request_id": response.get("request_id")}
|
||
return {"status": "error", "message": str(response.get("message") or "request failed"),
|
||
"data": response, "request_id": response.get("request_id")}
|
||
# ← 无论 UNAUTHORIZED / FORBIDDEN / RESOURCE_NOT_FOUND / UNKNOWN_ERROR,AstrBot 都按 200 返回
|
||
```
|
||
- **影响**:AstrBot 侧的访问日志、反向代理限流、监控告警、浏览器 devtools 全部看到 200,权限拒绝与服务器内部错误在 HTTP 层不可观测;前端 `client.ts:96` 里的 `!response.ok` 分支在桥接模式下永远不触发,只能靠 body 判定。安全审计("谁被拒绝了多少次")无法从访问日志得出。
|
||
- **修复建议**:给 `ErrorCode` 建立状态码映射表并在 `_to_bridge_response` / `_to_media_http_response` 层构造带状态码的响应:
|
||
```python
|
||
ERROR_STATUS = {ErrorCode.UNAUTHORIZED: 401, ErrorCode.FORBIDDEN: 403,
|
||
ErrorCode.RESOURCE_NOT_FOUND: 404, ErrorCode.VALIDATION_FAILED: 422,
|
||
ErrorCode.UPLOAD_TOO_LARGE: 413, ErrorCode.UNKNOWN_ERROR: 500}
|
||
```
|
||
桥接返回 `Response(json.dumps(body), status=ERROR_STATUS.get(code, 200), content_type="application/json")`;前端 `unwrapApiResponse` 已能同时处理两种包装,改动是向后兼容的。
|
||
|
||
---
|
||
|
||
### [P2-中等] `handle_request` 吞掉全部异常且不写日志,未知错误无从定位
|
||
|
||
- **位置**:`backend/routes/common.py:12-16`、`backend/dto/common.py:75-83`
|
||
- **问题**:任何非 `ApiError` 异常都被转成 `UNKNOWN_ERROR / "服务器内部错误"`,`details` 只留一个异常类名,**既不 logging 也不保留 traceback**。157 个 handler 全部走这一条路径。
|
||
- **代码**:
|
||
```python
|
||
# backend/dto/common.py:75-83
|
||
def response_from_exception(exc: Exception, request_id: str | None = None) -> dict[str, Any]:
|
||
if isinstance(exc, ApiError):
|
||
return exc.to_response(request_id=request_id)
|
||
return error_response(
|
||
error_code=ErrorCode.UNKNOWN_ERROR,
|
||
message="服务器内部错误",
|
||
details={"exception": exc.__class__.__name__}, # ← 只有类名
|
||
request_id=request_id,
|
||
)
|
||
```
|
||
- **影响**:生产环境出现 `KeyError` / `sqlite3.OperationalError` 时,运维只能看到"服务器内部错误 + KeyError",没有文件行号、没有 request_id 关联的堆栈,排障必须靠复现。项目自带 `LogService`(`logs/errors` 端点)却没有被这条路径喂数据。
|
||
- **修复建议**:
|
||
```python
|
||
import logging
|
||
logger = logging.getLogger("imagestudio.routes")
|
||
|
||
def handle_request(ctx, callback):
|
||
try:
|
||
return success_response(callback(), request_id=ctx.request_id)
|
||
except ApiError as exc:
|
||
logger.info("api_error request_id=%s code=%s", ctx.request_id, exc.error_code)
|
||
return exc.to_response(request_id=ctx.request_id)
|
||
except Exception as exc:
|
||
logger.exception("unhandled route error request_id=%s actor=%s", ctx.request_id, ctx.actor_id)
|
||
return response_from_exception(exc, request_id=ctx.request_id)
|
||
```
|
||
同时把未捕获异常落一条 `LogService` 错误日志,让 `GET logs/errors` 真正有内容。
|
||
|
||
---
|
||
|
||
### [P2-中等] 分页之后再过滤,`total` 与页大小失真
|
||
|
||
- **位置**:`backend/routes/job_routes.py:36-38`、`backend/routes/image_routes.py:45-49`
|
||
- **问题**:service 已按 `page/page_size` 从数据库分页取回,路由层再对**当前页**做可见性过滤,然后用当前页的隐藏数去修正**全局 total**。
|
||
- **代码**:
|
||
```python
|
||
# backend/routes/job_routes.py:36-38
|
||
if not ctx.has_permission("can_manage_materials"):
|
||
visible = [item for item in result["items"] if item.get("metadata", {}).get("source") != "advanced_material"]
|
||
result = {**result, "items": visible,
|
||
"total": max(int(result.get("total") or 0) - (len(result["items"]) - len(visible)), 0)}
|
||
|
||
# backend/routes/image_routes.py:45-49
|
||
visible = [item for item in payload["items"] if not _is_restricted_image(item)]
|
||
payload["restricted_hidden"] = len(payload["items"]) - len(visible)
|
||
payload["items"] = visible
|
||
payload["total"] = max(len(visible), int(payload.get("total") or 0) - payload["restricted_hidden"])
|
||
```
|
||
- **影响**:`total` 是全表计数(`JobListResult.total` 来自 `repository.list()` 的第二个返回值),减去的却只是当前页被隐藏的条数 → 分页器页数算错;每页实际条数少于 `page_size` 且各页不等长;极端情况下某一页全是受限项,前端会显示空页却还有下一页。用户看到"共 87 条"但翻完只有 40 条。
|
||
- **修复建议**:把可见性下推到仓储层的 WHERE 条件:
|
||
- `JobRepository.list(..., exclude_sources=("advanced_material",))`;
|
||
- `ImageRepository.list_images(..., include_restricted: bool)`,SQL 里过滤 `metadata->>'quarantined'` / `gallery_visibility`。
|
||
这样 `total` 与分页天然一致,路由层只剩权限判定,不再做数据裁剪。
|
||
|
||
---
|
||
|
||
### [P2-中等] `ProfileService._require_owner` 不认管理员权限,与 `ResourceAccessService._can_access` 语义相反
|
||
|
||
- **位置**:`backend/services/profile_service.py:160-169` vs `backend/services/resource_access_service.py:80-84`
|
||
- **问题**:同一套归属判定,两处实现规则不同——一处认 `can_manage_all_profiles` / `*`,另一处只认 `actor_id` 相等。
|
||
- **代码**:
|
||
```python
|
||
# backend/services/profile_service.py:160-169
|
||
def _require_owner(self, profile: CharacterProfile, ctx: RequestContext) -> None:
|
||
if ctx.actor_id and ctx.actor_id == profile.owner_user_id:
|
||
return
|
||
raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "角色档案不存在", {"profile_id": profile.profile_id})
|
||
|
||
# backend/services/resource_access_service.py:80-84
|
||
@staticmethod
|
||
def _can_access(owner_user_id: str | None, ctx: RequestContext) -> bool:
|
||
if ctx.has_permission("can_manage_all_profiles") or ctx.has_permission("*"):
|
||
return True
|
||
return bool(ctx.actor_id and owner_user_id and ctx.actor_id == owner_user_id)
|
||
```
|
||
- **影响**:即使按 P0-1 的建议把 `can_manage_all_profiles` 正确授予管理员,`GET profiles/{id}` / `PUT profiles/{id}` / `DELETE profiles/{id}` 依然会对管理员 404,而 `GET nodes/{id}/rounds` 却放行——管理能力在两条链路上表现相反,运维无法完成跨用户支持工单。连 `RequestContext.system()`(`permissions={"*"}`)在 profile 路径上也会被拒。
|
||
- **修复建议**:删掉 `_require_owner`,`ProfileService` 改为注入/复用 `ResourceAccessService._can_access` 同一份判定(或把该静态方法提到 `core/security.py` 作为唯一实现 `can_access_owner(owner_user_id, ctx)`),两处共用。
|
||
|
||
---
|
||
|
||
### [P2-中等] 157 个 handler 是同构样板 + 22 个各自为政的 service 工厂 + 30 处 `Database(load_database_settings())`
|
||
|
||
- **位置**:`backend/routes/` 全目录;典型对照 `backend/routes/settings_routes.py:16-164`、`backend/routes/data_backup_routes.py:9-28`、`backend/routes/wardrobe_routes.py:89-106`
|
||
- **问题**:每个 handler 都是同一个五行骨架(`service = service or _create_X()` → `def action(): require_*(ctx); return svc.foo(...)` → `return handle_request(ctx, action)`);每个路由模块自己写一份 `_create_*_service()`,每份都 `Database(load_database_settings())` + `AuditService(database)` + 一堆 repository 手工装配。统计:`return handle_request` 157 处,`Database(load_database_settings())` 30 处,`_create_*_service` 工厂 22 个。`node_routes._create_workflow_service`、`workflow_routes._create_workflow_service`、`history_routes` 里的同名装配是逐字重复的三份代码。
|
||
- **代码**:
|
||
```python
|
||
# backend/routes/settings_routes.py:42-53 与 56-67 与 70-81 …… 仅函数名和一行调用不同
|
||
def validate_settings(ctx, payload, service=None) -> dict:
|
||
settings_service = service or SettingsService()
|
||
def action() -> dict[str, Any]:
|
||
require_config_manager(ctx)
|
||
return settings_service.validate(payload)
|
||
return handle_request(ctx, action)
|
||
|
||
# backend/routes/data_backup_routes.py:9-11 —— 为了压行改用元组副作用,可读性极差
|
||
def list_backups(ctx:RequestContext,service:DataBackupService|None=None)->dict:
|
||
instance=service or DataBackupService()
|
||
return handle_request(ctx,lambda:(require_config_manager(ctx),instance.list_backups())[1])
|
||
|
||
# backend/routes/wardrobe_routes.py:94-96 —— 同样的元组 hack
|
||
return handle_request(ctx, lambda: (require_permission(ctx, "can_manage_materials"), wardrobe_service.save_template(profile_id, payload, ctx))[1])
|
||
```
|
||
- **影响**:新增路由的成本与出错面都被放大——P0-2 的越权、P1 的"构造在鉴权前"正是因为骨架靠复制粘贴而非统一封装才会成片出现;改一处横切逻辑(日志、审计、限流、状态码)要动 157 个地方。三份重复的 `WorkflowService` 装配意味着任何依赖变更要改三处,漏一处就是运行时 TypeError。`(guard, call())[1]` 的写法把"鉴权"伪装成表达式的一部分,静态检查与人眼 review 都极易漏看。
|
||
- **修复建议**:
|
||
1. 引入统一装饰器,把"鉴权 → 懒构造 service → 异常包装"收敛到一处:
|
||
```python
|
||
# backend/routes/common.py
|
||
def route(permission: str, factory: Callable[[], Any] | None = None):
|
||
def decorator(fn):
|
||
@functools.wraps(fn)
|
||
def wrapper(ctx, *args, service=None, **kwargs):
|
||
def action():
|
||
enforce(ctx, permission) # 复用 route_registry.permission_requirement
|
||
svc = service or (factory() if factory else None)
|
||
return fn(ctx, *args, service=svc, **kwargs)
|
||
return handle_request(ctx, action)
|
||
return wrapper
|
||
return decorator
|
||
```
|
||
handler 退化成一行业务调用,`permission` 参数与 `RouteSpec.permission` 可用测试断言强制一致(顺带闭合 P0-2)。
|
||
2. 建 `backend/routes/container.py`,提供 `get_workflow_service()` / `get_image_service()` / `get_queue_service()` 等**进程级单例或按 request 缓存**的工厂,删掉 22 份重复装配与 30 处 `Database(load_database_settings())`。
|
||
3. 用普通 `def action()` 替换 `data_backup_routes.py` / `wardrobe_routes.py` 里的 `(guard, call())[1]` 元组写法。
|
||
|
||
---
|
||
|
||
### [P3-轻微] `public_token` 权限档与实际暴露面不符,且 `media/fetch` 绕过分发器不留审计
|
||
|
||
- **位置**:`backend/route_registry.py:28`、`173`,`main.py:329-332`、`main.py:1753-1758`
|
||
- **问题**:矩阵里 `public_token` 声明 `auth_required: False`,但真正的注册路径是通配符桥接(`/{PLUGIN_NAME}/<path:endpoint>`,不携带权限元数据),`media/fetch` 与其余 168 条路由共用 AstrBot 的同一层鉴权——项目自己在 `media_routes.py:56-63` 的注释里也承认 `/api/plug` 请求需要登录态。同时该端点在 `dispatch_bridge_request` 里被**提前拦截**,完全不经过 `dispatch_extension_request`。
|
||
- **代码**:
|
||
```python
|
||
# main.py:329-332
|
||
if dispatch_method == "GET" and normalize_extension_path(dispatch_endpoint) == "media/fetch":
|
||
file_response = await _to_media_file_response(dispatch_query)
|
||
if file_response is not None:
|
||
return file_response # ← 不经过路由解析、不经过 handle_request、无审计
|
||
|
||
# main.py:1753-1758 —— 通配符注册,permission 字段在这条路径上不存在
|
||
def _bridge_registration_routes() -> list[dict[str, str]]:
|
||
path = f"/{PLUGIN_NAME}/<path:endpoint>"
|
||
return [{"method": method, "path": path, "endpoint": ""} for method in sorted({r.method for r in ROUTES})]
|
||
```
|
||
- **影响**:矩阵读起来像"这里有一个免鉴权端点",实际不是,误导后续维护者对暴露面的判断;反过来若哪天 AstrBot 放开 `/api/plug` 的鉴权,这条提前返回路径会真的变成公开文件读取(token 由 `MediaProxy` HMAC 签名 + 300s TTL 保护,`core/media_proxy.py:24` 的进程随机密钥算是兜住了,但重启后旧 token 全失效也意味着签名 URL 不能持久化分发)。另外该路径不产生任何访问记录。
|
||
- **修复建议**:把 `public_token` 的描述改为"签名 token + 宿主鉴权",或在 `_to_media_file_response` 前补一次 `ctx.is_authenticated` 判定使其与声明一致;同时在提前返回前记一条 `LogService` 媒体访问日志(含 request_id、actor、uri)。
|
||
|
||
---
|
||
|
||
### [P3-轻微] `node_routes._bool` 与 `params.as_bool` 重复,`images/{id}/moderation-review` 无前端调用方
|
||
|
||
- **位置**:`backend/routes/node_routes.py:399-402` vs `backend/routes/params.py:60-82`;`backend/route_registry.py:135` vs `frontend/shared/api/endpoints.ts`
|
||
- **问题**:
|
||
1. `node_routes` 自带一份布尔转换,与公共 `params.as_bool(value, non_string_truthiness=True)` 语义完全等价却各写一遍;
|
||
2. `POST images/{image_id}/moderation-review`(`materials` 权限)在 `endpoints.ts` 全表里没有对应条目,前端无任何调用方。
|
||
- **代码**:
|
||
```python
|
||
# backend/routes/node_routes.py:399-402
|
||
def _bool(value: Any) -> bool:
|
||
if isinstance(value, str):
|
||
return value.strip().lower() in {"1", "true", "yes", "on"}
|
||
return bool(value)
|
||
|
||
# backend/routes/params.py:74-82 —— 已有等价实现
|
||
def as_bool(value, *, default=False, non_string_truthiness=False) -> bool:
|
||
...
|
||
```
|
||
- **影响**:两份布尔语义未来会漂移(例如公共版本新增 `"y"` token 而 node_routes 版本不跟);受限图片复核能力做了后端却在 UI 上不可达,`_is_restricted_image` 隔离的图片实际上没有人工放行入口。
|
||
- **修复建议**:`node_routes.get_node_dependency_context` 改用 `as_bool(params.get("include_draft"), non_string_truthiness=True)` 并删除 `_bool`;确认 `moderation-review` 是否应在图库详情里补一个"管理员复核"操作,否则从 `ROUTES` 移除以缩小暴露面。
|