# Refract / 洞流 — 客户说明书（使用手册）

> 数据中心被动旁路加密流量检测平台
> 版本 v0.2 ｜  © 润迅数据

本手册面向部署与日常使用 Refract 的运维 / 安全 / 合规人员。阅读对象无需开发背景。

---

## 1. Refract 是什么 / 不是什么

**是**：接在镜像/分光口上的**只读观测平台**，从加密流量里识别 VPN/代理/隧道与加密货币挖矿，
给出带证据的判定，并自动开工单。

**不是**：它**不是防火墙、不是网关、不在数据通路上**。它**永远不会阻断、改写或解密**你的流量，
因此**不可能因它而中断业务**。处置动作（限速/隔离/约谈）由你的人和流程决定。

---

## 2. 工作原理（一分钟版）

1. 交换机把流量**镜像**一份（或用光分路器 TAP），送到 Refract 的采集网卡。
2. Refract 解析出每条会话的"指纹"与"行为特征"（**不看内容明文**）。
3. 多层弱信号融合打分，给每个源 IP 一个**置信度 + 判定档**（确认/高度疑似/疑似/正常）。
4. 非正常判定自动生成**工单**与**取证卷宗**，在 NOC 看板实时呈现。

---

## 3. 部署拓扑

```
        交换机 SPAN / 光分路器(TAP)
                  │  (只读镜像，单向)
                  ▼
        ┌──────────────────────┐
        │   Refract 采集主机     │   采集口：promisc、无 IP（纯被动）
        │  ┌────────────────┐   │   管理口：另一张网卡，走 SSH/Web
        │  │     采集解析    │   │
        │  │ 引擎(检测/打分) │   │
        │  │ Web NOC 看板    │   │
        │  │ TimescaleDB     │   │
        │  └────────────────┘   │
        └──────────────────────┘
                  │ 管理口
                  ▼
            浏览器访问 http://<管理IP>:8080
```

- **采集口**：接镜像/分光流量，须设为混杂模式、不配 IP。多张网卡可分别采集或 Zeek 集群聚合。
- **管理口**：独立网卡，用于浏览器访问与 SSH 运维。
- 线速需求高（25/40/100G）时启用 PF_RING ZC 绑核多队列。

---

## 4. 首次部署清单

1. 准备一台接好镜像/分光口的主机（或使用 Refract Appliance / Max R30 Edge）。
2. 复制配置模板：`cp deploy/.env.example deploy/.env`，**务必修改**：
   - `DB_PASSWORD`（数据库口令）
   - `REFRACT_ENV=production`（启用上线安全自检）
   - `REFRACT_JWT_SECRET`（`openssl rand -base64 48` 生成强随机串）
   - `REFRACT_ADMIN_PASSWORD` / `REFRACT_ANALYST_PASSWORD` / `REFRACT_VIEWER_PASSWORD`
   - `REFRACT_AUTH_REQUIRED=1`（开启全站登录墙）
   - `REFRACT_CAPTURE_IFACE=<你的采集口>`（如 `mgbe2_0`，用 `ip -br link` 确认）
3. 启动：`docker compose up -d`（默认干净启动，不含演示数据）。
4. 浏览器访问 `http://<管理IP>:8080`，用 admin 账号登录。
5. 接好分光线后，在「流量接入」页选采集口启动采集。

> ⚠ 生产环境若未设强密钥/口令，引擎会**拒绝启动**（fail-closed），这是有意的保护。

---

## 5. 看板导览（左侧菜单）

界面分三组：**检测 / 处置 / 系统**。

### 检测
- **总览**：全局 KPI（处理会话数、独立源 IP、疑似挖矿主机）、隧道与挖矿的**判定分布**、
  以及「重点隧道嫌疑」「疑似挖矿主机」两张 Top 榜，点「查看全部」进入对应检测页。
- **VPN检测**：所有命中隧道判定的源 IP 列表，按置信度倒序。
- **挖矿检测**：所有命中挖矿判定的源 IP 列表。
- **IP 详情**（点任意 IP）：
  - 头部显示该 IP 的**隧道 / 挖矿判定 + 置信度**（只展示命中的类别）。
  - **信号分解**：按 L1–L5 / M1–M5 分层列出每条证据，回答"**为什么判它**"。
  - **导出证据**：报告 PDF / 证据 JSON / 握手切片 pcap（按类别分别导出）。
  - **人工复核动作**：标注（喂校准）、加入白名单（误报闭环）。

### 处置
- **告警工单**：自动生成的工单队列，带类别徽章（隧道/挖矿）、严重度、置信度、状态。
  可改状态（待处理/已受理/已解决/误报）或一键「误报·加白」闭环。

### 系统
- **可信名单**：白名单。支持 **CIDR**（源 IP 整体跳过）、**ASN**、**SNI**（信任的目的地）。
  加白会联动删除对应判定、关闭相关工单。
- **模型校准**：人工标注样本 → 拟合 Platt/Isotonic → 校准后概率重新打分；展示可靠性曲线与估算误报率。
- **流量接入**：查看宿主网卡、一键启动/切换采集口（无需改配置重启；需启用采集控制）。
- **系统设置**：
  - **修改密码**（任意登录用户改自己密码）。
  - **登录锁开关**（管理员，运行时即时生效、免重启；⚠ 公网环境请保持开启）。
  - **用户管理**（管理员：列出/新增/删除用户，分配角色）。

页面**右上角页眉**常驻：实时连接指示灯（实时/离线）+ 当前用户/角色 + 登出。

---

## 6. 判定怎么读

| 判定 | 含义 | 建议 |
|---|---|---|
| **确认隧道 / 确认挖矿** | 确定性证据（握手指纹 / 明文签名）+ 切片铁证 | 高可信，可据此进入处置流程 |
| **高度疑似** | 多个中强信号融合 | 优先人工复核 |
| **疑似** | 单一/弱信号 | 关注、积累证据，勿单凭此处置 |
| **正常** | 无显著信号 | 无需关注 |

> 重要：**任何判定都不应被单独、自动地用于封禁**。Refract 是"望远镜"，扳机始终在人手里。

---

## 7. 角色与权限（RBAC）

| 角色 | 权限 |
|---|---|
| **viewer（只读）** | 查看看板与判定 |
| **analyst（分析员）** | 读 + 改工单状态、加白、标注校准、导出证据 |
| **admin（管理员）** | 全部 + 用户管理、登录锁开关、采集启停 |

---

## 8. 日常运维

- **重启自恢复**：核心服务 `restart: always`，宿主重启后自动拉起；数据持久化于命名卷，不丢失。
- **看状态**：`docker compose ps`；看日志 `docker compose logs -f engine`。
- **更新**：拉取新版镜像后 `docker compose up -d`（同架构可直接复用镜像）。
- **取证留存**：可配置 `REFRACT_EVIDENCE_RETENTION_DAYS` 周期裁剪旧卷宗；裁剪会留痕，
  与"篡改删除"可区分（合法裁剪不报警）。

---

## 9. 安全建议（重要）

1. **登录墙常开**：公网或共享网络部署务必 `REFRACT_AUTH_REQUIRED=1`。
2. **限制管理面访问**：把 NOC 端口（默认 8080）限制到可信来源或走 VPN/SSH 隧道，勿裸奔公网。
3. **强口令 + 改默认**：admin/analyst/viewer 口令、JWT 密钥、数据库口令全部设强随机值。
4. **采集控制按需开**：「流量接入」的一键启停依赖 docker 控制权限（容器内 root 级），
   **仅建议在气隙 appliance 内启用**；公网机优先用命令行启停采集。

---

## 10. 常见问题（FAQ）

**Q：会影响业务吗？**
A：不会。Refract 在旁路、只读，物理上不在数据通路，永不阻断/改写。

**Q：会解密我的流量吗？**
A：不会。默认只做指纹与行为分析，不碰 payload 明文。

**Q：右上角显示"离线"？**
A：那是实时推送（WebSocket）指示灯。请确认已登录（登录墙开启时实时连接需携带登录态），
刷新页面即可；若仍离线，检查引擎是否健康。

**Q：采集页提示"未启用"？**
A：一键采集控制需在 `.env` 设 `REFRACT_DOCKER_CONTROL=1` 并挂载 docker.sock 后重启引擎；
公网机不建议开启，可改用命令行启动采集。

**Q：为什么有些代理/隧道只标"疑似"不标"确认"？**
A：VLESS+Reality、Cloudflare WARP、iCloud Private Relay 等在纯被动视角下无法确证，
Refract 坚持不谎报。这是诚实，也是可信的前提。

---

*Refract / 洞流 © 润迅数据。被动旁路 · 只读不阻断 · 概率判定须人工复核。*