静态资源托管服务配置
简介
矩尺平台内置了静态资源托管能力，相当于在负载均衡中集成了一台 Web 服务器。您可以将前端页面（HTML、CSS、JS）、图片、字体、安装包等静态文件托管在矩尺平台上，通过虚拟服务直接对外提供访问，无需再单独部署 Nginx 或 Apache 来 serve 静态文件。
典型场景：
- 将 Vue/React 前端项目打包后的
dist目录上传，直接通过域名访问 - 将 APP 安装包（
.apk、.ipa）托管在平台上供用户下载 - 将公司官网静态页面部署到平台上，替代传统的 Web 服务器
整体流程
配置静态资源托管服务包括创建资源、设置资源参数、关联分发规则和验证访问：
第一步：上传静态资源 → 把文件放到平台上（压缩包上传 或 目录映射）
第二步：配置分发规则 → 在虚拟服务中指定"处理方式 = 静态资源"，选好静态资源和 URL 映射规则
第三步：验证访问 → 通过虚拟服务地址访问静态文件前提条件：静态资源需要在 HTTP 或 HTTPS 虚拟服务上使用，创建方法参见 快速创建HTTP虚拟服务 或 快速创建HTTPS虚拟服务。
Jenkins 自动化发布
需要由 Jenkins 在指定租户下管理配置和静态内容时，参见 Jenkins 管理配置集合与静态资源。该指南提供租户校验、压缩包上传/替换脚本、引擎同步与业务版本验收，以及目录映射的全引擎部署顺序和回退步骤。
上传包型资源首次绑定或新增承载引擎需完成普通配置操作及引擎登记，再用于日常流水线；配置集合中的静态资源定义只负责目录映射，不上传业务压缩包。
第一步：创建静态资源
入口：【负载流量管理 → 静态资源】，点击“新增”按钮。
矩尺平台支持两种方式提供静态文件：
方式一：压缩包上传（推荐）
将静态文件打包为 .zip 或 .tar.gz 格式，直接上传到平台。
| 配置项 | 说明 |
|---|---|
| 名称 | 便于识别的名称，例如 官网前端页面 |
| 上传方式 | 选择"上传压缩包" |
| 文件 | 选择本地的 .zip 或 .tar.gz 文件 |
上传后，平台会自动解压并展示文件目录树，您可以在目录树中：
- 查看所有文件和文件夹结构
- 单独上传、删除某个文件
- 新建文件夹
引用后检查同步状态
上传的资源包由管理节点保存。当虚拟服务引用该资源后，相关转发引擎会同步资源。双机业务应分别检查两台引擎的同步状态，不能只以“上传成功”判断业务已经可用；重要文件仍需按业务要求备份。
方式二：指定资源目录（目录映射）
这种方式不上传文件，而是使用各转发引擎上已经准备好的文件。需要分别设置“引擎根目录”和“资源相对路径”，二者不能混填。
- 在静态资源页面打开“转发引擎静态资源根目录”配置，找到目标引擎，编辑根目录并点击绿色确认按钮。例如将根目录设为
/data/www。 - 点击“新增”，切换“指定目录”，资源路径填写相对目录，例如
website，填写名称并确认。 - 确保文件实际位于引擎可访问的
/data/www/website/下。系统尝试创建目录不等于已经生成或同步文件内容。
截图中的目录和资源名为操作示例；下面使用 website 说明路径关系。
| 配置项 | 说明 |
|---|---|
| 名称 | 便于识别的名称 |
| 上传方式 | 选择“指定目录” |
| 引擎根目录 | 按引擎单独设置的绝对路径，例如 /data/www |
| 资源路径 | 相对于引擎根目录的路径，例如 website |
| 实际文件 | 根目录 + 资源路径 + 文件名，例如 /data/www/website/index.html |
适用场景：
- 静态文件已通过其他方式（如 rsync、共享存储）放在了转发引擎上
- 需要映射 NFS 挂载的远程存储目录
- 需要映射阿里云 OSS、NAS 等通过
ossfs或mount挂载为本地目录的远程存储
目录映射注意事项
- 资源路径填写相对目录，不是把完整的
/data/www/website再填一次。绝对路径配置在对应引擎的根目录中。 - 转发引擎进程必须能访问并读取实际目录；使用挂载存储时，应先确认挂载在引擎运行环境中可见。
- 指定目录方式的文件内容由您自行维护，不会因为两台引擎引用同一个资源对象就自动互相复制。可以在详情中切换引擎查看各自的目录树。
- 免费版不支持指定资源目录功能。
双机环境需要分别准备什么
| 检查项 | 引擎 A 示例 | 引擎 B 示例 |
|---|---|---|
| 引擎根目录 | /data/www | /srv/www |
| 同一资源的相对路径 | website | website |
| 必须存在的文件 | /data/www/website/index.html | /srv/www/website/index.html |
| 文件内容 | 本次发布的版本 | 与 A 一致的版本 |
两台引擎的根目录可以不同。修改根目录前应检查已有资源引用，避免其他静态服务随之指向新目录。发布完成后，分别核对文件目录树，并在切换承载引擎后检查业务内容。
第二步：配置静态资源参数
静态资源创建后，点击进入详情，可以配置以下参数：
MIME TYPE 配置
MIME TYPE 告诉浏览器"这个文件是什么类型"，浏览器据此决定如何渲染或处理文件（如直接显示图片、下载压缩包等）。
平台内置了常见文件后缀的 MIME TYPE 映射（如 .html → text/html，.js → application/javascript），您也可以自定义：
- 自定义 MIME TYPE：为特定后缀指定 MIME 类型，例如将
.apk映射为application/vnd.android.package-archive - 默认 MIME TYPE：当文件后缀在映射表中找不到时，使用此默认值。通常设为
application/octet-stream（浏览器会触发下载）
首页文件
当用户访问一个目录路径（例如 / 或 /docs/）时，平台自动返回的默认文件。不填则默认为 index.html。
预压缩功能
如果您的静态资源包中已经包含了预压缩好的 .gz 或 .br 文件，可以开启此功能，让平台直接传输压缩文件给浏览器，由浏览器自行解压。
| 配置 | 说明 |
|---|---|
| 开启预压缩 | 勾选后，平台会寻找并传输 .gz 或 .br 后缀的预压缩文件 |
| 压缩方式 | 选择 Gzip 或 Brotli |
举例： 您的静态资源包中同时有 app.js（未压缩）和 app.js.gz（预压缩）。开启 Gzip 预压缩后，浏览器请求 app.js 时，平台直接返回 app.js.gz 的内容，并在响应头中标注 Content-Encoding: gzip。这节省了平台实时压缩的 CPU 开销。
与七层压缩策略的区别
预压缩是"文件提前压好，平台直接传输"；七层压缩策略是"平台收到请求后实时压缩再传输"。如果静态文件不常变化，建议使用预压缩，性能更好。
第三步：在分发规则中配置静态资源
这是最关键的一步——让虚拟服务知道"哪些请求应该走静态资源"。
创建七层分发规则
在虚拟服务的配置中（或直接进入【负载流量管理 → 分发规则 → 七层分发规则】），新增一条七层分发规则：
关键配置：
| 配置项 | 设置 |
|---|---|
| 分发策略 | 添加一条或多条匹配规则（详见下方 URL 映射说明） |
| 处理方式 | 选择 "静态资源" |
| 静态资源 | 选择第一步创建的静态资源 |
| 匹配方式 | 选择“URL映射”或“URL去前缀映射”（详见下方） |
注意：处理方式的选项列表中有"HTTP 代理""HTTPS 代理""重定向""静态资源""指定其他错误码"等，创建静态资源托管服务请选择**"静态资源"**。
URL 映射规则详解（重点）
当用户通过虚拟服务访问一个 URL（例如 https://example.com/static/js/app.js），平台需要将这个 URL 对应到静态资源包中的实际文件。这就是"URL 映射规则"的作用。
矩尺平台支持两种映射方式：
URL映射（完整保留路径）
URL 路径 → 文件路径，一一对应，不做任何裁切。
| 场景 | URL 请求路径 | 静态资源包中的文件 | 是否匹配 |
|---|---|---|---|
| 正确的 | /index.html | index.html（在根目录下） | ✓ |
| 正确的 | /css/style.css | css/style.css | ✓ |
| 错误的 | /www/index.html | index.html | ✗（多了前缀 /www） |
适用场景： 将整个域名或某个路径专门用于静态资源。比如为静态资源单独创建一个虚拟服务，监听独立端口或域名，URL 路径与文件路径完全一致。
URL去前缀映射
去掉 URL 中的指定前缀后，剩余部分再匹配文件路径。
选择“URL去前缀映射”后，在出现的“前缀URL”字段填写要去掉的部分。
| 前缀设置 | URL 请求路径 | 去掉前缀后 | 文件路径 | 是否匹配 |
|---|---|---|---|---|
/blog | /blog/index.html | /index.html | index.html | ✓ |
/blog | /blog/css/style.css | /css/style.css | css/style.css | ✓ |
/blog | /other/index.html | — | — | ✗（前缀不匹配） |
适用场景： 虚拟服务同时承载 API 代理和静态资源。例如 /api/* 走 HTTP 代理到后端服务器，/blog/* 走静态资源。
复杂映射：配合分发策略使用
如果同一个虚拟服务中有多个静态资源（比如 /blog/ 走一套前端页面，/docs/ 走另一套文档页面），可以通过分发策略 + 多条分发规则实现：
规则 1（优先级高）：
分发策略：URL 路径前缀 = /blog/
处理方式：静态资源 → 选择"博客前端页面" → 去前缀映射（前缀 = /blog）
规则 2（优先级中）：
分发策略：URL 路径前缀 = /docs/
处理方式：静态资源 → 选择"文档前端页面" → 去前缀映射（前缀 = /docs）
默认规则（优先级低）：
处理方式：HTTP代理 → 后端服务器池常见错误： 分发策略中的 URL 前缀没有与去前缀映射的前缀对应上，导致文件找不到。
- 错误示例： 分发策略写的是
URL 路径前缀 = /static/，但匹配方式选了“URL映射”。这样请求/static/index.html时，平台会在资源目录下寻找static/index.html，而不是index.html。 - 正确做法： 如果文件在资源根部，选择“URL去前缀映射”并填
/static；如果希望保留路径，则按static/index.html的结构准备文件。
配合七层策略实现 URL 重写
当映射规则特别复杂（如 URL 中包含动态参数、需要正则替换等），可以在分发规则中绑定七层 HTTP 策略，利用七层策略的"请求更改"功能在匹配静态资源之前对 URL 进行重写。
第四步：验证访问
配置完成并执行变更后，通过浏览器访问虚拟服务地址加上对应的 URL 路径进行验证。
例如虚拟服务监听 10.1.9.117:80，静态资源包中有 index.html，分发规则配置为“URL映射”，则可以访问：
http://10.1.9.117/index.html如果配置了去前缀映射（前缀为 /blog），则应访问：
http://10.1.9.117/blog/index.html配置自查清单
配置完成后，建议逐项检查以下内容，避免常见错误：
| 检查项 | √/✗ |
|---|---|
| 静态资源是否已上传（或目录路径是否已配置）？ | |
| 目录映射方式下，转发引擎对该目录是否有读取权限？ | |
| 处理方式是否选的是"静态资源"（不是 HTTP 代理）？ | |
| 分发策略的匹配条件是否正确（URL 前缀 / 正则是否正确）？ | |
| 匹配方式是否正确：URL去前缀映射 → 核对前缀，URL映射 → 保留完整路径？ | |
| 如果有多个分发规则，优先级顺序是否正确？ | |
| MIME TYPE 是否配置正确（尤其是非标准文件后缀）？ | |
| 首页文件是否设置（或者依赖默认的 index.html）？ | |
| 变更是否已执行？ |
一台正常、另一台 404 时
先在资源详情中切换到异常引擎，核对根目录、相对路径及实际文件。指定目录方式重点检查文件是否只部署到了一台；上传包方式检查目标引擎同步是否完成。随后核对 URL 映射：请求 /static/index.html 使用完整 URL 映射时，查找的是资源目录下的 static/index.html，而不是根部的 index.html。不要只调整首页文件来掩盖路径问题。
更多静态资源的详细配置（同步状态查看、文件替换、MIME TYPE 管理等）请参考用户手册 静态资源。