210 lines
12 KiB
Markdown
210 lines
12 KiB
Markdown
# 公网反代「部署设置」对齐本地反代 —— 方案设计
|
||
|
||
> 目标：把本地反向代理（`ProxyView.vue` 规则弹窗）中真正有价值的安全与运维设置，按公网反代的语义迁移到
|
||
> 「公网反代」页（`/public-proxy`，`ProxyRemoteView.vue`）的「部署设置」中，由 havline-agent 生成对应的 Nginx vhost 配置。
|
||
>
|
||
> 原则：**公网反代只管「公网入口」这一层**。凡是会破坏 frps vhost 路由、或本质属于「本机内网分流」的选项，
|
||
> 一律不迁移（见「明确不做」一节）。
|
||
>
|
||
> 更新日期：2026-09-22
|
||
|
||
---
|
||
|
||
## 建议
|
||
「部署设置」弹窗从现在的单页改为**三个 Tab（基础 / 安全 / 高级）**，与本地反代弹窗结构对齐：
|
||
|
||
-
|
||
**基础**：启用 HTTPS、强制跳转、WebSocket、上传大小、代理超时
|
||
|
||
-
|
||
**安全**：IP 白名单 / 黑名单、Basic Auth（用户名 + 可选密码）
|
||
|
||
-
|
||
**高级**：仅 TLS 1.3、安全响应头、限流、连接数限制
|
||
|
||
第一梯队 7 项都是 agent 模板内改动 + Havline 参数透传，风险低、见效快；第二梯队 3 项需要 agent 多写一个 http 上下文文件。说一声我从第一梯队开始做，或者指定要哪几项。
|
||
|
||
|
||
|
||
## 一、现状对照
|
||
|
||
### 本地反代（ProxyView.vue）规则弹窗现有设置项
|
||
|
||
| 分组 | 设置项 |
|
||
| --- | --- |
|
||
| 基础 | 名称、前端域名、目标地址、**启用 HTTPS**、**HTTP 跳转 HTTPS**、启用规则 |
|
||
| 安全 · IP 访问控制 | 仅中国大陆 IP、黑名单模式 + 列表、白名单模式 + 列表 |
|
||
| 安全 · 认证 | Basic Auth（用户名 + **自定义密码**） |
|
||
| 安全 · 流量控制 | 请求限流（速率 / 突发）、连接数限制（每 IP 并发） |
|
||
| 安全 · 高级 | 忽略后端 TLS 证书、使用目标 Host 头、仅 TLS 1.3、安全响应头 |
|
||
| Nginx | auto / custom 自定义配置 |
|
||
|
||
### 公网反代（agent `nginxRoute` 模板）现有能力
|
||
|
||
`internal/agent/server.go` 的 `routeRequest` 与 `nginxRoute` 已支持：
|
||
|
||
- `domain` / `upstream`（`127.0.0.1:<frps vhost 端口>`）/ `tls` + `cert_dir`；
|
||
- `websocket`（Upgrade / Connection 头）；
|
||
- `redirect_https`（80 → 443 的 301 + 443 TLS server 两块）；
|
||
- `allow_ips`（location 内 allow + deny all）；
|
||
- `basic_auth_user`（密码由 agent 自动生成并落盘 htpasswd）；
|
||
- 默认头：Host / X-Real-IP / X-Forwarded-For。
|
||
|
||
Havline 侧对应链路：`ProxyOptions`（`internal/frp/model.go`）→ `DeployAgentRoute` → `AgentClient.SyncRouteEx`
|
||
→ `PUT /api/v1/routes`。
|
||
|
||
---
|
||
|
||
## 二、迁移清单
|
||
|
||
### 第一梯队：纯模板级改动，无 Nginx 上下文限制（建议先做）
|
||
|
||
| # | 功能 | 对应本地项 | 生成的 Nginx 指令 |
|
||
| --- | --- | --- | --- |
|
||
| 1 | **启用 HTTPS 开关** | 启用 HTTPS | 关闭时仅 `listen 80`；开启且证书已推送时 `listen 443 ssl` |
|
||
| 2 | **安全响应头** | 安全响应头 | `add_header Strict-Transport-Security / X-Frame-Options / X-Content-Type-Options / Referrer-Policy` |
|
||
| 3 | **仅 TLS 1.3** | 仅 TLS 1.3 | `ssl_protocols TLSv1.3;` |
|
||
| 4 | **客户端最大上传大小** | （本地为全局默认） | `client_max_body_size 50m;`（server 级，按规则可覆盖） |
|
||
| 5 | **代理超时** | （本地固定 3600s） | `proxy_read_timeout 3600s;`（长轮询 / 流媒体 / 大文件必需） |
|
||
| 6 | **IP 黑名单** | 黑名单模式 | location 内 `deny x.x.x.x;`（与现有白名单对称） |
|
||
| 7 | **Basic Auth 自定义密码** | Basic Auth 密码 | 用表单密码写 htpasswd；留空则保持「首次自动生成」 |
|
||
|
||
### 第二梯队：需要 Nginx `http` 上下文或额外数据下发（成本中等）
|
||
|
||
| # | 功能 | 关键约束 |
|
||
| --- | --- | --- |
|
||
| 8 | **请求限流** | `limit_req_zone` 只能出现在 `http` 块。agent 需额外生成 `havline-limits.conf`（宝塔将 vhost 目录 include 在 `http{}` 内，因此该文件顶层指令即 http 上下文），各域名 server 内 `limit_req zone=havline_<域名>_req burst=N nodelay;` |
|
||
| 9 | **连接数限制** | 同上，`limit_conn_zone` + `limit_conn havline_<域名>_conn N;` |
|
||
| 10 | **仅中国大陆 IP** | 需 `geo` 模块 + 中国 IP 段下发到 VPS（Havline 已有 china cidr 模块，7456 条 v4），下发体积最大、成本最高，建议最后做 |
|
||
|
||
### 明确不做（字段 / 语义不匹配）
|
||
|
||
| 功能 | 原因 |
|
||
| --- | --- |
|
||
| 使用目标 Host 头 | 公网回源目标是 frps 的 vhost 端口，**frps 靠 Host 头匹配隧道**。改成上游 Host 会让 vhost 无法路由，直接 404。必须保持 `$host` |
|
||
| 忽略后端 TLS 证书 | 公网 upstream 是 `http://127.0.0.1:<vhost端口>`，不涉及上游 TLS 校验，无作用 |
|
||
| 自定义 upstream 覆盖 | 技术上可行，但会让流量绕过 frps 隧道（健康检查「隧道」必然 ✗），语义属于「本机内网分流」，只在本地反代页做 |
|
||
|
||
---
|
||
|
||
## 三、字段契约
|
||
|
||
两侧 JSON key 必须严格一致（历史教训：字段未逐项对照导致多轮返工）。
|
||
|
||
| 显示名 | `ProxyOptions`（Go，`internal/frp/model.go`） | JSON key | TS（`web/src/api/types.ts`） | `routeRequest`（agent） | Nginx 指令 |
|
||
| --- | --- | --- | --- | --- | --- |
|
||
| 启用 HTTPS | `HTTPSDisabled bool` | `https_disabled` | `https_disabled?: boolean` | `HTTPSDisabled bool` | 关闭时不出 `listen 443` |
|
||
| 上传大小 | `ClientMaxBodySize string` | `client_max_body_size` | `client_max_body_size?: string` | `ClientMaxBodySize string` | `client_max_body_size 50m;` |
|
||
| 代理超时 | `ProxyReadTimeout string` | `proxy_read_timeout` | `proxy_read_timeout?: string` | `ProxyReadTimeout string` | `proxy_read_timeout 3600s;` |
|
||
| 安全响应头 | `SecurityHeaders bool` | `security_headers` | `security_headers?: boolean` | `SecurityHeaders bool` | `add_header ...` |
|
||
| 仅 TLS 1.3 | `TLS13Only bool` | `tls13_only` | `tls13_only?: boolean` | `TLS13Only bool` | `ssl_protocols TLSv1.3;` |
|
||
| IP 黑名单 | `DenyIPs []string` | `deny_ips` | `deny_ips?: string[]` | `DenyIPs []string` | `deny x;` |
|
||
| Basic Auth 密码 | `BasicAuthPassword string` | `basic_auth_password` | `basic_auth_password?: string` | `BasicAuthPassword string` | 写入 htpasswd |
|
||
| 请求限流（速率） | `RateLimitRate int` | `rate_limit_rate` | `rate_limit_rate?: number` | `RateLimitRate int` | `limit_req_zone ... rate=Nr/s;` |
|
||
| 请求限流（突发） | `RateLimitBurst int` | `rate_limit_burst` | `rate_limit_burst?: number` | `RateLimitBurst int` | `limit_req ... burst=N` |
|
||
| 连接数限制 | `ConnLimitMax int` | `conn_limit_max` | `conn_limit_max?: number` | `ConnLimitMax int` | `limit_conn_zone` / `limit_conn` |
|
||
| 仅中国大陆 | `ChinaOnly bool` | `china_only` | `china_only?: boolean` | `ChinaOnly bool` | `geo` + `allow`/`deny` |
|
||
|
||
约束：
|
||
|
||
- 这些字段**只作用于公网 Nginx 模板，绝不写入 frpc.toml**（与现有 `websocket` / `redirect_https` 等一致，在 `ProxyOptions` 上以注释标明）；
|
||
- 「启用 HTTPS」采用**反向字段 `https_disabled`**：字段缺省时保持现有行为（证书推送成功即启用 TLS），
|
||
保证新 Havline + 旧 agent、旧数据不出现行为突变。
|
||
|
||
---
|
||
|
||
## 四、实施步骤
|
||
|
||
### 阶段 1：第一梯队后端（agent + Havline）
|
||
|
||
1. `internal/agent/server.go`
|
||
- `routeRequest` 增加第一梯队字段；
|
||
- `nginxRoute` 模板按字段输出指令：`listen 443` 受 `HTTPSDisabled` 控制；`redirect_https` 仅在 TLS 实际启用时生成；
|
||
- `client_max_body_size` / `proxy_read_timeout` / 安全响应头 / `ssl_protocols` / `deny` 列表；
|
||
- Basic Auth：传入密码时 `htpasswd -nbB` 写入，未传则沿用现有「首次自动生成 + 复用」。
|
||
2. `internal/frp/model.go`：`ProxyOptions` 增加同名 Go 字段（含注释）。
|
||
3. `internal/frp/agent_client.go`：`SyncRouteEx` 参数改为**传结构体**（当前 10 个位置参数已到上限，继续追加易错）：
|
||
```go
|
||
type RouteSpec struct {
|
||
Domain, Upstream, CertDir string
|
||
TLS, WebSocket, RedirectHTTPS, HTTPSDisabled bool
|
||
VhostPort int
|
||
AllowIPs, DenyIPs []string
|
||
BasicAuthUser, BasicAuthPassword string
|
||
ClientMaxBodySize, ProxyReadTimeout string
|
||
SecurityHeaders, TLS13Only bool
|
||
}
|
||
func (c *AgentClient) SyncRouteSpec(ctx, spec RouteSpec) (map[string]any, error)
|
||
```
|
||
保留 `SyncRoute` / `SyncRouteEx` 作为兼容包装。
|
||
4. `internal/frp/service.go`：`DeployAgentRoute` 从 `proxy.Options` 组装 `RouteSpec` 透传。
|
||
|
||
### 阶段 2：第一梯队前端
|
||
|
||
5. `web/src/api/types.ts` 补 `FrpProxyOptions` 字段；
|
||
6. `ProxyRemoteView.vue`「部署设置」弹窗改为三个 Tab（与本地反代结构对齐）：
|
||
- **基础**：启用 HTTPS、HTTP 强制跳转、WebSocket、上传大小、代理超时；
|
||
- **安全**：IP 白名单、IP 黑名单、Basic Auth（用户名 + 可选密码）；
|
||
- **高级**：仅 TLS 1.3、安全响应头（第二梯队上线后再加限流/连接数/中国 IP）。
|
||
|
||
### 阶段 3：第二梯队（按需）
|
||
|
||
7. agent 增加 `havline-limits.conf` 生成器（http 上下文 zone 定义）+ 每域名 server 引用；
|
||
8. 中国 IP：Havline 将 china cidr 列表推送到 agent（`/var/lib/havline-agent/geo/china.conf`），agent 生成 `geo` 块。
|
||
|
||
---
|
||
|
||
## 五、验证方案
|
||
|
||
每次改动后全量跑（项目既有闭环）：
|
||
|
||
```powershell
|
||
cd f:\Havline-main\Havline-1.0.2
|
||
gofmt -w internal/agent/server.go internal/frp/model.go internal/frp/agent_client.go internal/frp/service.go
|
||
go build ./... ; go vet ./internal/frp ./internal/agent ./internal/api
|
||
go test ./internal/frp ./internal/api
|
||
cd web ; npx vue-tsc --noEmit ; npx vite build
|
||
```
|
||
|
||
agent 二进制需按既有流程交叉编译（amd64 + arm64）并升级：
|
||
|
||
```powershell
|
||
$env:GOOS='linux'; $env:GOARCH='amd64'; $env:CGO_ENABLED='0'
|
||
go build -trimpath -o internal/frp/agentbin/havline-agent-linux-amd64.new ./cmd/havline-agent
|
||
# arm64 同理；Move-Item 覆盖后，在「公网 Agent」页执行「升级 Agent」
|
||
```
|
||
|
||
VPS 侧实测（部署 7023 规则后）：
|
||
|
||
```bash
|
||
nginx -t # 语法
|
||
cat /www/server/panel/vhost/nginx/havline-7023.36800.cc.conf # 配置内容（或页面「查看配置」）
|
||
curl -I http://7023.36800.cc # 强制跳转 → 301
|
||
curl -sI -H 'Host: 7023.36800.cc' http://127.0.0.1:9080 # 回源自检
|
||
curl -k -sI https://7023.36800.cc # 响应头（HSTS / X-Frame-Options）
|
||
openssl s_client -connect 7023.36800.cc:443 -tls1_2 </dev/null | head -3 # 仅 TLS1.3 时应握手失败
|
||
curl -sI -H 'Host: 7023.36800.cc' -d @bigfile http://127.0.0.1:9080 # 上传大小限制
|
||
for i in $(seq 1 50); do curl -s -o /dev/null -w '%{http_code} ' http://7023.36800.cc/; done # 限流 → 429（第二梯队）
|
||
```
|
||
|
||
排查口径沿用现有约定：健康检查五段徽标（DNS / 证书 / 隧道 / 服务 / 反代生效态）任一 ✗，
|
||
悬停看详情定位断点，不再靠猜。
|
||
|
||
---
|
||
|
||
## 六、兼容性与回滚
|
||
|
||
| 场景 | 期望行为 |
|
||
| --- | --- |
|
||
| 新 Havline + 旧 agent | 旧 agent 忽略未知 JSON 字段（Go 默认行为），新选项静默不生效 → **部署前必须先「升级 Agent」**，页面提示 |
|
||
| 旧 Havline + 新 agent | 新字段缺省，行为与现状一致（`https_disabled` 缺省 = 启用 TLS） |
|
||
| frps v0.68.0 / v0.71.0 | 与本方案无关（作用于 Nginx vhost，不依赖 dashboard API） |
|
||
| 回滚 | 关闭对应开关后重新部署即可恢复；agent 侧每域名配置为整文件覆盖写，无残留 |
|
||
|
||
---
|
||
|
||
## 七、附：与既有文档的关系
|
||
|
||
- `docs/agent-proxy-roadmap.md`：功能梯队总览（本方案是其「第二批」在部署设置维度的细化）；
|
||
- `docs/frps-features.md`：frps 服务端配置能力对照（frps.toml 层面，与本文的 Nginx 层面互补）。
|