# CF-VNC 隧道 · Windows 一键部署包

> 版本 **a.1.0.1** ｜ 更新 2026-11-20 ｜ 适用 Windows 10 / 11（x64）

把本机 VNC 桌面通过 Cloudflare 隧道变成一条 **HTTPS 网页链接**：
不用公网 IP、不用路由器端口映射、控制端不用装任何软件，浏览器打开就能操作。

```
控制端浏览器
   │  HTTPS（Cloudflare 边缘，自动证书）
   ▼
Cloudflare 隧道（cloudflared）
   │  加密长连接，本机主动外连，不开放入站端口
   ▼
127.0.0.1:6080  cfvnc 网关（网页密码 / IP 白名单）
   ├─ /vnc.html     noVNC 网页客户端
   └─ /websockify   WebSocket ↔ TCP
        ▼
127.0.0.1:5900   TightVNC / UltraVNC / RealVNC
```

所有选项都写在 **`cfg.txt`** 里，程序不做交互提问；命令行一条命令启停。

---

## 1. 30 秒跑起来（临时模式，免账号）

1. 在 Windows 上装好 VNC 服务端（推荐 TightVNC），确认监听 `5900`，设好 VNC 密码。
2. 双击 **`1-一键启动.bat`**（等价于 `cfvnc.exe up`）。
3. 窗口里会打印一条 `https://xxxx.trycloudflare.com/vnc.html?...` 链接，以及网页登录的用户名/密码。
4. 把链接发给对方，浏览器打开即可。

> 临时模式的地址是随机分配，**关掉窗口就失效，下次启动会换新地址**。
> 需要长期固定地址，用下面的固定模式。

---

## 2. 固定域名（重启不换地址）

前提：域名已托管在 Cloudflare（本包已按 `brazzers.eu.org` 预填账号与区域）。

### 方式 A：API Token（推荐，全自动）

1. Cloudflare 后台 → 右上头像 → **My Profile → API Tokens → Create Token → Custom token**：
   - `Account` → `Cloudflare Tunnel` → **Edit**
   - `Zone` → `DNS` → **Edit**
   - `Zone` → `Zone` → **Read**
   - Zone Resources 选你的域名
2. 把令牌填进 `cfg.txt`：

```ini
mode=fixed
fixed_auth=api
hostname=vnc-win.brazzers.eu.org
api_token=你的令牌
```

3. 运行 `cfvnc.exe up`。首次会自动：
   - 创建（或复用）名为 `cfvnc-win` 的隧道
   - 写入 ingress：`vnc-win.brazzers.eu.org → http://127.0.0.1:6080`
   - 创建 DNS：`CNAME → <隧道ID>.cfargotunnel.com`（已开代理）
   - 启动 cloudflared 并打印 `https://vnc-win.brazzers.eu.org/vnc.html?...`

DNS 首次生效一般 1–3 分钟。以后再启动只做复用，不会重复建。

### 方式 B：Tunnel Token（前端在后台配）

Zero Trust → Networks → Tunnels 里创建隧道，复制 token 填 `tunnel_token=`，并把 Public Hostname 指到 `http://127.0.0.1:6080`；然后：

```ini
mode=fixed
fixed_auth=token
hostname=vnc-win.brazzers.eu.org
tunnel_token=eyJ...
```

### 方式 C：本地证书（半自动）

先运行一次 `cfvnc.exe login`（会打开浏览器授权），然后：

```ini
mode=fixed
fixed_auth=local
hostname=vnc-win.brazzers.eu.org
```

程序会调用 `cloudflared tunnel create / route dns` 并生成本地 `config-local.yml`。

---

## 3. cfg.txt 全部选项

只改等号右边，`#` 开头的整行是注释。改完直接运行，不用重启任何服务。

### 运行方式

| 键 | 默认 | 说明 |
|---|---|---|
| `action` | `up` | 无参数运行 `cfvnc.exe` 时执行的动作：`up` / `status` / `doctor` |
| `mode` | `temp` | `temp` 临时链接；`fixed` 固定域名 |

### 固定域名

| 键 | 默认 | 说明 |
|---|---|---|
| `hostname` | `vnc-win.brazzers.eu.org` | 对外域名，必须在 `domain` 下 |
| `fixed_auth` | `api` | `api` / `token` / `local` |
| `account_id` | 已预填 | Cloudflare 账户 ID，留空自动取第一个 |
| `zone_id` | 已预填 | 域名 Zone ID，留空按 `domain` 查 |
| `domain` | `brazzers.eu.org` | 根域名 |
| `api_token` | 空 | 推荐的最小权限令牌 |
| `api_email` / `api_key` | 空 | Global API Key 方式（权限过大，不建议） |
| `tunnel_name` | `cfvnc-win` | 隧道名，账号内唯一 |
| `tunnel_id` | 空 | 已知隧道 UUID 可直接填 |
| `tunnel_token` | 空 | `fixed_auth=token` 时必填 |
| `cloudflared_protocol` | `auto` | `auto` / `http2` / `quic`；UDP 7844 被封时用 `http2` |
| `edge_ip_version` | `4` | 出口 IP 版本：`4` / `6` / `0` |

### 本地 VNC 与网关

| 键 | 默认 | 说明 |
|---|---|---|
| `vnc_host` | `127.0.0.1` | VNC 服务端地址 |
| `vnc_port` | `5900` | VNC 端口（TightVNC 默认 5900） |
| `web_bind` | `127.0.0.1` | 网关监听地址，**不要改 0.0.0.0** |
| `web_port` | `6080` | 网关端口，被占用时改这里 |

### 网页鉴权

| 键 | 默认 | 说明 |
|---|---|---|
| `gate_user` | `vnc` | HTTP Basic 用户名 |
| `gate_pass` | 空 | 网页密码；留空且 `auto_password=1` 时首次随机生成，存 `data\gate_pass.txt` |
| `auto_password` | `1` | 自动生成/复用密码 |
| `allow_ips` | 空 | 白名单，逗号分隔 IP 或 CIDR；经隧道时取 `CF-Connecting-IP` |
| `novnc_page` | `vnc.html` | 根路径跳转页面（也可 `vnc_lite.html`） |

### noVNC 显示

| 键 | 默认 | 说明 |
|---|---|---|
| `view_only` | `0` | `1`=只读（只能看不能点） |
| `resize` | `remote` | `remote` 自适应 / `scale` / `local` |
| `quality` | `6` | 画质 0–9 |
| `compression` | `2` | 压缩 0–9，公网 2–4 较均衡 |
| `autoconnect` | `1` | 打开链接自动连接 |
| `reconnect` | `1` | 断线自动重连 |
| `vnc_password` | 空 | VNC 服务端密码；填了会写进链接自动登录 |

### 组件与自启

| 键 | 默认 | 说明 |
|---|---|---|
| `cloudflared_path` | `bin\cloudflared.exe` | 随包附带，缺失时才下载 |
| `cloudflared_url` | GitHub 官方 | 主下载源 |
| `cloudflared_mirror` | ghfast / ghproxy | 国内加速镜像，逗号分隔 |
| `start_vnc_server` | `0` | `1`=顺手拉起 `vnc_server_exe` |
| `vnc_server_exe` | 空 | 如 `C:\Program Files\TightVNC\tvnserver.exe` |
| `vnc_server_args` | 空 | 传给 VNC 服务端的参数 |
| `vnc_start_timeout` | `10` | 等 VNC 端口就绪的秒数 |
| `autostart_task` | `cfvnc-vnc-tunnel` | 计划任务名 |

---

## 4. 命令行

```bat
cfvnc.exe                 按 cfg.txt 的 action 执行（默认 up）
cfvnc.exe up              启动网关 + 隧道（前台，关窗即断开）
cfvnc.exe down            停止网关和隧道
cfvnc.exe restart         重启
cfvnc.exe status          查看端口、进程、访问地址
cfvnc.exe url             只打印链接和登录信息
cfvnc.exe doctor          环境诊断（组件/端口/API/DNS/权限）
cfvnc.exe config          打印生效配置（密钥打码）
cfvnc.exe install         安装开机自启（计划任务，隐藏窗口）
cfvnc.exe uninstall       卸载开机自启
cfvnc.exe logs            最近日志
cfvnc.exe login           fixed_auth=local 时登录 Cloudflare
cfvnc.exe gate            只启动本地网页网关（调试）
cfvnc.exe version         版本

cfvnc.exe -c D:\path\cfg.txt up    指定另一份配置
```

退出码：`0` 成功，`1` 失败，`2` 未知命令。

---

## 5. 控制端怎么连

1. 浏览器打开链接（Chrome / Edge / Firefox 均可）。
2. 先弹 **网页登录**：用户名 `gate_user`，密码 `gate_pass`（或 `data\gate_pass.txt` 里的随机密码）。
3. noVNC 再连 VNC：若 `vnc_password` 为空，会弹 VNC 密码框；填 VNC 服务端设的密码。
4. 想开只读演示，把 `view_only=1`。

> 本包暴露的是「网页 VNC」。不提供原生 VNC 客户端直连；如果一定要用 VNC Viewer，
> 需要在 Cloudflare 侧再加一条 TCP 类型的 hostname（不在本包默认范围内）。

---

## 6. VNC 服务端准备（Windows）

推荐 **TightVNC**（免费、体积小）：

1. 安装时勾选 **Service Mode**，设置 VNC 密码。
2. 确认监听 `5900`：`netstat -ano | findstr 5900`。
3. 防火墙不需要放行 `5900`：网关只连 `127.0.0.1`，隧道是本机主动外连。

注意：Windows 服务的 Session 0 隔离会导致「锁屏/登录界面」和「当前桌面」不是同一个画面。
TightVNC 服务模式通常能捕获登录桌面；如果要看当前用户桌面，可用 TightVNC 的
「Application Mode」或 UltraVNC 的 service 模式。远程协助场景建议直接让对方保持已登录。

---

## 7. 安全建议

- **两层密码**：网页 Basic Auth（`gate_pass`）+ VNC 密码，缺一不可。
- 不要把链接发到公开群；链接里若带 `vnc_password` 参数，等于把 VNC 密码一起给了对方。
- 需要更严的入口控制：
  - `allow_ips` 限定来源公网 IP；或
  - 在 Cloudflare Zero Trust → Access → Applications 给该域名加邮箱 OTP / 企业 SSO 策略。
- `api_token` 用最小权限，不要用 Global API Key；本包不会把密钥写到日志。
- 临时模式用完就关窗口；固定模式不用时 `cfvnc.exe down`。
- `data\gate_pass.txt`、`data\tunnel.json`、`cfg.txt` 都含敏感信息，别打包外发。
- 日志会记录访客 IP（`logs\gate.log`），按需清理。

---

## 8. 目录结构

```
CF-VNC隧道_a.1.0.1\
├─ cfg.txt                所有选项（本文件第 3 节）
├─ cfvnc.exe             主程序（网关 + 隧道管理 + CLI）
├─ bin\cloudflared.exe   随包隧道客户端
├─ 1-一键启动.bat         = cfvnc.exe up
├─ 2-停止.bat             = cfvnc.exe down
├─ 3-状态.bat             = cfvnc.exe status
├─ 4-诊断.bat             = cfvnc.exe doctor
├─ 5-访问链接.bat         = cfvnc.exe url
├─ 6-安装开机自启.bat     = cfvnc.exe install
├─ 7-卸载开机自启.bat     = cfvnc.exe uninstall
├─ 8-编辑配置.bat         用记事本打开 cfg.txt
├─ 命令行.bat             打开命令行并显示帮助
├─ README.md
├─ 交付报告_a.1.0.1.md
├─ data\                  运行时生成：state.json / pid / gate_pass.txt / url.txt
└─ logs\                  cfvnc.log / cloudflared.log / gate.log
```

---

## 9. 常见问题

**Q：浏览器一直弹登录框 / 401？**
`gate_pass` 与输入不一致。看 `data\gate_pass.txt`；或把 `auto_password=0` 并显式填 `gate_pass`。

**Q：网页能打开，但 noVNC 提示连接失败/黑屏？**
VNC 服务端没启动或端口不对。先 `cfvnc.exe doctor`，确认 `VNC 端口 127.0.0.1:5900 可连接`。

**Q：固定域名 520 / 1033 / 打不开？**
DNS 还没生效，或隧道正在重连。等 1–3 分钟；`cfvnc.exe status` 看隧道进程；
`logs\cloudflared.log` 看 `Registered tunnel connection`。

**Q：固定模式启动报 tunnel not found / token 无效？**
`data\tunnel.json` 缓存了旧隧道 ID 与 token（比如换过账号或删过隧道）。删除该文件后重试，
程序会重新创建或按名字接管。

**Q：公司网络/校园网连不上，日志里 QUIC 失败？**
把 `cloudflared_protocol=http2`。Cloudflare 的 UDP 7844 经常被封，HTTP/2 走 443。

**Q：临时地址每次都不一样？**
临时模式（Quick Tunnel）本身就是随机域名。要固定用 `mode=fixed`。

**Q：`web_port` 被占用？**
改 `web_port=6081`（`vnc_port` 与 `web_port` 不能相同）。

**Q：cloudflared 被杀软删了？**
`bin\cloudflared.exe` 是 Cloudflare 官方二进制。恢复信任，或从
`https://github.com/cloudflare/cloudflared/releases/latest` 重新下载，程序也会按
`cloudflared_mirror` 自动补。

**Q：怎么开机自启？**
右键 `6-安装开机自启.bat` → 以管理员身份运行。它会创建登录触发的计划任务，
用 VBS 隐藏窗口启动 `cfvnc.exe up`。卸载用 `7-卸载开机自启.bat`。

**Q：Ctrl+C 之后链接立刻失效？**
正常。`up` 是前台进程，网关和隧道都是它的子进程；要长期运行请用开机自启或
`start /min` 单独开一个窗口。

---

## 10. 技术细节

| 项 | 值 |
|---|---|
| 主程序 | Go 1.23 静态编译，单文件 `cfvnc.exe`（约 7.8 MB） |
| noVNC | 1.5.0，已用 `go:embed` 打进主程序，无需额外 Web 目录 |
| cloudflared | 2026.11.1（随包 `bin\cloudflared.exe`） |
| 网关 | `net/http` + `gorilla/websocket`，Basic Auth，常量时间比较 |
| WebSocket | `/websockify`，二进制子协议 `binary`，双向字节透传 |
| 健康检查 | `GET /healthz` 返回 JSON，含 VNC 可达性 |
| 状态 | `data\state.json`、`data\gate.pid`、`data\tunnel.pid`、`data\url.txt` |
| 固定模式 | Cloudflare API v4：`cfd_tunnel` 创建 / `configurations` 写 ingress / `dns_records` 建 CNAME |

---

## 11. 版本记录

- **a.1.0.1**（2026-11-20）修复：`autoconnect=0` / `reconnect=0` 不再向 noVNC 传 "0"
  （字符串 "0" 在 JS 里是真值，会强制自动连接/重连）。
- **a.1.0.0**（2026-11-20）首个版本：
  临时/固定双模式；API / Token / 本地证书三种固定认证；全 cfg 预设；
  noVNC 网页接入；Basic Auth + IP 白名单；VNC 端口探测；开机自启；
  `up/down/status/url/doctor/config/logs/install/uninstall` 命令族。
