Files
AndroidDeviceStreaming/deploy/windows/README.md
T

79 lines
5.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.
# Windows device gateway deployment
These scripts install the Rust gateway as a background Scheduled Task. This is not a native Windows Service binary. They require an administrator account to register the startup trigger, and prefer PowerShell 7 when installed.
## Installation
Default private directory: `%LOCALAPPDATA%\AndroidDeviceStreaming\agent`.
1. Run `prepare-agent.ps1` on the target computer. It creates the directory and grants access only to the current account, SYSTEM and Administrators.
2. Copy the following staged files into that directory:
| Source | Staged name |
|---|---|
| `bin/ads-agent.exe` | `ads-agent.exe.new` |
| `run-agent.ps1` | `run-agent.ps1.new` |
| Your edited `agent.example.json` | `agent.json.new` |
| Private agent-role environment file | `agent.env.new` |
| `install-agent.ps1` | `install-agent.ps1` |
3. Run `install-agent.ps1` from that directory. Supply the current Windows account credential at the secure prompt. For an encrypted remote-management channel, `-PasswordFromStdin` reads the password from standard input rather than the command line. Do not put passwords into scripts.
The installer backs up existing gateway files inside the protected directory, replaces only its own files, and refuses to overwrite an unrelated task with the same name. Its installation path is checked before any process stop or file replacement.
Task `ADS-Agent` uses password logon so it can run without an interactive desktop session. Windows Task Scheduler stores the account credential; it is not stored in the gateway JSON, environment file or source repository. Re-register the task if the Windows account password changes.
Configured behavior:
- Startup and account-logon triggers; duplicate instances ignored.
- Hidden, non-interactive PowerShell runner, with the Rust child in its process tree.
- No execution time limit; restart on process failure after one minute, up to 999 retries.
- Rust itself reconnects to the relay with a 1–30 second backoff.
- `agent.json` configures relay URL, public origin override, device alias and phone endpoint.
- `agent.env` contains only the gateway role credential and optional non-sensitive connection settings.
- Log: `logs/agent.log`; rotated on runner start when it exceeds 10 MiB.
## Deployed computer
Installed on `192.168.5.222` as account `TT`:
```text
C:\Users\TT\AppData\Local\AndroidDeviceStreaming\agent
```
Device: `home-phone`; target: `192.168.100.141:5555`; relay: `wss://ttstd.com/ads`; public origin: `175.178.213.60:443` with normal domain TLS validation.
Task registration, task restart, executable hash and post-restart public ADB smoke test were verified. Startup triggers were inspected; the computer was not rebooted. The Rust process working set was about 8.7 MiB at the sampled instant, excluding the PowerShell runner.
Management commands on that computer:
```powershell
Get-ScheduledTask -TaskName ADS-Agent
Get-ScheduledTaskInfo -TaskName ADS-Agent
Get-Content "$env:LOCALAPPDATA\AndroidDeviceStreaming\agent\logs\agent.log" -Tail 30
Start-ScheduledTask -TaskName ADS-Agent
Stop-ScheduledTask -TaskName ADS-Agent
```
## Managed multi-phone Agent (0.2)
The deployed computer has migrated to Agent ID `home-pc` (家里电脑), retaining `home-phone` and its TCP endpoint. `ADS-Agent-home-pc` runs the native supervised Agent as SYSTEM at startup; the old `ADS-Agent` task is disabled. The migration keeps a timestamped backup under the protected Agent directory and restores the legacy files/task on failure. No reboot was performed.
`migrate-managed.ps1` migrates the earlier TCP single-phone installation. Stage the new binaries as `ads-agent.exe.new` and `adsctl.exe.new` in its directory, then run the script in an elevated PowerShell 7 terminal. It verifies the legacy task belongs to that directory before stopping it. Parameters customize directory, Agent ID, display name and old task name. New installations should use `adsctl init` and `adsctl service install` instead.
For current status and logs, use:
```powershell
& "$env:LOCALAPPDATA/AndroidDeviceStreaming/agent/adsctl.exe" status
& "$env:LOCALAPPDATA/AndroidDeviceStreaming/agent/adsctl.exe" logs --follow
Get-ScheduledTask -TaskName ADS-Agent-home-pc
```
The managed log buffer is in memory; the old runner log is historical. See [Agent management](../../docs/agent-management.md) for Linux and Windows headless setup, CLI commands, role credentials and both GUIs.
## Desktop installers
Run `scripts/build-installers.ps1` from the repository root to build separate Avalonia and Flutter Windows x64 installers. Requires Inno Setup 6/7 (`-Compiler` selects ISCC.exe). Build Rust binaries first with `scripts/build.ps1`; `-SkipBuild` packages existing release folders. `-Edition Avalonia` or `Flutter` selects one client. Outputs and SHA-256 sidecars are in `bin/installers/`.
Installers use per-user installation, Start menu entries, optional desktop shortcuts, and Windows uninstall registration. Editions have separate install identities and can coexist; installing the same edition upgrades it in place. Close the client and stop any Agent hosted from its installation folder before upgrading. Credentials, local settings and device configuration are excluded; import credentials after installation. Uninstall retains settings in user data and does not remove separately installed Agent tasks or USB drivers. USB driver installation remains an explicit optional step. Setup executables are currently unsigned; distribution signing requires the publisher certificate.