服务端在线 · www.tndesk.cn · 全程加密当前版本 tndesk V1.0.0
tndesktndesk天牛远程控制
极光白
登录免费注册
GET STARTED

使用教程与部署指引

从部署服务端到发起第一次远程控制，从账号体系到网页控制台，一份文档讲清楚。

1. 快速开始（Windows）

V1.0.0 分两部分：客户端 tndesk.exe（控制端 + 被控端 + 7 组设置）与 服务端 tndesk-server.exe（信令 / 中继 / 管理 API / 管理软件）。服务端只需在一台有公网 IP 的机器上运行一次，所有客户端共用。

  1. 在 下载中心 获取 tndesk-V1.0.0-20261110.zip，解压得到客户端与服务端两组文件。
  2. 把 tndesk-server.exe、server.ini、start-server.bat 放到服务器目录，双击 start-server.bat（或 tndesk-server.exe --gui 打开管理软件）。
  3. 服务器安全组 / 防火墙放行 TCP 21130；管理 API 21121 只允许本机访问，不要对外开放。
  4. 客户端登录官网账号后，被控端自动连接 www.tndesk.cn:21130 上线，首页显示本机远程 ID。
  5. 在另一台电脑输入该 ID 与访问密码，即可发起「远程控制」或「仅查看」。
⚠️ 云服务器还要放行安全组：Windows 防火墙放行只是第一层，腾讯云 / 阿里云的安全组里也必须加入方向 TCP:21130，否则外网客户端会一直停在「正在连接服务器」。在另一台机器上用 telnet www.tndesk.cn 21130 能连上才算放行（本机连自己的公网 IP 可能因 NAT 回环而不准）。
💡 客户端主界面：左侧为「发起远程连接」（远程 ID、访问密码、最近连接），右侧为「本机远程 ID」与在线状态；下方是账号区。设置页内嵌在主界面，不再弹独立窗口。快捷键：F5 刷新、Ctrl+F 搜索设备、Ctrl+1 回首页。

2. 账号与设备

官网与客户端共用同一套 users / devices / sessions 数据表：

  • 网站注册、客户端登录、后台添加，三种方式写入同一个账号库；密码使用 password_hash 存储。
  • 客户端登录后拿到令牌（库中只存 SHA-256 哈希），并每 5 分钟把设备 ID、主机名、系统、CPU、内存、MAC、分辨率、内外网 IP、客户端版本登记到 devices 表。
  • 服务端在客户端连接时回调官网 api/v1/native.php?action=verify_token 校验令牌，令牌无效直接拒绝。
  • 设备按账号隔离：服务端会拒绝跨账号连接（管理员与桥接密钥除外）。
  • 在 用户中心 可查看 / 停用设备、修改密码；管理员可在后台禁用账号，禁用后该账号所有令牌立即失效。

3. 服务端部署

服务端是单文件 .NET Framework 4.0 程序，无需安装运行库之外的环境，也不依赖任何数据库（数据落 server-data\ 目录）。

组件端口协议用途
BNP/1 信令 + 会话中继21130TCP设备注册、握手、会话中继（对外）
管理 API21121HTTP仅监听 127.0.0.1，供官网 PHP 反向代理
官网80 / 443TCP账号、设备、版本分发、网页控制台

server.ini 关键字段：

public_addr=www.tndesk.cn      # 客户端要填的地址
listen_port=21130        # 信令/中继端口
admin_addr=127.0.0.1        # 管理 API 只监听本机
admin_port=21121
bridge_key=beetle-bridge-2026   # 生产必须更换，并与官网 NATIVE_BRIDGE_KEY 一致
site_api=http://www.tndesk.cn/api/v1/native.php
auth_mode=bridge            # bridge = 官网令牌校验；local = 离线放行
offline_allow=0             # 生产环境必须为 0

启动方式：直接运行 tndesk-server.exe 进入控制台模式（可输入 devices / status / quit）；tndesk-server.exe --gui 打开服务端管理软件；--selftest 跑 19 项内核自测，不开放端口。

⚠️ 上线前必须完成三项：更换 bridge_key（服务端 + 官网 config.php 同步）、offline_allow=0、官网启用 HTTPS。

4. 服务端管理软件

tndesk-server.exe --gui 打开，与客户端同一套视觉（无边框窗体、渐变顶栏、深色侧栏、圆角卡片、缓动动效），共 6 页：

页面能力
概览在线设备 / 活动会话 / 累计会话 / 运行时长；对外信令地址、监听地址、管理 API、官网鉴权、认证方式、数据目录、启动时间；最近事件流；快捷操作
设备管理按远程 ID / 设备名 / 账号 / IP 搜索；双击直接控制；控制、查看、文件管理、截图、录屏开始 / 停止、锁定、设备信息、复制 ID、强制下线
会话监控会话号、目标设备、模式、发起账号、开始时间、已持续；一键强制断开（两端都收到 SESSION_CLOSE）
日志审计实时日志、关键字过滤、暂停滚动、导出 .log、打开日志目录
服务配置直接编辑 server.ini（对外地址 / 端口 / 密钥 / 官网 API / 认证方式 / 离线放行 / 超时），保留未识别键，改端口与密钥提示重启
关于内核BNP/1 协议、加密、抓屏、文件、录屏、端口与上线检查清单

管理软件的远程操作全部经本机 127.0.0.1:21121 管理 API 与 127.0.0.1:21130 信令端口完成，不额外开放端口。关闭窗口即停止服务，因此有二次确认。

5. 客户端设置

客户端「设置」页内嵌在主界面，共 7 组，保存后写入 native-settings.ini：

  • 基本设置：开机自启、托盘、设备别名、无人值守。
  • 连接设置：连接超时、自动重连、并发会话、默认模式（控制 / 查看）。
  • 显示设置：画质、帧率、分块大小、关键帧间隔、缩放方式、显示器选择。
  • 键鼠设置：允许键盘 / 鼠标、滚轮、双击判定。
  • 快捷键设置：全屏、截图、录屏、文件、锁定、断开、切换显示器。
  • 安全设置：传输加密、访问密码、文件沙箱根目录、剪贴板与录屏授权。
  • 网络设置：服务端地址（默认 www.tndesk.cn）、端口 21130、管理端口、心跳、桥接密钥、官网是否走 HTTPS。

ℹ️ 「连接诊断」页会逐项检查：内核版本、服务端可达性、登录状态、被控端在线、屏幕抓取、在线设备数，并把结果写进日志，排障时先看这一页。

6. 网页控制台

登录官网后打开 远程控制台，即可在浏览器里管理自己账号下的设备：设备列表、实时画面、截图、录屏、文件管理（列表 / 上传 / 下载 / 删除）、远程锁定、设备信息与操作日志。管理员在后台 原生内核 页可跨账号查看与操作。

  • 实时画面按 action=frame 轮询，首帧最多等待 2.5 秒；鼠标坐标按 object-fit: contain 反算到远端分辨率。
  • 截图与录屏产物统一落在服务端 server-data\artifacts\，通过 action=artifact 下载。
  • 产物下载做归属校验：文件名前缀里的设备 ID 必须属于当前账号，否则返回 403。
  • 所有网页端管理操作写入 native_audit 表（账号、动作、设备、IP、时间）。

7. 文件与录屏

文件传输：客户端「文件管理」窗口与服务端管理软件「文件管理」、网页控制台共用同一套指令：list / stat / mkdir / delete / rename / get / put。被控端用 Path.GetFullPath + 根目录前缀校验做沙箱，.. 越界会被拒绝。单文件上传上限 200 MB。

截图与录屏：截图输出 JPG；录屏由自写 MjpegAviWriter 生成 MJPEG AVI，可直接用播放器打开。录屏开始 / 停止既可在远程桌面工具条操作，也可由服务端管理软件或网页控制台发起。

8. 在线升级

  1. 管理员在「后台 → 版本与升级」选择安装包，填写版本号（v1.0 ~ v9.9）、发布日期与更新内容后发布；文件大小与 SHA-256 由服务器自动计算。
  2. 客户端启动时请求 GET /api/v1/update.html?platform=windows-x64&v=V1.0.0（兼容 .php 后缀）。
  3. 服务端返回 has_update / version / release_date / lines / url / sha256 / size / force；完整履历见 更新履历。
  4. 客户端下载到临时目录 → 校验 SHA-256 → 备份旧版 → 原子替换 → 重启；失败自动回滚。

9. 移动端规划

Android / iOS 客户端按计划本轮暂不发布，但协议层已为移动端预留：控制面全部是平台无关 JSON，画面与文件走二进制数据面；HELLO.v 协商版本、DEVICE_INFO.capabilities 声明能力。移动端接入时只需实现 BNP/1 客户端与解码渲染，不需要改服务端。

ℹ️ 需要移动端时，优先复用服务端的信令与会话中继；docs/15-网页端与移动端对接.md 列出了接口与模块清单。

10. 故障排查

客户端一直显示「正在连接服务器」

先确认服务端在跑：服务器上执行 tndesk-server.exe --gui，概览页应显示信令地址 www.tndesk.cn:21130。其次确认安全组 / 防火墙放行 TCP 21130，客户端「网络设置」里的服务端地址与端口要和服务端一致，且不要带 http:// 前缀。

登录提示「令牌无效 / 未登录」

令牌有效期 30 天，或管理员禁用了该账号，重新登录即可。若服务端日志出现 verify_token 失败，检查 server.ini 的 site_api 是否指向官网 api/v1/native.php，以及官网是否可访问。

网页控制台提示「管理密钥无效」(401)

官网 config.php 的 NATIVE_BRIDGE_KEY 与服务端 server.ini 的 bridge_key 不一致，或管理 API 未启动。两处改成同一个值后重启服务端。

网页端下载截图 / 录屏返回 403

产物下载按设备归属校验：文件名里的设备 ID 必须属于当前账号。跨账号下载会被拒绝；首次上线的设备若尚未登记到 devices 表，服务端会按实时设备列表补齐账号归属，稍等几秒重试即可。

设备列表里看不到本机

被控端没有常驻运行。确认客户端首页「被控端服务」为已启动、状态灯为绿色；登录后设备会在 1 分钟内登记到官网 devices 表。被控端重启后需重新启动客户端（或勾选「开机自启」）。

连接失败：目标设备不在线

服务端按账号隔离设备，只有同一账号下的在线设备才能互连（管理员 / 桥接密钥除外）。确认两端登录的是同一个账号，且对方被控端在线。

画面卡顿 / 帧率低

BNP/1 目前一律经服务端中继转发（P2P 直连为后续版本能力）。可在「显示设置」降低画质与帧率、增大关键帧间隔；网络抖动时优先保证带宽，避免同时开多个会话。

远程文件为空 / 看不到目录

被控端「安全设置 → 文件沙箱根目录」限制了可访问范围，留空表示当前用户目录。目录不存在或越界会返回空列表。

上传大文件失败

单文件上限 200 MB；上传走 base64 分片，网络中断需重新上传。超大文件建议改用文件管理窗口，或先压缩再传。

Win7 启动提示缺少运行库

客户端与服务端均用 .NET Framework 4.0 编译，Win7 需安装 .NET Framework 4.x 与 VC++ 2015-2022 运行库（KB4474419 补丁）。

管理软件在服务器上看不到界面 / 无法截图

服务态或无 RDP 会话时桌面不可见属正常现象；可用 tndesk-server.exe --uicheck 做布局自检，结果写入同目录 uicheck.txt。日常运维建议用远程桌面登录后打开 --gui。