mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-09-30 06:16:37 +08:00
ryan
600a7acdfb
- 删除未经验证的环境要求（Docker 版本号、浏览器条目）与括号废话 - 故障排查改为真实处理路径（升级→重新发布→强制同步→重建 Agent→提交 issue），删除仅开发时用的排障章节 - 删除设计文档中的测试与验收、实现检查清单、贡献者阅读建议等开发内容 - 修正与代码不符的事实：reset-passwd 命令名、证书续签窗口 7 天、Pages 检查间隔 1440 分钟、Relay vhost 端口 8080、SSO 仅支持 OIDC 等 - 去除口语化表述与无意义括号，改写「不是…而是…」句式 - 同步修正文档站链接锚点，构建验证通过
118 lines
6.0 KiB
Markdown
118 lines
6.0 KiB
Markdown
# 新建反代配置
|
||
|
||
你会学到：如何一步一步在 OpenFlare 中从零新建并发布一个反向代理网站配置。本指南将指导你如何完成证书导入与申请、源站定义、路由规则配置、版本发布以及连通性验证。
|
||
|
||
---
|
||
|
||
## 推荐操作流程
|
||
|
||
在网关控制面中，建议遵循以下步骤新增反代规则：
|
||
|
||
```text
|
||
[ 步骤 1. 证书管理 ] ──► [ 步骤 2. 源站定义（可选） ] ──► [ 步骤 3. 新增网站配置 ]
|
||
│
|
||
[ 步骤 5. 验证访问 ] ◄── [ 步骤 4. 发布与激活版本 ] ◄───────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 第一步：证书准备
|
||
|
||
在使用 HTTPS 安全加密流量前，你需要先准备好对应的 TLS 证书（支持手动导入已有证书，或通过 DNS 验证自动向 CA 申请并托管续期）。
|
||
|
||
为了保持反代配置指南的简洁，证书相关的详细操作（包括如何在 Cloudflare 申请专用 DNS API Token）已独立拆分为专属指南。请先前往 **[TLS 证书与自动续期](./certificates.md)** 完成证书准备，然后回到这里继续下一步。
|
||
|
||
---
|
||
|
||
## 第二步：准备上游源站（可选）
|
||
|
||
源站（Origin）代表被代理的后端真实服务地址。虽然在新建网站时可以直接填写 IP，但推荐先在源站库中进行注册，以便后续复用与维护：
|
||
|
||
1. 进入左侧导航 **「网站管理」->「源站地址」**，点击 **「新增源站」**。
|
||
2. 填写源站名称（如 `production-api`）。
|
||
3. 填入合法的上游地址（如 `http://10.0.0.10:8080`），点击保存。
|
||
|
||
---
|
||
|
||
## 第三步：新建网站配置
|
||
|
||
证书和源站就绪后，即可创建核心网站代理路由：
|
||
|
||
1. 进入左侧导航 **「网站管理」->「域名列表」**，点击 **「新增 Zone」**：
|
||
* **域名**：输入该站点绑定的域名。
|
||
* **绑定证书**：选择第一步准备或申请好的证书。
|
||
2. 配置请求路由规则：进入 **「规则管理」** 页面，点击 **「新建规则」** 或编辑已有规则：
|
||
* **规则名称**：输入规则的唯一简易标识（如 `app-portal-route`）。
|
||
* **域名匹配**：填入对应的域名（支持通配符或精确域名，需与上面登记的域名一致）。
|
||
* 在下方 **「反向代理」** 选项卡下，选择 **回源方式** 为「直连上游」。
|
||
* **源站选择**：从下拉框中选择第二步创建的源站；或者选择手动输入并填入 `http://10.0.0.20:9000`。
|
||
3. 点击保存创建配置。
|
||
|
||
---
|
||
|
||
## 第四步：发布并生效配置
|
||
|
||
你在管理端新增的网站配置仅保存在 Server 数据库中，**不会立即生效**。必须生成配置版本快照并分发到 Agent 边缘节点：
|
||
|
||
1. 点击控制面板右上角的 **「预览并发布」** 按钮。
|
||
2. 检查配置文件的 Diff 差异，确认你刚刚新增的 `server` 块以及证书绑定规则无误。
|
||
3. 点击 **「确认发布」** 按钮。
|
||
4. **Agent 落地机制**：
|
||
* 数据面的 Agent 节点在心跳中发现激活的版本 Checksum 变更，会自动拉取完整的 OpenResty 配置文件和证书包到本地。
|
||
* 自动在本地执行配置校验（类似于 `openresty -t`），确认无语法错误后，执行平滑重载（`reload`）。
|
||
* 如果重载或校验失败，Agent 会安全阻断并回滚至上一稳定版本，保证节点高可用。
|
||
|
||
---
|
||
|
||
## 第五步：连通性与回滚验证
|
||
|
||
### 1. 验证访问
|
||
你可以通过以下方式验证新配置是否生效：
|
||
* **浏览器访问**：直接在浏览器输入 `https://your-domain.com` 查看是否成功代理后端。
|
||
* **命令行验证**（推荐）：使用 `curl` 探测：
|
||
```bash
|
||
curl -I https://your-domain.com
|
||
```
|
||
* **绕过 DNS 校验**：若你的域名尚未正式解析，可以临时指定 `Host` 请求头请求 Agent 节点物理 IP：
|
||
```bash
|
||
curl -I -H "Host: your-domain.com" https://AGENT_NODE_IP --insecure
|
||
```
|
||
|
||
### 2. 一键秒级回滚
|
||
如果发布的新配置导致了线上业务异常：
|
||
1. 导航至左侧 **「版本发布」** 菜单。
|
||
2. 在历史列表中找到发布前的上一个稳定版本。
|
||
3. 点击 **「激活」**。
|
||
4. 所有在线 Agent 节点将在秒级自动重载回历史配置，实现秒级避险。
|
||
|
||
---
|
||
|
||
## 边缘缓存（可选）
|
||
|
||
站点详情 **「缓存」** 页可开启边缘 `proxy_cache`（须同时开启 **性能设置 → 全局 OpenResty 缓存**）。行为对标 Cloudflare 默认模型，详见 [边缘缓存策略设计](../design/edge-cache-design.md)。
|
||
|
||
### 推荐设置
|
||
|
||
| 项 | 建议 |
|
||
| --- | --- |
|
||
| 策略 | **标准静态资源**（默认推荐）：仅 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`，**可能把个性化页面缓存并串用户**。仅在源站缓存头正确、或内容全局一致时使用。
|
||
|
||
### 生效方式
|
||
|
||
缓存开关与策略写在配置快照中。保存站点后须 **发布并激活配置版本**，Agent 应用后才生效。仅改 UI 不发布则节点仍用旧规则。
|
||
|
||
### 快速自检
|
||
|
||
1. 全局缓存已开，站点缓存已开，策略为「标准静态资源」。
|
||
2. 发布配置并确认节点应用成功。
|
||
3. 带登录 Cookie 连续两次请求同一 `/assets/app.js`（或带 hash 的 immutable 路径），访问日志中 `cache_status` 第二次应为 **HIT**（或 UI「命中」）。
|
||
4. 若仍为「未缓存」：确认策略是否匹配该路径扩展名、是否非 GET、源站是否返回 `Set-Cookie` / `private`，以及节点是否已应用新版本。更多见 [故障排查 · 边缘缓存](./troubleshooting.md#边缘缓存命中率异常)。
|