# 清理工作区孤立文件与已删除卷

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

手动处理满足保留条件的孤立Catalog文件及已软删除卷。会删除实际文件对象和元数据，不是dry-run。

```text
POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/garbage-collection
```

## 调用前准备

`MOI_ENDPOINT` 使用产品 API 前缀 `https://api.moi.matrixorigin.cn/v5`；专有部署填写对应的产品 API 地址。

只由已确认目标环境和清理范围的维护人员执行。需要该工作区catalog.orphan_cleanup权限；不能用普通文件删除权限或平台管理员身份名称推断已授权。

## 请求参数

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
curl --request POST "$MOI_ENDPOINT/workspaces/$WORKSPACE_ID/garbage-collection" \
  --header "X-API-Key: $AI_STUDIO_API_KEY" --header "X-Workspace-ID: $WORKSPACE_ID" \
  --header "Content-Type: application/json" \
  --data '{"orphan_file_threshold_hours":720,"batch_size":100}'
```

:::::
:::::{tab-item} 参数说明

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| orphan_file_threshold_hours | integer | 否 | 文件创建后的最小年龄，小时；省略/非正默认720小时，即30天。正数可缩短默认保留期，非强制最少30天。能解码为int64但超过time.Duration小时范围时拒绝；超int64范围或类型错误可触发默认清理。 |
| batch_size | integer | 否 | 省略/非正默认100；孤立文件候选和已删除卷分别使用此批量上限，不是全工作区总删除上限。 |

兼容行为：空/无效JSON体会重置整个请求为默认值继续清理；未知字段不代表受支持，也不会提供dry-run。不要用错误body、0阈值或0批量来“先试一下”。完整副作用/恢复见[清理语义](cleanup-semantics.md)。

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "orphan_files_cleaned": 1,
    "deleted_volumes_cleaned": 2,
    "message": "Garbage collection completed successfully"
  }
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| code | string | 成功OK。 |
| msg | string | 成功OK。 |
| data.orphan_files_cleaned | integer | |
| data.deleted_volumes_cleaned | integer | |
| data.message | string | |

:::::
::::::
:::::::

## 错误响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": "ErrServer",
  "msg": "Internal Server Error"
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| code | string | 参数范围无效ErrParamInvalid，权限/依赖或内部失败按标准错误返回。 |
| msg | string | 错误信息。失败可能已有部分删除完成，没有全程事务回滚保证；响应不带已完成计数。 |

:::::
::::::
:::::::
