ifu Agent 支持 Windows 和 Linux 操作系统，通过官方安装包统一安装（Windows: NSIS 安装包；Linux: DEB 包）。安装包默认安装前台模式，也可选择注册为系统服务。
运行模式说明
| 模式 | 说明 | 功能差异 |
|---|---|---|
| 前台模式（默认） | 随用户登录自动运行（无界面），程序以当前用户会话运行 | 支持全部功能（电源 + 音量/屏幕/键盘/鼠标/剪贴板） |
| 服务模式（可选） | 注册为系统服务（Windows LocalSystem / Linux root），开机自启 | 仅电源控制可靠；交互类功能不可用（无桌面会话） |
Windows 安装
使用安装包（推荐）
下载 ifuAgent-Setup-2.8.2.exe，双击运行：
- 阅读协议 → 组件选择页：默认选中"ifu Agent 前台模式"（必选）；如需服务模式，勾选"注册为系统服务（可选）"
- 选择安装路径（默认
C:\ifuAgent）→ 安装完成
前台模式安装内容：主程序 + 开机自启（当前用户登录时自动运行）+ 防火墙放行 + 开始菜单快捷方式。
服务模式注意：勾选"注册为系统服务"时，安装完成后会提示：服务模式下键盘/鼠标/剪贴板/屏幕/音量控制不可用（系统服务运行于 Session 0，无交互桌面）。这些功能需在前台模式下使用。
命令行安装服务（可选）
以管理员身份运行：
# 安装服务
C:\ifuAgent\ifuAgent.exe -install
# 启动服务
C:\ifuAgent\ifuAgent.exe -start
# 检查状态
C:\ifuAgent\ifuAgent.exe -status
前台模式手动运行
# 前台运行（无界面）
C:\ifuAgent\ifuAgent.exe -foreground
卸载
控制面板卸载，或运行 C:\ifuAgent\uninstall.exe（会清理服务、防火墙规则、开机自启项）。
Linux 安装
使用 DEB 包（推荐）
sudo dpkg -i ifu-agent_2.8.2_amd64.deb # arm64/armhf 同理
安装完成后默认前台模式：
# 前台模式运行（无界面，支持全部功能）
/opt/ifuAgent/ifuAgent
# 服务模式（仅电源控制可靠）
sudo systemctl enable --now ifuAgent
功能依赖检查：DEB 安装时会自动检查并提示缺失的功能依赖：
| 功能 | 依赖 |
|---|---|
| 音量 | pactl（pulseaudio-utils） |
| 屏幕开关 | xset（x11-xserver-utils，仅 X11） |
| 键盘/鼠标 | /dev/uinput 写权限（root 或 udev 规则） |
| 剪贴板 | xclip/xsel（X11）或 wl-copy（Wayland） |
手动安装（可选）
- 复制二进制并赋予执行权限：
sudo mkdir -p /opt/ifuAgent
sudo cp ifuAgent /opt/ifuAgent/
sudo chmod +x /opt/ifuAgent/ifuAgent
- 前台运行或注册服务（服务文件见包内
/etc/systemd/system/ifuAgent.service）：
sudo systemctl daemon-reload
sudo systemctl enable --now ifuAgent
验证安装
安装完成后，打开浏览器访问：
http://localhost:42000/health
如果返回类似 {"status":"success", ...} 的 JSON 数据，说明服务运行正常。
查询功能能力清单（可查看各功能可用性与缺失原因）：
http://localhost:42000/capabilities
配置手册
ifu Agent 设计为零配置启动，但也提供了丰富的命令行参数来满足特定需求。
默认配置
在不指定任何参数的情况下，程序使用以下默认端口：
| 服务 | 端口 | 说明 |
|---|---|---|
| HTTP | 42000 | 提供 REST API 和 Web 控制台 |
| TCP | 42001 | 提供 TCP Socket 控制接口 |
| UDP | 42002 | 提供设备发现服务 |
命令行参数
通过 ./ifuAgent -help 可以查看所有支持的参数。
运行模式参数：
| 参数 | 说明 |
|---|---|
-foreground |
强制前台模式运行（无界面）。默认无参数运行即为前台模式；已注册为服务后可用此参数强制前台调试运行 |
服务管理参数（主要用于 Windows 平台，Linux 建议使用 systemctl）：
| 参数 | 说明 |
|---|---|
-install |
将程序注册为 Windows 系统服务 |
-uninstall |
从系统中移除服务 |
-start |
启动已注册的系统服务 |
-stop |
停止正在运行的系统服务 |
-status |
查看服务的当前运行状态 |
信息参数：
| 参数 | 说明 |
|---|---|
-version |
显示程序版本、构建日期和 Go 运行环境信息 |
-help |
显示帮助信息和使用说明 |
功能自检
程序启动时自动检测各功能可用性（电源/音量/屏幕/键盘/鼠标/剪贴板）：
- 前台模式：控制台输出"功能自检"清单
- 服务模式：日志中提示交互类功能不可用及原因（Session 0）
也可随时通过 GET /capabilities 查询（返回 JSON 能力清单，含缺失原因）。
日志文件
程序运行过程中会产生日志文件，用于记录操作历史和错误信息。
- Windows：程序所在目录下的
logs\（如C:\ifuAgent\logs\） - Linux：
/var/log/ifuAgent/（root 运行）或当前目录下的logs/
日志文件按日期命名（ifuAgent_YYYY-MM-DD.log），超过 10MB 自动轮转（保留 3 份备份）。
继续阅读
- ifu Agent 通信协议与 API 详解—— 学会用 curl、脚本或自建控制端发送指令。
- ifu Agent 常见问题与排查—— 遇到问题先看这篇。
