# CF-VNC 隧道 · 交付报告

> 版本 **a.1.0.1** ｜ 日期 2026-11-20 ｜ 平台 Windows 10/11 x64 ｜ 作者 Doubao

---

## 1. 交付物

| 文件 | 说明 |
|---|---|
| `cfg.txt` | 全部选项预设：临时/固定、认证方式、端口、鉴权、noVNC 参数、组件、自启 |
| `cfvnc.exe` | 主程序：本地 noVNC 网关 + cloudflared 管理 + 命令行 |
| `bin\cloudflared.exe` | Cloudflare 官方隧道客户端（随包，离线可用） |
| `1-一键启动.bat` … `8-编辑配置.bat` | 双击入口 |
| `README.md` | 使用说明、cfg 全表、故障排查 |
| 本报告 | 验证记录与边界 |

源码：`src/`（11 个 Go 文件，约 2470 行，含 noVNC 1.5.0 嵌入资源）。

---

## 2. 实现要点

### 2.1 两种模式

| 模式 | 账号 | 地址 | 生命周期 |
|---|---|---|---|
| `mode=temp` | 不需要 | 随机 `https://xxx.trycloudflare.com` | 进程退出即失效 |
| `mode=fixed` | 需要（Token / API / 本地证书） | 自己的域名 | 固定，重启不变 |

### 2.2 固定模式全自动链路（`fixed_auth=api`）

```
GET  /accounts/{acc}/cfd_tunnel?name=cfvnc-win     查重
POST /accounts/{acc}/cfd_tunnel                    建隧道（config_src=cloudflare）
PUT  /accounts/{acc}/cfd_tunnel/{id}/configurations 写 ingress → http://127.0.0.1:6080
GET  /zones/{zone}/dns_records?name=host            查 DNS
POST /zones/{zone}/dns_records                      CNAME → {id}.cfargotunnel.com（proxied）
cloudflared tunnel run --token ...                  起隧道
```

不存在则建，存在则复用；RFC 1918 之外的 DNS 记录若类型/内容不对会自动改。

### 2.3 本地网关

- `GET /` → 302 到 `/vnc.html?autoconnect=1&resize=remote&path=websockify…`
- `GET /websockify` → WebSocket（`binary` 子协议）↔ TCP `vnc_host:vnc_port` 双向透传
- `GET /healthz` → JSON（版本、模式、VNC 可达性）
- HTTP Basic Auth，常量时间比较；`allow_ips` 支持 IP/CIDR（优先 `CF-Connecting-IP`）
- noVNC 1.5.0 全部静态资源 `go:embed` 进主程序

### 2.4 进程与状态

- 网关 / 隧道各自写 `data\gate.pid`、`data\tunnel.pid`
- `data\state.json` 记录模式、域名、链接、PID、启动时间
- `data\url.txt` 记录本次链接与网页账号密码（`0600`）
- `data\gate_pass.txt` 首次自动生成的 12 位网页密码（`0600`）
- `logs\` 三份日志：`cfvnc.log` / `cloudflared.log` / `gate.log`

---

## 3. 验证记录（实测，非推断）

### 3.1 Linux 同源构建（功能逻辑）

| 项 | 结果 |
|---|---|
| `cfvnc version` | `cfvnc a.1.0.1 (linux/amd64)` |
| `cfvnc config` | 正确打印，密钥打码（`Test…s123`） |
| `cfvnc doctor` | 9 项检查，端口/组件/写权限正常 |
| 网关鉴权 | 无凭据 `401`，正确凭据 `200`（各 1 次） |
| noVNC 静态资源 | 内置 120 个文件；`/app/ui.js` → `200 text/javascript`；`/vnc.html` → 15403 B |
| WebSocket | `Sec-WebSocket-Protocol: binary` 协商成功；发送 `hello-vnc` 收到回显 `hello-vnc` |
| 根路径跳转 | `302 → /vnc.html?autoconnect=1&compression=2&path=websockify&quality=6&reconnect=1&resize=remote` |

### 3.2 临时隧道（真实 Quick Tunnel）

2026-11-20 18:12（UTC+8）实测：

```
[4/4] 建立 Cloudflare 隧道
      启动临时隧道（Quick Tunnel）… 等待分配域名
      https://actual-episodes-translation-joint.trycloudflare.com/vnc.html?autoconnect=1&reconnect=1&resize=remote
      网页登录   用户名 vnc    密码 TestPass123
      [cf] INF Registered tunnel connection connIndex=0 ... protocol=quic
```

- 从启动到拿到域名：数秒
- 从拿到域名到 `Registered tunnel connection`：约 7 秒
- Ctrl+C 后 cloudflared 正常退出、PID 文件清理

### 3.3 固定模式 API（真实账号，创建后已删除）

用 `go test -tags live` 对真实 Cloudflare 账号执行（测试资源随即删除）：

```
verify: Global Key gaoxinze000@outlook.com
account: 8a2815bf73766d95b0789dca406c6b1a
zone:    e3e26d79fb3de96768828d0910b13030
tunnel:  dc64c43d-… tokenLen: 240
put config ok
dns: 已创建 cfvnc-selftest-39281.brazzers.eu.org
get token ok len= 240
cleanup dns ok
cleanup tunnel ok
```

事后核查：账号下无 `cfvnc-selftest-*` 隧道残留，DNS 查询 `count=0`。
（真实使用时应换成你自己的 `api_token`，不要用 Global Key。）

### 3.4 Windows 构建

| 项 | 结果 |
|---|---|
| 交叉编译 | `CGO_ENABLED=0 GOOS=windows GOARCH=amd64`，成功 |
| 文件类型 | `PE32+ executable (console) x86-64, for MS Windows` |
| 体积 | 7.8 MB（静态链接，无 DLL 依赖） |
| 哈希 | `5a3a051a5107730937c8f57d9f5149adf050c2ffbb9eff36dd1887c919aa7653` |

**诚实说明**：当前构建环境没有 Windows 实机/ Wine，`cfvnc.exe` 未做 Windows 运行时验证；
其核心逻辑与已实测的 Linux 构建同源，Windows 专属部分（`tasklist`、`taskkill`、
`schtasks`、`CREATE_NEW_PROCESS_GROUP`）按官方命令与 Go 官方 SysProcAttr 实现。
首次在 Windows 上运行建议先执行 `4-诊断.bat`，把输出发回来即可定位。

---

## 4. 安全设计

1. **两层认证**：网页 Basic Auth + VNC 密码，缺一不可。
2. **默认随机密码**：`gate_pass` 留空时首次生成 12 位，存 `0600` 文件。
3. **只监听回环**：网关 `127.0.0.1`，不开放局域网/公网入站；隧道是本机主动外连。
4. **可选 IP 白名单**：按 `CF-Connecting-IP` 过滤，支持 CIDR。
5. **密钥不入日志**：`config` 命令打码；`api_token` / `tunnel_token` 不打印。
6. **常量时间比较**：Basic Auth 用户/密码均用 `subtle.ConstantTimeCompare`。

---

## 5. 已知边界

| 边界 | 说明 |
|---|---|
| 仅网页 VNC | 本包不额外开 TCP hostname；原生 VNC Viewer 需自行加一条 TCP 隧道 |
| Windows Session 0 | 服务模式下「锁屏界面」与「当前桌面」可能不是同一画面，属 Windows 机制 |
| 临时模式 | 域名随机、重启即换，不适合长期入口 |
| 固定模式 | 必须有自己的域名并托管在 Cloudflare；API Token 需 Tunnel/DNS 权限 |
| 免费额度 | Cloudflare Tunnel 免费；流量受 Cloudflare 免费套餐约束 |
| Windows 实机 | 未在真实 Windows 上跑过（见 3.4），首次请先 `doctor` |

---

## 6. 文件校验

```
cfvnc.exe         5a3a051a5107730937c8f57d9f5149adf050c2ffbb9eff36dd1887c919aa7653
cloudflared.exe   341deda3db5ec498a0482254d6c38c0b7cf01a30c37bb5dd95d2216d08955e35
```

---

## 7. 版本

- `a.1.0.1`（2026-11-20）修复: `autoconnect=0` / `reconnect=0` 时 Go 侧仍把字符串 "0" 传给 noVNC，
  被 JS 当作真值; 现在为 0 时不带这两个参数。
- `a.1.0.0`（2026-11-20）首个交付版本。
