feat: [US-004] Add SSH tunnel auto-start for Windows services

- Add ssh-tunnel.ps1: Windows SSH tunnel manager (equivalent to ssh-tunnel.sh)
  - Supports password auth via plink.exe (PuTTY)
  - Supports ssh_hostkey for non-interactive batch mode
  - Commands: start, stop, restart, status

- Add start-backend-service.ps1: NSSM service wrapper
  - Starts SSH tunnels before uvicorn
  - Waits for tunnel ports to be accessible (30s timeout)
  - Configured by Install-ROA2WEB.ps1

- Add start.ps1: Windows equivalent of start.sh
  - Orchestrates SSH tunnel + backend + frontend startup

- Add backend/shared/ssh_tunnel_manager.py: Python monitoring
  - Background asyncio task monitors tunnel health every 30s
  - Auto-restarts tunnels after 2 consecutive failures
  - Exposes status to /health endpoint

- Update ROA2WEB-Console.ps1:
  - Add Deploy-Scripts function
  - Update Update-ServiceToUseVenv to use wrapper script

- Fix PowerShell reserved variable ($PID -> $tunnelPid)
- Fix script path detection (scripts/ vs deployment/windows/scripts/)
- Update README.md with ssh_hostkey documentation

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Claude Agent
2026-01-28 19:04:26 +00:00
parent dc1711acd0
commit 6718c956f7
9 changed files with 1766 additions and 26 deletions

View File

@@ -265,6 +265,76 @@ All endpoints prefixed with `/api`:
---
## SSH Tunnel Configuration
ROA2WEB uses SSH tunnels to connect to Oracle servers. Configuration is in `backend/ssh-tunnels.json`.
### Setup (one-time)
**Linux:**
```bash
# Copy SSH key to secrets folder
cp ~/.ssh/your_key backend/secrets/vending.ssh_key
chmod 600 backend/secrets/vending.ssh_key
# Or use password (requires sshpass)
echo "your_password" > backend/secrets/vending.ssh_pass
sudo apt install sshpass
```
**Windows:**
```powershell
# Option 1: SSH Key (recommended)
ssh-keygen -t rsa -b 4096 -f C:\inetpub\wwwroot\roa2web\backend\secrets\vending.ssh_key -N ""
# Then add public key to remote server's ~/.ssh/authorized_keys
# Option 2: Password (requires PuTTY)
choco install putty -y
echo "your_password" > C:\inetpub\wwwroot\roa2web\backend\secrets\vending.ssh_pass
```
### Configuration File
`backend/ssh-tunnels.json`:
```json
[
{
"id": "vending",
"name": "Vending Master",
"local_port": 1522,
"ssh_host": "79.119.86.134",
"ssh_port": 22122,
"ssh_user": "romfast",
"ssh_hostkey": "SHA256:xxxxx",
"oracle_host": "127.0.0.1",
"oracle_port": 1521
}
]
```
**Important:**
- `local_port` must match the port in `ORACLE_SERVERS` (.env) for this server
- `ssh_hostkey` is **required on Windows** (plink batch mode). Get it with:
```powershell
plink.exe -ssh user@host -P port "exit"
# Accept the key, then copy SHA256 fingerprint from output
```
### Commands
| Platform | Start | Stop | Status |
|----------|-------|------|--------|
| Linux | `./ssh-tunnel.sh start` | `./ssh-tunnel.sh stop` | `./ssh-tunnel.sh status` |
| Windows | `.\scripts\ssh-tunnel.ps1 start` | `.\scripts\ssh-tunnel.ps1 stop` | `.\scripts\ssh-tunnel.ps1 status` |
### Auto-Start (Production)
- **Linux**: `start.sh` automatically starts tunnels before backend
- **Windows Service**: `start-backend-service.ps1` wrapper starts tunnels before uvicorn
- **Auto-Reconnect**: Backend monitors tunnels and restarts them if they drop (every 30s check)
---
## Environment Configuration
Copy `.env.example` to `.env` in each microservice and configure: