Skip to main content
static 是一种服务运行时类型,在 info.yaml 中设置为 Type: static,与 wasmgrpc 并列。static 服务没有进程,也没有需要启动的模块。它存在的唯一目的,就是打包一组固定的传输和路由——通常是文件,但 static 服务也可以声明一个固定的代理——并让内核直接提供服务,而完全不需要运行任何服务代码。 这与 static 传输 是不同的概念:static 传输是四种传输类型之一,可以由任意运行时类型的服务注册。wasmgrpc 服务可以为其打包的资源注册一个 static 传输,同时动态处理其他路由。而 static 服务 则不同,它没有其他类型的路由需要处理——它暴露的一切都是提前声明好的。

何时使用

当某项功能完全是打包好的内容、不涉及任何请求时逻辑时,请选择 static 服务:文档合集、预先构建好的单页应用、共享的图标或字体包,或者一个指向已经在运行、内核无需自行启动的后端的固定代理。如果任何一条路由需要检查请求内容、计算响应,或调用另一个服务,请改用 wasmgrpc

通过 manifest.yaml 声明资源

static 服务在 manifest.yaml 中声明其传输和路由,该文件位于包根目录,与 info.yaml 并列:
info.yaml 依然用于标识该包,但省略了 Command
manifest.yaml 列出该服务拥有的传输,以及将它们绑定到 URL 上的路由:
每一项都遵循路由与传输中从概念上描述的相同结构:一个传输拥有一个 id、一个 type 以及特定于该类型的配置,一个路由则把一个 transport id 绑定到某个 HTTP 模式上。每种传输类型具体接受哪些字段,在 Static 传输Proxy 传输中有说明。static 传输的 source 是一个相对于包解压后的 Content 目录的路径——与包中其他地方 $PLUGIN_ROOT 所引用的根目录相同。

访问策略

清单中的路由和其他任何 HTTP 路由一样,携带一个 access 策略——策略模型本身请参阅访问控制。添加 require_auth,要求整个站点都必须由已登录用户访问:
一份清单可以针对同一个传输声明多条路由,每条路由都有自己的 access。例如,可以在同一个 assets 来源之上再添加第二条限制更严格的路由,用于管理员专属的区域:
空的或省略的 access 会让该路由保持公开,但仍受该服务已配置的服务级 Allow 约束——参阅服务配置。除此之外,access 遵循的都是访问控制中描述的同一种 require_auth / groups 结构,无论该路由属于 static 服务,还是由 wasmgrpc 服务在运行期间注册的路由。

static 服务中的代理

manifest.yaml 中的路由并不局限于 static 传输类型。带有 unixtcp 目标的 proxy 传输同样可以在这里声明,因为这些目标指向的是已经在别处监听的地址——没有需要内核启动的进程,因此也不需要继承任何东西。inherited 代理目标只对内核正在启动的 grpc 服务才有意义,因此不适用于 static 服务。 例如,一个只是把所有流量转发给同一主机上已经运行的后端的 static 服务:
networkaddressscheme 分别代表什么、有哪些可用的网络类型,以及内核在转发请求之前对请求头和访问检查做了什么,请参阅Proxy 传输——这种清单写法,只是 static 服务用来注册同一种代理传输的方式,效果等同于 grpc 服务在运行期间注册的代理传输。

加载方式与 wasmgrpc 的区别

对于 wasmgrpc 服务,内核会启动其运行时、完成一次身份握手,然后该服务在运行期间注册自己的传输和路由——参阅协议。static 服务则跳过了这一整套流程:内核直接读取 manifest.yaml,并通过相同的底层机制注册其中声明的传输和路由,既不需要握手,另一端也没有正在运行的进程。 这也改变了服务配置中哪些逐服务设置会生效:
  • RunAsUser 没有任何效果,因为没有进程可以以特定操作系统用户身份启动。
  • Checksum 仍然适用,因为它验证的是 .plg 归档文件本身,而不是运行时的任何内容。
  • Restart 仍然控制该服务是否在内核启动时自动加载,尽管对 static 服务而言,“启动”仅仅意味着注册其清单。

冲突与清理

static 服务的路由和其他任何服务的路由一样,遵循相同的冲突规则——路径归属以及 static 与非 static 的冲突规则,请参阅路由与传输。停止一个 static 服务会以与停止其他任何服务相同的方式移除其路由和传输,尽管实际上并没有任何东西真正在运行。