Files
AndroidDeviceStreaming/docs/agent-management.md
T

119 lines
7.5 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。
手机状态“已注册”表示设备转发工作线程已向控制中心注册,并不证明手机当前 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 后端。