aiops/docs/rdp.md

AIOps Web RDP 远程桌面

作者：Logan.Li
更新：2026-07-03
归档副本：/opt/rdp/docs/rdp.md · 变更记录：/opt/rdp/CHANGELOG.md

---

概述

AIOps 提供浏览器内 Windows 远程桌面（Canvas 渲染 + WebSocket）。当前已移除第三方 grdp 兜底实现，后端固定使用 AIOps 自研 RDP 协议栈。// Logan.Li

环境变量	行为
RDP_ENGINE	已不再参与引擎选择，保留环境变量不会改变行为
RDP_DEBUG=1	打开 [RDP:TRACE] 协议级日志

层级	状态	路径
X.224 / TPKT / TLS	✅ 自研灰度	backend/pkg/rdp/transport/
CredSSP / NTLMv2 (NLA)	✅ 自研灰度	backend/pkg/rdp/credssp/
MCS / GCC / 许可证 / 激活	✅ 自研灰度	backend/pkg/rdp/mcs_probe.go、session_connect.go
FastPath 位图 / MPPC / RLE	✅ 自研灰度	bitmap_decode.go、fastpath_recv.go、mppc.go、rle/
键鼠 / 剪贴板 / auto_exec	✅ 自研灰度	input_fastpath.go
文件传输 (SMB + 暂存回退)	✅ 自研	pkg/winsmb/、pkg/rdpfilestage/
前端 Canvas + 工具面板	✅ 自研	RdpDialog.tsx、RdpToolsPanel.tsx

自研协议栈不依赖第三方 RDP 实现，也不直接依赖控制器、数据库或 WebSocket。已删除的第三方目录备份在 /opt/rdp/third-party/grdp-aiops-backup-20260703。// Logan.Li

---

2026-07-03 变更记录

自研 RDP 引擎

变更项	说明
引擎入口	NewEngine() 固定返回 SessionEngine
兜底依赖	已移除 github.com/nakagami/grdp 和 backend/third_party
Dockerfile	不再复制 third_party 模块
新增模块	session_engine.go、session_connect.go、packet_io.go、fastpath_recv.go、bitmap_decode.go、input_fastpath.go、mppc.go、rle/
自研会话激活	ConfirmActive 后可选读 FontMap，发送 SuppressOutput(ALLOW_DISPLAY_UPDATES) 触发服务端推帧
自研位图输出	FastPath / SlowPath Bitmap + SurfaceCmd → PNG base64 → WebSocket type:bitmap
自研输入通道	Fast-Path Input：扫描码键鼠、Unicode 剪贴板、auto_exec（Win+R 粘贴命令）
协议日志	RDP_DEBUG=1 输出 [RDP:TRACE]，定位连接、bitmap、input 阶段

仍保留的探测 API（诊断用）

函数	用途
ProbeHandshake	X.224 安全协议协商
ProbeCredSSP	NLA 凭据验证
ProbeMCSConnect	MCS/GCC 握手探测（读完即关连接）
ProbeSessionFrames	建立会话后统计位图矩形数量

已知限制 / 待完善

• mcs_probe.go 超 700 行红线，后续需按 MCS/GCC/PDU 拆文件
• 未实现 cliprdr 虚拟通道双向同步、RDPGFX/H.264、动态虚拟通道
• 部分 Windows 主机在频繁探测后可能 connection reset（目标机策略/限流，非 NLA 失败）

---

架构与调用链

RdpDialog.tsx
  │ WebSocket /ws/rdp?id=&width=&height=&token=
  ▼
controller/rdp.go
  │ loadRDPCredential() → engine.Run()
  ▼
pkg/rdp/engine.go → SessionEngine
  ├── session_engine.go    readLoop + handleEvent
  ├── session_connect.go   OpenSession (CredSSP + MCS + SuppressOutput)
  ├── packet_io.go         TPKT / FastPath 读写
  ├── fastpath_recv.go     服务端更新解析
  ├── bitmap_decode.go     RLE/翻转 → PNG
  ├── input_fastpath.go    键鼠 / 剪贴板 / auto_exec
  ├── mppc.go              MPPC 解压
  └── rle/                 位图 RLE 解压算法

---

后端文件清单

协议栈 backend/pkg/rdp/

文件	说明
engine.go	Engine 接口、RDP_ENGINE 引擎选择
client.go	ProbeHandshake / ProbeTLSHandshake / ProbeCredSSP
session_engine.go	图形会话主循环、帧推送、输入分发
session_connect.go	OpenSession、SuppressOutput 激活
mcs_probe.go	MCS Connect、GCC、ClientInfo、ConfirmActive 构建与探测
packet_io.go	ReadWirePacket、WriteFastPathInput
fastpath_recv.go	FastPath 更新、MPPC、SurfaceCmd 解析
bitmap_decode.go	位图解码与 PNG 编码
input_fastpath.go	Fast-Path Input 事件编码
mppc.go	MPPC-64K 解压器
keymap.go	浏览器 KeyboardEvent.code → RDP 扫描码
transport/	TPKT、X.224、TLS
credssp/	CredSSP + NTLMv2 + ASN.1
rle/	RLE 位图解压（DecompressInto）

控制器 / 模型

文件	说明
controller/rdp.go	WebSocket 会话、审计录制
controller/rdp_session.go	会话列表 / 回放 / 终止 API
controller/rdp_file.go	文件 list/upload/download/stage
controller/rdp_cred.go	凭据加载辅助
model/rdp_session.go	RDPSession 表

文件传输

文件	说明
pkg/winsmb/	SMB 管理共享直传 C:\Users\Public\AIOpsShare\Download
pkg/rdpfilestage/	服务端暂存 + 一次性 token
frontend/.../RdpToolsPanel.tsx	工具面板（通用命令 / 文件 Tab）
frontend/.../rdpConstants.ts	虚拟 Download 盘路径常量

---

前端

文件	说明
RdpDialog.tsx	Canvas 渲染、WebSocket、键鼠捕获、工具栏
RdpToolsPanel.tsx	剪贴板同步、文件上传下载、auto_exec 回退
api/server/rdp-files.ts	文件传输 REST
api/audit/rdp.ts	会话审计 API

---

WebSocket 帧协议

服务端 → 浏览器

{ "type": "session",  "message": "123", "width": 1280, "height": 800 }
{ "type": "status",   "message": "正在连接 RDP ..." }
{ "type": "error",    "message": "..." }
{ "type": "bitmap",   "x": 0, "y": 0, "width": 64, "height": 64, "image": "data:image/png;base64,..." }
{ "type": "clipboard","text": "远端剪贴板内容" }

浏览器 → 服务端

{ "type": "mouse_move", "x": 100, "y": 200 }
{ "type": "mouse_down", "x": 100, "y": 200, "button": 0 }
{ "type": "mouse_up",   "x": 100, "y": 200, "button": 0 }
{ "type": "wheel",      "x": 100, "y": 200, "delta_y": -120 }
{ "type": "key",        "code": "KeyA", "key": "a", "down": true }
{ "type": "clipboard",  "text": "本地剪贴板" }
{ "type": "auto_exec",  "text": "C:\\Users\\Public\\AIOpsShare\\Download\\setup.exe" }

---

CredSSP 多策略重试

每条策略使用新建 TCP 连接（client.go）：

1. v6 + binding（默认）
2. v6 + binding + UseCBT
3. v6 + binding + ForceMIC
4. v2 + raw（兼容旧服务端）

关键修复：credssp.subjectPublicKey() 使用证书 SubjectPublicKey 原始 ASN.1，而非 PKIX SPKI。

---

外部项目借鉴边界

项目	可借鉴点	不直接采用原因
FreeRDP	协议完整性、通道、编解码、客户端能力矩阵	C 生态和体量过大，不适合直接嵌入
Apache Guacamole	Web 网关、协议代理、录制与前端桥接分层	依赖 guacd/C，不符合单 Go 后端目标
IronRDP	现代模块化、状态机测试、安全边界	Rust 生态，适合作为测试和分层参考
Teleport	身份、RBAC、审计、Desktop Gateway 架构	产品目标偏堡垒机，不是轻量 RDP client
tomatome/grdp / nakagami/grdp	Go 协议状态机、能力集、bitmap/input 参考	第三方实现已移除，仅保留 /opt 备份用于协议对照

第三方代码归档与文档

归档与变更记录目录：

/opt/rdp/
├── CHANGELOG.md            # 变更记录
├── README.md               # 索引
├── docs/rdp.md             # 完整说明（与本文档同步）
└── third-party/
    ├── nakagami-grdp-v0.8.7/
    ├── rdp-web-refs/
    └── grdpprobe/

第三方源码只能作为协议行为和工程分层参考；涉及 GPL 的项目不得直接搬运实现。// Logan.Li

---

验证命令

# 编译
cd backend && CGO_ENABLED=1 go build -o aiops .

# NLA 探测
go run /tmp/rdp_cred_probe.go   # ProbeCredSSP

# 会话位图统计（需可达的 Windows:3389）
go run /tmp/rdp_session_probe_main.go

# Docker 端到端
./run.sh docker up
# 浏览器：服务器管理 → Windows 主机 → RDP 连接

---

相关路由

路径	说明
GET /ws/rdp	WebSocket 图形会话
GET /api/v1/rdp-sessions	会话审计列表
GET /api/v1/servers/:id/rdp-files	远端文件列表
POST /api/v1/servers/:id/rdp-files/upload	上传
GET /api/v1/servers/:id/rdp-files/download	下载