7.9 KiB
Agent 管理与无界面部署
一个 ads-agent --config 进程管理一台电脑上的多部手机。ads-server 汇总所有 Agent,两套桌面客户端均提供“Agent 管理”:查看主机、选择手机、添加/移除/启用/停用、读取/应用配置、跟随日志、重启受监督 Agent。设备连接工作台继续使用同一组设备 ID。
手机状态“已注册”表示设备转发工作线程已向控制中心注册,并不证明手机当前 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 放在同一目录。通过受限权限的文件或环境变量提供设备端令牌,避免出现在命令行参数中。
.\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 默认没有手机,启动后通过另一个终端添加:
.\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。
配置
{
"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}
]
}
.\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。
.\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 在管理员终端执行:
.\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):
./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 授予管理权限。