Files
AndroidDeviceStreaming/docs/agent-management.md
T

160 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Agent 管理与无界面部署
一个 `ads-agent --config` 进程管理一台电脑上的多部手机。`ads-server` 汇总所有 Agent,两套桌面客户端均提供“Agent 管理”:查看主机、选择手机、添加/移除/启用/停用、读取/应用配置、跟随日志、重启受监督 Agent。设备连接工作台继续使用同一组设备 ID。
手机状态“已注册”表示设备转发工作线程已向控制中心注册。0.2.6 起,使用 `adb_serial` 的设备必须出现在对应 ADB server 列表且状态为 `device` 才会注册;设备离线时显示具体原因。注册状态不保证手机上的 TCP ADB 端口或后续命令一定可用。
## 角色与连接
- Agent 使用 `ADS_AGENT_TOKEN`;普通连接客户端使用 `ADS_CLIENT_TOKEN`。
- 远程管理使用独立的 `ADS_ADMIN_TOKEN`,至少 32 字符,且不得与上述令牌相同。控制中心未配置该变量时,管理接口关闭。
- 私有凭据文件 `agent.env`/`admin.env` 不提交 Git、不打入发行包。GUI 仅在内存中保留导入的令牌。
- Agent 主动连接控制中心,无需开放电脑入站管理端口。远程管理经过已校验证书的 HTTPS/WSS;数据链路仍按原有 P2P 优先及中继回退运行。
- 本机管理使用配置路径对应的私有 Windows 命名管道或 Unix socket,无需管理员令牌。Windows 仅允许配置目录所有者和 SYSTEM;Unix socket 权限 0600。配置目录不能允许其他用户写入。
已部署控制中心地址为 `wss://ttstd.com/ads`,源站覆盖为 `175.178.213.60:443`;覆盖 TCP 地址仍按 ttstd.com 验证 TLS。自行部署时替换这些值。
## 首次初始化
将 `ads-agent` 和 `adsctl` 放在同一目录。通过受限权限的文件或环境变量提供设备端令牌,避免出现在命令行参数中。
```powershell
.\adsctl.exe --config C:\ADS\agent.json --credentials C:\private\agent.env --server wss://ttstd.com/ads --connect-address 175.178.213.60:443 init --id office-pc --name 办公室
.\ads-agent.exe --quiet --supervise --config C:\ADS\agent.json
```
初始化会生成非敏感的 `agent.json` 及同目录的私有 `agent.env`,已有配置不会覆盖。`init` 默认没有手机,启动后通过另一个终端添加:
```powershell
.\adsctl.exe --config C:\ADS\agent.json status
.\adsctl.exe --config C:\ADS\agent.json devices add --id phone-one --target 192.168.100.141:5555
.\adsctl.exe --config C:\ADS\agent.json devices add --id phone-two --adb-serial USB_SERIAL
.\adsctl.exe --config C:\ADS\agent.json devices list
.\adsctl.exe --config C:\ADS\agent.json devices disable phone-one
.\adsctl.exe --config C:\ADS\agent.json devices enable phone-one
.\adsctl.exe --config C:\ADS\agent.json devices remove phone-two
.\adsctl.exe --config C:\ADS\agent.json logs --follow
.\adsctl.exe --config C:\ADS\agent.json restart
```
`--target` 直接接手机 adbd TCP;`--adb-serial` 通过 Agent 主机已有 ADB server 接 USB 或网络设备,可加 `--adb-server host:5037`。设备 ID 在控制中心全局唯一;同一物理手机请使用一个 ID。
省略配置路径时,Windows 默认 `%LOCALAPPDATA%/AndroidDeviceStreaming/agent/agent.json`,Unix 默认 `$XDG_CONFIG_HOME/ads/agent.json` 或 `~/.config/ads/agent.json`。
## 配置
```json
{
"version": 1,
"id": "office-pc",
"name": "办公室",
"server": "wss://ttstd.com/ads",
"connect_address": "175.178.213.60:443",
"adb_server": "127.0.0.1:5037",
"devices": [
{"id": "phone-one", "target": "192.168.100.141:5555", "enabled": true}
]
}
```
```powershell
.\adsctl.exe --config C:\ADS\agent.json config get
.\adsctl.exe config validate --file edited.json
.\adsctl.exe --config C:\ADS\agent.json config set --file edited.json
```
Agent ID 不能运行中修改。合法配置先原子持久化,再应用;只重建发生变化的手机工作线程,其余活动连接保留。修改全局服务器或 ADB 地址会重建相关连接。手机最多 128 部。令牌放在独立私有文件中,替换令牌后重启 Agent。
## 远程 CLI
`admin.env` 包含 `ADS_ADMIN_TOKEN=...`,可另加 `ADS_CONNECT_ADDRESS=175.178.213.60:443`。
```powershell
.\adsctl.exe --credentials C:\private\admin.env agents list
.\adsctl.exe --credentials C:\private\admin.env --agent office-pc status
.\adsctl.exe --credentials C:\private\admin.env --agent office-pc devices list
.\adsctl.exe --credentials C:\private\admin.env --agent office-pc logs --follow
.\adsctl.exe --credentials C:\private\admin.env --agent office-pc restart
```
同样的 devices/config 子命令可加 `--agent` 远程执行。`--json` 输出机器可读结果,失败返回非零退出码;`request` 从 stdin 读取一条结构化 JSON 请求,供 GUI 调用。没有远程任意 shell 执行接口。
## 无 GUI 自动启动
Windows 在管理员终端执行:
```powershell
.\adsctl.exe --config C:\ADS\agent.json service install
.\adsctl.exe --config C:\ADS\agent.json service status
.\adsctl.exe --config C:\ADS\agent.json service restart
.\adsctl.exe --config C:\ADS\agent.json service uninstall
```
创建名为 `ADS-Agent-office-pc` 的 SYSTEM 开机计划任务。如果已手动启动 Agent,安装只配置自动启动,保留当前进程;下次开机由任务接管,避免重复守护进程。配置文件和目录须允许 SYSTEM 访问;ADB server 进程也须在开机后启动(使用 `--adb-serial` 时)。不依赖用户登录或托盘程序。
Linux 使用相同二进制和命令(去掉 `.exe`):
```sh
./adsctl --config "$HOME/.config/ads/agent.json" service install
./adsctl --config "$HOME/.config/ads/agent.json" service status
# 用户服务无登录运行时,按系统策略启用 loginctl enable-linger USER
# 或在管理员终端安装系统级 unit;配置目录应属于实际 Agent 用户
sudo ./adsctl --config /home/agent/.config/ads/agent.json service install --system
```
已运行 Agent 时,安装保留当前进程,只启用下次自动启动。用户模式使用 systemd --user,系统模式写入 /etc/systemd/system 并按配置目录所有者身份运行。支持 start/stop/restart/status/uninstall;已有同名但不属于本配置的任务/unit 会被拒绝覆盖。macOS 可手动监督运行,当前没有原生 launchd 安装命令。
`--supervise` 保持子进程存活并处理管理重启。Windows Job Object/Linux 父进程死亡信号确保监督进程被结束时回收子进程。日志为进程内最近 500 条、每条最多 1024 字符;Agent 重启后日志清空,CLI 和 UI 会重置游标。需要长期日志时另用系统日志设施。
## 两套 UI 与托盘
- Avalonia 和 Flutter:进入“Agent 管理”,导入 admin.env,刷新并选择目标 Agent。管理本机时切换“管理本机 Agent”,指定配置路径,无需 admin.env。
- 本机初始化导入 agent.env 后初始化,再启动后台 Agent 或安装开机服务。配置编辑器中的手机列表在后台启动后点击“保存并应用配置”保存;首次 init 只建立主机配置。
- Avalonia `Ads.Desktop.exe --agent-tray` 提供只面向本机 Agent 的管理窗口和托盘。`scripts/start-agent-tray.ps1` 为快捷入口。
- 关闭管理 UI 不会停止已托管的 Agent。手机投屏和 ADB 连接仍在设备工作台操作。
## 协议与限制
v3 增加 `/agents/register`(Agent WSS)、`/agents`(管理员 HTTP/WSS 列表)、`/rpc?agent=ID`(管理员 HTTP POST/WSS 请求)。均在 `/v3` 下,支持部署路径前缀。关联请求有超时与数量限制;服务端保留有限的离线主机快照,重启控制中心后重新注册。此版本不提供远程二进制升级、用户账号管理、任意命令执行或跨平台 USB 后端。
Windows 排障:本机管理返回拒绝访问时,检查配置目录所有者是否为实际使用管理客户端的用户。管理员权限创建目录可能将所有者设为 Administrators,普通 UAC 桌面进程不能使用这个组访问私有管道。保留原 ACL,将专属配置目录所有者调整为实际用户,再重启 Agent 重建管道。不要向 Everyone 授予管理权限。
设备发现:两套客户端点击“发现 ADB 设备”,查询所选 Agent 主机的 ADB server,显示已添加、未添加、未授权/离线状态。选择在线且未添加的条目会填入添加表单,确认后添加;不自动暴露所有新插入的手机。CLI 使用 `adsctl devices discover`,远程可加 `--agent ID`。须先启动该主机的 ADB server;SYSTEM Agent 也通过配置的 TCP ADB server 地址查询。此能力需要控制中心与 Agent 更新到支持 devices_discover 的版本。
Linux 本机 Agent 初始没有配置时,先导入 agent.env 并初始化,再启动。桌面现在支持直接安装用户级 systemd 服务;无登录运行需管理员启用该用户 linger。新建私有配置目录使用 0700,以避免 Ubuntu 常见 umask 0002 创建组可写目录而被拒绝。已有目录不自动放宽权限。
## 持续监听设备上下线(0.2.6)
Agent 对已配置且启用的 `adb_serial` 持续检查 ADB 列表,同一个 ADB server 共享一次查询。每次查询结束后等待 2 秒,连接及响应查询有 5 秒超时;正常情况下约 2 秒发现变化,ADB 无响应时还需等待查询超时。
- 设备消失、`offline`、`unauthorized` 或 ADB server 不可达:撤销该手机的控制中心注册,关闭旧数据流及租约;Agent 管理连接继续保留,显示未就绪原因。
- 手机重新在线并授权后:使用原设备 ID 自动注册,本地连接客户端可重新获取租约;不重启 Agent、不改写配置,不中断其他在线手机。
- 手动停用的设备保持停用。默认仍需通过“发现 ADB 设备”或 CLI 添加新手机;0.2.7 可按 Agent 开启下述真实 USB 自动注册。
- 使用 `target` 直连手机的配置不依赖本机 ADB 列表,注册前及每 5 秒检测 TCP 连接,单次检测超时 3 秒。TCP 可达仅表示端口可连接,不代表所有 ADB 命令必定成功。
工作台可能保留已建立的本地连接行,便于手机恢复后重连;该行会明确显示远端离线,不再沿用旧的 ADB 就绪提示。若 Agent 状态仍显示旧版本,请更新实际运行的守护程序,仅更新桌面 UI 不会替换已启动的 Agent。
## 可选真实 USB 自动注册(0.2.7)
默认关闭,每台 Agent 单独设置。两套桌面客户端的 Agent 管理提供“开启 USB 自动注册”“关闭 USB 自动注册”和“取消所选 USB 设备的忽略”。先选择目标 Agent,再操作;读取配置可查看当前开关、忽略列表及 ID 映射。关闭只停止自动添加,已配置的手机继续按原有方式工作。
无界面主机可使用 CLI(远程管理加 `--agent ID` 及管理员凭据):
```sh
adsctl devices auto-usb on
adsctl devices auto-usb off
adsctl devices unignore USB_SERIAL
adsctl config get
```
对应 agent.json 字段:`auto_register_usb`(缺省 false)、`ignored_usb_serials`(删除后不再自动加入的序列号)与 `usb_device_ids`(序列号到稳定设备 ID 的映射)。保存和自动添加均经过校验及原子持久化;退出/重启保留这些记录。开启后约每 5 秒扫描一次物理 USB,并与 ADB 在线列表交叉确认;Windows 本机设备查询有 15 秒超时,查询失败只跳过本轮,不影响管理连接和已配置设备。
- 只处理 Agent 主机回环地址 ADB server 中状态为 `device` 的已授权手机。默认 127.0.0.1:5037,外部 ADB server 不自动注册。
- Windows 通过 PnP 父设备链确认 USB 设备位于 PCI 物理控制器下;Linux 检查 sysfs 的 PCI USB 设备并排除 vhci。模拟器、网络 ADB、ADS 虚拟 USB 与无法确认物理来源的设备均不自动添加。Windows/Linux 的特殊非 PCI 控制器也会跳过,可手动添加;macOS 此开关尚未支持物理设备检测。
- 新 ID 使用 Agent ID 与 USB 序列号的稳定散列并保存映射;拔插/重启不会换 ID。已手动添加的同序列号设备不会再添加一条,也不会覆盖其 ID 或停用状态。
- 删除手机会保存忽略记录;停用保留设备条目和 enabled=false,两者均不会被扫描自动恢复。恢复忽略可用上述 CLI,或在“发现 ADB 设备”中选择手机再取消忽略;手动重新添加也会取消对应忽略。
- 手机必须有可识别的 USB 序列号。序列号变化视为新设备;设备条目最多 128 个,历史映射与忽略列表各最多 512 条,并受配置文件 64 KiB 上限约束。
- 自动注册不会执行 `adb tcpip`,也不改变现有 ADB 数据通道实现。若手机已在线但转发提示无法访问 adbd,请按原有部署要求准备手机调试端口;注册不代表所有后续命令一定成功。
操作复用现有 config_get/config_set,控制中心无需新增管理协议;Agent 本身必须更新到 0.2.7。建议先更新实际守护程序,再从桌面端开启。