210 lines
14 KiB
Markdown
210 lines
14 KiB
Markdown
> 历史记录 / Historical record：ProxyDoctor 是项目旧名。以下旧版本、SHA256、测试数量与路径保留原样，不代表 VPSMaster 新构建已通过；当前范围见 README.md、CURRENT_STATUS.md 和新包同 SHA256 验收报告。
|
||
|
||
See [current status](CURRENT_STATUS.md) for implemented and outstanding work. Family-specific DNS/TCP/TLS checks now back suite/quality; untested.
|
||
|
||
# Current development scope (2026-11-01)
|
||
|
||
This branch develops an independent Python VPS diagnostics CLI. See [backlog](PROBLEM_BACKLOG.md), [architecture](ARCHITECTURE.md), [source research](OPEN_SOURCE_RESEARCH.md), [test plan](TEST_PLAN.md), and [changelog](CHANGELOG.md). The previous 0.5.0 documentation below is historical context.
|
||
|
||
Routine `proxydoctor suite` skips CPU and bandwidth benchmarks. Consent to traffic tests with `proxydoctor bandwidth --allow-bandwidth` or `proxydoctor suite --allow-bandwidth`. The displayed payload budget excludes protocol overhead and other checks. Use `suite --offline` to skip network checks. Third-party executable/script wrappers are temporarily disabled.
|
||
|
||
These changes have not been tested or released. Earlier test results do not validate this branch.
|
||
|
||
---
|
||
|
||
# ProxyDoctor
|
||
|
||
[中文](README.md) | [English](README.en.md)
|
||
|
||
Native Python read-only VPS diagnostics for Ubuntu 22.04 and newer. Python 3.10+;
|
||
no third-party runtime dependencies. Ubuntu 22.04/24.04 are the current acceptance
|
||
targets; other versions need separate testing. No automatic sudo, installation,
|
||
SSH/firewall changes or fetching/executing remote scripts.
|
||
|
||
## Run
|
||
|
||
Extract the source package and run from its directory:
|
||
|
||
```bash
|
||
bash proxydoctor.sh
|
||
bash proxydoctor.sh suite --lang en
|
||
bash proxydoctor.sh suite --offline --lang en
|
||
python3 -m proxydoctor check --lang en --port 8388 --json --output check.json
|
||
```
|
||
|
||
Downloading/cloning does not execute code. The default `suite` contacts external
|
||
services and streams compact colored rows. `check` defaults to local reads.
|
||
Ordinary users can run it; missing privileges remain unknown. Report files stay
|
||
local, do not overwrite existing files and redact IPs. Review before sharing;
|
||
redaction is not an anonymity guarantee. `--show-ip` displays egress IP in the
|
||
terminal only. Routes display actual hop IPs in the terminal; exports mask them.
|
||
|
||
## Four modules
|
||
|
||
| Module | Terminal output | Limits |
|
||
| --- | --- | --- |
|
||
| Resources/preflight | OS, architecture, CPU/model/count, kernel, memory, disk, SHA-256 sample; route/DNS config, target port, SSH guard/config, local/cloud firewall status | Visible resources may differ from quotas; SHA-256 is not a general CPU benchmark; local reads cannot establish cloud ingress |
|
||
| Network/IP | Real DNS/TCP probes; ownership/ASN/location/type, provider flags/scores, coverage and disagreements | AAAA answers do not prove IPv6 connectivity; provider scores are separate observations, not safety certification |
|
||
| Route | Linux IPv4/IPv6 UDP error queue, 30 hops by default, up to 64; IP, latency, estimated location | NAT/filtering or silent routers can prevent completion; geolocation is approximate |
|
||
| Media | Ten independent service adapters, repeat confirmation, catalog/metadata evidence and explicit unknown reasons | No paid account/DRM playback verification; public offers/catalogs do not prove full unlock |
|
||
|
||
Suite JSON schema_version=2 includes local checks, DNS/TCP, per-source bandwidth,
|
||
IP observations/provenance/conflicts, route hops and media probe evidence.
|
||
Green indicates acquired data/local success, red known warnings/restrictions,
|
||
yellow unknown/skipped/insufficient evidence. `--color auto|always|never` and
|
||
`NO_COLOR` are supported. Use `check --json` for detailed local evidence.
|
||
`sshd -T` defaults may differ from running instances/Match rules. Future repair
|
||
features still require separate SSH safeguards.
|
||
|
||
## Bandwidth
|
||
|
||
```bash
|
||
bash proxydoctor.sh bandwidth --lang en
|
||
bash proxydoctor.sh bandwidth --lang en --source ovh-rbx --rounds 3 --sample-mib 4
|
||
bash proxydoctor.sh bandwidth --lang en --source hetzner-fsn --sample-mib 1
|
||
bash proxydoctor.sh suite --lang en --bandwidth-source cloudflare
|
||
```
|
||
|
||
| ID | Source/node label | Download | Upload | Default |
|
||
| --- | --- | --- | --- | --- |
|
||
| cloudflare | Cloudflare / Anycast | Yes | Yes | Yes |
|
||
| ovh-rbx | OVHcloud / FR Roubaix | Yes | No | Yes |
|
||
| hetzner-fsn | Hetzner / DE Falkenstein | Yes | No | No; slow on current test network |
|
||
|
||
Excluded 128 KiB warmup per supported direction; 3–8 measured rounds of 1–20 MiB.
|
||
Default requested benchmark payload is at most 36.375 MiB, excluding protocol
|
||
and other module traffic. Medians/ranges/success counts stay separate per source.
|
||
Short samples (<1s), missing rounds and high variation stay yellow. Wall-time
|
||
HTTPS throughput includes connection setup and cannot verify advertised capacity.
|
||
Static files require exact HTTP 206 ranges; ignored Range responses are closed
|
||
without reading the full body, never falling back to a full-file download.
|
||
Unsupported upload is skipped, not counted as failure. Bandwidth JSON schema=2.
|
||
|
||
## IP sources and keys
|
||
|
||
```bash
|
||
bash proxydoctor.sh ipquality --lang en --show-ip --json-output ip.json
|
||
bash proxydoctor.sh ipquality --lang en --no-enrichment
|
||
bash proxydoctor.sh suite --lang en --no-ip-enrichment
|
||
```
|
||
|
||
Defaults: ipapi.is, proxycheck.io and IP2Location. On an ipapi.is transport failure,
|
||
ipify can provide an egress address. Subsequent sources query that exact address;
|
||
mismatched responses are rejected. These services see the source address and the
|
||
additional sources receive the selected egress IP. Disable extra sources with
|
||
`--no-ip-enrichment` or all suite networking with `--offline`.
|
||
|
||
Seventeen core fields cover ownership/ASN, location/timezone, type/network abuse
|
||
share and datacenter/proxy/VPN/Tor/recent-abuse/mobile/satellite/anycast/bogon flags.
|
||
Per-source observations and field provenance are retained. Conflicting booleans
|
||
become unknown with disagreement evidence. IP2Location's limited free-plan proxy
|
||
flag is kept separate, not converted into a broad VPN guarantee. proxycheck.io
|
||
risk/confidence and AbuseIPDB scores are not averaged. Network abuse share is not
|
||
a single-IP maliciousness probability.
|
||
|
||
Keyless limits currently include 100 queries/day for proxycheck.io and 1000/day
|
||
for IP2Location, subject to provider rules. No automatic quota retries. Anonymous
|
||
ipapi.is has limited fields; optional keys provide extended fields/AbuseIPDB reports.
|
||
Enter locally without echoing; never send keys to chat or commit them:
|
||
|
||
```bash
|
||
read -rsp 'ipapi.is API Key: ' PROXYDOCTOR_IPAPI_KEY
|
||
export PROXYDOCTOR_IPAPI_KEY
|
||
printf '\n'
|
||
read -rsp 'AbuseIPDB API Key: ' PROXYDOCTOR_ABUSEIPDB_KEY
|
||
export PROXYDOCTOR_ABUSEIPDB_KEY
|
||
printf '\n'
|
||
bash proxydoctor.sh ipquality --lang en
|
||
```
|
||
|
||
ipapi.is keys travel in HTTPS POST JSON; AbuseIPDB keys use headers, not URLs or
|
||
reports. Missing fields remain unknown. Complete coverage means defined fields,
|
||
not every database or a security certification. Zero reports do not guarantee
|
||
safety. Observed API egress/family may differ from media connections.
|
||
|
||
## Route and media
|
||
|
||
```bash
|
||
bash proxydoctor.sh suite --lang en --max-hops 64 --route-target 1.1.1.1
|
||
bash proxydoctor.sh suite --lang en --route-target 2606:4700:4700::1111 --no-geo
|
||
bash proxydoctor.sh media --lang en --json-output media.json
|
||
```
|
||
|
||
ipwho.is geolocation is cached per run; private/reserved hops are never queried.
|
||
Media covers Netflix, Disney+, YouTube Premium, Spotify, Prime Video, Max, Apple
|
||
TV+, Hulu, BBC iPlayer and Paramount+. Clear regional messages and visible priced
|
||
offers require repeat agreement. Netflix uses structured catalog metadata; BBC
|
||
also checks public test-channel metadata. No media segments/paid content are
|
||
fetched and signed media URLs are not retained. BBC's channel result is scoped
|
||
to that channel. HTTP 200/403 or catalog/offer visibility never proves playback.
|
||
|
||
## Exit codes
|
||
|
||
`check`: 0=no known warning/failure (unknowns may remain), 1=findings, 2=usage/export
|
||
error. Online suite/bandwidth/ipquality/media: 1 also covers incomplete/unknown/
|
||
variable measurements or unverified playback. Offline 0 means local execution
|
||
completed, not online success. Media intentionally leaves playback untested and
|
||
returns 1. Ctrl+C returns 130 without changing system settings.
|
||
|
||
## Install and contribute
|
||
|
||
Source runs directly. Install the supplied wheel into a local virtual environment:
|
||
|
||
```bash
|
||
python3 -m venv .venv
|
||
.venv/bin/python -m pip install /path/to/proxydoctor-0.5.0-py3-none-any.whl
|
||
.venv/bin/proxydoctor suite --offline --lang en
|
||
```
|
||
|
||
If Ubuntu lacks venv support, install its matching OS component separately;
|
||
ProxyDoctor never installs it automatically. Development: install pytest and run
|
||
`python -m pytest -q`. An Actions workflow is supplied; remote CI is not claimed
|
||
before repository publication. See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
|
||
|
||
## Stage 1 and scope
|
||
|
||
This iteration targets code plus Ubuntu 22.04/24.04 VM acceptance as selected by
|
||
the user; consult the delivered acceptance records for actual results. Overseas
|
||
VPS tests, real-key extended data, paid-account playback and other Ubuntu releases
|
||
remain separately unverified. Later stages cover sing-box installation, Karing
|
||
protocol validation, repair previews/backups/rollback, Web UI and secure subscription
|
||
transport. No public plaintext subscription server or automatic SSH/firewall changes.
|
||
|
||
## License and acknowledgements
|
||
|
||
Original code is MIT. Thanks to ECS, NodeQuality, NetQuality/IPQuality, NextTrace
|
||
and RegionRestrictionCheck for feature/presentation references. No upstream script
|
||
source/databases are bundled by the default implementation. See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
|
||
Explicit local-script adapters are opt-in; external behavior/output may not be
|
||
read-only or redacted.
|
||
|
||
Official data references: [Cloudflare](https://github.com/cloudflare/speedtest),
|
||
[OVHcloud](https://proof.ovh.net/), [Hetzner](https://docs.hetzner.com/storage/object-storage/troubleshooting/bandwidth-latency-issues/),
|
||
[ipapi.is](https://ipapi.is/developers.html), [proxycheck.io](https://proxycheck.io/api/),
|
||
[IP2Location](https://www.ip2location.io/ip2location-documentation), [AbuseIPDB](https://docs.abuseipdb.com/),
|
||
[ipwho.is](https://ipwhois.io/documentation), [ipify](https://www.ipify.org/).
|
||
[Netflix VPN guidance](https://help.netflix.com/en/node/114701) explains catalog restrictions.
|
||
|
||
|
||
## Reliability batch — 2026-11-01 (implemented, untested)
|
||
|
||
`suite` now creates a local redacted JSON report and sibling `.events.jsonl` recovery journal. Without `--json-output`, files are placed under `./reports/` with unique names. Detection does not modify system configuration, but does write these local output files. Linux file creation requests mode 0600; Windows uses inherited ACLs.
|
||
|
||
Each module start/completion and completed DNS/TCP result, route hop, and media service writes a flushed/fsynced snapshot. Module exceptions use `MODULE_ERROR` without storing raw exception text; other modules continue. `success` in `modules` means the module executed, not that a service is unlocked or a server is safe. Overall partial measurement remains incomplete. Ctrl+C records cancellation and returns 130. Previously completed journal records remain useful after a crash; use the Python `proxydoctor.reports.recover_latest(path)` API to read the latest complete snapshot.
|
||
|
||
Existing final/journal files and dangling final symlinks are rejected. Storage errors during checks produce a terminal warning, keep prior records, and return a nonzero result. The final JSON is exclusively created; a failed final write can leave a partial final file, so recover from the journal. No absolute durability guarantee applies to disk/controller failure. Storage paths must be in user-controlled directories; parent-directory symlink attacks are outside this first implementation.
|
||
|
||
Limits: module-level isolation does not isolate every individual local system check. Bandwidth and IP collection currently checkpoint on module completion; interruption can lose the current module's unfinished results. Media cancellation may wait for in-flight bounded network calls when the thread pool exits. SIGKILL/power loss cannot trigger cleanup; the journal contains only the last complete checkpoint. Standalone commands retain their existing save behavior. These changes and the new fault-injection tests have not been run yet.
|
||
|
||
## Resource observations (unverified)
|
||
|
||
`suite` and `check` now include visible CPU quotas, process affinity, visible memory bounds, swap, PSI and short-sample CPU steal. Numeric results are preserved separately from terminal language. The default 0.2-second passive observation does not benchmark the CPU or change cgroup settings. Missing data remains unknown. Visible limits do not establish dedicated capacity; namespace/host scope and long-term contention require separate verification. New tests have not been run.
|
||
|
||
Basic security now inspects fixed-path ownership/mode metadata and optional local update-cache age/counts. Password-file contents are not read. Review findings manually; cached counts do not establish patch status. Untested.
|
||
|
||
## Local report export and IP overview
|
||
|
||
Use `proxydoctor report --input report.json --output report.md` to export a local snapshot; `proxydoctor recover --journal report.json.events.jsonl --output recovered.json` recovers the last complete record. Add `--format markdown --lang en` for English Markdown recovery. Files are never overwritten. Inspect exports before sharing.
|
||
|
||
`proxydoctor ipquality --mail-probes` opts into bounded PTR/forward consistency and one outbound TCP/25 target without sending mail. The overview panel precedes provider evidence. DNSBL and IP maps are not yet integrated; see IPQUALITY_COVERAGE.md. Final code passed 239 tests on each Ubuntu VM.
|