现场部署

这是在一个现场搭建 TreeT 的整体顺序。（安装文件和详细步骤会随导入时提供的部署安装包一同 说明。）

准备事项（按角色）

安装前请准备以下内容。原则上每个角色使用不同的设备，也可根据规模合并。

角色	数量	需要准备
CMS 服务器	每个站点 1 台 （一台 CMS 可管理多个站点）	Ubuntu 26.04 LTS。Docker 由安装文件自动安装 → CMS 服务器安装
终端	每个站点 N 台 （通常 10~30 台）	Windows · Linux · Android 任选其一。显示器和有线网络。 最低配置：Windows 10 及以上（64 位）· 64 位 Linux（x86-64 · 树莓派已在 Pi 5 + 64 位系统 上确认）· Android 7.0 及以上
同步服务器	使用多屏时 1 台	Windows 10 及以上（64 位）或 64 位 Linux（x86-64 · arm64）。无需另装运行环境（单个可执行文件）
边缘中继器	仅内网隔离现场 1 台	Windows 11 22H2 及以上，同时连接内网和外网的设备

内网隔离现场

在终端无法直接访问外网（CMS）的现场，需要配置一台边缘中继器。只有这台同时连接内网和 外网的设备与外部通信，终端只连接这台设备。边缘中继器只使用向外发起的连接， 因此无需在防火墙上开放从外部进入的端口。

普通现场（终端能直接访问 CMS 的情况）不需要这台设备。

CMS 服务器的安装位置

请不要把 CMS 安装在 OneDrive、Dropbox、Google Drive 等云同步文件夹中。设置文件和 数据库会成为同步对象，可能引发冲突或文件锁定。请使用固定的本地路径 — 收到的安装包统一放在 C:\treet，CMS 本身则是把其中的安装包移到 Hyper-V 虚拟机（Ubuntu）中安装（参阅 CMS 服务器安装）。

需要开放的端口

这是设置防火墙、路由器时使用的表格。请先注意方向有两种 — 大多数是终端 向服务器发出连接，只有远程控制这一项方向相反，是进入连接。

终端 → 服务器（外发方向）

端口	用途	连接对象	被阻断时
8443	CMS 安全连接 — 注册·设置·排播·内容下载	CMS（或 MqttEdge）	画面不会切换到新排播
8080	CMS 明文连接 — 不使用 https 的现场	CMS	同上（〃）
8883	MQTT(TLS) — 远程指令·状态上报	CMS 消息代理（或 MqttEdge）	远程控制、即时生效不可用。播放本身会继续
53000 起	同步播放 — 每个同步池一个端口	SyncServer	多块屏幕的播放会错位

⚠️ 以 https（8443）运营的现场不对外开放 8080 — 因为它是明文入口。因此位于现场之外（不同网络）的 终端，请将CMS 地址和内容地址都设为 https://…:8443。在设备设置中只修改 CMS 地址时， 内容地址会由 CMS 一并跟随修改 — 如果两者原本是同一入口，则会连端口一起改为 https://…:8443/data。

⚠️ Android 7.0 及以下的设备需要 TreeTview Android 2026.9.135 及以上版本 — 这仅在 CMS 使用 Let’s Encrypt 证书的现场（https 8443）中出现。这些设备不认识 Let’s Encrypt 的根证书 （ISRG Root X1），因此无法信任 CMS，连接不上（实测：三星 Galaxy Note4 · Android 6，2026-09-22）。 自 2026.9.135 起，应用内置了该根证书，因此可以连接。安装了更低版本的设备无法连上 CMS， 所以无法通过 CMS 更新，必须直接安装新版本。

⚠️ 53000 号段只在现场内部通信 — 不会向互联网发出，因此无需在路由器上开放端口。 每增加一个池，端口会依次增加为 53001、53002…（由 CMS 自动寻找空闲编号）。

服务器 → 终端（进入方向）

端口	用途	被阻断时
5900	VNC 远程控制 — 直接查看并操作该屏幕	远程控制按钮打不开

🔴 **只有这一个方向相反。**即使打开了其他所有端口，漏掉这个也只会导致远程控制不可用 — 而且其余功能都正常，很难找到原因。如果每台设备使用不同端口，请在设备管理 → 设备页面顶部的 编辑基本信息 → 远程连接 栏中填写 地址[:端口]（管理员及以上）。

仅管理端使用的端口（与终端无关）

端口	用途
4822 · 8080	Guacamole 内部通信
5500 · 5901	VNC 中继器（内网隔离结构中的服务器端 · 播放器端）

🔵 数据库端口（3306）不对外开放。 只在堆栈内部通信。

使用 MqttEdge 的现场

如果有边缘中继器，终端只会连接边缘中继器，不直接连接 CMS。边缘中继器会向现场侧开放 8883（MQTT）和 8443（内容代理），对外则只有边缘中继器向中央发出的一条连接。

⭐ 因此即使在内网隔离环境中，也无需在路由器上开放外部进入的端口 — 因为边缘中继器 只使用向外发起的连接。

顺序

🔵 请按此顺序操作。尤其不能调换第 2 步和第 3 步 — CMS 地址是在播放器画面上 填写的，所以必须先装好播放器。

1. 安装 CMS — 在 CMS 主机上搭建服务器，并确定访问地址（IP/域名 + 端口）。 → CMS 服务器安装
2. 在终端上安装程序 — 安装播放器（+ 监护程序，需要时加装同步服务器）。 → 见下文*“在终端 PC 上安装”*
3. 填写 CMS 地址 — 在播放器画面按 F8。监护程序和同步服务器可在安装时填写（自相应版本起），或之后通过命令、文件填写。 → 见下文*“填写 CMS 地址”* · “其他程序也需要 CMS 地址”
4. 🔴 确认是否已生效 — 亲眼查看播放器日志中的 [사이트설정] 확인（站点设置 确认）行。 → 见下文*“如何确认是否正确生效”*。跳过这一步，后面出问题时将无从查找原因。
5. （仅 HTTPS + IP 地址现场）登记信任服务器证书 — 见下文*“以 IP 作为地址的现场”*。
6. 设备注册 + 排播 — 地址正确时，播放器会自动向 CMS 注册（设备证书也会 自动签发）。在 CMS 管理后台设置内容和排播。程序的新版本 按 CMS 的更新方式（自动 · 手动）由所有设备共同接收 （管理后台）。

安装与更新

各程序**所需的权限不同。**规划安装顺序时请事先了解。

程序	安装权限	安装位置
TreeTview（播放器）	普通用户	该用户的个人文件夹
🔴 SyncServer（同步）	管理员	程序文件夹（公用）
🔴 Watchdog（监护）	管理员	程序文件夹（公用）
🔴 MqttEdge（内网隔离中继）	管理员	公用文件夹

Watchdog 为什么需要管理员权限

因为它需要修改屏幕保护、睡眠等整台机器的设置。所以安装时 会弹出管理员授权窗口 — 这是正常的。

🔵 只有设置文件放在运维人员可以修改的位置（C:\ProgramData\TreeT\Watchdog）。 如果放在管理员文件夹里，每次改值都需要授权。 ⚠️ C:\ProgramData 是隐藏文件夹，在资源管理器中看不到 — 在地址栏直接输入 C:\ProgramData\TreeT\Watchdog 打开。

🔵 SyncServer 也是管理员安装 — 它需要在任何人登录之前就运行，所以开机时以系统账户启动。设置文件是 C:\Program Files\TreeT\SyncServer\SyncServer.json，修改时请以管理员身份打开记事本。

以普通用户身份安装的只有播放器，它按账户分别安装 — 如果同一台 PC 由多人使用， 需要用对应的账户登录后安装。

更新 = 重新运行同一个安装文件

没有单独的更新文件。直接运行新版本的安装文件即可覆盖现有安装。

此时设置、证书会保持不变。不会因为重新安装而需要重新填写现场设置。

在播放器画面上更新

除了直接运行安装文件，也可以在播放器画面上检查并安装。 CMS 有要下发给该设备的新版本时（程序版本）， 在现场这样操作：

1. 在播放器中按 F8 打开设置界面。
2. 在程序更新一项中点击 [확인]（确认） — 会显示当前版本和状态。
3. 如有可安装的版本，[지금 설치]（立即安装） 按钮会变为可用。

新版本在运营时间外安装 — 要立即安装请按 [지금 설치]（立即安装）

即使 CMS 中有了待接收版本，设备也不会立即安装。这是为了避免正在播放的屏幕毫无预告地 中断。设备会在其所在屏幕组的运营时间结束时自行安装；没有运营时间外的组（24 小时运营等） 会从 CMS 设置 › 应用更新 的 更新时刻（默认 03:00）起 60 分钟内安装。

不等待、要立即安装时，请按 [지금 설치]（立即安装）。可以在两个地方按：

在哪里	怎么做
在 CMS 中（多台一次完成）	设备管理（기기관리）→ 选择设备 → 对所选设备的命令 → 立即安装
在该设备上（单台）	F8 → 程序更新 → [확인] → [지금 설치]

安装开始后，播放器会暂时退出，然后以新版本重新启动。

🔵 可以等待的话就不必按。到了上述时间，该设备会自行安装。实测约需 90 秒。 ⚠️ 如果 CMS 设为手动更新，新版本必须先被批准（CMS 的 [지금 업데이트]（立即更新））—— 批准之前，即使按 [지금 설치] 也没有可安装的版本。

⚠️ 按下后请不要再按。按一次就够了 — 安装完成后设备会自行 重新启动并上报新版本。安装过程中再次按下并不会更快。

监护程序和同步服务器会自行下载安装

与播放器不同，这两个程序由**监护程序向 CMS 查询并代为安装。**按下 [지금 설치] 后 1 分钟内开始。

⚠️ 安装了低于 Watchdog 2026.9.43 版本的 PC 情况不同 — 该版本之前无法接收按钮指令， 因此最长要等 6 小时（监护程序的检查周期）。如果着急，请在该 PC 上重启监护程序 （任务计划程序 → Watchdog → 结束后运行，需管理员）。它在启动时会立即检查。

⚠️ **如果刚刚手动运行过安装文件，这样重启不会生效。**此时运行中的监护程序是 安装文件直接启动的，不受任务计划程序管理 — **即使”结束”显示”成功”， 它仍在运行。**重启 PC 即可理顺。

来源不明的文件会被拒绝

下载的安装文件只有在验证签名和校验和之后才会安装。验证失败时会丢弃该文件， 不予安装 — 如果安装被拒绝，请先确认文件是从哪里下载的。

安装时出现蓝色警告界面 — 这是正常的

运行安装文件时，Windows 可能会弹出名为 “Windows 已保护你的电脑” 的蓝色界面，杀毒软件也可能 隔离该文件。这并不代表文件已损坏。

Windows 信任的是很多人安装过的文件，而本程序是只安装在特定现场的 软件，安装次数积累不起来。因此每次发布新版本时都可能再次出现。

要继续安装：在蓝色界面中点击更多信息 → 仍要运行。

🔴 但请先确认以下几点 — 以免养成随手跳过警告的危险习惯：

• 文件是否从我们告知的途径下载
• 文件属性 → 数字签名选项卡中是否有 Jiseoan TreeT

⚠️ 如果杀毒软件删除了文件，请告知负责人 — 我们会向杀毒软件厂商提交误报申诉。 在此之前，等待申诉结果比添加例外更安全。

Linux 设备的更新 — 没有安装程序

Linux 没有像 Windows 那样的安装文件（.exe）。安装本身是一个压缩文件（.tar.gz）， 其中包含记录每个文件校验值的清单，以及该清单的签名。 从 CMS 接收新版本的方式（运营时间外 · [지금 설치]（立即安装））与 Windows 相同。

	Windows	Linux
收到的文件	安装文件（.exe）	压缩文件（.tar.gz） + 已签名的文件清单
安装方式	静默运行安装文件	解压到新文件夹后替换文件夹
校验内容	文件签名	清单的签名 + 每个文件的校验值
未能启动时	需要人工查看	自动回退到旧文件夹

新版本未能启动时会自动回退

播放器替换文件夹后，会检查新版本是否真的启动了。如果画面正常，播放器每 10 秒更新的 标记就会持续刷新；如果 3 分钟内该标记没有更新，就会回退到旧文件夹并重新启动旧版本。 失败的文件夹会加上 .failed 后缀保留下来，方便日后查明原因。

如果连回退也失败，日志中会留下**“사람이 봐야 합니다”（需要人工查看）**的记录 — 出现这一行时， 需要在现场手动启动。

更新途中断电也会自动恢复

如果恰好在替换文件夹的瞬间断电,安装文件夹可能为空,只剩下前一个版本。 监控程序会发现这种状态,把前一个版本移回安装位置并重新启动播放器。 此时 CMS 会收到一条错误: “바꿔 끼우는 도중 끊긴 뷰어 설치를 직전 판으로 되살렸습니다”(替换途中中断的播放器安装已恢复为前一个版本)。 写了一半的文件夹会加上 .failed 后缀保留。

如果安装文件夹和前一个版本都不存在,监控程序会向 CMS 发送一次 “사람이 봐야 합니다”(需要人工查看)—— 这时请在现场重新安装。

树莓派（arm64）的文件是单独的

即使同为 Linux，**普通 PC（x86-64）和树莓派（arm64）的可执行文件也不同。**通过文件名 区分 — 文件名中带 -arm64 的是树莓派专用。

设备	收到的文件
Linux PC	TreeTview-linux-<版本>.tar.gz · SyncServer-linux-<版本>.tar.gz
树莓派	TreeTview-linux-arm64-<版本>.tar.gz · SyncServer-linux-arm64-<版本>.tar.gz

⚠️ 上传了另一种文件时，设备上不会启动。 Linux 只会提示*“不是可执行格式”* （Exec format error）后结束，仅凭画面很难判断原因。 在设置 → 应用更新中上传时，请核对一次文件名。

同步服务器 · 监护程序以管理员（root）身份更新

在 Linux 上，这两个程序以 systemd 服务的方式安装，因此更新也是由监护程序以管理员权限 进行。先在旁边写入新文件，再一次性替换并重启服务。

• 不会覆盖现场设置文件 — 地址等数值会保持不变。
• 监护程序更新自身时会自行退出，由 systemd 用新文件重新启动。

在终端 PC 上安装

CMS 搭好后，在要显示画面的每一台终端 PC 上进行。

安装文件位于安装包的 설치파일\（安装文件）文件夹中（C:\treet\설치파일\） — 参阅 CMS 安装手册的*“开始之前”*。 🔴 请把整个文件夹移到终端 PC 上，在该 PC 上运行 — 安装文件是 以自身所在的文件夹为基准运行的。

⚠️ 请把安装包中的 TreeT_코드서명_공개인증서.cer（代码签名公钥证书）也一起带去。如果不先登记它， 自动更新会静默失败（参阅上文*“安装与更新”*）。

要安装什么

顺序	程序	是否必需
1	TreeTview — 显示画面的播放器	✅ 必需
2	Watchdog — 播放器退出时将其重新拉起，并代为安装新版本	✅ 推荐（无人值守现场实际上必需）
3	SyncServer — 仅在需要多块屏幕同步切换时	仅需要的现场
4	🔴 UltraVNC — 如需在 CMS 中查看这台设备的画面	✅ 推荐

SyncServer 要由 CMS 分配配额才会接收画面

仅安装还不够。能让多少台画面一起对齐（同步许可）由 CMS 决定 —— 在许可总量之内给每台同步服务器分配 配额，同步服务器只按这个数量接收画面。

顺序 — 前一步完成后，下一步才能进行：

1. 该 PC 的 Watchdog 必须已与 CMS 配对（每台 PC 批准一次 —— 同步服务器不单独申请，而是共用该证书）。
2. 在 CMS 中该 PC 的 设备页面 → SyncServer 选项卡 里，给这台同步服务器分配 配额（同时显示的画面数）（[싱크 라이선스 몫 바꾸기]（更改同步许可配额）—— master 账号。请向负责人申请）。
3. 同步服务器收到配额后，记录中会留下 싱크 라이선스: 동시 클라이언트 N대（同步许可：同时客户端 N 台），从此开始接收画面（通常 10 秒左右）。

看到这样的行时	含义	怎么处理
[싱크 라이선스] CMS 에서 이 싱크서버에 배분된 싱크 라이선스가 0 입니다 — 기기관리에서 몫을 나눠 주세요（CMS 分配给此同步服务器的同步许可为 0 —— 请在设备管理中分配配额）	尚未收到配额 —— 一个画面也不接收	执行第 2 步
클라이언트 접속차단! (싱크 라이선스 N대 초과 — CMS 에서 몫을 늘리세요)（客户端连接被阻止！（超出同步许可 N 台 —— 请在 CMS 中增加配额））	连上的画面多于配额 —— 只有超出的画面被阻止	增加配额或减少画面数
[싱크 라이선스] … 사이트 CA 가 없어 몫을 검증할 수 없습니다（没有站点 CA，无法验证配额）	找不到用来确认配额确实由 CMS 下发的证书 —— 不接收画面	把 SyncServer 升级到 2026.9.52 及以上，并确认该 PC 的 Watchdog 配对（第 1 步）已完成

🔵 收到的配额会保存在该 PC 上，即使 CMS 暂时连不上，7 天内 也照常运行。 🔴 计数单位是设备 —— 有多个画面的设备（如 2 分屏）也算 1 台。 🔵 不使用同步的现场完全不需要这一项 — 这正是上表中标注”仅需要的现场”的原因。

UltraVNC 不是我们的程序

需要另行下载安装。CMS 端的远程控制安装后即已开启， 但输出画面的一端在这台设备上 — 不安装的话，即使点击 [远程查看] 也不会显示画面。

• 端口为 5900（保持默认）
• 设置为自动启动（以服务方式安装）
• 密码无需设定 — 每次在 CMS 中点击按钮时，这台设备的 Watchdog 都会设置一次性密码（自 Watchdog 2026.9.153 起 · 比该版本旧的 Watchdog 使用站点通用密码，请将 Watchdog 升级到新版本）
• 只有地址 · 端口不同时才在 CMS 中填写（设备管理 → 设备页面 → 编辑基本信息 → 远程连接 栏中填写 地址[:端口] — 管理员及以上）

Watchdog 会弹出管理员授权窗口

安装过程中弹出授权窗口是正常的（参阅上表）。另外两个程序不会弹出。

请勿用磁盘镜像复制已安装 TreeT 的 PC

为一次准备多台设备时，请勿把已安装 TreeT 的 PC 磁盘做成镜像写入其他 PC。 设备身份记录和 CMS 注册信息也会被原样复制，一开机就可能夺走原 PC 的注册。

• 镜像请在安装 TreeT 之前（Windows · 驱动 · UltraVNC 为止）制作，TreeT 在每台 PC 上分别安装。
• 如果已经复制，请不要让该 PC 一直运行，删除 TreeT 后重新安装。设备页面出现 [신원] 같은 PC 의 Watchdog 정본 신원과 다릅니다（与同一 PC 上 Watchdog 的正本身份不同）时，可能就是这种情况。

Watchdog · SyncServer 会在安装过程中询问 CMS 地址

安装向导中会出现 CMS 地址 栏。请填写 CMS 的 IP 或名称（例：192.168.0.10）。

• 不写端口时，会变成 https://<填写的地址>:8443。CMS 只用 http 的现场， 请让此栏留空，安装后在下文 “其他程序也需要 CMS 地址” 的命令后加上 --scheme=http。
• 留空时会保留默认值（127.0.0.1 —— 这台 PC 自身）。这样连不上 CMS，安装后务必修改。
• 重新安装（更新）时不会询问 —— 为了保护已经设置好的地址。
• 🔴 这个地址**无法在 CMS 画面中修改。**地址错误会导致与 CMS 的连接中断，修改的通道也随之消失。

无人值守安装时用 /CMSURL= 传入：

.\Watchdog_Setup_<版本>.exe /VERYSILENT /CMSURL=192.168.0.10
.\SyncServer_Setup_<版本>.exe /VERYSILENT /CMSURL=192.168.0.10

只有特意传入 /CMSURL= 时，更新才会改变地址。

不让任务栏 · 通知出现在画面上方

播放器处于 全屏(Kiosk) 时,位于任务栏 之上。即使通知或其他窗口短暂夺走焦点,任务栏也不会出现在播放器上方。用快捷键退出全屏进入 窗口模式 后,它会像普通窗口一样降下去。

	Windows	Linux(树莓派)
播放器全屏时	播放器覆盖任务栏	窗口管理器(labwc)自行隐藏任务栏 —— 播放器不会关闭任务栏
通知	Watchdog 关闭通知,被打开时改回	—
从触摸屏边缘滑入	Kiosk 设置(Settings_All.cmd)将其关闭 —— 这是整台电脑的设置,Watchdog 发现不一致时 只报告	—
刚开机后	—	安装时运行的加固会 把任务栏从自动启动中去掉
窗口模式时	—	若开启了隐藏光标,播放器会关闭任务栏(备用)

⚠️ 光标只在播放器窗口上方隐藏 —— 在播放器未覆盖的画面(第二台显示器等)上仍可见(Windows · Linux 相同)。

🔵 播放器不在画面上时，任务栏 · 光标会显示 —— 关闭播放器(F4)或收起(F11)后，任务栏和光标会重新出现，可以立即使用这台 PC；播放器重新显示时，会恢复为 用户选择的状态(用 F9 · F10 选择的 —— 未选择时两者都隐藏)。播放器意外停止时，Watchdog 也会恢复任务栏和光标。

安装后需要确认的事项

播放器首次启动时会自动找到 CMS 并注册。无需人工注册。

CMS 管理后台的**设备管理（기기관리）**列表中出现该设备即表示成功。

没有出现时 — 几乎都是”地址”问题

这是播放器要连接哪个 CMS没有设对。请直接进行下文的*“填写 CMS 地址”*。

⚠️ 设备**开机正常，画面也会显示。**出问题的只有与 CMS 的连接， 所以表面上看起来一切正常。

运行安装检查 — check-install.ps1

安装包（C:\treet）中附带了一个检测安装是否正确的脚本。 它会检查那些仅凭屏幕有画面看不出来的问题。

安装即使以”成功”结束，也可能有问题

不要看到*“安装完成”*窗口就结束。

在终端 PC 上打开 PowerShell，逐行运行。

安装之前 — 以当前值为基准记录下来（有了它才能判断*“设置是否被保留”*）：

powershell -ExecutionPolicy Bypass -File C:\treet\check-install.ps1 -Before

安装之后 — 检查后置条件：

powershell -ExecutionPolicy Bypass -File C:\treet\check-install.ps1 -After

即使没有记录 -Before，-After 也能运行。只是它只能说明*“当前值是这样”*， 无法说明哪些发生了变化。

此工具不做修复 — 只做报告

目的是把检查了什么留作现场记录。如有发现，请把那段文字原样 转告我们。

填写 CMS 地址 — 在播放器画面上（仅首次一次）

播放器刚安装完时带着开发默认值（127.0.0.1）。需要在该 PC 上填写一次， 它才能找到 CMS。手动操作只有这一次，之后都在 CMS 中修改。

通过键盘快捷键操作 — 无需打开文件。

按键	作用
F8	打开设置界面 ← 在这里填写 CMS 地址
F11	暂时收起画面（最小化）
F10	开启/关闭全屏 —— 会记住所选状态(重启后保持)
F9	显示/隐藏鼠标指针和任务栏(Linux 也包括树莓派任务栏) —— 会记住所选状态
F4	退出播放器

1. 在播放器运行的状态下按 F8。
2. 在 CMS 주소（CMS 地址）栏中填写该现场的 CMS 地址 — 例：http://192.168.0.10:8080
3. 🔴 同时填写 MQTT 사이트（MQTT 站点）栏 — 与安装 CMS 时询问的站点名称完全一致 （包括大小写）。⚠️ 如果留空，画面会显示，但远程指令永远不会到达 — 消息代理 会以主题权限将其拦截，而且不会出现任何错误提示。
4. MQTT 주소（MQTT 地址）栏：如果与 CMS 在同一台机器上，只填 CMS 地址的主机部分（例：192.168.0.10）。
5. 保存后，播放器会用该地址找到 CMS 并自动注册。

即使树莓派 · Linux 没有中文字体，设置画面 · 启动画面中的韩文 · 日文 · 中文也能正常显示 —— 播放器自带字体(安装包增大约 13MB)。不从互联网下载，封闭网络中也可使用。

全屏时快捷键同样有效

即使终端处于全屏状态，F8、F11 也能使用。想暂时移开画面去做别的事，按 F11；要再看画面，选中播放器窗口即可。

直接修改文件是最后手段

仅在设置界面（F8）打不开时，才修改该 PC 上 %APPDATA%\TreeTview\config\setting.json 中的 path.baseUrl 这一项。

🔵 其余两项留空才是正确答案 — path.dataUrl 和 mqtt.host 留空时会跟随 path.baseUrl。 三项分开填写后，将来迁移 CMS 地址时只会改一项而忘记其余，实际上已经发生过这种事故， 设备一次都没有连上代理。

何时填写	填什么
path.dataUrl	仅当单独部署文件服务器时
mqtt.host	仅当在封闭网络中使用边缘中继时

🔴 必须在该 PC 上、以该用户身份修改。曾经实际发生过通过共享文件夹、其他账户或远程工具修改后， 文件改了但播放器读不到的情况。所以请务必执行下面的确认步骤 — 依据不是”改过了”， 而是播放器确实这样读取了。

如何确认是否正确生效（请勿跳过）

重启播放器后，打开该 PC 上的

%APPDATA%\TreeTview\logs\main_<今天日期>.log

查看最下方的 [사이트설정]（站点设置）行。

显示的行	含义
[사이트설정] 확인 — CMS 주소·MQTT·CA 설정에 걸리는 것 없음.（CMS 地址、MQTT、CA 设置均无问题）	✅ 通过
✗ CMS 주소가 아직 개발 기본값입니다 (http://127.0.0.1)（CMS 地址仍为开发默认值）	❌ path.baseUrl 未生效
✗ mqtt.host 가 아직 개발 기본값입니다 (127.0.0.1)（mqtt.host 仍为开发默认值）	❌ mqtt.host 中仍留有开发默认值。🔵 修复方式不是填入值，而是清空它（清空后会跟随 baseUrl）。仅在使用封闭网络的边缘中继时才填写地址
✗ mqtt.site 가 기본값 "site" 입니다（mqtt.site 为默认值 “site”）	❌ MQTT 사이트 栏为空 — 远程指令不会到达
· 사이트 CA 가 아직 없습니다（尚无站点 CA）	如果尚未首次注册，这是正常的（不是错误）

🔴 地址错误时的症状看起来不像”故障”。画面会正常全屏显示， Watchdog 会每隔几分钟反复重新拉起播放器。表面上看就是*“开着机，但就是 没有内容”*。上面这行日志是唯一准确的信号。

设备证书无需人工放置

播放器首次向 CMS 注册时，会自行生成密钥、申请签发证书并保存。 无需准备或复制任何东西 — 只要地址正确，其余都会自动完成。

不要复制其他 PC 的证书

证书的私钥绑定在那台机器上并被锁定。复制过来的证书无法打开， 更糟糕的是，它会掩盖自动签发失败的真正原因 — 因为文件存在，表面上看起来 正常，谁也查不出为什么连不上 CMS。

可能需要人工放置的只有 https 现场的站点 CA 这一项 （参阅下文*“以 IP 作为地址的现场”*）。

其他程序也需要 CMS 地址

只改播放器还不够。一起安装的程序也各自连接 CMS。

程序	要修改的文件	要修改的项
Watchdog	C:\ProgramData\TreeT\Watchdog\watchdog.json	appCheck.cmsUrl
SyncServer（仅使用它的现场）	C:\Program Files\TreeT\SyncServer\SyncServer.json	cms.url
MqttEdge（仅内网隔离现场）	安装文件夹中的 conf.d\site.conf	中央消息代理地址

Watchdog 地址错误时，更新会”静默”停止

播放器运行正常，画面也正常。唯一的问题是在 CMS 中发布新版本也装不上， 往往要等几个月后才会发现*“为什么还是旧版本”*。

用命令修改的方法 —— 不打开文件也能只修改地址。 在管理员 PowerShell 中逐行执行：

& "C:\Program Files\TreeT\Watchdog\Watchdog.exe" --configure 192.168.0.10
& "C:\Program Files\TreeT\SyncServer\SyncServer.exe" --configure 192.168.0.10

• 只写地址时会变成 https://192.168.0.10:8443。http 现场请加上 --scheme=http（http://192.168.0.10:8080）。
• 只想先看看时加上 --dry-run —— 只显示会改动几处，不写入。
• 修改前的原文件会以 .bak 保留在同一文件夹。
• 旧版 Watchdog 执行此命令会以 watchdog.json 을 못 찾았습니다（找不到文件）停止 —— 这时请按下文用记事本修改。
• 无论用命令还是记事本，修改后都要重新启动才会生效（见下表）。 用记事本修改的方法 — 以管理员身份打开记事本，只修改该文件中的地址。

刚安装完时，Watchdog 地址指向这台 PC 自身

安装程序写入的值是 "cmsUrl": "https://127.0.0.1:8443"。127.0.0.1 指的是该终端自身，那里没有 CMS — 请改为现场 CMS 的地址。🔴 地址后面不要加路径（例如 /treetweb）— 加了就无法注册。

端口已预先填写在两个栏中 — httpPort（明文入口，默认 8080）· httpsPort（安全入口，默认 8443）。只有 CMS 使用其他端口的现场才需要修改。 通过 https 连接时（例：https://192.168.0.10:8443），caFile 保持为空 — Watchdog 会通过 httpPort 从 CMS 获取一次站点 CA 并保存， 并把它的指纹写入日志。请与 CMS 设置画面上的站点 CA 指纹核对一次。

watchdog.json 是以 [ 开头的列表，地址位于第一个 { … } 块中的 appCheck 里。 只修改那一行，其余的值保持不变 — 尤其是如果清空 signerThumbprints，自动更新会被关闭。 下面是 CMS 为 192.168.0.10:8080 的现场的完整文件。

[
  {
    "autoHide": true,
    "updateLock": {
      "file": "%APPDATA%\\TreeTview\\update.lock",
      "maxHoldMinutes": 10
    },
    "startupDelayMs": 30000,
    "appCheck": {
      "cmsUrl": "http://192.168.0.10:8080",
      "caFile": "",
      "httpPort": 8080,
      "httpsPort": 8443,
      "tokenFile": "%APPDATA%\\TreeTview\\data\\device-token.json",
      "intervalMs": 600000,
      "autoApply": true,
      "downloadDir": "%APPDATA%\\TreeTview\\data\\update",
      "signerThumbprints": [
        "1CAE827334F20023B720E10A3460FEA788F2DD8B"
      ],
      "nodeHeartbeatInterval": 60000
    }
  },
  {
    "processName": "TreeTview.exe",
    "execPath": "%LOCALAPPDATA%\\TreeT\\TreeTview\\TreeTview.exe",
    "execArgv": [],
    "heartbeatTimeout": 30000,
    "scheduledTask": "TreeTview"
  },
  {
    "processName": "SyncServer.exe",
    "execPath": "%ProgramFiles%\\TreeT\\SyncServer\\SyncServer.exe",
    "execArgv": [],
    "program": "SyncServer"
  },
  {
    "processName": "mosquitto.exe",
    "execPath": "C:\\ProgramData\\TreeT\\MqttEdge\\vendor\\win64\\mosquitto.exe",
    "execArgv": ["-c", "mosquitto.conf"],
    "workingDir": "C:\\ProgramData\\TreeT\\MqttEdge",
    "program": "MqttEdge",
    "logFile": "logs/mosquitto.log"
  }
]

• 路径中的 \\ 是 JSON 语法，保持两个不变。
• 在没有 MqttEdge 的 PC 上，Watchdog 会自动跳过 mosquitto.exe 块 — 无需删除。
• 保存时编码为 UTF-8。

SyncServer 只需修改 cms 块中的一行（这里本来就没有 /treetweb）：

"cms": {
    "url": "http://192.168.0.10:8080",

修改后需要重启该程序才能生效。

程序	重启方法
Watchdog	任务计划程序 → Watchdog 任务 → 结束后运行（管理员）
SyncServer	任务计划程序 → SyncServer 任务 → 方法相同。或注销后重新登录
TreeTview（播放器）	任务计划程序 → TreeTview 任务 → 结束后运行。监护程序也会在 10 秒内自动将其拉起

确认是否正确生效 — Watchdog 启动时会在自己的日志中输出地址：

C:\Program Files\TreeT\Watchdog\logs\server_<今天日期>.log

显示的行	含义
업데이트 확인 시작 (10분 주기, CMS http://192.168.0.10:8080)（开始检查更新，10 分钟周期）	✅ 正在连接该地址（周期数值取决于 intervalMs）
업데이트 확인이 설정돼 있지 않습니다(watchdog.json 의 appCheck.cmsUrl)（未设置更新检查）	❌ 该项为空

在 CMS 中确认更可靠 — 即使日志中的地址正确，如果路径（/treetweb）错误，也无法注册。 在 设备管理（기기관리） 中打开该 PC 上的设备，如果 设备设置 选项卡的 此 PC 上的程序 中在 1~2 分钟内出现 Watchdog · SyncServer， 并且最后应答在 방금（刚刚）~1분 전（1 分钟前），就说明成功了（如果尚未关联到 PC，会先出现在设备管理列表上方的 PC 미확인 프로그램 行中）。如果没有出现，请先重新检查地址。

用 PowerShell（管理员）重启时，逐行执行：

Stop-Process -Name Watchdog -Force

Start-ScheduledTask -TaskName Watchdog

Stop-Process -Name SyncServer -Force

SyncServer 很快会被 Watchdog 重新拉起 — 因此随后仪表盘上出现一行*“SyncServer.exe 이(가) 죽어 있어 다시 띄웠습니다”*（SyncServer.exe 已停止，已重新启动） 是正常的。

请先注册播放器

Watchdog 借用播放器注册时获得的设备令牌。如果播放器尚未在 CMS 中 注册，Watchdog 日志中会出现 AUTH_TOKEN_REQUIRED — 这不是地址错误， 而是顺序问题。先把播放器连上，问题会自然解决。

自动启动

安装后会注册为登录该 PC 时自动启动。无需另行操作。

无人值守现场请同时检查自动登录

播放器在登录之后才会启动。要在停电后自动恢复，必须开启 Windows 自动登录 — 这是操作系统设置，我们的安装文件不会改动它。

以 IP 作为地址的现场（HTTPS）

如果 CMS 地址使用域名，可以使用公共证书，无需额外操作。 而通过 IP 地址访问的现场使用的是该站点专用的证书，因此需要让终端信任它， 登记一次即可。

登记时请亲眼核对指纹

由于获取证书的通道本身尚未受到保护，必须亲自确认画面上显示的指纹（fingerprint） 与 CMS 设置界面中记录的值一致后再接受。跳过这一核对，登记步骤的 保护作用就会失效。

登记通过导入时提供的工具完成，现场负责人只需核对指纹。

开发默认值 vs 现场值

注意

防火墙/端口（网页访问端口、实时控制与同步端口）以及多屏同步用的许可证，需根据现场配置 另行确认。详细的部署咨询请联系 TreeT 负责人。