mirror of
https://github.com/Finesssee/ProxyPilot.git
synced 2026-11-20 20:34:36 +00:00
- Rename cmd/cliproxytray to cmd/proxypilot-tray - Update all script references - Update workflow and docs
301 lines
9.5 KiB
Markdown
301 lines
9.5 KiB
Markdown
# ProxyPilot CLI + Tray Build Process
|
|
|
|
Documentation of the CLI and system tray application build and release process.
|
|
|
|
## Overview
|
|
|
|
ProxyPilot uses a **CLI + system tray architecture**:
|
|
- **proxypilot.exe** - CLI executable with all proxy functionality
|
|
- **ProxyPilot.exe** - System tray app that manages the CLI process and provides quick access to controls
|
|
|
|
The dashboard is accessed via web browser at `http://127.0.0.1:<port>/proxypilot.html`.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ ProxyPilot System │
|
|
│ │
|
|
│ ┌─────────────────────┐ ┌─────────────────────────────┐ │
|
|
│ │ ProxyPilot.exe │ │ proxypilot.exe │ │
|
|
│ │ (System Tray) │─────▶│ (CLI / Engine) │ │
|
|
│ │ │ │ │ │
|
|
│ │ - Start/Stop │ │ - Proxy Engine (port 8317) │ │
|
|
│ │ - Open Dashboard │ │ - Web Dashboard Server │ │
|
|
│ │ - Copy API URL │ │ - Provider Auth Mgmt │ │
|
|
│ │ - Autostart toggle │ │ - Routing Engine │ │
|
|
│ └─────────────────────┘ └─────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────────┐ │
|
|
│ │ Web Browser │ │
|
|
│ │ (Dashboard UI) │ │
|
|
│ │ proxypilot.html │ │
|
|
│ └─────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### CLI + Tray Separation
|
|
|
|
The architecture separates concerns:
|
|
|
|
**proxypilot.exe (CLI)**:
|
|
- All proxy engine functionality
|
|
- Serves web dashboard at `/proxypilot.html`
|
|
- Can run standalone from command line
|
|
- Supports all CLI flags (`--help`, `--setup-claude`, etc.)
|
|
|
|
**ProxyPilot.exe (Tray)**:
|
|
- Lightweight system tray wrapper
|
|
- Manages CLI process lifecycle (start/stop/restart)
|
|
- Opens dashboard in default browser
|
|
- Provides quick-access menu
|
|
|
|
Benefits of CLI + tray architecture:
|
|
- **Flexibility**: Use CLI directly or via tray app
|
|
- **No WebView2 dependency**: Dashboard runs in any browser
|
|
- **Simpler debugging**: Inspect network/console in browser DevTools
|
|
- **Cross-platform dashboard**: Same web UI works on all platforms
|
|
|
|
## Build Process
|
|
|
|
### Prerequisites
|
|
|
|
```bash
|
|
# Required tools
|
|
go install github.com/josephspurrier/goversioninfo/cmd/goversioninfo@latest
|
|
```
|
|
|
|
Inno Setup 6 must be installed for creating the Windows installer.
|
|
|
|
### Step 1: Build Web UI Assets
|
|
|
|
```bash
|
|
cd webui
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
This generates `webui/dist/` with the dashboard assets that are served by the CLI at `/proxypilot.html`.
|
|
|
|
### Step 2: Create Multi-Resolution Icon
|
|
|
|
The icon must have multiple sizes for proper Windows display (16px to 256px):
|
|
|
|
```python
|
|
from PIL import Image
|
|
|
|
img = Image.open('static/icon.png')
|
|
if img.mode != 'RGBA':
|
|
img = img.convert('RGBA')
|
|
|
|
sizes = [(16,16), (24,24), (32,32), (48,48), (64,64), (128,128), (256,256)]
|
|
img.save('static/icon.ico', format='ICO', sizes=sizes)
|
|
```
|
|
|
|
Copy to tray icon location:
|
|
```bash
|
|
cp static/icon.ico internal/trayicon/icon.ico
|
|
```
|
|
|
|
### Step 3: Generate Windows Resource Files
|
|
|
|
Generate `.syso` files for embedding icons in executables:
|
|
|
|
```bash
|
|
cd cmd/proxypilot-tray
|
|
goversioninfo -icon="../../static/icon.ico"
|
|
```
|
|
|
|
This creates `resource.syso` files that Go automatically includes during build.
|
|
|
|
### Step 4: Build Executables
|
|
|
|
```bash
|
|
# Build CLI executable
|
|
GOOS=windows GOARCH=amd64 go build -ldflags="-s -w" -o dist/proxypilot.exe ./cmd/server
|
|
|
|
# Build tray app (with -H windowsgui to hide console)
|
|
GOOS=windows GOARCH=amd64 go build -ldflags="-s -w -H windowsgui" -o dist/ProxyPilot.exe ./cmd/proxypilot-tray
|
|
```
|
|
|
|
### Step 5: Build Installer
|
|
|
|
```bash
|
|
# Using Inno Setup
|
|
"C:\Users\FSOS\AppData\Local\Programs\Inno Setup 6\ISCC.exe" installer/proxypilot.iss
|
|
```
|
|
|
|
Output: `dist/ProxyPilot-0.1.0-Setup.exe`
|
|
|
|
## Key Files
|
|
|
|
### Version Info Configuration
|
|
|
|
**cmd/proxypilot-tray/versioninfo.json**
|
|
```json
|
|
{
|
|
"FixedFileInfo": {
|
|
"FileVersion": {"Major": 0, "Minor": 1, "Patch": 0, "Build": 0},
|
|
"ProductVersion": {"Major": 0, "Minor": 1, "Patch": 0, "Build": 0}
|
|
},
|
|
"StringFileInfo": {
|
|
"FileDescription": "ProxyPilot System Tray",
|
|
"ProductName": "ProxyPilot",
|
|
"ProductVersion": "0.1.0"
|
|
},
|
|
"IconPath": "../../static/icon.ico"
|
|
}
|
|
```
|
|
|
|
### Tray Process Manager
|
|
|
|
**cmd/proxypilot-tray/engine.go** - Manages the CLI process:
|
|
- Spawns/stops `proxypilot.exe` subprocess
|
|
- Monitors process health
|
|
- Passes configuration and management password
|
|
|
|
### Tray Icon Embedding
|
|
|
|
**internal/trayicon/ico.go**
|
|
```go
|
|
package trayicon
|
|
|
|
import (
|
|
_ "embed"
|
|
)
|
|
|
|
//go:embed icon.ico
|
|
var proxyPilotICO []byte
|
|
|
|
func ProxyPilotICO() []byte {
|
|
return proxyPilotICO
|
|
}
|
|
```
|
|
|
|
### Installer Script
|
|
|
|
**installer/proxypilot.iss** - Inno Setup script that:
|
|
- Installs `proxypilot.exe` and `ProxyPilot.exe` to `%LOCALAPPDATA%\ProxyPilot`
|
|
- Creates Start Menu shortcut
|
|
- Adds optional Windows startup entry
|
|
- Copies config.example.yaml and creates config.yaml on first install
|
|
- Uses ProxyPilot icon for installer and shortcuts
|
|
|
|
## System Tray Menu
|
|
|
|
Simplified flat menu structure:
|
|
|
|
```
|
|
┌─────────────────────┐
|
|
│ Open Dashboard │ → Opens browser to proxypilot.html
|
|
├─────────────────────┤
|
|
│ Start/Stop │ → Toggle proxy engine (CLI process)
|
|
│ Copy API URL │ → Copies http://127.0.0.1:8317/v1
|
|
├─────────────────────┤
|
|
│ Quit │ → Stop engine and exit
|
|
└─────────────────────┘
|
|
```
|
|
|
|
## Release Process
|
|
|
|
### Create Release on GitHub
|
|
|
|
```bash
|
|
# Tag the release
|
|
git tag v0.1.0
|
|
git push origin v0.1.0
|
|
|
|
# Create release with assets
|
|
gh release create v0.1.0 \
|
|
--title "ProxyPilot v0.1.0" \
|
|
--notes "Release notes here" \
|
|
dist/ProxyPilot-0.1.0-Setup.exe \
|
|
dist/ProxyPilot.exe \
|
|
config.example.yaml
|
|
```
|
|
|
|
### Update Existing Release
|
|
|
|
```bash
|
|
# Delete old asset
|
|
gh release delete-asset v0.1.0 ProxyPilot.exe --yes
|
|
|
|
# Upload new asset
|
|
gh release upload v0.1.0 dist/ProxyPilot.exe
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Icon Not Showing in File Explorer
|
|
|
|
1. Ensure icon.ico has 256x256 size (required for Windows)
|
|
2. Clear Windows icon cache: `ie4uinit.exe -show`
|
|
3. Verify resource.syso was generated after icon update
|
|
4. Rebuild the executable
|
|
|
|
### Dashboard Not Loading in Browser
|
|
|
|
1. Ensure the CLI process is running (check tray status)
|
|
2. Verify the port is correct: `http://127.0.0.1:8317/proxypilot.html`
|
|
3. Check for port conflicts with another application
|
|
|
|
### Tray Icon Shows Wrong Image
|
|
|
|
1. Check internal/trayicon/icon.ico is the correct file
|
|
2. Rebuild the tray app to re-embed the icon
|
|
3. Restart the application
|
|
|
|
### Engine Not Starting
|
|
|
|
1. Check if port 8317/8318 are already in use
|
|
2. Review logs in `%LOCALAPPDATA%\ProxyPilot\logs\`
|
|
3. Ensure config.yaml is valid YAML
|
|
|
|
## File Structure
|
|
|
|
```
|
|
ProxyPilot/
|
|
├── cmd/
|
|
│ ├── server/
|
|
│ │ └── main.go # CLI entry point
|
|
│ └── proxypilot-tray/
|
|
│ ├── main_windows.go # Tray app entry point
|
|
│ ├── engine.go # CLI process manager
|
|
│ ├── versioninfo.json # Version/icon config
|
|
│ └── resource.syso # Compiled resources
|
|
├── internal/
|
|
│ └── trayicon/
|
|
│ ├── ico.go # Embeds icon.ico
|
|
│ └── icon.ico # ProxyPilot logo (multi-res)
|
|
├── static/
|
|
│ ├── icon.ico # Source icon (7 sizes)
|
|
│ └── icon.png # Original PNG logo
|
|
├── webui/
|
|
│ ├── src/ # React dashboard source
|
|
│ └── dist/ # Built assets (served by CLI)
|
|
├── installer/
|
|
│ └── proxypilot.iss # Inno Setup script
|
|
└── dist/ # Distribution files
|
|
├── proxypilot.exe # CLI executable
|
|
└── ProxyPilot.exe # Tray app
|
|
```
|
|
|
|
## Version History
|
|
|
|
- **v0.3.0** (2025-12-30) - CLI + Tray architecture
|
|
- Removed WebView2 dependency
|
|
- Dashboard served by CLI, opened in browser
|
|
- Tray app manages CLI subprocess
|
|
- Simplified deployment and debugging
|
|
|
|
- **v0.2.0** (2025-12-27) - Single-binary architecture
|
|
- Embedded proxy engine runs in-process
|
|
- Removed separate proxypilot-engine.exe
|
|
- Reduced total size from ~46MB to ~29MB
|
|
- Faster startup with no process spawning
|
|
|
|
- **v0.1.0** (2025-12-27) - Initial release
|
|
- System tray with minimal menu
|
|
- Multi-resolution icon support
|
|
- Single-file Windows installer
|