#稳定 URL

在 NocoBase 中，由存储引擎托管的文件会通过稳定 URL（Stable URL）访问。这个地址先进入 NocoBase，再由 NocoBase 检查文件记录和访问权限，最后重定向到存储引擎生成的实际地址。

#URL 格式

文件记录返回的地址通常是：

/files/<app>/<dataSource>/<collection>/<id><extname>

比如：

/files/main/main/attachments/42.pdf

如果 NocoBase 配置了 APP_PUBLIC_PATH=/nocobase，地址会自动带上该前缀：

/nocobase/files/main/main/attachments/42.pdf

其中：

• app 是应用名称
• dataSource 是数据源标识
• collection 是附件表或文件表名称
• id 是文件记录的 ID
• extname 是文件扩展名，没有扩展名时不会追加

文件创建后，id 和 extname 不允许修改，因此同一条文件记录的地址可以保持稳定。

#不同用途的地址

同一条文件记录会根据用途使用不同的 query 参数：

#在各个地方的表现

#附件字段和文件表

附件字段与文件表中的系统托管文件，上传、查询和关联读取后返回的 url 都是稳定 URL，preview 则是在同一地址上增加 preview=1。

图片、PDF、音视频和文本等文件仍可在 NocoBase 中预览。刚上传的本地图片会优先使用浏览器生成的临时本地预览，数据重新读取后再使用稳定 URL，避免上传完成时出现重复请求或缩略图闪烁。

#HTTP API

通过 HTTP API 上传或查询文件时，响应中的 url / preview 不再暴露本地路径、对象存储域名或预签名下载地址。调用方访问稳定 URL 时需要携带对应应用的登录凭证。

稳定 URL 返回 302 重定向，不直接代理文件流。如果使用 curl 等客户端读取文件内容，需要允许跟随重定向：

curl -L \
  -H "Authorization: Bearer <JWT>" \
  "https://example.com/files/main/main/attachments/42.pdf"

浏览器直接打开文件时通常使用登录 cookie。GET 和 HEAD 可以访问稳定 URL，其他 HTTP 方法会返回 405。

#Markdown 编辑器

在 Markdown 编辑器中上传文件后，写入 Markdown 内容的是稳定 URL。私有 S3、OSS、COS 或 S3 Pro 存储也可以使用这种方式，不需要把存储空间调整为公开读取。

如果 Markdown 内容会展示在未登录页面，那么查看者仍需要拥有文件查看权限。仅把稳定 URL 写入 Markdown，不会自动把文件公开。

#附件 URL 字段

附件 URL 字段上传到 NocoBase 存储引擎后，字段中保存的是稳定 URL。图片缩略图会使用对应的 preview 地址。

如果字段保存的是手工输入的外部 URL，并且文件记录没有 storageId，NocoBase 会继续保留并返回原始外部 URL。这类文件不经过稳定 URL 的权限检查和重定向流程。

#普通文件预览

图片、PDF、音频、视频和文本预览会直接使用稳定 URL。浏览器请求会携带 NocoBase 登录 cookie，再按当前角色检查附件表或文件表的 get/view 权限。

对于对象存储中的 PDF 等文件，最终预览方式还会受到存储服务 CORS 配置的影响。如果自定义前端通过 fetch() 读取重定向后的对象存储地址，也需要确保对象存储允许当前站点跨域访问。

#Office 文件预览

Microsoft Office Online Viewer 由 Microsoft 服务端拉取文件，无法携带用户浏览器中的 NocoBase cookie。因此，用户真正打开 Office 预览时，NocoBase 会先检查该文件的查看权限，再签发一个短期临时 URL。

临时 URL 默认有效 10 分钟，可以通过 TEMPORARY_FILE_ACCESS_EXPIRES_IN 配置为 5 到 10 分钟。它只绑定当前文件，过期后无法继续使用。重新打开预览时会重新申请，加载失败时预览器也可能重新申请一次。

#公开表单

访客在公开表单中上传文件后，NocoBase 会在当前公开表单会话中记录这些文件。上传者可以继续看到自己刚上传的图片或附件。

这个访问范围只服务于当前公开表单会话，并不是通用的公开文件链接。把地址复制到其他浏览器或当前会话失效后，仍可能无法访问。

#权限和重定向

访问稳定 URL 时，NocoBase 会按照 URL 中的应用、数据源、文件表和记录 ID 定位文件。其中：

1. 已登录用户使用当前应用的登录 cookie 或认证信息，并检查当前角色的文件查看权限。
2. 公开表单等插件可以对特定文件提供额外的受限授权。
3. 检查通过后，NocoBase 返回 302，跳转到本地存储或对象存储生成的实际地址。

因此，稳定 URL 隔离了业务数据和存储实现。切换存储域名、更新对象存储签名或调整缩略图规则时，业务字段中保存的地址通常不需要跟着修改。

#使用注意

• 稳定不等于公开。复制链接给其他人后，对方仍需要登录并拥有文件查看权限
• 稳定不等于永不失效。删除文件记录、删除文件、变更应用或数据源标识、移动到另一张文件表后，原地址会失效
• 不要持久化 temporaryAccessToken。它是短期凭证，也可能进入浏览器历史和访问日志
• 不要缓存 302 Location 作为永久地址。对象存储签名可能过期，应该每次从稳定 URL 重新解析
• 不要自行替换 URL 中的 app、dataSource、collection、id 或扩展名。路径与文件记录不一致时会被拒绝
• 反向代理需要把 APP_PUBLIC_PATH 下的 /files/ 路径转发到 NocoBase。使用子路径部署时，还应保留根路径 /files/ 的兼容转发规则。使用 NocoBase CLI 生成的代理配置时会自动包含这些规则
• 页面跨源访问 API 的部署（配置了指向其他源的 API_BASE_URL）需要把页面来源加入 CORS_ORIGIN_WHITELIST，否则登录 cookie 无法写入，稳定 URL 会因缺少凭证返回 403，详见环境变量
• 部署多个彼此独立的 NocoBase 服务时，应为每个服务使用不同的 hostname，不要只通过端口区分。浏览器 cookie 不按端口隔离，详细说明见生产环境部署
• 同一个 NocoBase 部署环境内的子应用会按应用名区分 cookie，不需要单独配置 hostname；不过另一个端口上的独立服务如果包含同名主应用或子应用，仍需要通过不同的 hostname 隔离
• 如果通过 <img>、<iframe>、fetch() 或第三方客户端访问文件，需要确认它会携带凭证，并能跟随 302 重定向
• 真正需要长期对外分享文件时，应使用专门的分享或公开访问方案，不要把稳定 URL 或 Office 临时 URL 当成分享链接

#相关链接

• HTTP API — 通过 API 上传文件并读取返回的稳定 URL
• 文件预览 — 查看不同文件类型的预览方式
• Office 文件预览 — 配置 Microsoft Office Online Viewer
• 存储引擎 — 配置本地存储和对象存储