feat: create standalone native fnOS repository
This commit is contained in:
@@ -0,0 +1,156 @@
|
||||
# FRPS 服务端自动管理方案（frps-manager）
|
||||
|
||||
> 目标：frpc 端在 Havline 提交穿透规则后，frps 端**自动完成反向代理配置与生效**，实现域名无端口访问（`http://tv.36800.cc`），并自动管理 VPS 侧证书。本文是基于现有项目（Havline v1.1.0 FRP 多服务端模块）的实施方案，不引入新服务、不改 frp 二进制。
|
||||
|
||||
## 1. 现状与问题
|
||||
|
||||
当前（v1.1.0）frpc 侧规则提交后：
|
||||
|
||||
| 环节 | 现状 | 问题 |
|
||||
| --- | --- | --- |
|
||||
| tcp 规则注册（远程端口） | ✅ 自动（frpc 登录时向 frps 动态注册） | 无 |
|
||||
| http 规则域名路由 | ⚠️ 需 frps.toml 预先配置 `vhostHTTPPort` | 首次使用 http 类型时 VPS 要手工改配置+重启 |
|
||||
| frps.toml 生成 | ✅ Havline 一键生成，用户手动复制到 VPS | 每次变更都要 SSH 手工同步 |
|
||||
| VPS 端口释放（80/443 被占） | ❌ 手动 SSH 停 Nginx | `port unavailable` 最常见根因 |
|
||||
| 改配置后生效 | ❌ 手动 `pkill frps` 重启（frp 无热加载） | 容易忘、容易误 |
|
||||
| VPS 侧证书 | ❌ 无 | HTTPS 要在 VPS 手工装证书 |
|
||||
| 配置漂移检测 | ❌ 无 | VPS 上的文件与 Havline 数据库可能不一致 |
|
||||
|
||||
## 2. 总体设计
|
||||
|
||||
在 Havline（frpc 所在机器）新增 **frps-manager** 子系统：Havline 通过 **SSH** 连接 VPS，执行「检测 → 生成 → 推送 → 生效 → 验证」闭环。VPS 侧**零安装**（只要求 frps + SSH）。
|
||||
|
||||
```text
|
||||
Havline (NAS) VPS (38.95.74.87)
|
||||
┌─────────────────────────────┐ ┌──────────────────────────┐
|
||||
│ FRP 模块（现有） │ │ frps (7000/80/443/7500) │
|
||||
│ 规则/服务端 CRUD │ │ ↑ frpc 动态注册端口 │
|
||||
│ frps-manager（新增） │ SSH │ frps.toml (推送产物) │
|
||||
│ 检测→生成→推送→reload→验证 │ ────────→ │ /etc/havline/frps/ │
|
||||
│ 证书申请→推送→挂载 │ │ /etc/havline/frps/certs/ │
|
||||
└─────────────────────────────┘ └──────────────────────────┘
|
||||
```
|
||||
|
||||
核心思路：**frps 不认识"反代"，它只认 frps.toml**。因此"自动反代"= ① 规则变化时重算出应然的 frps.toml（含 vhost 端口、subDomainHost、TLS 配置）→ ② 与 VPS 现状 diff → ③ 无变化则跳过，有变化则原子推送 → ④ 通过 frps **admin API 热重载**（无需重启进程）→ ⑤ 回读验证。证书同理：Havline 证书页现有 ACME 能力签好后把证书文件推到 VPS 并写入 frps.toml 的 `transport.tls`/`webServer.tls` 段。
|
||||
|
||||
## 3. 服务端模型扩展（frp_servers 表）
|
||||
|
||||
新增「服务端连接信息」（加密存储，复用 secret.Box）：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `ssh_host` | TEXT | VPS SSH 地址（可与 server_addr 不同） |
|
||||
| `ssh_port` | INTEGER | 默认 22 |
|
||||
| `ssh_user` | TEXT | 建议 root 或具备 sudo 的用户 |
|
||||
| `ssh_auth` | TEXT | `password` / `key` |
|
||||
| `ssh_secret_enc` | TEXT | 密码或私钥（加密） |
|
||||
| `frps_dir` | TEXT | VPS 上 frps 目录，默认 `/etc/havline/frps` |
|
||||
| `frps_bin` | TEXT | frps 二进制路径，默认 `/usr/local/bin/frps` |
|
||||
| `mgmt_enabled` | INTEGER | 是否启用自动管理（0/1，默认 0=纯手动，向后兼容） |
|
||||
|
||||
迁移 `023_frp_server_ssh.sql`。SSH 凭据用 secret.Box 加密，接口不回显（同 Token 处理）。
|
||||
|
||||
## 4. 核心流程
|
||||
|
||||
### 4.1 检测（Probe）——服务端详情新增「检测服务端」按钮
|
||||
|
||||
一次 SSH 会话内批量执行（只读，不改任何东西）：
|
||||
|
||||
```bash
|
||||
frps --version # 版本
|
||||
ss -tlnp | grep -E ':(80|443|7000) ' # 端口占用者（frps? nginx? 其他?）
|
||||
systemctl is-active nginx frps # 服务状态
|
||||
cat /proc/$(pidof frps)/cmdline # 实际使用的配置路径
|
||||
cat <配置路径> # 现有 frps.toml 内容（做 diff）
|
||||
```
|
||||
|
||||
返回结构化报告：frps 版本/运行状态/配置路径、80/443 占用者判定（frps/nginx/其他/空闲）、现有 frps.toml 与 Havline 期望配置的 **diff 摘要**、待办建议（如「80 被 nginx 占用，需释放」）。这就是用户之前反复手工排查的自动化。
|
||||
|
||||
### 4.2 下发（Apply）——「自动反代」的主流程
|
||||
|
||||
触发时机：用户点「下发配置」，或规则保存后若 `mgmt_enabled` 且检测到配置将变化（规则含 http 类型 / 证书变更）自动触发。
|
||||
|
||||
1. **生成期望配置**：扩展现有 `buildFRPSServerConfig`：
|
||||
- 存在 http/https/tcpmux 规则 → 输出 `vhostHTTPPort = 80`、`vhostHTTPSPort = 443`（去端口访问的关键）；
|
||||
- 存在 subdomain 规则 → 输出 `subDomainHost = <用户在服务端表单新填的主域>`；
|
||||
- 证书启用时输出 `transport.tls.force` / `webServer.tls` 段；
|
||||
2. **SSH 推送（原子）**：新内容写 `/etc/havline/frps/frps.toml.new` → `mv` 原子替换 → 旧文件留 `frps.toml.bak`（回滚点）；
|
||||
3. **热重载**：调 frps admin API `PUT /api/reload`（frps webServer 7500 已有 Basic Auth 凭据）——**不杀进程**，连接不断；API 不可用时降级 `systemctl restart frps`（nohup 场景提示用户）；
|
||||
4. **验证**：重读 VPS 上的 frps.toml 确认与期望一致 + `ss` 确认 80/443 已由 frps 监听 + 通过公网侧发起一次探测请求；
|
||||
5. 全程动作与输出写入系统日志（复用 logstore），UI 弹窗展示每步结果。
|
||||
|
||||
### 4.3 释放端口（安全加固提示，不偷偷杀人）
|
||||
|
||||
检测发现 80/443 被 nginx 等占用时，**不自动杀进程**（危险动作），而是：
|
||||
- 检测报告中标红 + 给出一键命令；
|
||||
- UI 提供「释放端口」按钮：二次确认后执行 `systemctl stop nginx && systemctl disable nginx`（仅当占用者确认为 nginx 时可点，其他占用者只提示不动手）；
|
||||
- 释放后自动重跑 Apply 验证闭环。
|
||||
|
||||
### 4.4 证书管理（VPS 侧 HTTPS）
|
||||
|
||||
复用 Havline 证书页现有 ACME（lego）能力，证书签发在 NAS 侧完成（DNS-01，无需 VPS 参与），然后：
|
||||
|
||||
1. 证书页选「部署到 VPS」→ 选目标服务端；
|
||||
2. SSH 推送 `fullchain.pem` / `privkey.pem` 到 `/etc/havline/frps/certs/<域名>/`（0600）；
|
||||
3. frps.toml 写入 `webServer.tls.certFile/keyFile`（管理面板 HTTPS）；对外流量 TLS 若需要也在 frps 侧终止时，走 `transport.tls` 相关段（v0.71 支持 `transport.tls.force` + 证书）；
|
||||
4. 续期：Havline 证书定时任务续期成功后自动重推 + reload（证书 60 天滚动，VPS 侧无感）。
|
||||
|
||||
> 设计取舍：对外业务的 HTTPS 终止仍推荐在 **Havline Nginx（NAS 侧）**（本手册方案 A 架构），frps 侧证书用于 webServer 管理面板与 `tls.force` 场景。若用户想让 VPS 终止 TLS，同一套推送机制也覆盖。
|
||||
|
||||
## 5. API 与 UI
|
||||
|
||||
### 5.1 新增 API（挂在 `/api/frpmulti` 下，鉴权与现有中间件一致）
|
||||
|
||||
| 方法/路径 | 作用 |
|
||||
| --- | --- |
|
||||
| `PUT /servers/{id}/ssh` | 保存 SSH 连接信息（加密存储） |
|
||||
| `GET /servers/{id}/probe` | 检测：frps 状态/端口占用/配置 diff |
|
||||
| `POST /servers/{id}/apply` | 下发期望配置 + reload + 验证 |
|
||||
| `POST /servers/{id}/release-port` | 释放被占端口（body: `{port, confirm: true}`） |
|
||||
| `POST /servers/{id}/push-cert` | 推送证书到 VPS 并挂载 |
|
||||
|
||||
### 5.2 前端（FrpView.vue）
|
||||
|
||||
- 服务端表单「高级配置」折叠区新增「远程管理」分组：SSH 地址/端口/用户/认证方式/密钥（ConfiguredSecretField，v-model）/frps 目录；
|
||||
- 服务端列表操作列新增「管理」按钮 → 弹窗（复用 `proxy-modal` 自绘骨架）三块：检测报告（分色状态行）、diff 视图（`<pre>` 左右对照期望/现状）、操作按钮（下发配置 / 释放端口 / 推送证书）；
|
||||
- 规则保存时的自动下发提示：非阻塞 toast「检测到 vhost 配置变化，点击下发」。
|
||||
|
||||
## 6. 实现拆解与工作量
|
||||
|
||||
| 模块 | 文件 | 内容 | 量级 |
|
||||
| --- | --- | --- | --- |
|
||||
| 迁移 | `migrations/023_frp_server_ssh.sql` | SSH 字段 | 小 |
|
||||
| SSH 客户端 | `internal/frp/ssh.go`（新） | 连接池/单会话命令执行/SFTP 推送/超时 | 中（x/crypto/ssh 已在 go.mod） |
|
||||
| 检测 | `internal/frp/probe.go`（新） | 探测命令编排 + 结果结构体 + 80 占用者判定 | 中 |
|
||||
| 配置 diff/应用 | `internal/frp/frps_apply.go`（新） | 期望配置生成（扩展现有 frps_template）、diff、原子推送、admin API reload、验证 | 中 |
|
||||
| 证书推送 | `internal/frp/cert_push.go`（新） | 证书文件推送 + frps.toml 证书段写入 | 小 |
|
||||
| Service/API | `frpmulti_handler.go` + `router.go` | 5 个端点 | 小 |
|
||||
| 前端 | `FrpView.vue` + `client.ts` | 管理弹窗 + 表单分组 + 按钮 | 中 |
|
||||
| 测试 | `probe_test.go` `frps_apply_test.go` | 命令输出解析、diff、原子写逻辑 | 中 |
|
||||
|
||||
总计约 1500–2000 行（含测试），纯增量、不动现有链路（`mgmt_enabled=0` 时行为与 v1.1.0 完全一致）。
|
||||
|
||||
## 7. 安全设计
|
||||
|
||||
1. SSH 凭据 secret.Box 加密落库，API 永不回显（同 token 掩码机制）；
|
||||
2. 推荐文档引导用户用**密钥登录**（Havline 可一键生成 ed25519 密钥对、展示公钥让用户贴到 VPS `authorized_keys`）；
|
||||
3. 所有远程命令为**固定白名单模板**（版本/端口/状态/替换文件/reload），不拼接用户输入，杜绝命令注入；SFTP 只写 `/etc/havline/frps/` 前缀内路径；
|
||||
4. 危险动作（释放端口、重启 frps）二次确认 + 动作日志；
|
||||
5. Apply 幂等：重复执行无副作用（diff 无变化即跳过）；
|
||||
6. frps admin API 调用走本机 127.0.0.1:7500（SSH 远端执行 curl），不暴露公网。
|
||||
|
||||
## 8. 里程碑
|
||||
|
||||
| 阶段 | 内容 | 验收 |
|
||||
| --- | --- | --- |
|
||||
| M1 | 迁移 + SSH 客户端 + 检测（Probe） | 服务端「检测」按钮能报告 frps 状态与 80 占用者 |
|
||||
| M2 | 期望配置生成 + diff + 原子推送 + reload + 验证 | 改规则后一键下发，`http://域名` 直达，`port unavailable` 类问题由系统自愈 |
|
||||
| M3 | 证书推送 + 续期联动 | 证书页一键部署到 VPS，续期自动重推 |
|
||||
| M4 | UI 完善 + 文档（手册第 6 节追加方案 A'） | 手册更新，`port unavailable` 类问题由系统自愈 |
|
||||
|
||||
## 9. 明确不做（本期）
|
||||
|
||||
- 不实现 VPS 伴生 agent（能力更强但需安装，作为后续可选演进）；
|
||||
- 不做 frps 二进制的远程安装/升级（用户自装，检测报告给出版本即可）；
|
||||
- 不做多 VPS 并行下发编排（现有逐服务端模型已覆盖）；
|
||||
- 不改 frp 二进制、不依赖 frp 私有接口（只用 admin API 与文件系统）。
|
||||
Reference in New Issue
Block a user