Skip to Content
OpenFlare
使用指南安装部署技术参考架构设计更新日志

新建反代配置

本指南介绍如何准备证书和源站、创建反向代理路由,并验证边缘节点是否应用配置。


推荐操作流程

在网关控制面中,建议遵循以下步骤新增反代规则:

  [ 步骤 1. 证书管理 ] ──► [ 步骤 2. 源站定义(可选) ] ──► [ 步骤 3. 新增网站配置 ]
                                                                   │
  [ 步骤 4. 验证同步和访问 ] ◄────────────────────────────────────┘

第一步:证书准备

在使用 HTTPS 安全加密流量前,你需要先准备好对应的 TLS 证书(支持手动导入已有证书,或通过 DNS 验证自动向 CA 申请并托管续期)。

为了保持反代配置指南的简洁,证书相关的详细操作(包括如何在 Cloudflare 申请专用 DNS API Token)已独立拆分为专属指南。请先前往 TLS 证书与自动续期 完成证书准备,然后回到这里继续下一步。


第二步:准备上游源站(可选)

源站(Origin)代表被代理的后端真实服务地址。虽然在新建网站时可以直接填写 IP,但推荐先在源站库中进行注册,以便后续复用与维护:

  1. 进入左侧导航 「网站管理」->「源站地址」,点击 「新增源站」。
  2. 填写源站名称(如 production-api)。
  3. 填入合法的上游地址(如 http://10.0.0.10:8080),点击保存。

第三步:新建网站配置

证书和源站就绪后,即可创建核心网站代理路由:

  1. 进入左侧导航 「网站管理」->「域名列表」,点击 「新增 Zone」,登记注册根域(如 example.com,不可填写 *.example.com)。进入该 Zone 的域名列表添加具体域名或通配符域名:
    • 域名:输入 api、@、* 或完整名称(如 *.s3.example.com)。* 展开为 *.example.com,不支持 *.s3 简写。
    • 绑定证书:选择第一步准备或申请好的证书。
    • 如需批量移除闲置域名,可在该 Zone 的 「域名」 标签页点击 「清理未关联域名」,一键清理所有未关联代理路由的域名。
  2. 配置请求路由规则:进入 「规则管理」 页面,点击 「新建规则」 或编辑已有规则:
    • 规则名称:输入规则的唯一简易标识(如 app-portal-route)。
    • 域名匹配:从已登记域名中选择具体或通配符域名,也可通过「快捷新增域名」创建并绑定。
    • 在下方 「反向代理」 选项卡下,选择 回源方式 为「直连上游」。
    • 源站选择:从下拉框中选择第二步创建的源站;或者选择手动输入并填入 http://10.0.0.20:9000。
  3. 点击保存创建配置。

使用 IP 地址进行 HTTPS 回源

上游可填写源站 IP,例如 https://203.0.113.10 或 https://[2001:db8::10]:8443。将「源站 Host 请求头」留空时,边缘节点连接配置中的 IP 和端口,使用实际访问域名作为回源 TLS SNI 和证书校验名称,HTTP Host 默认透传该域名。通配符路由按每次请求的具体子域名回源。启用证书名称校验时,源站证书须覆盖对应的访问域名。

如果源站使用固定域名,可在「源站 Host 请求头」中填写该域名,同时指定回源 TLS 名称和 HTTP Host。上游填写域名且此字段留空时,回源 TLS 名称取上游域名,HTTP Host 透传访问域名。

为网站配置身份验证

  1. 为网站的所有域名绑定证书并启用 HTTPS。在规则详情打开「访问认证」,将认证模式设为「身份验证」,填写账号和密码。
  2. 设置「密码有效期」。访客登录后,在此时长内可访问网站。默认 24 小时,可设为 1 至 720 小时。节点应用新的账号、密码或有效期后,访客需要重新登录。
  3. 在「响应页面 → 身份认证页」点击预览区或「编辑」,进入 HTML 编辑器。可加载内置模板后修改,右侧会实时预览。编辑完成后点击保存,HTML 上限为 256 KiB。所有启用「身份验证」的站点共用此页面。

自定义页面使用同页 POST 表单,省略 action 可保留原请求的返回地址。样式可直接写在 HTML 内。页内的 {{login_error}} 会在认证失败时替换为提示文案。

<form method="post">
  <label>账号 <input name="username" autocomplete="username" required></label>
  <label>密码 <input name="password" type="password" autocomplete="current-password" required></label>
  <p role="alert">{{login_error}}</p>
  <button type="submit">登录</button>
</form>

登录和会话校验在边缘节点完成。认证后的请求只需在本地校验 Cookie 签名,无需联系控制面。HTTP 访问会跳转到 HTTPS。旧版 Agent 使用 Basic Auth 继续保护站点,并停用该站点的 Pages API 反代。升级 Agent 后即可提供 HTML 登录页。

通配符域名示例

要让 bucket.s3.example.com 等域名共用站点规则:

  1. 在 example.com Zone 下添加 *.s3.example.com 并绑定路由;不需要逐个登记 bucket 域名。
  2. 使用 HTTPS 时绑定 SAN 包含 *.s3.example.com 的证书。*.example.com 证书不能替代它;*.s3.example.com 证书也不覆盖 s3.example.com 或 a.bucket.s3.example.com。
  3. 在 Cloudflare 分组中选择该通配符域名:节点模式跟随节点 IPv4 写 A 记录;自定义模式可写 A、AAAA 或 CNAME。分别验证 DNS 记录和节点配置应用状态。
  4. 保存路由后,Pingora 同步通配符匹配规则。具体域名优先于通配符,重叠通配符以更长的后缀优先。TLS 仍受证书覆盖范围限制。
  5. 使用具体主机名访问验证,例如 https://bucket.s3.example.com,不要直接打开带 * 的地址。Zone 统计会聚合命中的实际 Host;Uptime Kuma 则需要至少绑定一个具体域名,否则跳过该路由的监控创建/更新并记录原因。

不允许 foo*.example.com、a.*.example.com 或多个 *;带协议、路径、端口、域名内部空白及非法 DNS 标签的输入也会被拒绝。


第四步:验证同步和访问

保存路由后,控制端通知在线边缘节点拉取并校验新快照。候选配置应用失败时,节点继续使用最后一份健康快照,并在节点详情的「应用记录」中报告失败。

1. 验证访问

你可以通过以下方式验证新配置是否生效:

  • 浏览器访问:直接在浏览器输入 https://your-domain.com 查看是否成功代理后端。
  • 命令行验证(推荐):使用 curl 探测:
    curl -I https://your-domain.com
  • 绕过 DNS 校验:若你的域名尚未正式解析,可以临时指定 Host 请求头请求 Agent 节点物理 IP:
    curl -I -H "Host: your-domain.com" https://AGENT_NODE_IP --insecure

2. 处理应用失败

在节点详情的「应用记录」中查看失败原因,修正后保存配置,节点将自动尝试新快照。如果已修复的是节点环境,可对该节点执行「强制同步」,重新尝试同一配置。


边缘缓存(可选)

在站点详情的「缓存」页启用缓存并设置匹配规则。节点的缓存容量和对象上限在 Pingora 性能策略 中配置。

推荐设置

项建议
策略标准静态资源(默认推荐):仅 css/js/map/图片/字体等,不含 HTML/JSON
登录 Cookie不会单独跳过缓存;带会话的用户仍可命中静态资源
源站静态资源建议 Cache-Control: public, max-age=…;动态/个性化必须 private 或 no-store
响应 Set-Cookie不会写入边缘缓存
无源站缓存头按状态码使用默认 Edge TTL(如 200 约 120 分钟)

高级策略「所有可缓存 GET」

类似 Cloudflare Cache Everything:路径不再限制扩展名。若源站对 HTML 未声明 private/no-store,可能把个性化页面缓存并串用户。仅在源站缓存头正确、或内容全局一致时使用。

生效方式

保存站点缓存规则后,控制端自动同步缓存开关与策略。

快速自检

  1. 全局缓存已开,站点缓存已开,策略为「标准静态资源」。
  2. 保存配置并确认节点应用成功。
  3. 带登录 Cookie 连续两次请求同一 /assets/app.js(或带 hash 的 immutable 路径),访问日志中 cache_status 第二次应为 HIT(或 UI「命中」)。
  4. 若仍为「未缓存」:确认策略是否匹配该路径扩展名、是否非 GET、源站是否返回 Set-Cookie / private,以及节点是否已应用新版本。更多见 故障排查 · 边缘缓存。

本页目录