# 自有 HTTPS 反向代理

[English guide](SELF_HOSTED_ORIGIN.en.md)

> 本功能自 **0.4.2** 起随包发布。

## 适用场景与安全边界

你已有 Lucky、Nginx、Caddy 等 HTTPS 反向代理，不需要 Funnel、cpolar 或 FRP 隧道。进入电脑端 **移动访问 → 远程 → 自建连接 → 自有反向代理**，让插件提供一个独立的、带设备配对认证的私有 HTTP 后端：

```text
手机 → https://phone.example.com:8815（你的代理终止 TLS）
     → http://192.168.50.10:3444（本插件的私有 HTTP 后端）
     → 当前 DSH WebServer（仍由插件内部连接）
```

- **只有第一段允许暴露公网。HTTP 后端不能做公网端口映射。** HTTP 段仅适用于可信私网；局域网其他设备上的代理也会接触明文流量。
- 后端不是裸 DSH：仍执行设备配对、认证、归一化后精确匹配的 Host/Origin 校验、CSRF、Secure Cookie 和 WebSocket 路径策略。没有配对的访问不能直接进入 DSH。**不要用浏览器直接打开这个明文 HTTP 后端做验证**：Cookie 带 `Secure`，浏览器在 `http://` 下会丢弃它们，登录或 CSRF 会无提示失败。
- 不要把公网反代目标改成 DSH 的 WebServer 端口（默认 3080），也不要反代现有 LAN HTTPS 3443。新后端默认 3444，**明确拒绝 3443 和 3080**，并拒绝 1024 以下需要特权的端口。注意 3444 同时是 cloudflared 命名隧道的默认转发端口：同一时刻只有一个远程提供方能运行，但切换到本提供方时请确认该端口已释放。DSH 与 LAN 的原有设置不变。
- 公网 TLS、证书续期、DNS、路由和代理由你管理。插件不会安装隧道组件、部署 VPS、修改代理/防火墙/路由器，也不会为该提供方发起公网探测。

## 填写四项设置

以下均为通用示例，替换成自己的地址。

| 字段 | 代理与 DSH 同机 | 代理在另一台 LAN 设备 |
| --- | --- | --- |
| 公网 HTTPS 地址 | `https://phone.example.com:8815` | `https://phone.example.com:8815` |
| 私有监听 IPv4 | `127.0.0.1` | DSH 电脑的私网地址，如 `192.168.50.10` |
| HTTP 后端端口 | `3444` | `3444` |
| 允许的代理来源 CIDR | `127.0.0.0/8` | 代理的实际来源，如 `192.168.50.1/32` |

公网地址只能是 HTTPS Origin，可带非 443 端口；不包含路径、账号密码、查询参数或 fragment。私有/保留 IP、本地域名和 IPv6 字面地址不适用于此提供方。

监听地址必须是**本机已有的明确回环或 RFC1918 私有 IPv4**，不能填 `0.0.0.0`、主机名、公网 IP 或 IPv6。端口必须是 **1024–65535** 的整数，并排除 3443（局域网网关）与 3080（DSH 自身）；请使用未被占用的端口。

CIDR 限制针对 TCP 连接的**直接来源地址**，不是手机 IP，也不是 `X-Forwarded-For`、`X-Real-IP` 或 `Forwarded`。Docker、桥接或 NAT 可能改变这个地址，应填写后端实际看到的私网来源。优先用单地址 `/32`，不要为了排错放宽整个局域网。最多 16 项，用空格或逗号分隔；只允许回环/私网网段，网络地址不能带主机位。LAN 监听必须显式列出私网代理来源。

点击 **保存并启动后端**。已经开启时会重新载入配置。面板会分别显示公网 HTTPS 地址与**正在监听的 HTTP 后端**；停止后仍可查看、复制已保存的后端地址。

## 反向代理要求（含 Lucky）

1. 在代理上为公网地址配置可信的 HTTPS 证书，并终止 TLS。不要让手机忽略证书错误。
2. 代理目标使用面板给出的 **HTTP 后端地址**，而不是手机使用的 HTTPS 地址。
3. **保留请求的外部 Host，包含非默认端口。** 上例后端必须收到 `Host: phone.example.com:8815`，不能改成 `192.168.50.10:3444`，也不能漏掉 `:8815`。
4. 透传浏览器的 Origin、Cookie、Set-Cookie，以及认证/CSRF 相关头，不要改写 Cookie 的域或安全属性；不要缓存配对或认证响应。
5. 透传 WebSocket 升级（HTTP/1.1、Upgrade、Connection）以及双向数据。已有的 WebSocket 路径白名单继续生效；第三方插件需要时仍在现有面板中单独允许其路径。

根据 [Lucky 官方 Web 模块文档](https://lucky666.cn/docs/modules/web)，WebSocket 默认支持，不必寻找单独的开启开关。Host 自定义模式应使用 **“使用请求Host”**，不要选 **“使用目标地址Host”**，并核对非默认端口没有丢失。TLS/证书仍配置在 Lucky，不在这个 HTTP 后端上配置。

若代理在另一台机器上，还需由管理员保证网络可达，并将主机防火墙入站范围限制到代理的实际私网来源；此功能不自动改防火墙。

## 状态与手机验证

**“后端已监听”只证明本地 HTTP 监听成功，不代表公网 HTTPS、证书或 WebSocket 已成功。** 本提供方的连接诊断也只报告本地状态，不自动向公网地址探测。

在电脑端点击 **生成远程配对二维码**，再在 Android App **0.4.0 或更高版本**的 **远程访问** 流程扫码（不要使用 LAN 扫码流程）。现场验证中 0.3.16 会拒绝自有域名配对；现有自有域名逻辑保留 HTTPS 自定义端口，无需为此功能修改 APK。

上线前，必须用手机从目标外网实际检查：

- 公网地址的域名、端口和证书均正确；
- 扫码配对并登录 DSH 成功；
- 发起对话或其他实时操作，确认 WebSocket 持续工作；
- 关闭此后端后远程入口失效，而原有 LAN 访问仍正常。

本仓库的本地集成测试使用真实 HTTPS 代理、HTTP 后端和 WebSocket 回环链路；它不能替代你自己的 Lucky、服务器、外网和手机验收。

## 停止、清除配置与重置设备

| 操作 | 结果 |
| --- | --- |
| 关闭远程访问 | 停止此后端，保留配置与配对设备。 |
| 清除代理配置（需确认） | 停止此后端，只删除它的代理设置；保留远程配对设备、LAN 和其他提供方配置。 |
| 关闭并清除远程设备（需确认） | 现有通用重置操作；清除共享远程配对，所有远程设备需重新配对；保留代理设置与 LAN 设备。 |
| 切换提供方 | 现有协调器先停止前一提供方；只允许一个远程提供方运行，不影响 LAN。 |

默认数据根目录为 `$DSH_HOME/mobile-access/`（定制安装以实际路径为准）。新增设置是 `remote/origin/config/settings.json`，开启状态是 `remote/origin/control.json`；沿用 `remote/devices.json` 共享远程设备存储。正常退出后配置保留；再次启动 DSH 时，仅当前选中且已开启的提供方恢复监听。

## 常见问题

- **端口占用**：换一个空闲后端端口并同步修改代理目标；不要挪动现有 LAN 或 DSH 端口。
- **监听地址不可用**：填写 DSH 本机当前私有 IPv4，不是代理机器的 IP。
- **被拒绝 / 403**：核对直接来源 CIDR、完整外部 Host 和 HTTPS Origin；伪造转发头不会绕过这些检查。
- **HTTP 页面可开但实时功能失败**：核对代理 WebSocket 转发、超时及路径白名单，不要通过关闭来源验证来排错。
- **只有“后端已监听”**：这是预期语义；继续检查公网 DNS、端口映射到 HTTPS 代理、证书及手机实际访问。