v2ray-deploy-local-client-guard

name: v2ray-deploy-local-client-guard description: > Project-local deployment guard for v2ray client + v2ray_deploy local mode. Enforces explicit mode selection, outbound proxy listen check, and Telegram connectivity acceptance criteria.

Goal

When deploying on a target host, ensure all of the following are true:

v2ray_deploy runs in local mode: --local True.
Subscription service bind/port are explicit (PROXY_MGT_BIND / PROXY_MGT_PORT).
Public proxy port is exposed on 0.0.0.0 (default expected: 18080).
Hard acceptance command succeeds:
- curl -I --max-time 15 -x http://127.0.0.1:8080 https://api.telegram.org/

Mandatory Safety Rules

Always state mode explicitly before service changes:
- local mode: --local True
- remote mode: no --local True (high risk)
Default to local mode only.
If user requests v2ray-bench-autoswitch.timer or v2ray-bench-apply, warn that this may restart v2ray.service and cause short interruption; require confirmation.

Execution Checklist (Host-Scoped)

Confirm target host exists and is reachable via Ansible.
Before deploying bench/timers, ask target host bandwidth (especially uplink/downlink cap) and confirm speed-test profile.
- Default profile: --bytes 2000000 --timeout 20
- If bandwidth is very low or shared with production traffic, reduce --bytes further or limit --max-nodes.
Precheck v2ray installation:
- verify /usr/local/bin/v2ray exists and systemctl status v2ray is available.
- if missing, stop here and explicitly ask user to install v2ray first.
Sync latest project code to target host.
Ensure /etc/proxy_mgt.env contains:
- PROXY_MGT_BIND=0.0.0.0 (or user-specified)
- PROXY_MGT_PORT=5000 (or user-specified)
Restart and verify v2ray-deploy-local.service.
Verify /local-fast-ip from localhost and public IP.
Verify v2ray inbound listeners:
- local http proxy: 127.0.0.1:8080
- public http proxy: 0.0.0.0:18080 (or user-specified)
Run hard acceptance command:
- curl -I --max-time 15 -x http://127.0.0.1:8080 https://api.telegram.org/
Report pass/fail with exact command evidence.
If proxy ports are changed, sync shell proxy env in /root/.bashrc:

update http_proxy/https_proxy/HTTP_PROXY/HTTPS_PROXY to the new HTTP port
update all_proxy/ALL_PROXY to the new SOCKS port
if no permission to read/write /root/.bashrc, stop immediately and notify user

Verify v2ray-bench binaries include:

v2ray-bench-nodes
v2ray-bench-apply
v2ray-bench-autoswitch
v2ray-bench-show

If v2ray-bench-show is missing but repository has subprojects/v2ray-bench/bin/v2ray-bench-show, install it explicitly to /usr/local/bin/v2ray-bench-show with executable permission.

Recommended Verification Commands

test -x /usr/local/bin/v2ray || echo "MISSING: /usr/local/bin/v2ray"
systemctl status v2ray --no-pager -n 5
systemctl is-active v2ray-deploy-local.service
systemctl is-active v2ray
ss -lntp | egrep ':5000 |:8080 |:18080 '
curl -sS --max-time 20 http://127.0.0.1:5000/local-fast-ip | head -n 3
curl -I --max-time 15 -x http://127.0.0.1:8080 https://api.telegram.org/
test -r /root/.bashrc -a -w /root/.bashrc || echo "NO_PERMISSION:/root/.bashrc"
ls -l /usr/local/bin/v2ray-bench-nodes /usr/local/bin/v2ray-bench-apply /usr/local/bin/v2ray-bench-autoswitch /usr/local/bin/v2ray-bench-show

Troubleshooting Notes

If local endpoint is OK but public endpoint fails, verify current host public IP (avoid DNS/NAT/stale-IP confusion).
If :8080 cannot be exposed on 0.0.0.0, check port conflicts (common with Docker).
Keep 127.0.0.1:8080 as the canonical health-check path even when public proxy uses a different port (e.g. 18080).
Current scripts/install.sh may omit v2ray-bench-show in some revisions; treat /usr/local/bin/v2ray-bench-show as a required post-install check.
If v2ray is not installed on target host, do not continue deployment validation; notify user first, then continue only after installation is completed.
If /root/.bashrc update is required but permission is missing, do not bypass with alternative files; stop and ask user to grant permission or handle manually.