静态 - Arupa Documentation

静态挂载允许插件直接通过内核的 HTTP 服务器公开其包中的文件。适用于页面、样式表、脚本、图像以及其他无需插件代码处理每个请求的文件。插件在注册期间声明静态挂载。挂载被接受后，内核将从声明的文件或目录中提供匹配的请求。请求无需跨越插件进程或 WASM 边界。

声明静态挂载

静态挂载包含三个部分：

属性	含义
`prefix`	资源可用的 URL 路径。
`directory`	要提供的文件或目录。使用 `$PLUGIN_ROOT` 引用插件包中提取的 `Content` 目录。
`access`	挂载资源的可选访问策略。

具体语法取决于您使用的语言和生成的 SDK。以下语言无关的声明显示了挂载点包含的信息：

prefix: /my-plugin/assets/
directory: $PLUGIN_ROOT/assets
access: public

内核加载插件时，目录或文件必须存在。将资源打包到 Content/ 目录下，并通过 $PLUGIN_ROOT 引用它：

my-plugin.plg
├── info.yaml
└── Content/
    └── assets/
        ├── app.js
        └── app.css

挂载目录

挂载目录时，请使用以 / 结尾的 URL 前缀：

prefix: /my-plugin/assets/
directory: $PLUGIN_ROOT/assets

前缀映射到目录子树。例如：

/my-plugin/assets/app.js → Content/assets/app.js
/my-plugin/assets/app.css → Content/assets/app.css

URL 前缀应以 / 开头。末尾的 / 表示该前缀匹配其下方的子树。不带尾部斜杠的路径 /my-plugin/assets 不是同一个子树路径；如果您需要重定向或在该路径上获取索引响应，请添加 HTTP 路由。如果前缀不包含尾部斜杠，内核会将目录挂载规范化为子树前缀。请显式使用尾部斜杠，以便读者和客户端能够清楚地了解映射关系。

挂载单个文件

提供单个文件时，请使用不带尾部斜杠 / 的精确 URL 路径：

prefix: /my-plugin/index.html
directory: $PLUGIN_ROOT/pages/index.html

仅提供精确路径。对 /my-plugin/index.html/anything 的请求与此挂载不匹配。尽管声明属性名为 directory，但它既可以接受目录，也可以接受单个文件。不要在文件挂载点末尾添加斜杠 /。末尾的斜杠会告诉内核将源视为目录挂载点。

URL 路径规则

静态挂载点前缀遵循内核的路径模式规则：

前缀必须是以 / 开头的绝对路径；
不带末尾斜杠 / 的前缀匹配一个精确路径；
以 / 结尾的前缀匹配该路径的子树；并且
/* 不是通配符，会被拒绝。

根前缀 / 被视为静态文件的子树，可以匹配所有绝对请求路径。除非插件旨在提供应用程序的通用静态内容，否则请避免声明根路径。

访问控制

内核在提供文件之前应用 access 策略。请求还必须满足为插件配置的插件级访问策略。如果任一策略拒绝请求，则不会提供文件。空的挂载策略不会绕过非空的插件级策略。使用插件配置来限制插件拥有的所有资源，并使用挂载策略来对单个静态资源进行更具体的限制。有关策略模型，请参阅访问控制。

冲突和匹配

静态挂载与插件 HTTP 路由和其他静态挂载共享应用程序的 URL 空间。保持每个插件的前缀唯一。如果另一个插件已经拥有相同的静态前缀或冲突的HTTP 路由模式，内核将拒绝该挂载。当多个挂载可以匹配一个请求时，匹配前缀最长的挂载优先。当静态挂载与插件 HTTP 路由的匹配长度相同时，该挂载也优先。选择特定的前缀以避免 URL 的意外所有权。

打包检查清单

加载插件之前，请验证：

每个挂载的文件或目录都位于包的 Content/ 树中；
directory 值使用 $PLUGIN_ROOT 而不是构建机器路径；
目录前缀以 / 结尾；
文件前缀不以 / 结尾；并且
该软件包包含挂载点引用的所有文件。

静态文件适用于可以直接提供的文件。如果请求需要应用程序逻辑、请求数据或生成的响应，请改用 HTTP 传输方式。

​声明静态挂载

​挂载目录

​挂载单个文件

​URL 路径规则

​访问控制

​冲突和匹配

​打包检查清单