新建反代配置
本指南介绍如何准备证书和源站、创建反向代理路由,并验证边缘节点是否应用配置。
推荐操作流程
在网关控制面中,建议遵循以下步骤新增反代规则:
[ 步骤 1. 证书管理 ] ──► [ 步骤 2. 源站定义(可选) ] ──► [ 步骤 3. 新增网站配置 ]
│
[ 步骤 4. 验证同步和访问 ] ◄────────────────────────────────────┘第一步:证书准备
在使用 HTTPS 安全加密流量前,你需要先准备好对应的 TLS 证书(支持手动导入已有证书,或通过 DNS 验证自动向 CA 申请并托管续期)。
为了保持反代配置指南的简洁,证书相关的详细操作(包括如何在 Cloudflare 申请专用 DNS API Token)已独立拆分为专属指南。请先前往 TLS 证书与自动续期 完成证书准备,然后回到这里继续下一步。
第二步:准备上游源站(可选)
源站(Origin)代表被代理的后端真实服务地址。虽然在新建网站时可以直接填写 IP,但推荐先在源站库中进行注册,以便后续复用与维护:
- 进入左侧导航 「网站管理」->「源站地址」,点击 「新增源站」。
- 填写源站名称(如
production-api)。 - 填入合法的上游地址(如
http://10.0.0.10:8080),点击保存。
第三步:新建网站配置
证书和源站就绪后,即可创建核心网站代理路由:
- 进入左侧导航 「网站管理」->「域名列表」,点击 「新增 Zone」,登记注册根域(如
example.com,不可填写*.example.com)。进入该 Zone 的域名列表添加具体域名或通配符域名:- 域名:输入
api、@、*或完整名称(如*.s3.example.com)。*展开为*.example.com,不支持*.s3简写。 - 绑定证书:选择第一步准备或申请好的证书。
- 如需批量移除闲置域名,可在该 Zone 的 「域名」 标签页点击 「清理未关联域名」,一键清理所有未关联代理路由的域名。
- 域名:输入
- 配置请求路由规则:进入 「规则管理」 页面,点击 「新建规则」 或编辑已有规则:
- 规则名称:输入规则的唯一简易标识(如
app-portal-route)。 - 域名匹配:从已登记域名中选择具体或通配符域名,也可通过「快捷新增域名」创建并绑定。
- 在下方 「反向代理」 选项卡下,选择 回源方式 为「直连上游」。
- 源站选择:从下拉框中选择第二步创建的源站;或者选择手动输入并填入
http://10.0.0.20:9000。
- 规则名称:输入规则的唯一简易标识(如
- 点击保存创建配置。
使用 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 透传访问域名。
为网站配置身份验证
- 为网站的所有域名绑定证书并启用 HTTPS。在规则详情打开「访问认证」,将认证模式设为「身份验证」,填写账号和密码。
- 设置「密码有效期」。访客登录后,在此时长内可访问网站。默认 24 小时,可设为 1 至 720 小时。节点应用新的账号、密码或有效期后,访客需要重新登录。
- 在「响应页面 → 身份认证页」点击预览区或「编辑」,进入 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 等域名共用站点规则:
- 在
example.comZone 下添加*.s3.example.com并绑定路由;不需要逐个登记 bucket 域名。 - 使用 HTTPS 时绑定 SAN 包含
*.s3.example.com的证书。*.example.com证书不能替代它;*.s3.example.com证书也不覆盖s3.example.com或a.bucket.s3.example.com。 - 在 Cloudflare 分组中选择该通配符域名:节点模式跟随节点 IPv4 写 A 记录;自定义模式可写 A、AAAA 或 CNAME。分别验证 DNS 记录和节点配置应用状态。
- 保存路由后,Pingora 同步通配符匹配规则。具体域名优先于通配符,重叠通配符以更长的后缀优先。TLS 仍受证书覆盖范围限制。
- 使用具体主机名访问验证,例如
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,可能把个性化页面缓存并串用户。仅在源站缓存头正确、或内容全局一致时使用。
生效方式
保存站点缓存规则后,控制端自动同步缓存开关与策略。
快速自检
- 全局缓存已开,站点缓存已开,策略为「标准静态资源」。
- 保存配置并确认节点应用成功。
- 带登录 Cookie 连续两次请求同一
/assets/app.js(或带 hash 的 immutable 路径),访问日志中cache_status第二次应为 HIT(或 UI「命中」)。 - 若仍为「未缓存」:确认策略是否匹配该路径扩展名、是否非 GET、源站是否返回
Set-Cookie/private,以及节点是否已应用新版本。更多见 故障排查 · 边缘缓存。