---
docStatus: current
---

# OSS 实例、文件浏览与图片预览

从开发套件管理工作区存储实例、浏览文件和预览图片，并从 Hosted Service 环境绑定打开对应实例。

开发套件的「对象存储」是独立的 OSS 管理应用。这里的实例指工作区逻辑存储空间 **Profile**，不要求先绑定 Hosted Service；底层 Bucket 和云存储密钥由平台管理。

## 从实例列表打开文件

1. 打开工作区的开发套件 → 对象存储，查看当前工作区有权访问的实例。
2. 点击实例名称或「打开实例」，查看状态、单文件大小上限及更新时间。
3. 在文件列表按 key 前缀筛选，使用上一页、下一页浏览，每页最多展示 50 条。文件列表由存储端分页，不先下载全部文件。
4. 点击文件的「详情 / 预览」，读取大小、Content-Type、ETag，并对图片加载临时签名 GET。

空实例和空筛选结果是正常结果。权限拒绝、实例不可用和读取失败会显示错误，不解释为空列表。非 ACTIVE 实例可查看生命周期元数据，不能浏览或申请文件访问。

## 从 Hosted Service 找到绑定实例

进入后端项目的「环境」页面，选择环境的「资源绑定」，再点击对应绑定的「打开实例」。平台根据 Provider 登记的管理应用关联，查找当前 Runtime 的实际应用版本和页面声明，打开对应 Profile。

这里展示的是环境**当前配置绑定**，不证明运行中的部署已采用这一修订。同一 Profile 可以绑定多个环境或项目，实例详情展示该空间中的文件，不能据此断言文件都由当前服务上传。未绑定服务的实例同样出现在 OSS 独立应用中。

Provider 未登记管理入口、应用未安装、停用或当前版本缺少详情页面时，平台明确提示原因。页面链接使用当前环境和工作区的应用目录，不使用固定域名、安装 ID 或全局最新版补齐。

## 权限与图片 URL

OSS 管理采用工作区级资源权限。Owner 根据平台验证的用户身份，实时核验当前工作区访问权和 Profile 的工作区归属。前缀只用于筛选，不是门店、客户或项目的权限边界。业务系统的附件归属和终端用户授权仍由业务后端负责。

Hosted 环境绑定查询继续受项目所有者或工作区管理权限约束；能看到绑定不等于获准读取文件。应用会话、同包 Module 调用和 Object Storage Owner 的资源校验分别执行。

图片预览默认申请 300 秒签名 URL，到期后可点击「重新获取预览地址」。每次新申请都校验当前权限，已经签发的链接仍可使用至到期。前端仅获得签名 URL，不获得 Profile Token 或存储密钥；URL 不作为永久文件引用。

图片只作为图片解码展示，不在应用页面内执行 HTML 文档。对于不支持图片预览的文件，仍可查看元数据。

长期业务接入仍遵循 [对象存储与签名上传指南](/development/backend-development/object-storage-upload/)：后端先生成 key，上传核验后保存 key，展示时重新签名。

## 管理 API 与 Module 方法

以下是 Object Storage Owner 的用户授权管理 API。平台应用通过标准 SDK、App Gateway 和同包 `workspace-object-storage` Module 调用；浏览器不直接携带 Profile Token 请求这些接口。原 Hosted Service capability 接口保持独立的绑定 Token 合同。

| HTTP 路径                                                            | Module 方法                             | 用途        |
| ------------------------------------------------------------------ | ------------------------------------- | --------- |
| `GET /api/object-storage/profiles`                                 | `listObjectStorageProfiles`           | 当前工作区实例列表 |
| `GET /api/object-storage/profiles/{profileRef}`                    | `getObjectStorageProfile`             | 指定实例详情    |
| `GET /api/object-storage/profiles/{profileRef}/objects`            | `listObjectStorageObjects`            | 分页列文件     |
| `POST /api/object-storage/profiles/{profileRef}/objects/head`      | `getObjectStorageObjectMetadata`      | 文件元数据     |
| `POST /api/object-storage/profiles/{profileRef}/download-requests` | `prepareObjectStorageDownloadRequest` | 临时签名 GET  |

`profileRef` 从真实实例列表或环境绑定取得，`key` 从该 Profile 的文件列表取得。不能编造标识，也不能把底层物理前缀拼进 key。

分页方法参数为 `profileRef` 和可选 `prefix`、`pageSize`、`cursor`。`pageSize` 默认 50，允许 1 到 200；`prefix` 允许空值及以 `/` 结尾的目录前缀。后续请求原样提交 `nextCursor`，更换前缀后清空游标。

```json
{
  "contractVersion": "1.0.0",
  "items": [
    {
      "key": "images/example.png",
      "size": 117,
      "lastModified": "2026-11-11T00:00:00Z",
      "eTag": null
    }
  ],
  "nextCursor": null,
  "hasMore": false
}
```

上述是 CModel 的 `data`，不是完整响应。管理 API 的成功和业务失败均采用 HTTP 200，顶层保持 `contractVersion`、`errorCode`、`data` 三字段；SDK 返回成功的 `data`，业务错误保留其错误码。

元数据方法接收 `profileRef`、`key`，返回 `contractVersion`、`key`、`size`、`contentType`、`eTag`。下载申请接收 `profileRef`、`key`，以及可选 `expiresInSeconds`（默认 300，范围 60 到 3600），返回 `contractVersion: "1.1.0"`、`method: "GET"`、`url`、`headers`、`expiresAt`。签名请求必须按返回的 URL 与 headers 原样使用。

直接调用两个 POST 管理 API 时，JSON body 使用 `contractVersion: "1.0.0"`；Module 负责填充该固定合同字段。

## 管理入口关联与页面声明

Provider 的 `configJson` 可通过 `managementUi` 关联管理应用：

```json
{
  "contractVersion": "1.0.0",
  "managementUi": {
    "applicationResourceLocator": "source-environment/developer-bundle/PLATFORM_APPLICATION/storage-console",
    "profilePageKey": "profile-detail",
    "profileParameter": "profileRef"
  }
}
```

其中 Locator 是结构示例，实际值必须来自该环境的权威应用目录。Owner 只按该登记关联导航，不按某个 Provider 名称或编号编写分支。关联不授予访问权。

OSS 应用使用已有作者配置 `7.3.0` 的 `pages` 声明 `profile-list` 与 `profile-detail`，详情页面模板为 `/index.html?profileRef={profileRef}`。Manager 读取当前 Runtime 中实际资源的精确版本及该版本页面，再通过已有 `target` 链接协议打开。详见 [页面声明与链接发现](/development/bundle-development/platform-application-development/pages/)。

管理功能随开发套件 Bundle 正常整包升级生效，不需要改造或重新部署已有业务 Hosted Service。已有 Profile、key、上传和下载合同继续有效。