企业官网建设流程全解析

• 桌面应用
• CLI
• 智能硬件

本篇技术文章以 LGTV Companion 项目根目录的 README 为主体，完整覆盖其安装前提、UI 配置流程、已知限制与故障排查清单，并结合仓库中的 Windows 服务源码、WebOS 客户端与 WOL（Wake-on-LAN）实现，深入解释"PC 关机/休眠/屏幕熄灭 → 电视关机，PC 唤醒 → 电视开机"这一联动机制的完整技术链路。读完本文后，你可以独立完成电视侧与 Windows 侧的全部前置配置，理解服务如何监听系统电源事件并驱动 WebOS 设备，以及如何用命令行与命名管道 API 实现自动化脚本。

一、项目定位：为 OLED 电视做"PC 显示器伴侣"

README 将本项目概括为：UI 与 Service 共同控制 LG WebOS 电视与显示器的应用。它的设计目标是成为一个"装完即忘"（set-and-forget）的工具，提供三项核心能力：

1. 自动设备管理：响应 PC 的关机、重启、低功耗模式、用户闲置以及多显示器环境下的监视器拓扑变化，自动开关 WebOS 设备；
2. 强大的命令行工具：控制 WebOS 设备并修改其大部分设置；
3. 对外 API：供外部脚本或应用程序调用，便于自动化。

项目背景很直接：随着 OLED 电视被越来越多地当作 PC 显示器使用，标准 PC 显示器所具备的"随主机开关机"功能在电视上缺失，而 OLED 面板对长时间显示静态画面的烧屏（pixel-wear）敏感，因此让电视跟随 PC 电源状态自动关机尤为重要。

从源码结构看，仓库采用多工程组织：LGTV Companion Service/是 Windows 服务（LGTVsvc.exe），LGTV Companion UI/是图形界面，LGTV Companion User/是桌面用户态守护进程（LGTVdaemon.exe），LGTV Companion Console/与LGTV Companion Updater/分别是命令行接口与更新器，公共代码集中在Common/。README 的"Limitations"与"Troubleshooting"两节内容则全部由这套架构的实际网络行为决定，下文会逐一对应解释。

二、安装前的关键前提（电视侧 + 网络侧）

README 的"Installation and usage"第 1 步列出的前提条件是整个方案能否工作的基础，必须全部满足：

1. 电视必须先开机，并通过 Wi-Fi 或网线接入局域网；
2. 确认电视支持网络唤醒（Turn on via Wi-Fi），按型号在电视设置中找到对应路径：
   • CX 系列：Settings（遥控器上的齿轮键）→ All Settings → Connection → Mobile Connection Management → TV On with Mobile，启用Turn On via Wi-Fi；
   • C1 / C2 / C3 / C4 系列：All Settings → General → Devices → External Devices → TV On With Mobile →Turn on via Wi-Fi。
   • 注意：无论电视走 Wi-Fi 还是网线，都必须启用此项。这一点在仓库命令行文档 Docs/Commandline.md 中也有对应印证：-wol true|false命令修改的正是同一个 Wake-On-Lan 设置（即 "On with Mobile" / "Turn on via Wi-Fi"）。
3. 在路由器管理界面为 WebOS 设备配置静态 DHCP 租约，确保电视在局域网中的 IP 永远不变。

README 热帖提示（HOT TIP）：在电视设置中，把设备内置的"自动关机"（Auto Power off）时间调得足够长（例如 8 小时），避免它在你的 PC 使用会话中主动断电。C2 系列的路径为：All settings → General → OLED Care → Device Self-Care → Energy Saving → Auto Power off。LGTV Companion 会接管显示器电源状态管理，内置自动关机越少介入越好。

这些前提之所以关键，源于项目的底层机制（后文详述）：开机靠 WOL 广播魔术包（仅限二层、同子网），关机靠 WebOS 的 SSAP/WebSocket API（依赖稳定 IP 与配对密钥）。IP 不固定或"Turn On via Wi-Fi"未启用，方案直接失效。

三、安装与配置全流程

3.1 获取与安装

• 最新版本安装包可从项目的 Releases 页面下载；也可以在 Windows Terminal/PowerShell 中通过 Winget 安装：

winget install LGTVCompanion

• 关于 SmartScreen 拦截：Windows Defender SmartScreen 可能会阻止下载或运行安装包。开发者无法直接影响 SmartScreen 的收录情况，如果安装包下载不了，需要在浏览器中强制继续下载；如果安装程序无法运行，需要右键安装包 → Properties → General → Security 区域勾选Unblock来解除阻止。README 还建议下载时向 Microsoft 报告该应用为安全，以避免未来再次被拦截。

安装程序会安装并启动三部分：

从源码可以印证：服务名在 LGTV Companion Service/main.cpp 中定义为LGTVsvc，显示名为 "LGTV Companion Service"，依赖Dhcp\0Dnscache\0LanmanServer（即需要 DNS 缓存服务，符合其"服务运行在 LocalSystem 下需要网络解析"的实现特点）。

3.2 UI 配置步骤（README 步骤 3–11 完整保留）

1. 从开始菜单打开 "LGTV Companion"；
2. 点击Scan按钮让应用自动发现局域网内的 WebOS 设备（新版界面中该按钮显示为Configure）。若扫描不到，可手动添加设备；
3. （可选）通过下拉菜单手动添加、删除、配置设备参数，包括：网络 IP 地址、物理地址（MAC，可在电视的网络设置中查到）、WOL 唤醒选项（默认选项在多数组网下可用，若电视难以开机则尝试其他选项）。README 提示：点击 UI 中的What's this?链接可查看所有选项的详细说明；
4. 在主窗口确保勾选Automatically manage this device，这样应用才会对该设备自动响应电源事件（关机、重启、挂起、恢复、闲置）；
5. （可选）点击汉堡菜单图标调整全局设置。README 提示User Idle Mode（用户闲置模式）独立于其他所有 Windows 电源选项工作，可为防烧屏提供最大保护并额外省电；
6. 非英文系统注意：如果操作系统语言不在内置词典中，需要在"shutdown settings"对话框中手动勾选表示"系统正在重启/重新开机"（而非关机）的词语所对应的复选框。原因在于：README 指出"据作者所知，服务判断系统是被重启还是被关机的唯一办法，就是查看事件日志中的特定事件"。仓库源码证实了这一点——LGTV Companion Service/main.cpp 中服务通过EvtSubscribe订阅System通道的EventID=1074事件，并在 SvcEventLogSubscribeCallback 中解析 XML 的param5（关机原因字符串），与 Common/preferences.h 中的event_log_shutdown_strings_/event_log_restart_strings_词典逐项比对来区分 SHUTDOWN 与 REBOOT；两种自定义词典（*_custom_）即对应 UI 中的手动勾选。
7. 点击Apply保存配置文件并自动重启服务。配置文件为config.json、日志为log.txt，文件名定义见 Common/common_app_define.h；
8. 电视会弹出配对对话框，需要接受。这一步建立了 WebOS 会话密钥：首次连接时客户端发送不含client-key的注册握手（LG_HANDSHAKE_NOTPAIRED），配对成功后session_key写入配置，后续连接使用含client-key的握手（LG_HANDSHAKE_PAIRED），两个握手模板定义在 Common/lg_api.h；
9. （推荐）再次打开下拉菜单选择Test，确认设备正确响应开/关命令；
10. 关闭主 UI。服务继续在后台运行。

四、从源码看完整事件链路：电源事件如何变成电视的开/关

README 只描述了"现象"，仓库源码则完整展示了"机制"。整条链路分为四个环节。

4.1 事件源：服务如何知道 PC 要关机/休眠/屏幕熄灭

在 SvcCtrlHandler 中，服务同时注册了多路事件源：

• SERVICE_CONTROL_POWEREVENT：
  • PBT_APMSUSPEND→EVENT_SYSTEM_SUSPEND（系统挂起）；
  • PBT_APMRESUMESUSPEND→EVENT_SYSTEM_RESUME（从挂起恢复）；
  • PBT_APMRESUMEAUTOMATIC→EVENT_SYSTEM_RESUMEAUTO（现代待机自动唤醒）；
  • PBT_POWERSETTINGCHANGE且设置 GUID 为GUID_CONSOLE_DISPLAY_STATE时，按数据值映射为屏幕熄灭（0）/ 变暗（2）/ 点亮（其他）事件。
• SERVICE_CONTROL_SHUTDOWN/PRESHUTDOWN：直接触发EVENT_SYSTEM_SHUTDOWN；注意 SvcReportStatus 会根据全局选项shutdown_timing_在接受 PRE_SHUTDOWN（early 模式）还是 SHUTDOWN（default/delayed 模式）之间切换——对应 Common/preferences.h 中PREFS_SHUTDOWN_TIMING_DEFAULT/EARLY/DELAYED三档，DELAYED 模式下服务会先向 SCM 报告 STOP_PENDING 争取约 4 秒缓冲再发送关机事件（main.cpp L276-L308）。
• 事件日志订阅（EventID=1074）：用于在关机与重启之间做语义区分，解析逻辑见 3.2 第 6 步。
• 服务启动时还会调用SetProcessShutdownParameters(0x100, SHUTDOWN_NORETRY)（main.cpp L441）争取足够的关机宽限时间，避免 WebOS 关机请求还没发出进程就被终止。

所有事件类型统一定义在 Common/event.h：EVENT_SYSTEM_SHUTDOWN、EVENT_SYSTEM_SUSPEND、EVENT_SYSTEM_DISPLAYOFF、EVENT_SYSTEM_USERIDLE、EVENT_SYSTEM_TOPOLOGY、EVENT_SYSTEM_REMOTE_CONNECT等，以及用户强制事件EVENT_FORCE_DISPLAYON/OFF和通用请求事件EVENT_REQUEST、EVENT_BUTTON。

4.2 事件分发：Companion 核心决策表

LGTV Companion Service/companion.cpp 中的Companion::Impl是核心调度器。启动时为每个已配置设备创建一个SessionWrapper（内含一个WebOsClient会话，共享一个 boost::asioio_context与 TLS 1.2 上下文，见 companion.cpp L37-L48、L49-L67）。事件经dispatchEvent()按设备分发后进入 processEvent，对"启用了自动管理（session.device_.enabled）"的设备执行如下映射（源码行号见 L506-L615）：

其中setHdmiInput()（companion.cpp L452-L462）展示了开机后的 HDMI 输入切换：通过LG_URI_LAUNCH（system.launcher/launch）发送{"id":"com.webos.app.hdmi1"}这类载荷（模板定义在 Common/lg_api.h），并可配置开机后延迟执行（set_hdmi_input_on_power_on_delay）。

此外，服务在每次事件处理后调用sendToIpc()（companion.cpp L642-L681），在external_api_support_开启时把SYSTEM_SHUTDOWN、SYSTEM_USER_IDLE、SYSTEM_RESUME等状态字符串推送到命名管道——这正是 README"对外 API"能力的事件侧实现。

4.3 WebOsClient：配对、关机与 WOL 开机的实现

每个设备的通信客户端 LGTV Companion Service/web_os_client.cpp 基于 Boost.Beast WebSocket 实现（对应 README"Thanks to"一节致谢的 Boost、Beast、nlohmann/json）：

• 端口与传输：SSL 端口3001、非 SSL 端口3000（web_os_client.cpp L30-L32），设备结构体Device.ssl字段决定走哪条路径（Common/device.h）；
• 典型控制报文（Common/lg_api.h）：
  • 开机（亮屏）：ssap://com.webos.service.tvpower/power/turnOnScreen
  • 黑屏/熄屏：ssap://com.webos.service.tvpower/power/turnOffScreen
  • 关机：ssap://system/turnOff
  • 电源状态轮询：ssap://com.webos.service.tvpower/power/getPowerState（keep-alive 心跳也复用它，周期 60 秒）；
• 开机（powerOn）的双轨策略：startNextWork()中WORK_POWER_ON分支会同时this->run()（尝试 WebSocket 连接，用于确认设备已上电）与this->runWOL()（发送魔术包），在device_settings_.extra.timeout秒内循环重试。这与 README 的 Limitations 相互印证：
  • 部分 LG OLED 电视在执行自动像素刷新（pixel refresh）期间无法通过网络开机；一些机型在刷新结束后能听到内部继电器"咔哒"一声，此时才真正断电、可以被唤醒——这解释了为什么重试循环要持续数十秒（power_on_timeout_默认 40 秒，见 preferences.h L44）；
• WOL 魔术包与四种唤醒方式：runWOL/onWOL 构造 102 字节魔术包，按 Common/device.h 的wake_method选择目标地址：

README 的排障建议"优先使用选项二，发往 IP 地址"（primarily use option two, send to IP-address），在源码中即WOL_TYPE_IP+ 临时 ARP 注入路径。

• 连接保持策略：device.h L12-L14 定义PERSISTENT_CONNECTION_OFF/ON/KEEPALIVE三档（默认 OFF），控制工作队列空闲后是延迟关闭、保持连接还是周期性心跳。

4.4 用户态守护进程：闲置检测与拓扑

LGTV Companion User/Daemon.h 声明了守护进程的职责边界：checkDisplayTopology()/verifyTopology()（显示器拓扑变化检测，对应事件EVENT_SYSTEM_TOPOLOGY）、Raw Input 系列函数（RawInput_RegisterDevices、RawInput_AddToCache等，用于检测用户输入判断闲置/活动，即 UI 中的 User Idle Mode）、checkRemoteStreamingProcesses()/sunshine_CheckLog()（检测 Sunshine 等远程串流服务的连接状态，对应EVENT_SYSTEM_REMOTE_CONNECT/DISCONNECT）、以及isFullscreenApplicationRunning()（全屏应用检测，服务于闲置模式的排除策略）。用户忙碌/闲置状态由守护进程经 IPC 上报给服务（companion.cpp L820-L841 中的userbusy/useridle分支），服务仅接受来自物理控制台会话（WTSGetActiveConsoleSessionId()比对）的消息，防止远程会话误触发。

五、关键配置参数一览（结合源码默认值）

配置保存为config.json（节点名"LGTV Companion"，含Version与Topology子节点），以下默认值来自 Common/preferences.h 与 Common/device.h：

多设备拓扑状态持久化在topology_config.json（companion.cpp L246-L304），topology_keep_on_boot_开启时服务重启后自动恢复拓扑。

六、命令行与脚本 API（README "Commandline arguments" 一节的扩展）

README 说明LGTV Companion.exe可接受数百个命令行参数，完整清单见 Docs/Commandline.md。其通用格式为：

"LGTV Companion.exe" -[command] [[Argument 1] [Argument 2] ...] [[Device1|Name] [Device2|Name]...]

• 所有命令以连字符-开头，参数以空格分隔；
• 设备参数可选：可写设备索引（Device1，按 UI 下拉顺序编号）或友好名称；省略设备名则作用于所有已配置设备；
• 一条命令行可串联多个命令，每个未被转义的-开启一条新命令；
• 双引号既是控制字符转义手段，也是 LG JSON API 的必要组成部分，向设备发送 JSON 时须用\"转义。

两个命令行入口的分工（Docs/Commandline.md "The two command line interfaces"）：

• "LGTV Companion.exe"：多线程 GUI 应用，把命令尽快发出、不等待响应，适合 fire-and-forget；
• "LGTVcli.exe"：单线程，会按序把设备响应以 JSON 对象呈现给用户；需要响应时用它。其输出格式控制：-output [default|friendly|key] [key]及缩写-od、-of、-ok [key]。

常用命令示例（原文档示例保留）：

"LGTV Companion.exe" -poweron Device1 "OLED 42" :: 指定友好名（含空格用引号转义） "LGTV Companion.exe" -poweroff :: 关闭所有设备 "LGTV Companion.exe" -poweron Device1 -autodisable Device1 :: 开机后临时禁用 Device1 自动管理 "LGTV Companion.exe" -sethdmi1 Device1 -sethdmi 2 Device2 :: 分别切换 HDMI 输入 "LGTV Companion.exe" -mute Device1 :: 静音 "LGTV Companion.exe" -picturemode normal device1 device2 :: 设置画质模式 "LGTV Companion.exe" -contrast 80 device1 :: 设置对比度 "LGTV Companion.exe" -wol true :: 打开电视侧 WOL 设置 LGTVcli.exe -of -poweron Device1 "OLED 42" :: 友好格式输出 LGTVcli.exe -ok backlight -get_system_settings picture [\"backlight\"] :: 只输出 backlight 值 LGTVcli.exe -get_system_settings picture [\"color\",\"contrast\",\"backlight\"] device1

应用管理类命令（仅LGTV Companion.exe）：-autodisable、-autoenable（临时启停自动管理，服务重启后失效）、-streaming_connect/-streaming_disconnect（强制串流客户端连/断事件）、-clearlog、-idle/-unidle（手动触发/解除 User Idle Mode）。HDMI 类命令还包括-set_input_type（切 PC 模式等）、-gamemode_hdmiX、-freesyncoled_hdmiX、-hdmipcmode_hdmiX等。

脚本化：README 宣称的"API"通过异步命名管道实现——管道名\\.\pipe\LGTVyolo定义在 Common/common_app_define.h，服务端实现为 Common/ipc_v2.h /IpcServer2（在 companion.cpp L111 构造），支持外部脚本"读事件 + 发命令 + 读响应"的双向通信。前提是在 UI 中启用 "External API"。各语言的示例脚本位于 Docs/Example scripts/ 目录，包含 AutoHotkey 命名管道读写示例、PowerShell 函数集（如 adjustBacklight.ps1）等。API 的详细约定见 Docs/Scripting.md。

七、已知限制（README Limitations 逐条解读）

1. 像素刷新期间无法网络开机：部分 LG OLED 在执行自动像素刷新时不响应 WOL，听到继电器咔哒声（真正断电）后才可被唤醒。服务侧以 40 秒级的 WOL 重试窗口缓解此问题；
2. PC 与电视必须同网：WebOS API 需要双向连通；
3. 电视不能处于与 PC 不同的子网/VLAN：开机依赖 WOL 魔术包广播，WOL 广播是二层（L2）行为，只覆盖同一子网。跨子网唤醒需要网络设备做定向转发，超出本应用范围（"让作者知道你的组网情况可以寻求建议"）。这与runWOL()中仅向255.255.255.255/ 设备 IP / 子网广播三类本地地址发包的实现完全一致。

八、故障排查清单（README Troubleshooting 完整保留）

电视难以开机（powering on）时，按以下顺序检查：

• 电视设置中必须启用 "Turn on via WiFi"（无论 Wi-Fi 还是网线），见"前提条件"；
• Wi-Fi 连接时，部分用户需要启用Quickstart+（2021 及更早机型）或Always ready（2022 及更新机型），并禁用HDD Eco mode，以避免网卡（NIC）失活（网线连接似乎不需要）；
• 确认设备配置正确（IP、MAC），并尝试其他 WOL 选项，首选选项二：发往 IP 地址；
• 确认网络中间设备不会丢弃 WOL 广播包；
• 若电视关机状态下与路由器/接入点的连接因任何原因（路由器重启、断电、固件升级等）中断，电视可能不会自动重连网络，因此无法响应开机指令——此时需要手动开机一次让它重新连网；
• 若在显示器拓扑变化时设备不响应，确保已启用Always ready（2022 及更新机型）；
• 注意：用遥控器手动关机、或触发电视内置自动关机（Settings → General → OLED Care → Device Self-Care → Energy Saving → Auto Power off）后，有时也需要先用遥控器把电视点亮。

电视难以关机（powering off）时，最可能的原因：

• IP 配置有误。核对配置，并确保电视在路由器管理页面拥有静态 DHCP 租约；
• 应用尚未获得配对密钥。在 UI 中删除该设备 → 点击 Apply → 重新添加设备，以强制重新配对（对应 4.3 节中session_key为空时发送未配对握手的机制）。

通用手段：启用内置日志器查看输出（log.txt，由log_level_控制级别），它对定位功能问题非常有用。

九、系统要求、安全与隐私

• 系统要求：现代 Windows 环境，Windows 10 或 11 均可；一个局域网（LAN）。
• 供应链安全：README 声明项目达成SLSA（Supply-chain Levels for Software Artifacts）Level 3合规，以此展示对质量与安全的承诺；代码签名由 SignPath.io（SignPath Foundation 证书）免费提供。
• 隐私：程序不会向任何其他联网系统传输任何信息（Privacy Policy 原文承诺）。从源码看，除向已配置电视 IP 的 3000/3001 端口发起连接、以及更新器检查版本外，通信对象仅限于局域网内的 WebOS 设备。
• 构建：仓库提供 vcpkg.json 管理 Boost/OpenSSL 等依赖，构建步骤参见 Docs/Build how-to.md；当前仓库代码版本号为 5.5.7（Common/common_app_define.h）。

十、小结与延伸阅读

LGTV Companion 的 README 看似只是安装与排障手册，但仓库源码给出了其全部技术底牌：一个订阅 Windows 电源广播与EventID=1074事件日志的服务，配合一套按事件类型映射到 WebOS SSAP 请求（turnOnScreen/turnOffScreen/system/turnOff）与 WOL 魔术包重试的调度器，再叠加用户态守护进程的闲置/拓扑/串流检测与命名管道对外 API。关键参考路径：

• Docs/Commandline.md — 全部命令行参数与示例；
• Docs/Scripting.md — 脚本 API 说明；
• Docs/Example scripts/ — AutoHotkey / PowerShell 示例；
• LGTV Companion Service/main.cpp — 服务入口、电源事件源与关机/重启判别；
• LGTV Companion Service/companion.cpp — 事件决策表与 IPC 命令处理；
• LGTV Companion Service/web_os_client.cpp — WebSocket 客户端、WOL 与配对握手；
• Common/device.h、Common/preferences.h、Common/event.h — 配置结构体与事件常量定义。

• 桌面应用
• CLI
• 智能硬件