高级配置

参数、批量与稳定性相关

1. 批量部署

目标：一次把内核与 14 个官方插件铺到多台终端，并统一配置。

• 打包形态：build.bat（Windows）或 scripts/build_all.sh（CI / Linux）会产出 dist/stage/<目标平台>，其目录结构即安装后布局，可直接被 NSIS / deb 打包脚本复用。
• 静默安装：Windows 安装包基于 NSIS，可配合其静默参数批量下发；Linux 提供 deb 包（含 systemd 单元）。
• 统一配置：把 config.json 作为配置管理项下发，其中至少统一好 listen 端口与认证材料。
• 插件分发：官方插件随安装包内置；第三方插件放入数据目录的 plugins/，或用 plugins.extra_paths[] 指定任意路径。
• 上层收口：终端数量大时，建议上层系统只对接中间层（Agent Server），由中间层负责把命令路由到具体终端，避免逐台维护地址与令牌。

2. 长时间运行（无人值守）

• 自启动：Windows 安装包会把内核注册为系统服务 FoxAgent（启动类型「自动」），随开机自启，不需要用户登录；同时清理旧版写入的当前用户开机启动项，避免与服务抢端口。Linux 当前为前台模式，需自行配合 nohup 或进程管理器守护。
• 无人值守下的交互能力：音量 / 屏幕 / 键鼠 / 剪贴板 / 桌面提示 / 截图属于 user 会话域。内核以服务（Session 0）运行时会把这些插件跨会话创建到当前登录用户的会话中，因此服务态下依然可用；只有在终端无人登录（没有可依附的用户会话）时才不可用，/capabilities 会标注原因。
• 进程守护：内核会守护插件子进程——插件异常退出按 1s / 2s / 4s 退避重启，连续失败达上限后停止并标记 Failed。
• 内存释放：建议对查询终端、自助机配置定时重启（用 power.reboot 命令周期性下发），这也是常见用法。
• 崩溃恢复：Windows 下内核作为服务常驻，异常退出由 SCM 按恢复策略自动重启，无需人工介入；Linux 前台模式下建议由上层监控 /health，失联时重新拉起进程。
• 优雅退出：收到中断信号后，内核会先关闭传输层、再清理插件进程，避免留下孤儿进程。

3. 权限与安全

FoxAgent 没有账号体系，安全由三层凭据承担，按强度从高到低：

• 回环免认证：127.0.0.1 / ::1 默认免认证，但叠加 Origin / Referer / Host 校验；同时高危命令（power.*、screen.*、input.*、clipboard.*、process.kill、timesync.set、notify.toast）即使来自回环也强制认证。内核会把内置默认清单与 config.json 的 auth.high_risk_commands 做并集合并并回写，因此覆盖安装后新增的高危命令自动生效、无需手改配置；可在配置里追加自定义项，但不能靠删配置项缩小保护范围。
• 管理端点例外：/admin/* 与 GET /blob/{id} 无论来源一律要求令牌或证书，不接受回环免认证；/health、/capabilities 为免认证。Web 控制台页面本身为静态资源可直接打开，但页内每个管理请求都要带令牌，故不会因「浏览器能打开页面」而暴露管理能力。
• 拦截链失败方向：命令前钩子（守卫插件）超时、崩溃或返回错误时默认按拒绝处理（fail-closed），避免安全策略静默失效；代价是守卫不可用时全部命令都会被拒。可用配置项 events 调整：
• events.intercept_fail_open（默认 false）：置 true 后守卫失败时放行，用于「可用性优先」的现场。
• events.breaker_failures / events.breaker_cooldown_ms：某守卫连续失败达阈值即熔断，冷却期内不再等待超时，避免单个守卫故障拖垮整条命令链。
• 插件可访问范围：fox.file（文件读取）与 fox.log（日志查看）为只读插件，可访问路径由 plugins.config["fox.file"].roots / plugins.config["fox.log"].paths 白名单限定，白名单为空即拒绝一切访问；fox.log 默认指向内核自身日志目录 <数据目录>/logs，装上即可用。
• 启用 HMAC：fox-agent hmac init 生成密钥并启用；fox-agent hmac status 查看状态；轮换用 fox-agent hmac init --force。默认时间窗 300 秒。声明启用但密钥非法时，内核启动阶段即失败，不会带病运行。
• 启用 mTLS：fox-agent tls init 生成 CA 与控制台客户端证书，再在配置中打开 tls.enabled 与 tls.require_client_cert；fox-agent tls status 查看状态。
• 插件目录权限：内核会校验插件目录权限（Linux 属主 / Windows DACL），防止低权限用户替换插件。

4. 性能与稳定性

5. 离线环境部署

1. 在联网环境执行构建，得到 dist/stage/<目标平台> 或安装包。
2. 把安装包与需要下发的配置（含令牌或 HMAC 密钥、证书）一并拷入现场。
3. 现场离线安装，安装包不会访问公网。
4. 如需启用 TLS / HMAC，离线生成材料后离线分发：fox-agent tls init / fox-agent hmac init 均在本地完成，不需要联网。
5. 升级同样走离线覆盖安装，不依赖在线更新通道。

6. 典型故障排查（现象 → 原因 → 处理）

分享