160 lines
13 KiB
Markdown
160 lines
13 KiB
Markdown
# 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。建议先更新实际守护程序,再从桌面端开启。
|