站点后端（动态处理器）

除了静态文件之外，已上传的网站还可以拥有真正的后端——绑定到各个地址的小型 JavaScript 处理器。每个处理器都绑定到一个路径和一个 HTTP 方法；当访客打开该地址时，Qubix 会运行该处理器，并返回它所构建的任何内容——一个页面、一个 JSON 应答、一个重定向或一个状态码。

当某个页面必须在服务端做一些事情，而不仅仅是显示静态内容时，请使用它：通过 POST 请求接收线索、用生成的 HTML 应答特定路径，或根据请求发送重定向。对于普通的静态 whitepage 和落地页，您不需要它——让 Backend 标签页保持为空，网站就会作为纯文件被提供。

打开后端标签页

网站卡片顶部有三个标签页：文件、Backend 和 预览。活动标签页会被保存在地址栏中，因此您可以直接复制指向某个特定标签页的链接。

1. 打开 «网站» 板块，点击您需要的网站。
2. 切换到 Backend 标签页。

如果该网站尚无任何处理器，列表会显示提示，说明 «+ new» 可以从模板创建一个。

备注

仅当页面必须在服务端处理某些内容时，才需要 Backend 标签页。纯静态页面无需任何处理器即可工作。

创建处理器

1. 在 Backend 标签页上，点击处理器列表上方左上角的 «+ new»。系统会从现成的模板创建一个新处理器，并在编辑器中打开它。

   🎬 GIF: 点击 «+ new» 后，模板处理器在编辑器中打开

2. 在编辑器上方的标头表单中，设置 路径——处理器应答所在的地址。该字段接受带占位符的模板（例如 /users/:id）：
   • :name —— 捕获一个路径段（例如，/users/:id 中的 :id 可匹配 /users/42）；
   • * —— 捕获横跨多个段的其余路径；
   • ** —— 匹配其余路径但不捕获它。
3. 选择 method —— GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS 或 ANY（应答任何方法）。
4. 保持勾选 enabled 复选框，让处理器在线上站点上工作。取消勾选可保留已保存但未激活的处理器。
5. 在中央编辑器中，编写处理器代码（见下文 处理器代码）。
6. 点击 保存（或 Cmd+S，在 Windows 上为 Ctrl+S）。

在左侧列表中，每个处理器都以其方法和路径来显示（未设置方法的处理器显示为 ANY）；已禁用的处理器会相应地标记出来。

当两个处理器都匹配时

如果有多个处理器都可能应答同一地址，Qubix 会选择最具体的那个——拥有精确路径的处理器胜过带占位符或通配符的处理器。因此，您可以让一个精确处理器和一个宽泛的兜底处理器并存而互不冲突。

处理器代码

处理器是一个 JavaScript 函数，它接收一个请求对象——称之为 r——该对象暴露了请求（方法、路径、查询和表单参数、标头、捕获到的路径段）和响应（设置标头、返回带正文的状态码或重定向）。编辑器起始的模板已经展示了典型的结构。

该编辑器是一个带有语法高亮和自动补全的完整代码编辑器：开始输入 r.，Qubix 就会连同描述一起建议可用的请求和响应字段，因此您无需把它们记在脑子里。

与脚本相同的工具集

在处理器内部，您同样可以使用共享的 Qubix 工具集：只读的数据库查询、对外部服务的请求，以及在多次调用之间保持的状态。它们的工作方式与 脚本 中相同——详情请参阅该文章。出站请求只允许发往管理员加入白名单的地址。查询可访问的表和列，请参阅 sql 查询可用的表。

r 对象参考

处理器通过 r 对象读取请求并构建响应。

读取请求：

字段	含义
r.method	请求的 HTTP 方法（GET、POST……）
r.uri	处理器应答的地址（例如 /promo/123）
r.rawUri	包含服务前缀的完整外部地址
r.args	地址和表单参数（键 → 值）
r.params	从路径模板中捕获的值（例如 /users/:id 中的 id）
r.requestBuffer	以字符串形式表示的请求正文
r.headersIn	请求标头
r.remoteAddress	访客的 IP 地址
r.variables	点击上下文：geo、click_id、sub1……sub5、lang
r.session	访客会话：get(key)、set(key, value)、delete(key)

构建响应：

字段 / 方法	操作
r.headersOut	响应标头（可设置和删除）
r.return(status, body?, location?)	发送响应；location 为重定向地址
r.log(...)、r.warn(...)、r.error(...)	写入运行日志（在测试运行器中可见）

Crypto 辅助方法

处理器还提供 crypto 辅助方法：

方法	作用
crypto.uuid()	生成随机标识符
crypto.hmac(algo, key, data)	对 data 用 key 计算 HMAC，以十六进制编码返回；algo 为 'sha256'、'sha1' 或 'md5'

例如，在通过 fetch 向外部服务发送数据前，可用此方法对数据进行签名。

测试处理器

每个处理器在编辑器右侧都有一个内置的测试运行器——发送一个测试请求，即可准确看到处理器的应答内容，而无需触碰线上站点。

1. 选择 method 并输入要测试的 路径（例如 /users/42）。
2. （可选）填写请求输入项：
   • 查询 (JSON) —— 作为 JSON 对象的查询参数；
   • 正文 (raw) —— 原始请求正文；
   • geo 和 click_id —— 作为请求变量传递给处理器的值。
3. 点击 运行。

结果显示在下方：

• 响应 status（以绿色 / 蓝色 / 红色标示）以及本次运行耗时；
• 参数 —— 从路径模板中捕获的值；
• 重定向 —— 重定向目标（如果处理器设置了的话）；
• 响应的 标头 和 正文；
• 控制台 —— 处理器在运行期间记录的所有内容。

如果请求触及或更改了处理器存储的状态，面板还会将 会话 标记为已触动。

校验 Query 字段

查询 (JSON) 必须是有效的 JSON。如果不是，测试将不会运行，且该字段会被高亮——请修复 JSON 后再次点击 运行。

编辑站点文件

卡片的另一半是 文件 标签页——左侧以树形结构展示网站的静态文件（HTML、CSS、JS、图片、字体），右侧为代码编辑器。文本文件会以语法高亮打开；用 保存 或 Cmd+S 保存（在 Windows 上为 Ctrl+S）。图片、视频、音频及其他文件会提供预览或下载。您可以在文件夹之间拖动文件，也可以从您的电脑拖入新文件。

关于 文件 标签页的完整说明，请参阅 网站 和 上传网站。

字段与行为说明

路径 —— 处理器应答所在的地址模板。支持 :name（一个段）、*（其余部分，捕获）和 **（其余部分，不捕获）。捕获到的段对处理器可用，并在测试运行器中显示为 params。

method —— 触发处理器的 HTTP 方法。ANY 应答每一种方法。

enabled —— 处理器是否在线上站点上运行。已禁用的处理器仍会被保存，但会被跳过。

«+ new» —— 从内置模板创建一个处理器，可直接编辑。

接下来

网站

网站卡片，以及文件和实时标签页。

上传网站

如何上传网站并编辑其文件。

编写脚本

相同的 JavaScript 工具集，用于广告自动化。