From 6637a0d5159603d1469b4425f0ed4f21dcdd4808 Mon Sep 17 00:00:00 2001 From: griffinmx <104078533+griffinmx@users.noreply.github.com> Date: Sun, 1 Nov 2026 23:49:40 -0800 Subject: [PATCH] Organize Beta.1 documentation and polish the security roadmap Reviewed source snapshot: 6f61f862391424d7175263c87e76380218513617 Default compact display and repository layout from the prior accepted local baseline are included. --- .github/CONTRIBUTING.md | 3 + .github/ISSUE_TEMPLATE/bug_report.md | 2 +- .github/SECURITY.md | 3 + CURRENT_STATUS.md | 6 - DEVELOPMENT_BRIEF.zh.md | 413 ------------------ MANIFEST.sha256.json | 74 ++-- PROBLEM_BACKLOG.md | 274 ------------ README.en.md | 150 +++---- README.md | 203 +++------ SECURITY_ROADMAP.md | 44 -- THIRD_PARTY_NOTICES.md | 6 +- USER_CHECKLIST_STATUS.md | 104 ----- docs/GITHUB_ABOUT.md | 10 - docs/README.md | 9 + .../archive/ALPHA_RELEASE_REPORT.md | 4 +- .../archive/ALPHA_TASK_STATUS.md | 4 +- .../archive/ARCHITECTURE-alpha.md | 1 + .../archive/OPEN_SOURCE_RESEARCH.md | 2 +- .../archive/PUBLIC_BETA_CHANGE_REPORT.md | 2 +- docs/archive/README.md | 7 + .../archive/TEST_PLAN-alpha.md | 2 +- .../history-beta-before-p0-20261101.md | 4 +- docs/{ => archive}/pre-alpha-README.en.md | 12 +- docs/{ => archive}/pre-alpha-README.md | 14 +- .../status-history-before-2026-11-01.md | 3 +- docs/development/ARCHITECTURE.md | 15 + docs/{ => development}/CI.md | 0 .../development/CONTRIBUTING.md | 0 .../development/REFERENCES.md | 2 +- docs/development/TESTING.md | 22 + docs/{ => guide}/DATA_SERVICES.md | 0 docs/guide/INSTALL.md | 42 ++ .../guide/IPQUALITY_COVERAGE.md | 2 +- docs/guide/USAGE.md | 51 +++ CHANGELOG.md => docs/release/CHANGELOG.md | 8 +- .../release/KNOWN_LIMITATIONS.md | 2 +- .../release/RELEASE_NOTES.md | 6 +- docs/security/ROADMAP.md | 45 ++ SECURITY.md => docs/security/SECURITY.md | 0 proxydoctor/cli.py | 3 +- proxydoctor/console.py | 9 +- proxydoctor/suite.py | 10 +- tests/test_compact_display.py | 40 ++ tests/test_phase1_delivery.py | 2 +- tests/test_suite.py | 2 +- 45 files changed, 438 insertions(+), 1179 deletions(-) create mode 100644 .github/CONTRIBUTING.md create mode 100644 .github/SECURITY.md delete mode 100644 CURRENT_STATUS.md delete mode 100644 DEVELOPMENT_BRIEF.zh.md delete mode 100644 PROBLEM_BACKLOG.md delete mode 100644 SECURITY_ROADMAP.md delete mode 100644 USER_CHECKLIST_STATUS.md delete mode 100644 docs/GITHUB_ABOUT.md create mode 100644 docs/README.md rename ALPHA_RELEASE_REPORT.md => docs/archive/ALPHA_RELEASE_REPORT.md (91%) rename ALPHA_TASK_STATUS.md => docs/archive/ALPHA_TASK_STATUS.md (86%) rename ARCHITECTURE.md => docs/archive/ARCHITECTURE-alpha.md (98%) rename OPEN_SOURCE_RESEARCH.md => docs/archive/OPEN_SOURCE_RESEARCH.md (94%) rename PUBLIC_BETA_CHANGE_REPORT.md => docs/archive/PUBLIC_BETA_CHANGE_REPORT.md (93%) create mode 100644 docs/archive/README.md rename TEST_PLAN.md => docs/archive/TEST_PLAN-alpha.md (98%) rename docs/{ => archive}/history-beta-before-p0-20261101.md (78%) rename docs/{ => archive}/pre-alpha-README.en.md (94%) rename docs/{ => archive}/pre-alpha-README.md (91%) rename docs/{ => archive}/status-history-before-2026-11-01.md (96%) create mode 100644 docs/development/ARCHITECTURE.md rename docs/{ => development}/CI.md (100%) rename CONTRIBUTING.md => docs/development/CONTRIBUTING.md (100%) rename OPEN_SOURCE_REFERENCES.md => docs/development/REFERENCES.md (93%) create mode 100644 docs/development/TESTING.md rename docs/{ => guide}/DATA_SERVICES.md (100%) create mode 100644 docs/guide/INSTALL.md rename IPQUALITY_COVERAGE.md => docs/guide/IPQUALITY_COVERAGE.md (90%) create mode 100644 docs/guide/USAGE.md rename CHANGELOG.md => docs/release/CHANGELOG.md (96%) rename KNOWN_LIMITATIONS.md => docs/release/KNOWN_LIMITATIONS.md (95%) rename RELEASE_NOTES.md => docs/release/RELEASE_NOTES.md (81%) create mode 100644 docs/security/ROADMAP.md rename SECURITY.md => docs/security/SECURITY.md (100%) create mode 100644 tests/test_compact_display.py diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..c5aaaeb --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,3 @@ +# Contributing + +See the [contribution guide](../docs/development/CONTRIBUTING.md) and [development tests](../docs/development/TESTING.md). Keep diagnostics read-only; do not submit secrets or raw private reports. diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index a0832d4..52a26e0 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -16,4 +16,4 @@ labels: bug ## Steps and redacted evidence / 复现步骤与脱敏证据 Do not attach passwords, keys, subscriptions, raw journals or full system inventories. -Unknown/provider-limited results are not automatically bugs. For sensitive vulnerabilities use the private route in SECURITY.md. +Unknown/provider-limited results are not automatically bugs. For sensitive vulnerabilities use the private route in [the security policy](../SECURITY.md). diff --git a/.github/SECURITY.md b/.github/SECURITY.md new file mode 100644 index 0000000..38bebf6 --- /dev/null +++ b/.github/SECURITY.md @@ -0,0 +1,3 @@ +# Security policy + +Read the [security and privacy policy](../docs/security/SECURITY.md). Do not put credentials or raw reports in public Issues. Use private vulnerability reporting if enabled; otherwise request a private contact first. diff --git a/CURRENT_STATUS.md b/CURRENT_STATUS.md deleted file mode 100644 index 4d320c6..0000000 --- a/CURRENT_STATUS.md +++ /dev/null @@ -1,6 +0,0 @@ -# VPSMaster · Private Beta上线准备 - -基线01b325d / 032d6f3eec70484f49ae938d76b6386ec317c8a20a2cc206c9756ea0d25c6a94原样保留。 -本轮独立分支更新安全加固定位、五阶段Planned路线和私有CI/发行准备。未开发新的加固/自动修复/Web UI。 -文档和CI属于包内变化，因此新候选须重新构建、完整回归及最终ZIP实机验收。实际SHA与GitHub CI结果见包外PRIVATE_GITHUB_ACCEPTANCE_REPORT.md，不能沿用基线通过。 -仓库必须Private，发行必须草稿/Pre-release，未获公开授权。媒体/三网/ICMP-TCP/BGP/IP数据及未验证系统边界仍按README和KNOWN_LIMITATIONS解释。 diff --git a/DEVELOPMENT_BRIEF.zh.md b/DEVELOPMENT_BRIEF.zh.md deleted file mode 100644 index 35cd04c..0000000 --- a/DEVELOPMENT_BRIEF.zh.md +++ /dev/null @@ -1,413 +0,0 @@ -> 历史记录 / Historical record：ProxyDoctor 是项目旧名。以下旧版本、SHA256、测试数量与路径保留原样，不代表 VPSMaster 新构建已通过；当前范围见 README.md、CURRENT_STATUS.md 和新包同 SHA256 验收报告。 - -# VPS 综合检测工具——完整开发与工程优化任务书 - -## 0. 项目背景与最终目标 - -我正在独立开发一个基于 Python 的开源 VPS 综合检测工具，主要面向中文 VPS 社区及 Linux 初学者。 - -当前已有初步完成的功能： - -- Linux 发行版、内核、CPU、内存、磁盘等基础信息检测。 -- Traceroute 路由跟踪及终端显示。 -- 现有代码已在 Ubuntu 22.04 Server 和 Ubuntu 24.04 Desktop 虚拟机环境中进行过测试。 - -以上完成情况是我的阶段性描述，请通过实际代码和测试重新核实，不能仅凭我的描述认定全部测试通过。 - -本项目的目标不是简单复制其他 VPS 检测脚本，而是开发一个： - -**自主实现为主、安全透明、功能完整、结果准确、适合小白、可长期维护，并能被未来 FlexMaster 项目调用的 VPS 综合诊断工具。** - -项目现阶段只开发 Python CLI 检测工具，不开发代理部署功能和 Web UI。 - -未来 FlexMaster 将复用本项目的检测核心，但二者作为独立项目维护。 - ---- - -## 1. 开发原则（最高优先级） - -1. **自主实现优先。** 能够通过 Python 标准库或成熟 Python 依赖完成的功能，优先自主编写。 -2. **保留已有成果。** 不推倒重来，不重复开发已经稳定实现的本机检测与 Traceroute。 -3. **避免重复造轮子。** 对磁盘基准、专业网络吞吐和高级路由诊断，可调用 fio、iperf3、mtr 等成熟工具。 -4. **合法利用外部资源。** 对地理位置、ASN、IP 风险、信誉信息等本机无法独立获取的数据，可使用合法的第三方 API 或数据库。 -5. **源码借鉴必须合法。** 先检查 LICENSE、版权声明及第三方依赖许可，不未经确认直接复制 GPL/AGPL 项目的实现代码。 -6. **检测结果必须真实。** 不伪造延迟、丢包、IP 纯净度、流媒体解锁状态或测速结果。 -7. **默认安全。** 普通检测只读；性能、磁盘写入、持续测速及较大流量测试必须明确提示并取得用户确认。 -8. **单模块故障隔离。** 外部 API、网络、权限或依赖出错时，不能导致整个程序崩溃。 -9. **结构化优先。** 检测逻辑、数据模型、CLI 输出、报告导出相互解耦。 -10. **面向小白。** 最终实现一条命令启动，中文输出清楚，提供英文选项，并解释结果含义。 -11. **以证据判定完成。** 每个任务必须有对应实现、测试记录及验收说明。 -12. **不得擅自执行高风险动作。** 不自动修改 SSH、防火墙、路由、DNS、系统网络配置，不部署代理，不向外上传完整报告。 - ---- - -## 2. 需要解决的全部功能问题 - -请对以下十一类功能进行逐项审查、设计、实现及测试。 - -要求建立完整的问题追踪表，记录每项的状态： - -- 已实现且通过测试 -- 已实现但有缺陷 -- 部分实现 -- 尚未实现 -- 外部条件不足，待实机验证 -- 不适用，并说明原因 - -### 第一类：VPS 本机与硬件检测 - -- 准确识别 Linux 发行版、内核、CPU 架构及虚拟化类型。 -- 识别 CPU 型号、核心数、频率及实际资源配额。 -- 检测内存、Swap、磁盘容量与资源限制。 -- 检测 CPU steal、内存压力、资源争用。 -- 实现可重复、可比较的 CPU 性能基准。 -- 检测磁盘吞吐、IOPS、读写延迟，严格限制磁盘写入和占用。 -- 支持用户输入购买规格，并对比实际可见配置；无法核实时明确说明。 - -### 第二类：基础网络与 DNS - -- 检测公网 IPv4、IPv6、默认路由和网络接口。 -- 分别验证 IPv4/IPv6 外网连通性。 -- 测量 DNS 解析时间、成功率和错误类型。 -- 区分 DNS、网络路径及目标服务故障。 -- 测试 TCP 连接、TLS 握手与 UDP 连通性。 -- 检查 MTU/PMTU、双栈异常与 IPv6 连接问题。 -- 正确处理 NAT、容器、多网卡环境，避免误判公网出口。 - -### 第三类：Traceroute、BGP 与线路分析 - -- 保留现有 Traceroute 核心代码并完善。 -- 支持可行的 ICMP、UDP、TCP 探测方式。 -- 显示逐跳 IP、RTT、超时及具有明确统计依据的丢包数据。 -- 查询逐跳 ASN、运营商、推测地区。 -- 避免将不响应的路由器错误判断为线路故障。 -- 避免将单个中间节点的高延迟直接认定为拥堵。 -- 检测中国电信、联通、移动相关线路特征。 -- 支持 BGP、上游网络与 ASN 信息分析。 -- 明确区分 VPS → 中国与中国 → VPS 的测试方向。 -- 地理位置只显示推测结果，不声称是真实物理线路。 -- 无中国侧测试节点时，不伪造中国到 VPS 的去程检测。 - -### 第四类：IP 地理位置、纯净度与信誉 - -- 查询国家、地区、城市、ASN、运营商。 -- 识别住宅、机房、移动网络等 IP 分类。 -- 查询代理、VPN、Tor 及相关风险标签。 -- 支持多个数据源交叉验证与冲突提示。 -- 查询公开黑名单、DNSBL、邮件信誉。 -- 检测 PTR 等 DNS 邮件相关信息。 -- 不使用缺乏依据的绝对“纯净度分数”。 -- 处理 API 限速、失效、付费要求和服务条款。 -- 每条结果记录来源、查询时间、可信度及限制。 - -### 第五类：流媒体与在线服务可用性 - -- 检测 Netflix、Disney+、YouTube 等服务。 -- 检测 ChatGPT 等在线服务的网络与地区可用性。 -- 区分网络可达、地区识别、受限、需要登录、无法确认及实际播放成功。 -- 检测 DNS、TLS、HTTP 错误及服务端限制。 -- 禁止将 HTTP 200 直接判定为成功解锁。 -- 处理网站检测规则变化、反爬限制和误报。 -- 明确声明账号权限、订阅资格和实际播放能力可能无法自动验证。 -- 支持用户自定义合法检测目标。 -- 不尝试绕过账号验证、反爬或访问限制。 - -### 第六类：多地区测速与长期稳定性 - -- 研究可信的全球及中国不同运营商测试节点。 -- 测量延迟、抖动、丢包、下载和上传速率。 -- 严格区分测试方向、节点地理位置与节点运营商。 -- 限制带宽、并发、执行时间及流量消耗。 -- 识别测试节点瓶颈，避免假性低速。 -- 支持可中断的 24/48 小时低负载监测。 -- 分析晚高峰性能劣化、间歇性断线、突发丢包。 -- 关联 CPU steal、内存压力及网络质量的时间变化。 -- 中断监测时安全退出并保留已有数据。 - -### 第七类：基础安全体检 - -- 只读检查 SSH 配置和潜在高风险认证方式。 -- 检查监听端口及可能暴露的服务。 -- 识别系统防火墙状态，说明云安全组无法从本机完整确认。 -- 检查系统更新状态及基础安全设置。 -- 检测重要文件权限风险。 -- 避免把正常业务配置直接定义为漏洞。 -- 提供有依据的修复建议，但不自动执行。 -- 避免泄露密码、Token、私钥及其他敏感信息。 - -### 第八类：报告、诊断与历史记录 - -- 设计统一的结构化检测结果 Schema。 -- 区分成功、失败、跳过、不支持和无法判断。 -- 保存检测时间、方法、来源、错误与置信度说明。 -- 将技术指标转换成普通用户能理解的中文解释。 -- 提供基于规则和真实测量结果的诊断建议。 -- 支持本地 JSON、Markdown 报告，必要时提供 HTML。 -- 对分享用报告进行脱敏。 -- 上传失败、断网或意外退出时不丢失已有报告。 -- 支持历史记录及不同时间、不同服务器的对比。 -- 生成 VPS 购买验收报告，区分实际测量与用户提供的购买规格。 -- 不生成未经校准的绝对性能评分。 - -### 第九类：安装、兼容性与用户体验 - -- 实现面向小白的一键安装与运行。 -- 检查 Python 版本、依赖及权限。 -- 使用虚拟环境隔离依赖，不污染系统 Python。 -- 优先兼容 Ubuntu 22.04 Server、24.04 Desktop。 -- 评估其他发行版、容器、ARM/x86 架构兼容性。 -- 提供中文和英文输出，处理终端编码问题。 -- 尽可能支持非 root 检测。 -- 缺少依赖时友好提示、降级或跳过。 -- 提供帮助、参数说明、更新、卸载和离线说明。 -- 安装脚本可审查，采用可信来源及版本固定/完整性验证。 -- 不要求用户盲目执行来源不明的 curl | bash。 - -### 第十类：可靠性、隐私与自动化测试 - -- 验证默认检测确实不修改系统配置。 -- 区分普通检测与高负载、有写入的基准测试。 -- 对运行时间、CPU、磁盘、流量设置安全上限。 -- 处理超时、网络失败、权限错误和依赖缺失。 -- 保证模块故障隔离。 -- 处理 Ctrl+C、安全取消与临时文件清理。 -- 防止命令注入、路径问题、终端控制字符污染和敏感日志泄露。 -- 使用 Mock、单元测试、集成测试和异常场景测试。 -- 在两种 Ubuntu 虚拟机及真实 VPS 上验证。 -- 建立安全的社区错误反馈方式。 -- 检查第三方许可证、依赖安全和 API 使用条款。 - -### 第十一类：开源维护与未来 FlexMaster 集成 - -- 每个检测模块既能由 CLI 使用，也能通过 Python API 调用。 -- 检测核心与终端 UI 解耦。 -- 为未来 FlexMaster 设计稳定、可复用的接口。 -- 完善 README、安装说明、贡献指南及测试文档。 -- 提供标准 GitHub Issue 模板和脱敏日志机制。 -- 明确支持系统、已知问题和未验证环境。 -- 建立外部贡献代码审查与自动化测试规范。 -- 为开源发布准备合适的 LICENSE、依赖声明及第三方版权通知。 - ---- - -## 3. 参考成熟项目，但不能直接拼接它们 - -请实际阅读以下 GitHub 仓库的相关源码、目录结构、检测逻辑和许可证文件： - -1. YABS - https://github.com/masonr/yet-another-bench-script - -2. Backtrace - https://github.com/oneclickvirt/backtrace - -3. 融合怪 ECS - https://github.com/oneclickvirt/ecs - -4. NodeQuality - https://github.com/LloydAsp/NodeQuality - -5. OneClickVirt - https://github.com/oneclickvirt/oneclickvirt - -重点研究： - -- YABS：fio、iperf3、基准流程及结构化结果。 -- Backtrace：三网回程、ASN、线路识别。 -- 融合怪：多模块综合检测与功能覆盖。 -- NodeQuality：环境隔离、报告组织、异常恢复。 -- OneClickVirt：自动化工程组织及兼容性测试。 - -必须实际检查相关源码，不仅阅读 README。 - -每项借鉴方案要说明： - -- 项目与源码链接 -- 具体文件、函数或调用入口 -- 采用何种实现方式 -- 采用原因 -- 许可证及版权义务 -- 可能涉及的 API 条款或费用 -- 安全风险及兼容性问题 - -如果可以自主开发，请优先自主实现。确需借助已有项目时，优先选择通过公开接口、系统命令或兼容许可证的独立依赖实现。 - -不要未经授权复制 GPL/AGPL 代码；不要认为调用外部程序就自动豁免全部许可证义务。必要时明确标记为待确认。 - ---- - -## 4. 与现有竞品的竞争策略 - -请参考融合怪和 NodeQuality 的功能覆盖，但不要只追求更多测试项目。 - -我们的重点竞争优势为： - -**A. Safe by Default** -- 只读优先 -- 低负载模式 -- 资源限制 -- 错误隔离 -- 数据本地优先 -- 不修改 SSH、防火墙及网络配置 - -**B. Explain, Not Just Measure** -- 用中文说明检测结果 -- 提供数据来源和可信度 -- 解释风险与异常 -- 给出明确的下一步排查建议 -- 不编造检测结论 - -**C. Compare Over Time** -- 本地检测历史 -- 24/48 小时稳定性监测 -- 晚高峰异常分析 -- 多 VPS 比较 -- 购买验收报告 - -请在竞品研究中区分： - -1. 竞争项目已经实现的能力。 -2. 竞争项目部分实现或存在局限的能力。 -3. 我们能够通过实际工程实现证明的优势。 - -不允许仅凭宣传描述声称优于竞争项目。 - ---- - -## 5. 技术架构与实现要求 - -保持 Python 为核心技术栈。 - -推荐采用以下逻辑分层，可以根据现有代码合理调整： - -- Core：模块调度、配置、数据模型、异常处理。 -- Checks：系统、网络、路由、IP、流媒体、安全等检测。 -- Benchmarks：CPU、磁盘和吞吐性能基准。 -- Providers：外部 API、数据库、测速节点接口。 -- Diagnostics：解释规则和异常诊断。 -- Reports：JSON、Markdown、HTML、脱敏和历史比较。 -- CLI：终端交互、语言切换和进度展示。 -- Tests：Mock、单元、集成与回归测试。 - -要求： - -- 模块可以独立运行。 -- 外部依赖允许替换。 -- 接口返回结构化对象，不依赖解析 CLI 文字。 -- 所有网络请求具有明确超时。 -- 默认测试不要求 root。 -- 高风险或高负载操作使用显式确认机制。 -- 使用固定版本或受控版本范围管理依赖。 -- 提供稳定的数据格式与错误编码。 -- 保持未来与 FlexMaster 的接口兼容性。 - ---- - -## 6. Work 的执行流程 - -### 第一步：代码审查与现状确认 - -先查看我现有项目代码、Git 状态、测试、依赖和目录。 - -识别哪些功能已经存在、哪些功能不稳定、哪些功能尚未开发。 - -不得覆盖已有成果。 - -### 第二步：建立问题追踪表 - -把上面十一类需求全部登记。 - -为每一项标注： - -- 编号及问题描述 -- 当前代码位置 -- 实际完成状态 -- 建议实现方法 -- 所需依赖/API -- 测试方法 -- 风险及限制 -- 完成证据 - -不要单纯因为某个功能名称出现在代码里就标记完成。 - -### 第三步：技术方案与开源研究 - -针对未实现或不可靠的功能，先比较自主实现、Python 依赖、系统工具及第三方 API 方案。 - -涉及 GPL/AGPL 代码复制、付费 API、上传用户数据或改变原有架构的重大决定时，先征求我确认。 - -### 第四步：逐模块开发 - -完成代码实现、测试、必要文档和错误处理。 - -优先复用现有组件，避免一次性进行无关的大规模重构。 - -### 第五步：测试与验证 - -在有权限的隔离测试环境中执行安全测试。 - -对于 Ubuntu 22.04 Server、24.04 Desktop，以及真实 VPS 的测试，分别记录结果。 - -没有真实 VPS 环境时，通过 Mock 和有限的本地测试推进，但必须注明尚未实机验证。 - -禁止擅自在生产 VPS 上运行高负载测试。 - -### 第六步：汇总与交付 - -输出真实完成情况和未解决问题。 - -不要为了交付而将模拟、跳过或不确定的检测伪装为通过。 - ---- - -## 7. 需要创建和维护的项目文件 - -建议在仓库中维护： - -- `PROBLEM_BACKLOG.md`：全部问题及实际状态 -- `ARCHITECTURE.md`：模块架构与数据接口 -- `OPEN_SOURCE_RESEARCH.md`：开源项目源码研究与许可证分析 -- `TEST_PLAN.md`：测试场景及验收标准 -- `SECURITY.md`：安全边界、隐私和漏洞报告 -- `CHANGELOG.md`：已经完成的实际更新 -- `README.md`：面向用户的使用说明 - -如果文件已存在，应审查并更新，不要无故覆盖。 - ---- - -## 8. 最终验收标准 - -我希望最终获得的不是只有功能菜单的半成品，而是实际可运行、可信的工具。 - -验收时需要证明： - -1. 十一类问题都有明确状态及依据。 -2. 声称完成的功能具有相应测试证据。 -3. 常规扫描不会擅自更改服务器网络和安全配置。 -4. 基准和大流量测试有明确授权及资源限制。 -5. 一个模块失败不影响其他模块运行。 -6. 结果可在终端查看、导出并安全保存。 -7. 第三方数据具有来源和不确定性说明。 -8. 用户能够理解检测结果及异常原因。 -9. 项目能够通过合理的安装流程运行。 -10. 代码模块可被未来 FlexMaster 独立调用。 -11. 开源借鉴内容具备合法的版权和许可证处理方案。 -12. 未验证的功能不得宣传为已经完成。 - -## 9. 本次工作授权边界 - -请先完成现有代码审查、问题登记、开源源码研究及架构分析。 - -完成这些后，在隔离分支中逐模块推进低风险开发和自动化测试，保留原有代码及 Git 历史。 - -**未经我进一步确认，不要执行生产 VPS 测试、安装系统级依赖、修改防火墙/SSH、使用付费 API、上传检测数据、合并主分支或公开发布。** - -每完成一组实质性工作，请向我汇报： - -- 实际完成了什么 -- 修改了哪些文件 -- 测试通过了哪些项目 -- 哪些仍然存在问题 -- 下一步建议 - -最终目标：建立一个具有独立代码价值、可信检测结果、安全工程设计，并能持续维护的 Python VPS 综合诊断工具。 \ No newline at end of file diff --git a/MANIFEST.sha256.json b/MANIFEST.sha256.json index bec8d7c..e306bc0 100644 --- a/MANIFEST.sha256.json +++ b/MANIFEST.sha256.json @@ -8,36 +8,18 @@ "LICENSE": "07cace8b56becb2cd64969414c59082df9aa7453eeed8caab8378aaff38f6820", ".gitattributes": "1cbf58d18ccb72113d6d1bb3996400d557ccc83cda00a11cd63ef5ca38bbf199", ".gitignore": "7acff1fc699456d32b8d2a69205704d48193320644ed6d97c0f28612db75e87e", - "ALPHA_RELEASE_REPORT.md": "ad4bbfa8600bd85278beb926bd7e4a8e5ca2d417f0dbec901931848fa50a86dc", - "ALPHA_TASK_STATUS.md": "c64603125bc8ac129f0c753f21cd8b3a3ff029e6b7c5100d20574bbbc4b84d10", - "ARCHITECTURE.md": "2d0167efe06df1eb10f0386b3a48c743fcd555a57e7a5247f1af24e6d2524701", - "CHANGELOG.md": "6a813acbc64657a7aa3df39e9abdc5bb2e6a00b25eabae05940e8f4b7831fc68", - "CONTRIBUTING.md": "ff542d9f3161d4034a9b1eb24c48fdbcf2834813e728a348393df8787825999d", - "CURRENT_STATUS.md": "82632c2351318c115322ec0537450014b7306fa9bcdfaddf6b1d9a6b804bfa7f", - "DEVELOPMENT_BRIEF.zh.md": "2826390187880a27ee3a14405ee2bff012fdda532fa567ee16643959842193f9", - "IPQUALITY_COVERAGE.md": "57bb12daad9b52e2c9ff55a7de5dafcd7278e57ea86a2545e15701cfb4b27fdd", - "KNOWN_LIMITATIONS.md": "c874b401af6bed7539dceaab9a15fe0c74653846ff1f2bad142687c68461fc93", - "OPEN_SOURCE_REFERENCES.md": "f75ae885e4f31902a77e3eea90cfee3a3a0b38c0772ba70dc8935448fe483051", - "OPEN_SOURCE_RESEARCH.md": "b55daa9b58b49fc2acd7cc3ecec077a64ea5bb68be2893ed2f616cb581434803", - "PROBLEM_BACKLOG.md": "e4ba9faf47c25ebb8af39f5d22185c1ccf191d9248f60fd6985406be34e42403", - "PUBLIC_BETA_CHANGE_REPORT.md": "33f3eefb59f8445ccd974b3a40881febbfe3855baeb188c9edfe55167bbcf6e9", - "README.en.md": "b7472946383d790249f0612ea045b128f9b1309bb9eefb78f46701fde6ef5224", - "README.md": "7a3071c306cfe3403401c61a85ce4cd23b1761efee7e8cf56cb5adc8aee32325", - "RELEASE_NOTES.md": "020d12ae499c5049b0362b3ac97e6e43a1956b4035594450da5da669d3818b01", - "SECURITY.md": "24dd0d7306bd3643f9d9773db51ea777d9049337afdd92d5ce3c6dfd38b2c81f", - "SECURITY_ROADMAP.md": "1eb9799e41419201701b4cc5bf49045b02b63021044285eec4e9661aa591f949", - "TEST_PLAN.md": "1c4cbc8d4608a3983c6ed7de782c9e7f0deba25b9b8f191e3eb1cd5f4757dd29", - "THIRD_PARTY_NOTICES.md": "f6aaa77f22195916ca027e7756d74e3a206399c9e6a6c399d530a21a05f4e768", - "USER_CHECKLIST_STATUS.md": "ef3255e772499813fb2c28cb9bdad3eac2ab970f4d4aff7e8a827c0f2c1b45f5", + "README.en.md": "8af18dd3ffc5b49209bea79c0f931174feda6b9476e62e8d56ab2c0d1905df1d", + "README.md": "b34606732b22930a29cd7cf3626c8ab7671738983cc164caae1070256043202d", + "THIRD_PARTY_NOTICES.md": "5049c589e832f752d9561240facccd23456cb41123820e0a93bac1532b416afe", "proxydoctor/__init__.py": "78648a703705f6f05484eabdd61c9cc302943dd96c25c8448666d07a1eaa713b", "proxydoctor/__main__.py": "f21b83731acbaa16519e17fa795601ccd3543400cd5c59bb40098a488c225d84", "proxydoctor/bandwidth.py": "822392dd28872e55f4c67253983c69c4545a89dfbacc68d805c45d16c3283130", "proxydoctor/bgp.py": "4c9fea00e616058700f73335fe1995764b85d610a89b22936b4e5dd9f563c0c6", "proxydoctor/carriers.py": "11506fef02973552ab74367f3c1f91c7a7ec484ac574c71eada6ab82fc5448aa", "proxydoctor/checks.py": "f010c09c834af2f4ac48128113bb5aebef9d1fb0c796891623d02232ccf09e31", - "proxydoctor/cli.py": "103bd8fa9d961320ae60dd90892e1343f3c45eb0f6723c15c705cba8fc6bcc82", + "proxydoctor/cli.py": "c88708f6bcfefdfe1f2b5eebe9651aec4c25d56b4658d987b5d502d61734a48b", "proxydoctor/connectivity.py": "2b6d4cfe69271ad582c3b0eb81bc69d38a9395c80cc12df2804bd01854f22385", - "proxydoctor/console.py": "e63da77fbb7c554ceb756a6155a124f689040a8722aa2eb84080f91d5eb14cf7", + "proxydoctor/console.py": "f6d29e9483e28d3252bba182f8152dc39ba28767afe8e8323fa50fdda88d6d2b", "proxydoctor/geo.py": "e4dde1452488743a0fc9a74e65bca65cad894ee357bc09c1d2b6dbdc2f0cfd04", "proxydoctor/i18n.py": "a7a72f7ce2d64d20564828438eba9becf68ee3ef33c7e39dc90efe767d636d4d", "proxydoctor/ipquality.py": "4dd1fc1421d11d03d8c803626393ca02d7be81527d4984da57c9ef2140c395bb", @@ -53,7 +35,7 @@ "proxydoctor/schema.py": "6ae0e99c696fae778e88f96132142ac8eecb51a6a5df91ba38b816895aa1ca88", "proxydoctor/security.py": "363327e43ab13dc8ebb9bb88f49fd14cea4aedca0952e9733159f99a195bb019", "proxydoctor/session.py": "3302f8aa1f031ca13c863ad0b464d94b11a41ee944e97cdb2f4d6ad2e7990737", - "proxydoctor/suite.py": "86717aee014e0b7695e8390d4970167a0b9b092200552612ce04b895f572f0a2", + "proxydoctor/suite.py": "631a9b050c17a44abfd2b89630d362810743e51a83c2e503d03012a8f233d958", "proxydoctor/worker.py": "c4745ba21aa68d4ce57c9bb8727841f8839d1c1c2d820e0e8e7ff071c88b0e06", "tests/conftest.py": "9ba6f678d6297f2dc85f42121790246cd86b120dd52e537ee09d4c19f2cdf1b9", "tests/test_alpha_quality.py": "a833be4ec7f0600383495b838ea1e95f50112003d47b2cc2cebbec50d0eba706", @@ -61,6 +43,7 @@ "tests/test_branding.py": "d9cf33286f9591564e722dd5c5be038eed85a4a3643f0348fb00f7d3db475ef6", "tests/test_bytecode_policy.py": "b66e5358d5e7adf36d5413b776e494d8c66d1dda368d259a79a02f0ea622d657", "tests/test_checks.py": "4ff2ff8562a13635d24cf6a29dd7063578bcc1a202840aeb76c7619c06cacfb3", + "tests/test_compact_display.py": "cff6d55554cd992db2f936da769b6f5dc031c0d9687d2148e3918298a9408d88", "tests/test_connectivity.py": "e4cea940bf3783e312f7acf28b80c7fc709579e3809a415a5822b05431d6fde1", "tests/test_console_geo.py": "24d91b4abf292f666fde27244099bab7d52afff99b835c2fda26bd73a86aba03", "tests/test_final_hardening.py": "75350b7d1e33082c6865a413851a5fa27ef3d339d6a22eeea1a0304c55ed8f07", @@ -70,7 +53,7 @@ "tests/test_measurements.py": "d2dfa5d3273a662c6d343b163e449d0baae85ebb3e81d94e75e6882109cd5a04", "tests/test_media.py": "cd97e7d0ac600847ecd91ea0be5a2b1eb1dca573c9f25e697e0529d676351139", "tests/test_nodequality.py": "444eeb659e3bd70e67bb11b89df9de9c856609a102a25036c59b5947a2bd94f1", - "tests/test_phase1_delivery.py": "4d83d7464dffbf7eedde97a2750eb93140ebb4c344306c7bcdc76332a2966da9", + "tests/test_phase1_delivery.py": "69850fd65a22001dd8e354f8e68253cec12e1715135c57c49cf511a016358c83", "tests/test_public_beta.py": "9a8f62bb4c199e2c3bf9a7c639c7180d1367825e76eb96f33e58af10925d394a", "tests/test_quality.py": "a7afc7a3794032f4a9bc53ab8385188168f1fe96615ae2cac1b2d0eaf0b72561", "tests/test_recovery.py": "05803bfbc5de22c9a974335d0d67554af98e082568b91ac542ff5035a47434c2", @@ -81,16 +64,37 @@ "tests/test_security.py": "49e5b4a02b6d9d08a57265d5fa7311331b3041e1403d6883a42c1728dc1564fa", "tests/test_server_info.py": "52bd0f409cc01ffaabb3fde25a0781dab286065d475f2c639ed586b89b5608c2", "tests/test_stage1.py": "9413983d55805a663d5b831b64146f191846192788ff014f4db256c5f68d3b9a", - "tests/test_suite.py": "61c83fe1bdb54deea884120ae8f9cc17373cdbe2f27bc84b600f86e614b1b5cb", - "docs/CI.md": "b0a391418bb98d077eb46c1ca4f4ba4cedf6aa7b45ce8cef682e20c88576ba3b", - "docs/DATA_SERVICES.md": "d91be04176e6dda22c831cb9cd24f968ad82c1851c53bb6cbf356c51141b4a4c", - "docs/GITHUB_ABOUT.md": "cff3e044fcdc8f702fd2ee0b36f5e854c0ef710d127dbdb2544424d216d0ad60", - "docs/history-beta-before-p0-20261101.md": "fd1130fcf1e896b84954e1a6805ecf75dd88fb5ec7c2938ee8d0fce0e8488be0", - "docs/pre-alpha-README.en.md": "0f6c892c62870b925ccdefd2659f09ef49c8c34d7a763cb922b6f121f5972843", - "docs/pre-alpha-README.md": "ebc76331f714158bb0f4d3b4bd4e20ac92713bece32cfafab4b1ff32cae3d4a1", - "docs/status-history-before-2026-11-01.md": "28cd2e77331469b9ffd4b7f298ad6eaecefd48e00b6f7e2823b54d4cacab1ca0", + "tests/test_suite.py": "060496ba254109852a8a47669b4d0f0236b5e8ce1755b9889f7717148d5ad436", + "docs/archive/ALPHA_RELEASE_REPORT.md": "02c4e902c402918ccc93e5519d61f46c20be741d2177b5b2566f5022d281b231", + "docs/archive/ALPHA_TASK_STATUS.md": "d34694421c89ac6bdd8ec8d7f934e062f05ebb667b099e5647655c8614b0df01", + "docs/archive/ARCHITECTURE-alpha.md": "c10fd83a73613f93d95a8c024a4827ed682f2282efe5b26474a9935d7db6dc1b", + "docs/archive/history-beta-before-p0-20261101.md": "b653320e061bc233725c516f4af197dae064c98e907e7c2964d1d2d1a64e4660", + "docs/archive/OPEN_SOURCE_RESEARCH.md": "3c8d475c43cfb1f887ef3a3a52e5c828f684e9dca8f859d0fef73193f00ca19b", + "docs/archive/pre-alpha-README.en.md": "b2f1d1d8fbaf36340330b465c8e5b7ba82dbacebab2558a994753a1ccafe5874", + "docs/archive/pre-alpha-README.md": "b78ebddbe4d6ad6882a9d9a7f888721daf672a4e2886313af27993fc6dca0aca", + "docs/archive/PUBLIC_BETA_CHANGE_REPORT.md": "d08880333fea862cb4c6c83cd7a25c7d314b7ccc0ed96dc695561aef29b39f7e", + "docs/archive/README.md": "0d004615164da565a4c3166441d8814ef8ba7cc82c7d5be057c9bc8aab56ff8a", + "docs/archive/status-history-before-2026-11-01.md": "8d16d9d40292c2a157d445007c0ba1b9fa64c2cae5235be3025e0d33e799be4b", + "docs/archive/TEST_PLAN-alpha.md": "13d21028725cc7259c7de9d52169f370a87f5df1326995a4c608b062f961d826", + "docs/development/ARCHITECTURE.md": "affd2a73cf821824a05ace6b06d4629aa5d4b8af21c349063a99195b623a5b91", + "docs/development/CI.md": "b0a391418bb98d077eb46c1ca4f4ba4cedf6aa7b45ce8cef682e20c88576ba3b", + "docs/development/CONTRIBUTING.md": "ff542d9f3161d4034a9b1eb24c48fdbcf2834813e728a348393df8787825999d", + "docs/development/REFERENCES.md": "497d430e272e3fb1466980baae2af6e6d38a0e26ef47166b7eafc0e6fb59a192", + "docs/development/TESTING.md": "4217a35c53bf77404badc7145e5ad4a69bfb6a2803f23183d1d186cb6f2a241a", + "docs/guide/DATA_SERVICES.md": "d91be04176e6dda22c831cb9cd24f968ad82c1851c53bb6cbf356c51141b4a4c", + "docs/guide/INSTALL.md": "320a91fdf7f97f27153dd383a05c5db1013aae1400e4f3a9e603b1579c21581a", + "docs/guide/IPQUALITY_COVERAGE.md": "c83c14ae7a00700e484fa707546876fba512d5080adf9ec3827b941df4d3e4c1", + "docs/guide/USAGE.md": "7ede2dfa108b8b8a7563c7da6fd25525e20b1f4e25a4389ad1058573fc8a896d", + "docs/README.md": "fc451f854a312ebf13fab73b1e2215105b2f97c5dd31cf832e7ea50d9a6b8fea", + "docs/release/CHANGELOG.md": "a999eb3a33694afe4099a3ada9d69766c7584533dacfc0ae8a249163d9524ab9", + "docs/release/KNOWN_LIMITATIONS.md": "37abd811206a4b2cefccacc445d48d08a70ebde364fc2e5a4050ec353cc3500a", + "docs/release/RELEASE_NOTES.md": "3118790651074d98c2a13779ae613b1d7538795d12834d7c85a9662d91a8717c", + "docs/security/ROADMAP.md": "bdec671b5690927df12fdc48ed54b55afdfa51fa573213944236630a7da0a497", + "docs/security/SECURITY.md": "24dd0d7306bd3643f9d9773db51ea777d9049337afdd92d5ce3c6dfd38b2c81f", ".github/workflows/tests.yml": "a0d3002520e97206d94aa3ff9ee02be81f062c0dbb280c579af29e9d95846a58", - ".github/ISSUE_TEMPLATE/bug_report.md": "e0a64101b0552afc7bc0722379ade9e730faeb8e510ec89f6c2d177926c52a64", - ".github/ISSUE_TEMPLATE/feature_request.md": "e4efabb0a5961e03344f59985797f4a349989d94ce3bd9edabf5f4d5a656bc68" + ".github/CONTRIBUTING.md": "53d976a3571d70cabfa32e98185a905b25a91a1d9694f92502f037503b3d0076", + ".github/ISSUE_TEMPLATE/bug_report.md": "b5eb7883641a2cad94b1770f47f946aecda05917d0961eb1d8c639ce4da4f64e", + ".github/ISSUE_TEMPLATE/feature_request.md": "e4efabb0a5961e03344f59985797f4a349989d94ce3bd9edabf5f4d5a656bc68", + ".github/SECURITY.md": "e13fd5de68bce030755b1c93c47c31e7a91a866d26dcdbc762f6ea84a3f6ac7b" } } diff --git a/PROBLEM_BACKLOG.md b/PROBLEM_BACKLOG.md deleted file mode 100644 index 467e494..0000000 --- a/PROBLEM_BACKLOG.md +++ /dev/null @@ -1,274 +0,0 @@ -> 历史记录 / Historical record：ProxyDoctor 是项目旧名。以下旧版本、SHA256、测试数量与路径保留原样，不代表 VPSMaster 新构建已通过；当前范围见 README.md、CURRENT_STATUS.md 和新包同 SHA256 验收报告。 - -> 最终加固：路由错误分类、跳点 ASN/运营商来源、窄终端适配已有回归。环境覆盖与结论以同 SHA256 的 FINAL_TEST_REPORT.md 为准。完整大陆三网、海外 VPS、ARM、新装 22 Server 尚未完成。 -> 历史 Alpha/问题状态记录：当前 1.0 公测候选请以 CURRENT_STATUS.md 和 PUBLIC_BETA_CHANGE_REPORT.md 为准；新增代码不等于已完成实测。 - -> 最新Alpha优先项状态见 [ALPHA_TASK_STATUS.md](ALPHA_TASK_STATUS.md)。以下包含本轮前历史统计，不能作为最新发布验收结论。 - - -## 报告与IP质量更新（2026-11-01） - -- 新增离线 `report` 命令：JSON→中英文Markdown，保留指标、来源、未知和跳过原因；输出独占创建，HTML/Markdown注入内容转义。 -- 新增 `recover` 命令：恢复日志最后完整快照→JSON/Markdown；未完成运行标为recovered_partial，明确不是新检测。输入有读取预算。 -- 分享副本增加敏感键、Bearer凭证、URL用户信息/查询参数脱敏；仍需人工复核，不保证任意文本完全匿名。 -- 新增IP概览面板，CJK对齐与长行换行；多来源类型/代理/VPN/Tor证据放在下面，不合成纯净度评分。 -- 新增可选 `--mail-probes`：PTR/正向一致性、单目标出站TCP25，默认不启用，不发送邮件。DNSBL明确未查询；IPMap尚未接入。 -- 实际阅读xykt/IPQuality源码与AGPL许可，只参考需求与组织，未复制实现，详见IPQUALITY_COVERAGE.md。 -- 报告/恢复/PTR实网版本两版Ubuntu均237测试通过；最终面板加入后，两版完整离线回归均239测试通过（22：4.04秒；24：4.49秒）。报告导出、恢复JSON/Markdown、中英文离线真实CLI均退出0。IP数据不完整时退出1符合预期。 -- 实网：22的单目标出站TCP25可连接，24未确认；两台PTR未取得有效结果，不能据此判断邮件信誉。无付费API、系统依赖安装或完整报告上传。 - -证据：工作区outputs/ReportIP22-*、ReportIP24-*（真实导出/探测），PanelFinal22-pytest.txt / PanelFinal24-pytest.txt（最终239测试）。此前223测试记录属于前版，不覆盖所有新增功能。 - - -## 最新双机验收（2026-11-01） - -同版代码已在Ubuntu22.04.5/Python3.10.12和Ubuntu24.04.3/Python3.12.3分别完成223项测试、17/17实际CLI验收。中文/英文离线、Ctrl+C保存、恢复和防覆盖通过；两台实网检测均完整执行但存在目标TCP/IPv6/媒体未确认项，不能说网络全部通过。22.04初次验收脚本内存预期错误，按VirtualBox独立配置修正后复测通过。完整范围及原始证据见工作区outputs/双虚拟机-当前版本验收报告.md。此前未测试段落属于编写时状态，最新以本节为准。测试通过不表示全部101项需求完成。 - - -## Ubuntu 24.04 实测更新（2026-11-01） - -当前分支在Ubuntu24.04.3/Python3.12.3完成223项测试、17/17实际CLI验收。 -中英文离线、默认测速拦截、Ctrl+C保存和防覆盖通过；网络实测正常执行但结果incomplete。 -DNS有结果，固定IPv4 TCP超时、IPv6不可达、TLS跳过；30跳路由未到达目标，媒体多数未知。 -综合报告schema版本升为3。此前“尚未测试”的段落是编写时记录；最新验证以本节为准。 -完整日志/范围见工作区outputs/Current24-验收报告.md。Ubuntu22新版、真实VPS及未实现项目仍待验收。 - -# 全部需求追踪表 - - -更新：2026-11-01。范围：独立 Python CLI；不开发代理部署或 Web UI。 - -本轮按用户要求不执行测试。历史 outputs/ 验收报告属于 0.5.0，不能证明本分支修改通过。状态中“部分实现”只表示源码证据；未将存在函数名等同于验收。 - -优先级：P0 默认安全与保存/隔离 → P1 结构化本机、双栈网络和证据 → P2 路由/信誉/媒体与报告 → P3 基准、长期监测、安装与集成。 - -P0 本轮：综合流程移除自动 CPU 基准；带宽要求显式许可；暂停可上传数据的第三方脚本入口。实现未测试。保存/隔离已编写，待验证；最新汇总见 CURRENT_STATUS.md。 - - -## 第一类：VPS 本机与硬件检测 - - -| 编号 | 需求 | 状态 | 优先级 | 代码/证据 | 实现/依赖 | 验证方案 | 限制 | -|---|---|---|---|---|---|---|---| -| 01-01 | 准确识别 Linux 发行版、内核、CPU 架构及虚拟化类型。 | 部分实现 | P1 | proxydoctor/checks.py; suite.py（源码审查；非通过证据） | 只读 /proc、cgroup v1/v2、PSI；CPU/fio 基准独立授权；标准库；可选 fio | tests/test_server_info.py; test_checks.py，逐项补缺并运行；本轮未执行 | 配额不等于物理资源；VM 不代表商家配置 | -| 01-02 | 识别 CPU 型号、核心数、频率及实际资源配额。 | 部分实现 | P1 | proxydoctor/checks.py; suite.py（源码审查；非通过证据） | 只读 /proc、cgroup v1/v2、PSI；CPU/fio 基准独立授权；标准库；可选 fio | tests/test_server_info.py; test_checks.py，逐项补缺并运行；本轮未执行 | 配额不等于物理资源；VM 不代表商家配置 | -| 01-03 | 检测内存、Swap、磁盘容量与资源限制。 | 部分实现 | P1 | proxydoctor/checks.py; suite.py（源码审查；非通过证据） | 只读 /proc、cgroup v1/v2、PSI；CPU/fio 基准独立授权；标准库；可选 fio | tests/test_server_info.py; test_checks.py，逐项补缺并运行；本轮未执行 | 配额不等于物理资源；VM 不代表商家配置 | -| 01-04 | 检测 CPU steal、内存压力、资源争用。 | 部分实现 | P1 | proxydoctor/checks.py; suite.py（源码审查；非通过证据） | 只读 /proc、cgroup v1/v2、PSI；CPU/fio 基准独立授权；标准库；可选 fio | tests/test_server_info.py; test_checks.py，逐项补缺并运行；本轮未执行 | 配额不等于物理资源；VM 不代表商家配置 | -| 01-05 | 实现可重复、可比较的 CPU 性能基准。 | 尚未实现 | P1 | proxydoctor/checks.py; suite.py（源码审查；非通过证据） | 只读 /proc、cgroup v1/v2、PSI；CPU/fio 基准独立授权；标准库；可选 fio | tests/test_server_info.py; test_checks.py，逐项补缺并运行；本轮未执行 | 配额不等于物理资源；VM 不代表商家配置 | -| 01-06 | 检测磁盘吞吐、IOPS、读写延迟，严格限制磁盘写入和占用。 | 尚未实现 | P1 | proxydoctor/checks.py; suite.py（源码审查；非通过证据） | 只读 /proc、cgroup v1/v2、PSI；CPU/fio 基准独立授权；标准库；可选 fio | tests/test_server_info.py; test_checks.py，逐项补缺并运行；本轮未执行 | 配额不等于物理资源；VM 不代表商家配置 | -| 01-07 | 支持用户输入购买规格，并对比实际可见配置；无法核实时明确说明。 | 尚未实现 | P1 | proxydoctor/checks.py; suite.py（源码审查；非通过证据） | 只读 /proc、cgroup v1/v2、PSI；CPU/fio 基准独立授权；标准库；可选 fio | tests/test_server_info.py; test_checks.py，逐项补缺并运行；本轮未执行 | 配额不等于物理资源；VM 不代表商家配置 | - - -## 第二类：基础网络与 DNS - - -| 编号 | 需求 | 状态 | 优先级 | 代码/证据 | 实现/依赖 | 验证方案 | 限制 | -|---|---|---|---|---|---|---|---| -| 02-01 | 检测公网 IPv4、IPv6、默认路由和网络接口。 | 部分实现 | P1 | checks.py; quality.py; net.py（源码审查；非通过证据） | 分协议族 DNS/TCP/TLS/UDP 探针；PMTU 需注明权限与路径限制；socket/ssl；可选系统工具 | tests/test_quality.py; test_review.py，逐项补缺并运行；本轮未执行 | NAT 出口不代表入站；DNS 解析预算待核查 | -| 02-02 | 分别验证 IPv4/IPv6 外网连通性。 | 尚未实现 | P1 | checks.py; quality.py; net.py（源码审查；非通过证据） | 分协议族 DNS/TCP/TLS/UDP 探针；PMTU 需注明权限与路径限制；socket/ssl；可选系统工具 | tests/test_quality.py; test_review.py，逐项补缺并运行；本轮未执行 | NAT 出口不代表入站；DNS 解析预算待核查 | -| 02-03 | 测量 DNS 解析时间、成功率和错误类型。 | 尚未实现 | P1 | checks.py; quality.py; net.py（源码审查；非通过证据） | 分协议族 DNS/TCP/TLS/UDP 探针；PMTU 需注明权限与路径限制；socket/ssl；可选系统工具 | tests/test_quality.py; test_review.py，逐项补缺并运行；本轮未执行 | NAT 出口不代表入站；DNS 解析预算待核查 | -| 02-04 | 区分 DNS、网络路径及目标服务故障。 | 尚未实现 | P1 | checks.py; quality.py; net.py（源码审查；非通过证据） | 分协议族 DNS/TCP/TLS/UDP 探针；PMTU 需注明权限与路径限制；socket/ssl；可选系统工具 | tests/test_quality.py; test_review.py，逐项补缺并运行；本轮未执行 | NAT 出口不代表入站；DNS 解析预算待核查 | -| 02-05 | 测试 TCP 连接、TLS 握手与 UDP 连通性。 | 部分实现 | P1 | checks.py; quality.py; net.py（源码审查；非通过证据） | 分协议族 DNS/TCP/TLS/UDP 探针；PMTU 需注明权限与路径限制；socket/ssl；可选系统工具 | tests/test_quality.py; test_review.py，逐项补缺并运行；本轮未执行 | NAT 出口不代表入站；DNS 解析预算待核查 | -| 02-06 | 检查 MTU/PMTU、双栈异常与 IPv6 连接问题。 | 尚未实现 | P1 | checks.py; quality.py; net.py（源码审查；非通过证据） | 分协议族 DNS/TCP/TLS/UDP 探针；PMTU 需注明权限与路径限制；socket/ssl；可选系统工具 | tests/test_quality.py; test_review.py，逐项补缺并运行；本轮未执行 | NAT 出口不代表入站；DNS 解析预算待核查 | -| 02-07 | 正确处理 NAT、容器、多网卡环境，避免误判公网出口。 | 部分实现 | P1 | checks.py; quality.py; net.py（源码审查；非通过证据） | 分协议族 DNS/TCP/TLS/UDP 探针；PMTU 需注明权限与路径限制；socket/ssl；可选系统工具 | tests/test_quality.py; test_review.py，逐项补缺并运行；本轮未执行 | NAT 出口不代表入站；DNS 解析预算待核查 | - - -## 第三类：Traceroute、BGP 与线路分析 - - -| 编号 | 需求 | 状态 | 优先级 | 代码/证据 | 实现/依赖 | 验证方案 | 限制 | -|---|---|---|---|---|---|---|---| -| 03-01 | 保留现有 Traceroute 核心代码并完善。 | 部分实现 | P2 | routes.py; geo.py（源码审查；非通过证据） | 保留 UDP；扩展多轮与 TCP/ICMP，ASN 来源独立记录；标准库；可选 mtr；ASN API | tests/test_routes.py; test_console_geo.py，逐项补缺并运行；本轮未执行 | 中间跳不响应不等于丢包；无中国探针不生成去程 | -| 03-02 | 支持可行的 ICMP、UDP、TCP 探测方式。 | 部分实现 | P2 | routes.py; geo.py（源码审查；非通过证据） | 保留 UDP；扩展多轮与 TCP/ICMP，ASN 来源独立记录；标准库；可选 mtr；ASN API | tests/test_routes.py; test_console_geo.py，逐项补缺并运行；本轮未执行 | 中间跳不响应不等于丢包；无中国探针不生成去程 | -| 03-03 | 显示逐跳 IP、RTT、超时及具有明确统计依据的丢包数据。 | 部分实现 | P2 | routes.py; geo.py（源码审查；非通过证据） | 保留 UDP；扩展多轮与 TCP/ICMP，ASN 来源独立记录；标准库；可选 mtr；ASN API | tests/test_routes.py; test_console_geo.py，逐项补缺并运行；本轮未执行 | 中间跳不响应不等于丢包；无中国探针不生成去程 | -| 03-04 | 查询逐跳 ASN、运营商、推测地区。 | 尚未实现 | P2 | routes.py; geo.py（源码审查；非通过证据） | 保留 UDP；扩展多轮与 TCP/ICMP，ASN 来源独立记录；标准库；可选 mtr；ASN API | tests/test_routes.py; test_console_geo.py，逐项补缺并运行；本轮未执行 | 中间跳不响应不等于丢包；无中国探针不生成去程 | -| 03-05 | 避免将不响应的路由器错误判断为线路故障。 | 尚未实现 | P2 | routes.py; geo.py（源码审查；非通过证据） | 保留 UDP；扩展多轮与 TCP/ICMP，ASN 来源独立记录；标准库；可选 mtr；ASN API | tests/test_routes.py; test_console_geo.py，逐项补缺并运行；本轮未执行 | 中间跳不响应不等于丢包；无中国探针不生成去程 | -| 03-06 | 避免将单个中间节点的高延迟直接认定为拥堵。 | 尚未实现 | P2 | routes.py; geo.py（源码审查；非通过证据） | 保留 UDP；扩展多轮与 TCP/ICMP，ASN 来源独立记录；标准库；可选 mtr；ASN API | tests/test_routes.py; test_console_geo.py，逐项补缺并运行；本轮未执行 | 中间跳不响应不等于丢包；无中国探针不生成去程 | -| 03-07 | 检测中国电信、联通、移动相关线路特征。 | 尚未实现 | P2 | routes.py; geo.py（源码审查；非通过证据） | 保留 UDP；扩展多轮与 TCP/ICMP，ASN 来源独立记录；标准库；可选 mtr；ASN API | tests/test_routes.py; test_console_geo.py，逐项补缺并运行；本轮未执行 | 中间跳不响应不等于丢包；无中国探针不生成去程 | -| 03-08 | 支持 BGP、上游网络与 ASN 信息分析。 | 尚未实现 | P2 | routes.py; geo.py（源码审查；非通过证据） | 保留 UDP；扩展多轮与 TCP/ICMP，ASN 来源独立记录；标准库；可选 mtr；ASN API | tests/test_routes.py; test_console_geo.py，逐项补缺并运行；本轮未执行 | 中间跳不响应不等于丢包；无中国探针不生成去程 | -| 03-09 | 明确区分 VPS → 中国与中国 → VPS 的测试方向。 | 尚未实现 | P2 | routes.py; geo.py（源码审查；非通过证据） | 保留 UDP；扩展多轮与 TCP/ICMP，ASN 来源独立记录；标准库；可选 mtr；ASN API | tests/test_routes.py; test_console_geo.py，逐项补缺并运行；本轮未执行 | 中间跳不响应不等于丢包；无中国探针不生成去程 | -| 03-10 | 地理位置只显示推测结果，不声称是真实物理线路。 | 部分实现 | P2 | routes.py; geo.py（源码审查；非通过证据） | 保留 UDP；扩展多轮与 TCP/ICMP，ASN 来源独立记录；标准库；可选 mtr；ASN API | tests/test_routes.py; test_console_geo.py，逐项补缺并运行；本轮未执行 | 中间跳不响应不等于丢包；无中国探针不生成去程 | -| 03-11 | 无中国侧测试节点时，不伪造中国到 VPS 的去程检测。 | 尚未实现 | P2 | routes.py; geo.py（源码审查；非通过证据） | 保留 UDP；扩展多轮与 TCP/ICMP，ASN 来源独立记录；标准库；可选 mtr；ASN API | tests/test_routes.py; test_console_geo.py，逐项补缺并运行；本轮未执行 | 中间跳不响应不等于丢包；无中国探针不生成去程 | - - -## 第四类：IP 地理位置、纯净度与信誉 - - -| 编号 | 需求 | 状态 | 优先级 | 代码/证据 | 实现/依赖 | 验证方案 | 限制 | -|---|---|---|---|---|---|---|---| -| 04-01 | 查询国家、地区、城市、ASN、运营商。 | 尚未实现 | P2 | ipquality.py; geo.py（源码审查；非通过证据） | 保留分源风险；补 PTR 与允许使用的 DNSBL；现有三来源；可选密钥 API | tests/test_measurements.py; test_phase1_delivery.py，逐项补缺并运行；本轮未执行 | 来源条款/限额需逐项审核；风险分不可合并 | -| 04-02 | 识别住宅、机房、移动网络等 IP 分类。 | 尚未实现 | P2 | ipquality.py; geo.py（源码审查；非通过证据） | 保留分源风险；补 PTR 与允许使用的 DNSBL；现有三来源；可选密钥 API | tests/test_measurements.py; test_phase1_delivery.py，逐项补缺并运行；本轮未执行 | 来源条款/限额需逐项审核；风险分不可合并 | -| 04-03 | 查询代理、VPN、Tor 及相关风险标签。 | 部分实现 | P2 | ipquality.py; geo.py（源码审查；非通过证据） | 保留分源风险；补 PTR 与允许使用的 DNSBL；现有三来源；可选密钥 API | tests/test_measurements.py; test_phase1_delivery.py，逐项补缺并运行；本轮未执行 | 来源条款/限额需逐项审核；风险分不可合并 | -| 04-04 | 支持多个数据源交叉验证与冲突提示。 | 部分实现 | P2 | ipquality.py; geo.py（源码审查；非通过证据） | 保留分源风险；补 PTR 与允许使用的 DNSBL；现有三来源；可选密钥 API | tests/test_measurements.py; test_phase1_delivery.py，逐项补缺并运行；本轮未执行 | 来源条款/限额需逐项审核；风险分不可合并 | -| 04-05 | 查询公开黑名单、DNSBL、邮件信誉。 | 尚未实现 | P2 | ipquality.py; geo.py（源码审查；非通过证据） | 保留分源风险；补 PTR 与允许使用的 DNSBL；现有三来源；可选密钥 API | tests/test_measurements.py; test_phase1_delivery.py，逐项补缺并运行；本轮未执行 | 来源条款/限额需逐项审核；风险分不可合并 | -| 04-06 | 检测 PTR 等 DNS 邮件相关信息。 | 尚未实现 | P2 | ipquality.py; geo.py（源码审查；非通过证据） | 保留分源风险；补 PTR 与允许使用的 DNSBL；现有三来源；可选密钥 API | tests/test_measurements.py; test_phase1_delivery.py，逐项补缺并运行；本轮未执行 | 来源条款/限额需逐项审核；风险分不可合并 | -| 04-07 | 不使用缺乏依据的绝对“纯净度分数”。 | 尚未实现 | P2 | ipquality.py; geo.py（源码审查；非通过证据） | 保留分源风险；补 PTR 与允许使用的 DNSBL；现有三来源；可选密钥 API | tests/test_measurements.py; test_phase1_delivery.py，逐项补缺并运行；本轮未执行 | 来源条款/限额需逐项审核；风险分不可合并 | -| 04-08 | 处理 API 限速、失效、付费要求和服务条款。 | 尚未实现 | P2 | ipquality.py; geo.py（源码审查；非通过证据） | 保留分源风险；补 PTR 与允许使用的 DNSBL；现有三来源；可选密钥 API | tests/test_measurements.py; test_phase1_delivery.py，逐项补缺并运行；本轮未执行 | 来源条款/限额需逐项审核；风险分不可合并 | -| 04-09 | 每条结果记录来源、查询时间、可信度及限制。 | 尚未实现 | P2 | ipquality.py; geo.py（源码审查；非通过证据） | 保留分源风险；补 PTR 与允许使用的 DNSBL；现有三来源；可选密钥 API | tests/test_measurements.py; test_phase1_delivery.py，逐项补缺并运行；本轮未执行 | 来源条款/限额需逐项审核；风险分不可合并 | - - -## 第五类：流媒体与在线服务可用性 - - -| 编号 | 需求 | 状态 | 优先级 | 代码/证据 | 实现/依赖 | 验证方案 | 限制 | -|---|---|---|---|---|---|---|---| -| 05-01 | 检测 Netflix、Disney+、YouTube 等服务。 | 部分实现 | P2 | media.py（源码审查；非通过证据） | 保守证据状态机；自定义目标仅合法 HTTPS 且限响应；urllib/ssl | tests/test_media.py，逐项补缺并运行；本轮未执行 | HTTP 200 不等于播放；反爬/订阅保持未知 | -| 05-02 | 检测 ChatGPT 等在线服务的网络与地区可用性。 | 尚未实现 | P2 | media.py（源码审查；非通过证据） | 保守证据状态机；自定义目标仅合法 HTTPS 且限响应；urllib/ssl | tests/test_media.py，逐项补缺并运行；本轮未执行 | HTTP 200 不等于播放；反爬/订阅保持未知 | -| 05-03 | 区分网络可达、地区识别、受限、需要登录、无法确认及实际播放成功。 | 尚未实现 | P0 | media.py（源码审查；非通过证据） | 保守证据状态机；自定义目标仅合法 HTTPS 且限响应；urllib/ssl | tests/test_media.py，逐项补缺并运行；本轮未执行 | HTTP 200 不等于播放；反爬/订阅保持未知 | -| 05-04 | 检测 DNS、TLS、HTTP 错误及服务端限制。 | 尚未实现 | P2 | media.py（源码审查；非通过证据） | 保守证据状态机；自定义目标仅合法 HTTPS 且限响应；urllib/ssl | tests/test_media.py，逐项补缺并运行；本轮未执行 | HTTP 200 不等于播放；反爬/订阅保持未知 | -| 05-05 | 禁止将 HTTP 200 直接判定为成功解锁。 | 部分实现 | P2 | media.py（源码审查；非通过证据） | 保守证据状态机；自定义目标仅合法 HTTPS 且限响应；urllib/ssl | tests/test_media.py，逐项补缺并运行；本轮未执行 | HTTP 200 不等于播放；反爬/订阅保持未知 | -| 05-06 | 处理网站检测规则变化、反爬限制和误报。 | 尚未实现 | P2 | media.py（源码审查；非通过证据） | 保守证据状态机；自定义目标仅合法 HTTPS 且限响应；urllib/ssl | tests/test_media.py，逐项补缺并运行；本轮未执行 | HTTP 200 不等于播放；反爬/订阅保持未知 | -| 05-07 | 明确声明账号权限、订阅资格和实际播放能力可能无法自动验证。 | 部分实现 | P2 | media.py（源码审查；非通过证据） | 保守证据状态机；自定义目标仅合法 HTTPS 且限响应；urllib/ssl | tests/test_media.py，逐项补缺并运行；本轮未执行 | HTTP 200 不等于播放；反爬/订阅保持未知 | -| 05-08 | 支持用户自定义合法检测目标。 | 尚未实现 | P2 | media.py（源码审查；非通过证据） | 保守证据状态机；自定义目标仅合法 HTTPS 且限响应；urllib/ssl | tests/test_media.py，逐项补缺并运行；本轮未执行 | HTTP 200 不等于播放；反爬/订阅保持未知 | -| 05-09 | 不尝试绕过账号验证、反爬或访问限制。 | 尚未实现 | P2 | media.py（源码审查；非通过证据） | 保守证据状态机；自定义目标仅合法 HTTPS 且限响应；urllib/ssl | tests/test_media.py，逐项补缺并运行；本轮未执行 | HTTP 200 不等于播放；反爬/订阅保持未知 | - - -## 第六类：多地区测速与长期稳定性 - - -| 编号 | 需求 | 状态 | 优先级 | 代码/证据 | 实现/依赖 | 验证方案 | 限制 | -|---|---|---|---|---|---|---|---| -| 06-01 | 研究可信的全球及中国不同运营商测试节点。 | 尚未实现 | P3 | bandwidth.py; quality.py（源码审查；非通过证据） | 显式流量许可；增加受控节点、可取消 JSONL 监测；HTTPS；可选 iperf3 | tests/test_bandwidth_sources.py，逐项补缺并运行；本轮未执行 | 载荷预算不含协议开销；节点瓶颈不代表线路 | -| 06-02 | 测量延迟、抖动、丢包、下载和上传速率。 | 尚未实现 | P3 | bandwidth.py; quality.py（源码审查；非通过证据） | 显式流量许可；增加受控节点、可取消 JSONL 监测；HTTPS；可选 iperf3 | tests/test_bandwidth_sources.py，逐项补缺并运行；本轮未执行 | 载荷预算不含协议开销；节点瓶颈不代表线路 | -| 06-03 | 严格区分测试方向、节点地理位置与节点运营商。 | 部分实现 | P3 | bandwidth.py; quality.py（源码审查；非通过证据） | 显式流量许可；增加受控节点、可取消 JSONL 监测；HTTPS；可选 iperf3 | tests/test_bandwidth_sources.py，逐项补缺并运行；本轮未执行 | 载荷预算不含协议开销；节点瓶颈不代表线路 | -| 06-04 | 限制带宽、并发、执行时间及流量消耗。 | 尚未实现 | P3 | bandwidth.py; quality.py（源码审查；非通过证据） | 显式流量许可；增加受控节点、可取消 JSONL 监测；HTTPS；可选 iperf3 | tests/test_bandwidth_sources.py，逐项补缺并运行；本轮未执行 | 载荷预算不含协议开销；节点瓶颈不代表线路 | -| 06-05 | 识别测试节点瓶颈，避免假性低速。 | 尚未实现 | P3 | bandwidth.py; quality.py（源码审查；非通过证据） | 显式流量许可；增加受控节点、可取消 JSONL 监测；HTTPS；可选 iperf3 | tests/test_bandwidth_sources.py，逐项补缺并运行；本轮未执行 | 载荷预算不含协议开销；节点瓶颈不代表线路 | -| 06-06 | 支持可中断的 24/48 小时低负载监测。 | 尚未实现 | P3 | bandwidth.py; quality.py（源码审查；非通过证据） | 显式流量许可；增加受控节点、可取消 JSONL 监测；HTTPS；可选 iperf3 | tests/test_bandwidth_sources.py，逐项补缺并运行；本轮未执行 | 载荷预算不含协议开销；节点瓶颈不代表线路 | -| 06-07 | 分析晚高峰性能劣化、间歇性断线、突发丢包。 | 尚未实现 | P3 | bandwidth.py; quality.py（源码审查；非通过证据） | 显式流量许可；增加受控节点、可取消 JSONL 监测；HTTPS；可选 iperf3 | tests/test_bandwidth_sources.py，逐项补缺并运行；本轮未执行 | 载荷预算不含协议开销；节点瓶颈不代表线路 | -| 06-08 | 关联 CPU steal、内存压力及网络质量的时间变化。 | 部分实现 | P3 | bandwidth.py; quality.py（源码审查；非通过证据） | 显式流量许可；增加受控节点、可取消 JSONL 监测；HTTPS；可选 iperf3 | tests/test_bandwidth_sources.py，逐项补缺并运行；本轮未执行 | 载荷预算不含协议开销；节点瓶颈不代表线路 | -| 06-09 | 中断监测时安全退出并保留已有数据。 | 尚未实现 | P3 | bandwidth.py; quality.py（源码审查；非通过证据） | 显式流量许可；增加受控节点、可取消 JSONL 监测；HTTPS；可选 iperf3 | tests/test_bandwidth_sources.py，逐项补缺并运行；本轮未执行 | 载荷预算不含协议开销；节点瓶颈不代表线路 | - - -## 第七类：基础安全体检 - - -| 编号 | 需求 | 状态 | 优先级 | 代码/证据 | 实现/依赖 | 验证方案 | 限制 | -|---|---|---|---|---|---|---|---| -| 07-01 | 只读检查 SSH 配置和潜在高风险认证方式。 | 部分实现 | P1 | checks.py（源码审查；非通过证据） | 保留 SSH/监听/防火墙只读；补更新缓存和权限检查；标准库；系统只读命令 | tests/test_checks.py; test_review.py，逐项补缺并运行；本轮未执行 | Match 条件和云安全组无法完整推断 | -| 07-02 | 检查监听端口及可能暴露的服务。 | 部分实现 | P1 | checks.py（源码审查；非通过证据） | 保留 SSH/监听/防火墙只读；补更新缓存和权限检查；标准库；系统只读命令 | tests/test_checks.py; test_review.py，逐项补缺并运行；本轮未执行 | Match 条件和云安全组无法完整推断 | -| 07-03 | 识别系统防火墙状态，说明云安全组无法从本机完整确认。 | 部分实现 | P0 | checks.py（源码审查；非通过证据） | 保留 SSH/监听/防火墙只读；补更新缓存和权限检查；标准库；系统只读命令 | tests/test_checks.py; test_review.py，逐项补缺并运行；本轮未执行 | Match 条件和云安全组无法完整推断 | -| 07-04 | 检查系统更新状态及基础安全设置。 | 部分实现 | P1 | security.py; checks.py（源码审查；非通过证据） | 保留 SSH/监听/防火墙只读；补更新缓存和权限检查；标准库；系统只读命令 | tests/test_security.py; checks.py; test_review.py，逐项补缺并运行；本轮未执行 | Match 条件和云安全组无法完整推断 | -| 07-05 | 检测重要文件权限风险。 | 部分实现 | P1 | security.py; checks.py（源码审查；非通过证据） | 保留 SSH/监听/防火墙只读；补更新缓存和权限检查；标准库；系统只读命令 | tests/test_security.py; checks.py; test_review.py，逐项补缺并运行；本轮未执行 | Match 条件和云安全组无法完整推断 | -| 07-06 | 避免把正常业务配置直接定义为漏洞。 | 尚未实现 | P1 | checks.py（源码审查；非通过证据） | 保留 SSH/监听/防火墙只读；补更新缓存和权限检查；标准库；系统只读命令 | tests/test_checks.py; test_review.py，逐项补缺并运行；本轮未执行 | Match 条件和云安全组无法完整推断 | -| 07-07 | 提供有依据的修复建议，但不自动执行。 | 部分实现 | P0 | checks.py（源码审查；非通过证据） | 保留 SSH/监听/防火墙只读；补更新缓存和权限检查；标准库；系统只读命令 | tests/test_checks.py; test_review.py，逐项补缺并运行；本轮未执行 | Match 条件和云安全组无法完整推断 | -| 07-08 | 避免泄露密码、Token、私钥及其他敏感信息。 | 尚未实现 | P1 | checks.py（源码审查；非通过证据） | 保留 SSH/监听/防火墙只读；补更新缓存和权限检查；标准库；系统只读命令 | tests/test_checks.py; test_review.py，逐项补缺并运行；本轮未执行 | Match 条件和云安全组无法完整推断 | - - -## 第八类：报告、诊断与历史记录 - - -| 编号 | 需求 | 状态 | 优先级 | 代码/证据 | 实现/依赖 | 验证方案 | 限制 | -|---|---|---|---|---|---|---|---| -| 08-01 | 设计统一的结构化检测结果 Schema。 | 尚未实现 | P2 | checks.Result; suite.run_suite; cli.redact（源码审查；非通过证据） | 兼容旧 Schema；增证据模型、增量记录、Markdown、历史差异；标准库 JSON/SQLite | tests/test_stage1.py; test_suite.py，逐项补缺并运行；本轮未执行 | 目前结束才保存；脱敏不是匿名保证 | -| 08-02 | 区分成功、失败、跳过、不支持和无法判断。 | 尚未实现 | P2 | checks.Result; suite.run_suite; cli.redact（源码审查；非通过证据） | 兼容旧 Schema；增证据模型、增量记录、Markdown、历史差异；标准库 JSON/SQLite | tests/test_stage1.py; test_suite.py，逐项补缺并运行；本轮未执行 | 目前结束才保存；脱敏不是匿名保证 | -| 08-03 | 保存检测时间、方法、来源、错误与置信度说明。 | 尚未实现 | P2 | checks.Result; suite.run_suite; cli.redact（源码审查；非通过证据） | 兼容旧 Schema；增证据模型、增量记录、Markdown、历史差异；标准库 JSON/SQLite | tests/test_stage1.py; test_suite.py，逐项补缺并运行；本轮未执行 | 目前结束才保存；脱敏不是匿名保证 | -| 08-04 | 将技术指标转换成普通用户能理解的中文解释。 | 尚未实现 | P2 | checks.Result; suite.run_suite; cli.redact（源码审查；非通过证据） | 兼容旧 Schema；增证据模型、增量记录、Markdown、历史差异；标准库 JSON/SQLite | tests/test_stage1.py; test_suite.py，逐项补缺并运行；本轮未执行 | 目前结束才保存；脱敏不是匿名保证 | -| 08-05 | 提供基于规则和真实测量结果的诊断建议。 | 尚未实现 | P2 | checks.Result; suite.run_suite; cli.redact（源码审查；非通过证据） | 兼容旧 Schema；增证据模型、增量记录、Markdown、历史差异；标准库 JSON/SQLite | tests/test_stage1.py; test_suite.py，逐项补缺并运行；本轮未执行 | 目前结束才保存；脱敏不是匿名保证 | -| 08-06 | 支持本地 JSON、Markdown 报告，必要时提供 HTML。 | 部分实现 | P2 | checks.Result; suite.run_suite; cli.redact（源码审查；非通过证据） | 兼容旧 Schema；增证据模型、增量记录、Markdown、历史差异；标准库 JSON/SQLite | tests/test_stage1.py; test_suite.py，逐项补缺并运行；本轮未执行 | 目前结束才保存；脱敏不是匿名保证 | -| 08-07 | 对分享用报告进行脱敏。 | 部分实现 | P2 | checks.Result; suite.run_suite; cli.redact（源码审查；非通过证据） | 兼容旧 Schema；增证据模型、增量记录、Markdown、历史差异；标准库 JSON/SQLite | tests/test_stage1.py; test_suite.py，逐项补缺并运行；本轮未执行 | 目前结束才保存；脱敏不是匿名保证 | -| 08-08 | 上传失败、断网或意外退出时不丢失已有报告。 | 尚未实现 | P0 | checks.Result; suite.run_suite; cli.redact（源码审查；非通过证据） | 兼容旧 Schema；增证据模型、增量记录、Markdown、历史差异；标准库 JSON/SQLite | tests/test_stage1.py; test_suite.py，逐项补缺并运行；本轮未执行 | 目前结束才保存；脱敏不是匿名保证 | -| 08-09 | 支持历史记录及不同时间、不同服务器的对比。 | 尚未实现 | P2 | checks.Result; suite.run_suite; cli.redact（源码审查；非通过证据） | 兼容旧 Schema；增证据模型、增量记录、Markdown、历史差异；标准库 JSON/SQLite | tests/test_stage1.py; test_suite.py，逐项补缺并运行；本轮未执行 | 目前结束才保存；脱敏不是匿名保证 | -| 08-10 | 生成 VPS 购买验收报告，区分实际测量与用户提供的购买规格。 | 尚未实现 | P2 | checks.Result; suite.run_suite; cli.redact（源码审查；非通过证据） | 兼容旧 Schema；增证据模型、增量记录、Markdown、历史差异；标准库 JSON/SQLite | tests/test_stage1.py; test_suite.py，逐项补缺并运行；本轮未执行 | 目前结束才保存；脱敏不是匿名保证 | -| 08-11 | 不生成未经校准的绝对性能评分。 | 尚未实现 | P2 | checks.Result; suite.run_suite; cli.redact（源码审查；非通过证据） | 兼容旧 Schema；增证据模型、增量记录、Markdown、历史差异；标准库 JSON/SQLite | tests/test_stage1.py; test_suite.py，逐项补缺并运行；本轮未执行 | 目前结束才保存；脱敏不是匿名保证 | - - -## 第九类：安装、兼容性与用户体验 - - -| 编号 | 需求 | 状态 | 优先级 | 代码/证据 | 实现/依赖 | 验证方案 | 限制 | -|---|---|---|---|---|---|---|---| -| 09-01 | 实现面向小白的一键安装与运行。 | 尚未实现 | P3 | proxydoctor.sh; pyproject.toml; README.md（源码审查；非通过证据） | 虚拟环境安装、版本校验、受控更新卸载；Python >=3.10；setuptools | tests/test_phase1_delivery.py; test_i18n.py，逐项补缺并运行；本轮未执行 | 现有脚本只启动，不隔离安装；ARM 未实测 | -| 09-02 | 检查 Python 版本、依赖及权限。 | 尚未实现 | P3 | proxydoctor.sh; pyproject.toml; README.md（源码审查；非通过证据） | 虚拟环境安装、版本校验、受控更新卸载；Python >=3.10；setuptools | tests/test_phase1_delivery.py; test_i18n.py，逐项补缺并运行；本轮未执行 | 现有脚本只启动，不隔离安装；ARM 未实测 | -| 09-03 | 使用虚拟环境隔离依赖，不污染系统 Python。 | 尚未实现 | P3 | proxydoctor.sh; pyproject.toml; README.md（源码审查；非通过证据） | 虚拟环境安装、版本校验、受控更新卸载；Python >=3.10；setuptools | tests/test_phase1_delivery.py; test_i18n.py，逐项补缺并运行；本轮未执行 | 现有脚本只启动，不隔离安装；ARM 未实测 | -| 09-04 | 优先兼容 Ubuntu 22.04 Server、24.04 Desktop。 | 尚未实现 | P3 | proxydoctor.sh; pyproject.toml; README.md（源码审查；非通过证据） | 虚拟环境安装、版本校验、受控更新卸载；Python >=3.10；setuptools | tests/test_phase1_delivery.py; test_i18n.py，逐项补缺并运行；本轮未执行 | 现有脚本只启动，不隔离安装；ARM 未实测 | -| 09-05 | 评估其他发行版、容器、ARM/x86 架构兼容性。 | 外部条件不足，待实机验证 | P3 | proxydoctor.sh; pyproject.toml; README.md（源码审查；非通过证据） | 虚拟环境安装、版本校验、受控更新卸载；Python >=3.10；setuptools | tests/test_phase1_delivery.py; test_i18n.py，逐项补缺并运行；本轮未执行 | 现有脚本只启动，不隔离安装；ARM 未实测 | -| 09-06 | 提供中文和英文输出，处理终端编码问题。 | 部分实现 | P3 | proxydoctor.sh; pyproject.toml; README.md（源码审查；非通过证据） | 虚拟环境安装、版本校验、受控更新卸载；Python >=3.10；setuptools | tests/test_phase1_delivery.py; test_i18n.py，逐项补缺并运行；本轮未执行 | 现有脚本只启动，不隔离安装；ARM 未实测 | -| 09-07 | 尽可能支持非 root 检测。 | 部分实现 | P3 | proxydoctor.sh; pyproject.toml; README.md（源码审查；非通过证据） | 虚拟环境安装、版本校验、受控更新卸载；Python >=3.10；setuptools | tests/test_phase1_delivery.py; test_i18n.py，逐项补缺并运行；本轮未执行 | 现有脚本只启动，不隔离安装；ARM 未实测 | -| 09-08 | 缺少依赖时友好提示、降级或跳过。 | 尚未实现 | P3 | proxydoctor.sh; pyproject.toml; README.md（源码审查；非通过证据） | 虚拟环境安装、版本校验、受控更新卸载；Python >=3.10；setuptools | tests/test_phase1_delivery.py; test_i18n.py，逐项补缺并运行；本轮未执行 | 现有脚本只启动，不隔离安装；ARM 未实测 | -| 09-09 | 提供帮助、参数说明、更新、卸载和离线说明。 | 尚未实现 | P3 | proxydoctor.sh; pyproject.toml; README.md（源码审查；非通过证据） | 虚拟环境安装、版本校验、受控更新卸载；Python >=3.10；setuptools | tests/test_phase1_delivery.py; test_i18n.py，逐项补缺并运行；本轮未执行 | 现有脚本只启动，不隔离安装；ARM 未实测 | -| 09-10 | 安装脚本可审查，采用可信来源及版本固定/完整性验证。 | 尚未实现 | P3 | proxydoctor.sh; pyproject.toml; README.md（源码审查；非通过证据） | 虚拟环境安装、版本校验、受控更新卸载；Python >=3.10；setuptools | tests/test_phase1_delivery.py; test_i18n.py，逐项补缺并运行；本轮未执行 | 现有脚本只启动，不隔离安装；ARM 未实测 | -| 09-11 | 不要求用户盲目执行来源不明的 curl | bash。 | 尚未实现 | P3 | proxydoctor.sh; pyproject.toml; README.md（源码审查；非通过证据） | 虚拟环境安装、版本校验、受控更新卸载；Python >=3.10；setuptools | tests/test_phase1_delivery.py; test_i18n.py，逐项补缺并运行；本轮未执行 | 现有脚本只启动，不隔离安装；ARM 未实测 | - - -## 第十类：可靠性、隐私与自动化测试 - - -| 编号 | 需求 | 状态 | 优先级 | 代码/证据 | 实现/依赖 | 验证方案 | 限制 | -|---|---|---|---|---|---|---|---| -| 10-01 | 验证默认检测确实不修改系统配置。 | 尚未实现 | P0 | net.py; console.py; checks.Host; __main__.py（源码审查；非通过证据） | 模块隔离、全局预算、取消保存、终端与日志脱敏；Mock/pytest（开发依赖） | tests/，逐项补缺并运行；本轮未执行 | 修改后未测试；真实 VPS 尚缺 | -| 10-02 | 区分普通检测与高负载、有写入的基准测试。 | 尚未实现 | P0 | net.py; console.py; checks.Host; __main__.py（源码审查；非通过证据） | 模块隔离、全局预算、取消保存、终端与日志脱敏；Mock/pytest（开发依赖） | tests/，逐项补缺并运行；本轮未执行 | 修改后未测试；真实 VPS 尚缺 | -| 10-03 | 对运行时间、CPU、磁盘、流量设置安全上限。 | 尚未实现 | P0 | net.py; console.py; checks.Host; __main__.py（源码审查；非通过证据） | 模块隔离、全局预算、取消保存、终端与日志脱敏；Mock/pytest（开发依赖） | tests/，逐项补缺并运行；本轮未执行 | 修改后未测试；真实 VPS 尚缺 | -| 10-04 | 处理超时、网络失败、权限错误和依赖缺失。 | 部分实现 | P0 | net.py; console.py; checks.Host; __main__.py（源码审查；非通过证据） | 模块隔离、全局预算、取消保存、终端与日志脱敏；Mock/pytest（开发依赖） | tests/，逐项补缺并运行；本轮未执行 | 修改后未测试；真实 VPS 尚缺 | -| 10-05 | 保证模块故障隔离。 | 尚未实现 | P0 | net.py; console.py; checks.Host; __main__.py（源码审查；非通过证据） | 模块隔离、全局预算、取消保存、终端与日志脱敏；Mock/pytest（开发依赖） | tests/，逐项补缺并运行；本轮未执行 | 修改后未测试；真实 VPS 尚缺 | -| 10-06 | 处理 Ctrl+C、安全取消与临时文件清理。 | 尚未实现 | P0 | net.py; console.py; checks.Host; __main__.py（源码审查；非通过证据） | 模块隔离、全局预算、取消保存、终端与日志脱敏；Mock/pytest（开发依赖） | tests/，逐项补缺并运行；本轮未执行 | 修改后未测试；真实 VPS 尚缺 | -| 10-07 | 防止命令注入、路径问题、终端控制字符污染和敏感日志泄露。 | 尚未实现 | P0 | net.py; console.py; checks.Host; __main__.py（源码审查；非通过证据） | 模块隔离、全局预算、取消保存、终端与日志脱敏；Mock/pytest（开发依赖） | tests/，逐项补缺并运行；本轮未执行 | 修改后未测试；真实 VPS 尚缺 | -| 10-08 | 使用 Mock、单元测试、集成测试和异常场景测试。 | 部分实现 | P0 | net.py; console.py; checks.Host; __main__.py（源码审查；非通过证据） | 模块隔离、全局预算、取消保存、终端与日志脱敏；Mock/pytest（开发依赖） | tests/，逐项补缺并运行；本轮未执行 | 修改后未测试；真实 VPS 尚缺 | -| 10-09 | 在两种 Ubuntu 虚拟机及真实 VPS 上验证。 | 外部条件不足，待实机验证 | P0 | net.py; console.py; checks.Host; __main__.py（源码审查；非通过证据） | 模块隔离、全局预算、取消保存、终端与日志脱敏；Mock/pytest（开发依赖） | tests/，逐项补缺并运行；本轮未执行 | 修改后未测试；真实 VPS 尚缺 | -| 10-10 | 建立安全的社区错误反馈方式。 | 尚未实现 | P0 | net.py; console.py; checks.Host; __main__.py（源码审查；非通过证据） | 模块隔离、全局预算、取消保存、终端与日志脱敏；Mock/pytest（开发依赖） | tests/，逐项补缺并运行；本轮未执行 | 修改后未测试；真实 VPS 尚缺 | -| 10-11 | 检查第三方许可证、依赖安全和 API 使用条款。 | 尚未实现 | P0 | net.py; console.py; checks.Host; __main__.py（源码审查；非通过证据） | 模块隔离、全局预算、取消保存、终端与日志脱敏；Mock/pytest（开发依赖） | tests/，逐项补缺并运行；本轮未执行 | 修改后未测试；真实 VPS 尚缺 | - - -## 第十一类：开源维护与未来 FlexMaster 集成 - - -| 编号 | 需求 | 状态 | 优先级 | 代码/证据 | 实现/依赖 | 验证方案 | 限制 | -|---|---|---|---|---|---|---|---| -| 11-01 | 每个检测模块既能由 CLI 使用，也能通过 Python API 调用。 | 尚未实现 | P1 | 现有模块函数; CONTRIBUTING.md; LICENSE（源码审查；非通过证据） | 稳定 Python API、文档与 Issue 模板、许可登记；标准库；无新运行依赖 | tests/，逐项补缺并运行；本轮未执行 | 核心仍与 UI 混合；不承诺已兼容 FlexMaster | -| 11-02 | 检测核心与终端 UI 解耦。 | 尚未实现 | P1 | 现有模块函数; CONTRIBUTING.md; LICENSE（源码审查；非通过证据） | 稳定 Python API、文档与 Issue 模板、许可登记；标准库；无新运行依赖 | tests/，逐项补缺并运行；本轮未执行 | 核心仍与 UI 混合；不承诺已兼容 FlexMaster | -| 11-03 | 为未来 FlexMaster 设计稳定、可复用的接口。 | 尚未实现 | P1 | 现有模块函数; CONTRIBUTING.md; LICENSE（源码审查；非通过证据） | 稳定 Python API、文档与 Issue 模板、许可登记；标准库；无新运行依赖 | tests/，逐项补缺并运行；本轮未执行 | 核心仍与 UI 混合；不承诺已兼容 FlexMaster | -| 11-04 | 完善 README、安装说明、贡献指南及测试文档。 | 尚未实现 | P1 | 现有模块函数; CONTRIBUTING.md; LICENSE（源码审查；非通过证据） | 稳定 Python API、文档与 Issue 模板、许可登记；标准库；无新运行依赖 | tests/，逐项补缺并运行；本轮未执行 | 核心仍与 UI 混合；不承诺已兼容 FlexMaster | -| 11-05 | 提供标准 GitHub Issue 模板和脱敏日志机制。 | 部分实现 | P1 | 现有模块函数; CONTRIBUTING.md; LICENSE（源码审查；非通过证据） | 稳定 Python API、文档与 Issue 模板、许可登记；标准库；无新运行依赖 | tests/，逐项补缺并运行；本轮未执行 | 核心仍与 UI 混合；不承诺已兼容 FlexMaster | -| 11-06 | 明确支持系统、已知问题和未验证环境。 | 尚未实现 | P1 | 现有模块函数; CONTRIBUTING.md; LICENSE（源码审查；非通过证据） | 稳定 Python API、文档与 Issue 模板、许可登记；标准库；无新运行依赖 | tests/，逐项补缺并运行；本轮未执行 | 核心仍与 UI 混合；不承诺已兼容 FlexMaster | -| 11-07 | 建立外部贡献代码审查与自动化测试规范。 | 尚未实现 | P1 | 现有模块函数; CONTRIBUTING.md; LICENSE（源码审查；非通过证据） | 稳定 Python API、文档与 Issue 模板、许可登记；标准库；无新运行依赖 | tests/，逐项补缺并运行；本轮未执行 | 核心仍与 UI 混合；不承诺已兼容 FlexMaster | -| 11-08 | 为开源发布准备合适的 LICENSE、依赖声明及第三方版权通知。 | 部分实现 | P1 | 现有模块函数; CONTRIBUTING.md; LICENSE（源码审查；非通过证据） | 稳定 Python API、文档与 Issue 模板、许可登记；标准库；无新运行依赖 | tests/，逐项补缺并运行；本轮未执行 | 核心仍与 UI 混合；不承诺已兼容 FlexMaster | - -共登记 101 项。每行验收前须补测量记录与精确证据；不得批量升级完成状态。 - -## P0 第二组实现记录（2026-11-01，未测试） - -- `runner.py`：六模块独立执行边界、固定错误码、取消透传、执行状态与时间。 -- `reports.py`：独占创建、脱敏增量 JSONL、flush/fsync、最终 JSON、恢复读取 API、存储失败降级。 -- `suite.py`：接入默认本地保存、Ctrl+C 保存/130、失败模块继续；`quality.py`/`routes.py`/`media.py` 增加结果保存回调。 -- `tests/test_recovery.py`：新增模块错误、取消、尾部损坏、写入冲突、符号链接及刷盘失败场景，未执行。 - -关联第八类保存/中断、第十类故障隔离/取消需求由“尚未实现”推进为“部分实现（未测试）”；尚不能标记已实现且通过测试。完整限制见架构和测试计划的 Reliability batch。 - - -## 资源检测第三组（2026-11-01：已编写，未测试） - -- 新增 `proxydoctor/resources.py`，提供独立 `collect()` Python API 和数值渲染。接入综合检测的独立 resources 模块及 `check` 的 JSON/终端输出。 -- 读取 `/proc/self/cgroup` 和 mountinfo，映射 cgroup v1/v2 挂载与成员路径，取最多 64 级可见父级中的最严格 CPU/内存配额；结合 sched_getaffinity 和逻辑 CPU 数计算可见 CPU 上限。 -- 输出内存可见上限、Swap 总量/使用量、cgroup 当前内存使用及 CPU/内存/IO PSI。保留数字和单位，不解析中文描述；缺失或格式不合法保持未知。 -- 对 `/proc/stat` 进行默认 0.2 秒被动采样，计算 steal 的计数差值比例。排除重复包含在 user/nice 中的 guest 字段；计数回退、缺失或无增量保持未知。 -- 新增 `tests/test_resources.py` 的七个 fixture 场景：v2 父级限制、v1、子树挂载、缺失/非法数据、steal 差值、被动采样和非 Linux 降级。均未执行。 - -限制：namespace 隐藏的父级无法确认；混合层级/特殊挂载仍待实机验证。cgroup 当前内存用量与最严格父级上限可能属于不同层级，不可相减充当可用内存。meminfo、PSI、steal 可能反映宿主视图；不代表容器专属指标或长期超售证据。配额为可见上限，不证明独享、保证容量或购买规格。短采样不是 CPU 性能基准，颜色表示数据是否可读，暂不判断压力高低。 - -尚未实现：虚拟化类型细化、CPU 频率与购买规格对比、可授权 CPU/磁盘基准。没有运行测试或 VM 实测，不更新为“已实现且通过测试”。 - -实现语义参考 Linux 内核官方文档： - -- [cgroup v2](https://docs.kernel.org/admin-guide/cgroup-v2.html)（层级限制、cpu.max、memory.max） -- [PSI](https://docs.kernel.org/accounting/psi.html)（avg10/60/300 百分比和 total 微秒） -- [/proc](https://docs.kernel.org/filesystems/proc.html)（CPU 计数与内存字段） - -下次验收需先运行新增测试和现有回归，再分别在 Ubuntu 22.04 Server、24.04 Desktop 验证宿主/cgroup/权限视图；真实 VPS 未具备，不以 VM 代替。 - - -## 双栈网络第四组（2026-11-01，已编写但未测试） - -新增 `connectivity.py`，接入 `suite` 和 `quality`；旧 quality.py API 保留但不再是这两个 CLI 入口的主检测。每协议族默认2次独立系统解析（每次2秒子进程时限），4个固定数字IP端点执行 TCP→证书验证TLS（每目标4秒网络预算）。DNS时间包含进程启动、系统缓存与解析，不能作为纯DNS服务器延迟；成功率仅为本次小样本。 - -分离DNS/TCP/TLS结果，TCP成功且TLS失败时保留两者；错误不含原始异常、URL凭证。固定端点不代表全互联网或中国运营商，TLS不验证HTTP业务可用性。仅观察出站；未测UDP/PMTU/入站/云安全组。没有真实网络执行；网络时限不等于进程所有本地调度/证书加载时间的绝对总上限。 - -增加 `tests/test_connectivity.py` 六个场景：DNS无地址/超时、协议族错误、证书失败保留TCP成功、分族样本统计、探针错误隔离、Ctrl+C透传。尚未执行。 - -逐项状态仍为部分实现；02类 DNS/TCP/TLS 代码证据新增 connectivity.py。整体进度见 CURRENT_STATUS.md。 - -## 基础安全第五组（2026-11-01：实现未测试） - -新增 `proxydoctor/security.py`：独立 Python collect/render API，接入 suite 独立安全模块和 check 的结构化/双语终端输出。检查固定9个文件/目录的 lstat 权限、所有者和类型，不读取 shadow/gshadow 内容、不提权、不刷新包缓存、不执行任何修复。检测世界可写、同组可写、非root所有者、敏感文件世界可读，均为人工审阅提示而非漏洞确认；shadow 的同组只读本身不报风险。符号链接不跟随判断，结果未知。 - -更新状态只读取 apt 成功时间戳和可选 update-notifier 缓存的明确英文计数。记录缓存年龄；无缓存/无权限/本地化或不识别格式不解释为零更新。未调用 apt update/upgrade，不联网、不查询付费API。即使缓存为0也不能证明无漏洞或已完整修补。仅固定入口/父目录，不递归审计 sudoers.d/sshd_config.d；ACL、capabilities、运行态、ESM/订阅资格和完整包版本安全比对未实现。 - -新增 `tests/test_security.py` 九个离线场景（含权限、符号链接、错误不泄密、缓存缺失/年龄/本地化、禁止读取私密内容和非Linux降级），本轮没有执行测试。此前与本轮全部新增实现仍待回归和双Ubuntu实测。 diff --git a/README.en.md b/README.en.md index 31cf0e1..7353acf 100644 --- a/README.en.md +++ b/README.en.md @@ -1,124 +1,86 @@ # VPSMaster -**VPS Diagnostics & Security Hardening Toolkit** +**Know your VPS. Manage your server more safely.** -Open-source Linux VPS diagnostics, security auditing and future safe server hardening toolkit. +VPS Diagnostics & Security Toolkit — an open-source Linux VPS diagnostics and security management toolkit. -[中文](README.md) · [English](README.en.md) · [Limitations](KNOWN_LIMITATIONS.md) · [Contributing](CONTRIBUTING.md) +![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue) ![Linux](https://img.shields.io/badge/Platform-Linux-lightgrey) [![MIT License](https://img.shields.io/badge/License-MIT-green)](LICENSE) ![Beta.1](https://img.shields.io/badge/Status-Beta.1-orange) -VPSMaster is a Python toolkit for Linux VPS users, especially beginners and the Chinese Linux community. -The **1.0.0b1 Beta is CLI-focused**: transparent diagnostics are available; Linux security hardening, safe backup/rollback, continuous monitoring and Web UI remain planned. The aim is controlled, auditable and recoverable management. -Routine checks do not change SSH, firewall, routes or system DNS. Missing evidence remains unknown. +[中文首页](README.md) · [Usage](docs/guide/USAGE.md) · [Issues](https://github.com/griffinmx/VPSMaster/issues) -## Available +## About -| Area | Current Beta | Boundary | -| --- | --- | --- | -| System/resources | OS, kernel, CPU, memory, Swap, disk capacity, visible quotas, short steal/PSI samples | No dedicated-hardware proof or CPU/disk benchmark | -| Network | DNS, IPv4/IPv6 TCP and certificate-verified TLS, interfaces/routes | Subject to permissions, connectivity and target availability | -| Traceroute | Native UDP; optional system ICMP/TCP; IP, RTT, timeout, optional ASN/operator/location | 30 TTLs by default, max64; router silence is not forwarding loss | -| BGP/ASN | RIPE RIS prefixes, origins, neighbours and AS_PATH samples | Collector view, not local packet paths or commercial relationships | -| IP risk | Provider-specific ownership, network type, proxy/VPN/Tor/risk evidence, conflicts | Quotas, missing fields and disagreement remain visible | -| Media | Ten public service pages, including Netflix, Disney+ and YouTube | Reachability only, no unlock or account playback guarantee | -| Security | Read-only SSH, ports, firewall, selected permissions and update caches | No full vulnerability scan or automatic repair | -| Reports | Local redacted JSON/Markdown, recovery journals, English/Chinese themes | Review before sharing; incomplete data may remain partial | -| Opt-in tests | Bounded repeated bandwidth and fixed China targets | Mainland three-carrier coverage is experimental, disabled by default | +Built with Python for VPS beginners and Linux users, VPSMaster helps explain server resources, connectivity, IP information and basic security risks. Beta.1 provides CLI diagnostics and local reports. Default diagnostics are read-only and do not modify SSH, firewall, routes or system DNS. -Execution success does not mean every provider or destination is available. Results retain status, method, time, source and limitations. +The project aims to grow into a Linux security diagnostics and hardening assistant, with SSH/firewall hardening, configuration backup and rollback, continuous security monitoring and a local Web UI as future priorities. -## Install and use +## Features -Requires Linux, Python3.10+ and stdlib venv. No third-party Python runtime dependencies, pip, sudo or automatic system package installation. -Obtain the ZIP/checksum through a trusted channel and review install.py. A checksum detects change, not publisher authenticity. +| Module | Available now | +| --- | --- | +| Server | Linux, CPU, memory, swap, disk capacity, virtualization and resource observations | +| Network | DNS, TCP/TLS, IPv4/IPv6 and UDP/ICMP/TCP traceroute | +| Routing & IP | BGP, ASN, ownership, network types and provider-specific risk observations | +| Services | Basic public-page reachability for selected media services | +| Security | Read-only SSH, port, firewall and file-permission checks | +| Reports | Chinese/English CLI, local JSON/Markdown, redaction and interruption recovery | + +## Install + +Requires **Linux, Python 3.10+ and standard-library venv**. Download the ZIP and matching `SHA256SUMS.txt` from [Releases](https://github.com/griffinmx/VPSMaster/releases) into the same directory. During private testing, access is restricted; a release draft is not a generally available published download. ```bash -sha256sum -c VPSMaster-v1.0.0-beta.1.zip.sha256 +sha256sum -c SHA256SUMS.txt python3 -m zipfile -e VPSMaster-v1.0.0-beta.1.zip . cd VPSMaster-v1.0.0-beta.1 python3 -I -B install.py --run +``` + +The installer creates an isolated user environment and prints the launcher path. The first scan is offline. Root is not required; the installer invokes neither pip, sudo nor a system package manager. Missing dependencies produce an error without changing the system. [Installation guide](docs/guide/INSTALL.md) + +## Common commands + +Use the printed launcher path for custom installations; the default is: + +```bash VM="$HOME/.local/share/vpsmaster/1.0.0b1/bin/vpsmaster" -"$VM" --version -"$VM" check --theme framed --lang en +"$VM" check --lang en "$VM" suite --offline --lang en "$VM" quality --lang en -"$VM" trace --target 1.1.1.1 --method tcp --tcp-port 443 --geo --lang en -"$VM" bgp --target 1.1.1.1 --lang en -"$VM" media --lang en -"$VM" suite --lang en --json-output report.json -"$VM" report --input report.json --output report.md --lang en -"$VM" recover --journal report.json.events.jsonl --output recovered.json --lang en +"$VM" trace --target 1.1.1.1 --method udp +"$VM" ipquality +"$VM" suite --json-output report.json +"$VM" report --input report.json --output report.md +"$VM" --help ``` -`--run` initially performs offline checks. Existing installation/report paths are refused; choose a new user-owned `--prefix` for a separate install. -ICMP/TCP require an existing system traceroute and appropriate permissions. Missing dependency/permission failures are explicit; there is no automatic elevation. -Online commands contact external services, which see the source IP. `check` is offline unless its explicit public-IP lookup is selected. +The legacy `proxydoctor` command remains compatible. See [usage](docs/guide/USAGE.md) for full options and opt-in bandwidth tests. Remote services see your source IP; review redacted reports before sharing. -Bandwidth needs explicit consent, for example `bandwidth --allow-bandwidth --rounds 3 --sample-mib 4`. -`--china` selects experimental mainland candidates; availability is incomplete. Hong Kong Mobile never substitutes for mainland Mobile. -Download means node → this host, upload means this host → node. Short samples are not line capacity. -The current `attempted` summary counts scheduled sample slots, including skipped slots, not actual wire requests; inspect sample errors. +## Beta limitations -### Compatibility +- Media checks test page reachability, not unlocking or playback. Mainland three-carrier bandwidth tests are experimental and off by default. +- ICMP/TCP may require system `traceroute` and permissions. BGP, geography and risk observations depend on third-party data. +- Lab coverage: Ubuntu 22.04 Desktop and 24.04 Server, x86_64. Overseas VPS, ARM, public IPv6 and a fresh Ubuntu 22.04 Server image are not comprehensively validated. +- No one-click hardening, automatic proxy deployment or Web UI. Beta does not imply production stability or independent security certification. -Former project name: **ProxyDoctor**. New visible brand/command: **VPSMaster / vpsmaster**. -The installer also creates the legacy `proxydoctor` launcher. Python package/distribution identity `proxydoctor`, imports, JSON schemas and `PROXYDOCTOR_*` variables remain compatible. -New installs default to `~/.local/share/vpsmaster/1.0.0b1`; old directories/reports are not migrated or overwritten. -Both source scripts `vpsmaster.sh` and `proxydoctor.sh` remain usable. Supplied launchers/workers use `-B`; arbitrary external imports are outside that promise. +[Detailed limitations](docs/release/KNOWN_LIMITATIONS.md) · [Release notes](docs/release/RELEASE_NOTES.md) -### Illustrative CLI output +## Roadmap -Placeholders below show structure, **not benchmark results for this build**: +| Phase | Direction | Status | +| --- | --- | --- | +| 1 · VPS diagnostics | Resources, connectivity, routes, BGP/IP, basic security and recoverable reports | Current Beta foundation | +| 2 · Improve diagnostics | CPU/disk benchmarks, mainland carrier tests, IP cross-checking, routing advice, security baselines and purchase acceptance | Planned | +| 3 · Security hardening | SSH/key policies, UFW/nftables, Fail2ban, updates and permissions, with selectable plans and previews | Planned; future priority | +| 4 · Backup, rollback & monitoring | Configuration backups/diffs, SSH access protection, verification, conditional rollback, auditing and monitoring | Planned | +| 5 · Visual management | Local Web UI, risks/tasks, recovery, multiple VPS and optional service management | Long-term plan | -```text -1.0.0b1 · VPSMaster · 1.0 public beta (not the final release) - 1 127.0.0.1 ms Private/reserved AS? --- [reached] -Trace result reached -Recovery journal: -``` +Future hardening requires explicit confirmation: **detect → explain → preview → confirm → back up → execute → verify → roll back**. Protecting SSH access is essential; rollback cannot cover every outage. A future management UI must not expose its entry point publicly by default. -## Validation and limitations +Future capabilities are not implemented or included in this Beta, and have no fixed delivery dates. [Detailed roadmap](docs/security/ROADMAP.md) -Lab baselines are Ubuntu22.04.5 Desktop/Python3.10.12 and Ubuntu24.04.3 Server/Python3.12.3, x86_64. -Each VPSMaster candidate requires fresh installation from its final ZIP; only a matching-SHA acceptance report establishes that build's pass. -The old ProxyDoctor ZIP is preserved and cannot be renamed as proof for the new build. -ICMP/TCP loopback success and limited public observations do not establish complete public routing. +## Documentation & contributing -- Media is public-page reachability, not unlock, paid entitlement or actual playback. -- Mainland three-carrier speed testing is experimental and off by default. -- BGP/geolocation depend on third-party accuracy, terms and quotas; geography is estimated. -- Overseas VPS, ARM, public IPv6 and a fresh Ubuntu22 Server image are not comprehensively validated. -- PTY bytes/width checks do not prove GUI font rendering. Beta is not production stability or independent security certification. -- No Web UI, one-click hardening, automated proxy deployment, full management panel, long monitoring or CPU/disk benchmarks are currently provided. +[Usage](docs/guide/USAGE.md) · [中文首页](README.md) · [Installation](docs/guide/INSTALL.md) · [Limitations](docs/release/KNOWN_LIMITATIONS.md) · [Roadmap](docs/security/ROADMAP.md) -See [full limitations](KNOWN_LIMITATIONS.md), [status](CURRENT_STATUS.md) and [Beta notes](RELEASE_NOTES.md). - -## Security and privacy - -No default configuration changes, automatic repairs or full-report uploads. Installation creates a user venv; diagnostics/reports create local files. -`--show-ip` affects the terminal; exported files mask known IP/credential patterns, not arbitrary identifying text. Review before sharing. -Ctrl+C/SIGTERM attempts cancellation and persistence; recovery uses the last complete journal event. SIGKILL, power/storage failure can prevent final JSON. -Exit codes: 0 completed, 1 findings/incomplete/storage failure, 2 usage/install error, 130 cancelled. -Never publish raw logs, subscriptions, passwords, tokens or keys. See [SECURITY.md](SECURITY.md). - -## Roadmap — Planned - -**Trusted diagnostics now; safe Linux hardening is the future focus.** None of these plans imply current implementation or fixed delivery dates. - -1. **Detection:** CPU/disk benchmarks, mainland carrier coverage, network/BGP analysis, IP intelligence cross-checks, accuracy/compatibility and more security rules. -2. **One-click hardening:** SSH/key/password policy, UFW/nftables, Fail2ban, unused services/ports, updates/patches, permissions and Linux baselines; explain risks, preview plans and let users select actions. -3. **Backup, verification and rollback:** back up before changes, show diffs, verify alternative SSH access and preserve management channels, recheck connectivity, bounded rollback where reliable, audit logs and recovery guidance. Rollback cannot guarantee recovery from every outage, reboot, cloud firewall or host failure. -4. **Continuous monitoring:** periodic audits, configuration drift, unusual SSH login/port changes, report history, update/risk alerts, network stability and purchase acceptance reports. -5. **Visual security management:** local Web UI, evidence-based risk display, hardening tasks, backup/rollback interface, multi-server exploration and optional service maintenance. No public management listener by default. - -Future flow: **detect → explain → preview → confirm → back up → execute → verify → roll back**. -Explicit consent, alternative SSH access, cloud-firewall awareness, business-port protection, idempotency and audit records are required. High-risk changes must not be unattended defaults; disabling protection or broadening permissions is not a repair strategy. See [SECURITY_ROADMAP.md](SECURITY_ROADMAP.md). - -## Contributing, Issues and license - -See [CONTRIBUTING.md](CONTRIBUTING.md). Use the authorized private repository’s [Issues](https://github.com/griffinmx/VPSMaster/issues) → New issue tab with the bundled [bug](.github/ISSUE_TEMPLATE/bug_report.md) or [feature](.github/ISSUE_TEMPLATE/feature_request.md) template. -The repository is Private; public access needs owner approval. Use private channels for sensitive vulnerability reports. - -MIT project; former-brand contributor notices remain in [LICENSE](LICENSE). -No third-party traceroute clients, databases or remote test scripts are bundled/executed. References/attribution are in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) and [OPEN_SOURCE_REFERENCES.md](OPEN_SOURCE_REFERENCES.md). -Our license does not grant rights to third-party APIs/data/test services; their terms, quotas and permissions apply separately. -Reports do not expire automatically; review [data-service retention/sharing terms](docs/DATA_SERVICES.md), including applicable IP2Location cache limits. +[Documentation](docs/README.md) · [Security/privacy](docs/security/SECURITY.md) · [Issues](https://github.com/griffinmx/VPSMaster/issues) · [Contributing](docs/development/CONTRIBUTING.md) · [MIT License](LICENSE) · [Third-party notices](THIRD_PARTY_NOTICES.md) diff --git a/README.md b/README.md index 8ecce85..7128bbf 100644 --- a/README.md +++ b/README.md @@ -1,191 +1,86 @@ # VPSMaster -**VPS Diagnostics & Security Hardening Toolkit** +**看清你的 VPS，让服务器管理更安全。** -面向Linux VPS用户的开源服务器检测与安全管理工具。 +VPS Diagnostics & Security Toolkit — 面向 VPS 新手和 Linux 用户的开源检测与安全管理工具。 -[中文](README.md) · [English](README.en.md) · [已知限制](KNOWN_LIMITATIONS.md) · [贡献指南](CONTRIBUTING.md) +![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue) ![Linux](https://img.shields.io/badge/Platform-Linux-lightgrey) [![MIT License](https://img.shields.io/badge/License-MIT-green)](LICENSE) ![Beta.1](https://img.shields.io/badge/Status-Beta.1-orange) -VPSMaster 是一款基于Python、面向Linux VPS用户的开源服务器检测与安全管理工具，提供系统环境检测、网络质量诊断、IP信息分析及基础安全体检。主要面向中文Linux社区及VPS初学者，也帮助有经验的用户了解服务器状态和风险。 +[English](README.en.md) · [使用文档](docs/guide/USAGE.md) · [反馈问题](https://github.com/griffinmx/VPSMaster/issues) -当前以安全、易用、默认只读的CLI为基础；未来重点是Linux安全加固、配置备份/回滚、持续安全监控与可视化管理，目标是可控、可审计、可回滚的服务器管理。 -**当前 `1.0.0b1` 是以 CLI 为核心的 Beta 公测候选，非生产稳定版；管理能力仍在规划中。** -项目强调安全、易用和检测结果透明：普通检测默认不修改 SSH、防火墙、路由或系统 DNS，未知结果不会被写成安全或成功。 +## 项目简介 -> Open-source Linux VPS diagnostics, security auditing and future safe server hardening toolkit. Current Beta is read-only diagnostics; hardening and Web UI are Planned. +VPSMaster 基于 Python，帮助你快速了解 Linux VPS 的硬件资源、网络质量、IP 信息及基础安全风险。当前 Beta.1 提供 CLI 检测与本地报告，普通检测默认只读，不修改 SSH、防火墙、路由或系统 DNS。 -## Available / 当前可用 +项目将从 VPS 检测工具逐步发展为 Linux 服务器安全诊断与加固助手，未来重点是 SSH 与防火墙安全加固、配置备份与回滚、持续安全监控及 Web UI 管理。 -| 模块 | 当前 Beta 能力 | 判断边界 | -| --- | --- | --- | -| 服务器信息与资源 | Linux/内核/架构、CPU、内存、Swap、磁盘容量、可见配额、短时 steal/PSI | 不能证明硬件独享；没有 CPU/磁盘基准 | -| 网络基础 | DNS、分 IPv4/IPv6 的 TCP、证书验证 TLS、接口和路由信息 | 取决于权限、网络和目标服务，保留错误与未知 | -| Traceroute | 自主 UDP，可选系统 traceroute 的 ICMP/TCP；IP、RTT、响应/超时、可选 ASN/位置 | 默认30跳、最多64跳；跳点不响应不等于真实转发丢包 | -| BGP / ASN | RIPE RIS 前缀、起源 ASN、邻居及有限 AS_PATH 样本 | 采集器视角，不代表本机选路、商业上游或优质线路承诺 | -| IP 信息与风险 | 多来源归属、网络类型、代理/VPN/Tor/风险信息及冲突；可选 PTR/TCP25 | 不合成不透明“纯净度”；第三方可能失败、限额或缺字段 | -| 流媒体网页 | Netflix、Disney+、YouTube 等10项公开服务页面的基础可达性 | **不保证解锁、登录后地区权限或实际播放** | -| 基础安全体检 | SSH、监听端口、防火墙、固定敏感路径权限、更新缓存 | 只读提示，不是完整漏洞扫描或自动修复 | -| 本地报告 | 脱敏 JSON、Markdown、逐步恢复日志、失败隔离、中英文终端主题 | 分享前仍需人工复核；断电/SIGKILL不能保证未落盘数据 | -| 可选带宽与中国目标 | 多来源多轮有界下载/部分上传、固定中国候选与三城九方向追踪入口 | 需明确允许流量；大陆三网实验性，默认关闭；不是完整全国回程 | +## 核心功能 -“模块执行完成”不等于目标可用或检测结论完整。`success / failure / skipped / unsupported / unknown` 与原因、时间、方法和来源分别保留。 +| 模块 | 当前功能 | +| --- | --- | +| 服务器检测 | Linux、CPU、内存、Swap、磁盘、虚拟化与资源状态 | +| 网络诊断 | DNS、TCP/TLS、IPv4/IPv6、UDP/ICMP/TCP Traceroute | +| 线路与 IP | BGP、ASN、IP 归属、网络类型和风险来源 | +| 服务可达性 | 部分流媒体等公开网页可达性检查 | +| 基础安全体检 | SSH、端口、防火墙、文件权限等只读检查 | +| 本地报告 | 中英文 CLI、JSON、Markdown、脱敏与中断恢复 | -## 安装 +## 快速安装 -需要 Linux、Python **3.10+** 及标准库 `venv`。运行时没有第三方 Python 包依赖；安装器不调用 pip、sudo 或系统包管理器。 -先从可信渠道取得 ZIP 和校验文件，并阅读 `install.py`；校验和不能独立证明发布者身份。 +需要 **Linux、Python 3.10+ 和标准库 venv**。从 [GitHub Releases](https://github.com/griffinmx/VPSMaster/releases) 获取 ZIP 与配套 `SHA256SUMS.txt`，放到同一目录。仓库仍为 Private 时，仅获授权用户可访问；Draft 是发行草稿，并非所有用户均可下载的正式版本。 ```bash -sha256sum -c VPSMaster-v1.0.0-beta.1.zip.sha256 +sha256sum -c SHA256SUMS.txt python3 -m zipfile -e VPSMaster-v1.0.0-beta.1.zip . cd VPSMaster-v1.0.0-beta.1 python3 -I -B install.py --run -VM="$HOME/.local/share/vpsmaster/1.0.0b1/bin/vpsmaster" -"$VM" --version -"$VM" check --lang zh --theme framed ``` -安装到用户目录的隔离环境，`--run` 首次只运行离线体检。缺少 Python/venv 会明确退出，不擅自安装系统依赖。 -已有安装目录不会覆盖。需要另一路径时用 `python3 -I -B install.py --prefix "$HOME/vpsmaster-beta-test"`，并使用打印出的启动器路径。 +安装器在用户目录创建隔离环境，输出可执行入口路径；首次运行离线体检，不要求 root，也不调用 pip、sudo 或系统包管理器。缺少依赖时明确退出，不擅自修改系统。[安装、升级与卸载](docs/guide/INSTALL.md) -### 更名与兼容性 +## 常用命令 -- 项目旧名 **ProxyDoctor**；当前用户可见品牌统一为 **VPSMaster**。 -- 新命令为 `vpsmaster`，同一安装目录保留 `proxydoctor` 兼容入口；两者调用同一实现。 -- Python 包名、发行元数据中的旧包标识 `proxydoctor`、导入路径、已有 JSON schema 和 `PROXYDOCTOR_*` 环境变量保留。没有宣称支持新的 `VPSMASTER_*` 变量。 -- 新默认目录为 `~/.local/share/vpsmaster/1.0.0b1`；旧安装、报告和 `~/.local/share/proxydoctor/` 不自动改名或迁移。 -- 源码入口 `bash vpsmaster.sh ...` 与 `bash proxydoctor.sh ...` 均可用。提供的启动器与 Python workers 使用 `-B`，不通过删除缓存掩盖问题；外部自行导入不在此承诺范围。 - -## 使用 +默认安装使用下面的入口；自定义目录请使用安装器打印的路径。 ```bash -# 本机体检，不发起外部探测（--detect-public-ip 是另行选择的联网选项） -"$VM" check --lang zh --color always -"$VM" suite --offline --lang en - -# 联网模式：目标服务会看到请求来源 IP -"$VM" quality --lang zh -"$VM" suite --lang zh --json-output report.json -"$VM" trace --target 1.1.1.1 --method udp --max-hops 30 -"$VM" trace --target 1.1.1.1 --method tcp --tcp-port 443 --geo -"$VM" bgp --target 1.1.1.1 -"$VM" ipquality -"$VM" media - -# 本地导出和恢复；不覆盖已有文件 +VM="$HOME/.local/share/vpsmaster/1.0.0b1/bin/vpsmaster" +"$VM" check --lang zh # 本机体检 +"$VM" suite --offline --lang zh # 离线综合检测 +"$VM" quality --lang zh # DNS / TCP / TLS 网络检测 +"$VM" trace --target 1.1.1.1 --method udp # 逐跳追踪 +"$VM" ipquality # IP 归属与风险信息 +"$VM" suite --json-output report.json # 联网综合检测并保存报告 "$VM" report --input report.json --output report.md -"$VM" recover --journal report.json.events.jsonl --output recovered.json "$VM" --help ``` -ICMP/TCP 需要系统已有 traceroute，权限不足显示 `PERMISSION_DENIED`，缺依赖明确跳过/退出，不自动提权安装。 -`--geo` 最多查询12个公网跳点，私有/保留地址不外发；位置是数据库推测，不是物理路径证明。 +`proxydoctor` 兼容命令仍可用。完整参数与可选测速见[使用指南](docs/guide/USAGE.md)。联网服务会看到来源 IP；分享报告前仍需人工复核脱敏结果。 -默认不运行带宽测试。确需测试时单独允许，并先核对命令预告的负载预算： +## Beta 已知限制 -```bash -"$VM" bandwidth --allow-bandwidth --rounds 3 --sample-mib 4 -# 实验性：中国大陆三网候选，并不保证三网都有可用节点 -"$VM" bandwidth --china --allow-bandwidth --rounds 3 --sample-mib 1 -"$VM" cn-nodes -"$VM" return-route --method udp --max-hops 30 -``` +- 流媒体仅网页可达性，不代表解锁或播放；大陆三网测速仍为实验性，默认关闭。 +- ICMP/TCP 可能需要系统 `traceroute` 和相应权限；BGP、IP 地理位置及风险信息受第三方数据限制。 +- 已验证实验环境为 Ubuntu 22.04 Desktop、24.04 Server（x86_64）；海外 VPS、ARM、公网 IPv6、全新 Ubuntu 22.04 Server 镜像尚未全面验证。 +- 当前没有一键安全加固、自动代理部署和 Web UI；Beta 不代表稳定生产版本或独立安全认证。 -下载方向为“节点 → 本机”，上传为“本机 → 节点”；中国候选当前下载为主。香港移动单独标注，不能替代大陆移动。 -短文件成功不是线路容量；`attempted` 目前统计计划样本槽，包含失败后自动跳过的槽位，不是实际网络请求次数，需查看每个样本错误。 +[完整技术限制](docs/release/KNOWN_LIMITATIONS.md) · [Beta 发行说明](docs/release/RELEASE_NOTES.md) -### CLI 示例输出 +## 后续开发方向 -以下是**格式示意**，`` 等为占位符，不是本发行包的测速成绩： +| 阶段 | 方向与目标 | 状态 | +| --- | --- | --- | +| Phase 1 · VPS 综合检测 | 系统与资源、网络连通性、逐跳追踪、BGP/IP、基础安全及报告恢复 | 当前 Beta 基础能力 | +| Phase 2 · 检测能力完善 | CPU/磁盘基准、三网测速完善、IP 情报交叉验证、线路建议、安全基线与购买验收 | Planned / 规划中 | +| Phase 3 · 一键安全加固 | SSH 与密钥策略、UFW/nftables、Fail2ban、更新及权限加固；可选方案、风险解释和修改预览 | Planned / 未来重点 | +| Phase 4 · 备份、回滚与监控 | 配置备份与差异、保留 SSH 通道、执行后复验、有条件回滚、审计及持续安全监控 | Planned / 规划中 | +| Phase 5 · Web UI 与管理 | 本地面板、风险与任务汇总、备份恢复、多 VPS 和可选服务管理 | 长期规划 | -```text -1.0.0b1 · VPSMaster · 1.0 公测版（非最终版本） - 1 127.0.0.1 ms 内网/保留地址 AS? --- [reached] -追踪结果 reached -恢复日志: <本地文件路径> -``` +未来安全加固必须由用户明确确认，遵循 **检测 → 解释 → 预览 → 确认 → 备份 → 执行 → 验证 → 回滚**。重点保护 SSH 管理访问，不承诺所有故障都能自动恢复；Web 管理入口默认不向公网开放。 -终端逐项回显，支持 `default / iprisk / framed` 和中英文；`framed` 适配窄终端。 -Linux纯文字控制台默认英文，显式 `--lang zh` 保留中文，但需要终端字体支持。 +以上未来能力尚未实现，不属于当前 Beta，不承诺固定交付时间。[完整开发路线](docs/security/ROADMAP.md) -## 已验证环境与验收范围 +## 文档与贡献 -已有实机基线是 **Ubuntu 22.04.5 Desktop / Python3.10.12 / x86_64** 与 **Ubuntu 24.04.3 Server / Python3.12.3 / x86_64**。 -本次 VPSMaster 构建使用新 ZIP、全新 HOME/安装目录重新验收；**仅旁附与 ZIP SHA256 一致的验收报告可证明本构建通过**。 -旧 ProxyDoctor 验收包保留，不能换名充当 VPSMaster 的通过证据。 +[中文使用文档](docs/guide/USAGE.md) · [English README](README.en.md) · [安装指南](docs/guide/INSTALL.md) · [已知限制](docs/release/KNOWN_LIMITATIONS.md) · [安全加固路线](docs/security/ROADMAP.md) -当前测试不等于全新22 Server镜像、海外VPS、ARM或公网IPv6已全面验证。 -ICMP/TCP 的回环成功和有限公网观察，不代表所有线路或完整公网路径可用。 -版本与实际范围见 [当前状态](CURRENT_STATUS.md)、[发行说明](RELEASE_NOTES.md) 和包外验收报告。 - -## 安全与隐私 - -普通检测不修改 SSH、防火墙、路由或系统 DNS，不自动修复或上传完整报告。 -安装器只创建指定的用户隔离环境；检测和导出会创建本地报告。联网 API、媒体页和测速服务仍会看到请求来源 IP。 -提供的入口有超时与取消处理；Ctrl+C/SIGTERM 尝试保存已有结果，恢复以最后完整日志事件为准。 -退出码：`0` 完成，`1` 有发现/不完整/存储失败，`2` 参数或安装错误，`130` 中断。 - -`--show-ip` 只影响终端显示；导出默认脱敏 IP、已知密钥字段和URL凭据，但不是任意文本匿名器。 -不要公开原始日志、订阅地址、密码、Token或私钥。安全问题见 [SECURITY.md](SECURITY.md)，未知不能当作安全保证。 - -## Roadmap / 安全加固开发路线 — Planned / 规划中 - -**现在主打可信检测，未来核心竞争力是安全加固。** 以下全部为长期规划，不是当前已有功能，不承诺固定交付日期。 - -### Phase 1 — 检测能力完善（Planned） - -- CPU和磁盘性能基准；中国大陆电信、联通、移动节点覆盖。 -- 网络线路/BGP分析、IP情报交叉验证、网络检测准确性与兼容性改善。 -- 服务器安全体检规则扩展。 - -### Phase 2 — 一键安全加固（Planned，未来重点） - -- SSH安全配置检查与加固、密钥认证和密码登录策略管理。 -- UFW/nftables规则管理、Fail2ban等暴力破解防护。 -- 不必要服务/开放端口检查、更新/补丁策略、用户与文件权限加固、Linux安全基线。 -- 方案预览、风险解释及用户按需选择；当前Beta没有一键加固或自动修复。 - -### Phase 3 — 安全备份、验证与回滚（Planned） - -- 修改前自动备份、变更差异、当前SSH管理连接检查与管理通道保留。 -- 执行后SSH/网络复验、具备可靠机制时的超时回滚、操作审计日志。 -- 配置恢复向导和失败恢复提示。 -- 自动回滚不能保证恢复所有断网、重启、云安全组或宿主机故障。 - -### Phase 4 — 持续安全监控（Planned） - -- 定期安全体检、配置漂移、SSH异常登录和可疑端口变化提醒。 -- 安全报告历史对比、更新/风险变化提醒。 -- 长期网络稳定性监测、VPS购买验收报告。 - -### Phase 5 — 可视化安全管理（Planned） - -- 本地Web UI、安全评分与风险展示、加固任务管理。 -- 备份/回滚界面、多服务器管理探索、可选服务部署维护。 -- Web UI默认不得向公网直接暴露管理入口；评分必须说明依据和不确定性。 - -未来加固流程：**检测 → 解释 → 预览 → 确认 → 备份 → 执行 → 验证 → 回滚**。 -默认只读、明确授权、替代SSH管理连接验证、云安全组考虑、幂等与审计、业务端口保护均为前提。 -高风险变更不作无人值守默认动作，也不通过关闭安全保护或放宽权限“修复”。详见 [安全加固设计原则](SECURITY_ROADMAP.md)。 - -## Known Limitations / 已知限制 - -- 流媒体主要是公开网页可达性，不保证解锁、订阅权限、地区可用性或实际播放。 -- 中国大陆三网测速仍为实验性能力，默认关闭；没有完整可靠三网覆盖承诺。 -- BGP/IP 地理信息依赖第三方来源、准确性、服务条款和限额；位置不证明物理路由。 -- 海外 VPS、ARM、公网 IPv6、全新 Ubuntu22 Server 镜像未全面验证；新GUI字体渲染须单独目视验收。 -- Beta 不代表生产稳定性、独立安全认证或资源独享证明。 -- **当前没有 Web UI、一键安全加固、自动代理部署或完整管理面板。** 也没有长时间监控、CPU/磁盘基准或完整全国三网回程。 - -详见 [KNOWN_LIMITATIONS.md](KNOWN_LIMITATIONS.md)。更新请安装到新的、确认不存在的目录；卸载前备份报告，只移除自己确认的安装目录。 - -## 贡献、Issues 与许可 - -欢迎文档、翻译、可复现Bug和有来源的检测规则贡献，见 [CONTRIBUTING.md](CONTRIBUTING.md)。 -在有权访问的仓库中使用 [Issues](https://github.com/griffinmx/VPSMaster/issues) → New issue；[Bug 模板](.github/ISSUE_TEMPLATE/bug_report.md) 和 [功能建议模板](.github/ISSUE_TEMPLATE/feature_request.md) 已随源码提供。 -仓库当前为Private，只有获授权用户可访问；未经所有者确认不会公开。敏感安全问题不要发到公开Issues。 - -项目采用 [MIT](LICENSE)，保留旧品牌贡献者版权。标准库运行，不打包第三方测速客户端/地理数据库，不下载执行外部检测脚本。 -感谢相关开源项目与数据服务，详见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 和 [OPEN_SOURCE_REFERENCES.md](OPEN_SOURCE_REFERENCES.md)。 -本项目MIT许可不覆盖第三方API、数据库或测速服务，使用时仍需遵守其条款、配额与权限；没有长期或高负载使用授权保证。 -数据保留/分享边界（含IP2Location适用缓存期限）见 [第三方接口条款](docs/DATA_SERVICES.md)；当前工具不自动删除历史报告。 +[文档目录](docs/README.md) · [安全与隐私](docs/security/SECURITY.md) · [Issues](https://github.com/griffinmx/VPSMaster/issues) · [贡献指南](docs/development/CONTRIBUTING.md) · [MIT LICENSE](LICENSE) · [第三方来源及许可声明](THIRD_PARTY_NOTICES.md) diff --git a/SECURITY_ROADMAP.md b/SECURITY_ROADMAP.md deleted file mode 100644 index c7dc53c..0000000 --- a/SECURITY_ROADMAP.md +++ /dev/null @@ -1,44 +0,0 @@ -# VPSMaster 安全加固设计路线 — Planned - -## Roadmap / 安全加固开发路线 — Planned / 规划中 - -**现在主打可信检测，未来核心竞争力是安全加固。** 以下全部为长期规划，不是当前已有功能，不承诺固定交付日期。 - -### Phase 1 — 检测能力完善（Planned） - -- CPU和磁盘性能基准；中国大陆电信、联通、移动节点覆盖。 -- 网络线路/BGP分析、IP情报交叉验证、网络检测准确性与兼容性改善。 -- 服务器安全体检规则扩展。 - -### Phase 2 — 一键安全加固（Planned，未来重点） - -- SSH安全配置检查与加固、密钥认证和密码登录策略管理。 -- UFW/nftables规则管理、Fail2ban等暴力破解防护。 -- 不必要服务/开放端口检查、更新/补丁策略、用户与文件权限加固、Linux安全基线。 -- 方案预览、风险解释及用户按需选择；当前Beta没有一键加固或自动修复。 - -### Phase 3 — 安全备份、验证与回滚（Planned） - -- 修改前自动备份、变更差异、当前SSH管理连接检查与管理通道保留。 -- 执行后SSH/网络复验、具备可靠机制时的超时回滚、操作审计日志。 -- 配置恢复向导和失败恢复提示。 -- 自动回滚不能保证恢复所有断网、重启、云安全组或宿主机故障。 - -### Phase 4 — 持续安全监控（Planned） - -- 定期安全体检、配置漂移、SSH异常登录和可疑端口变化提醒。 -- 安全报告历史对比、更新/风险变化提醒。 -- 长期网络稳定性监测、VPS购买验收报告。 - -### Phase 5 — 可视化安全管理（Planned） - -- 本地Web UI、安全评分与风险展示、加固任务管理。 -- 备份/回滚界面、多服务器管理探索、可选服务部署维护。 -- Web UI默认不得向公网直接暴露管理入口；评分必须说明依据和不确定性。 - -未来加固流程：**检测 → 解释 → 预览 → 确认 → 备份 → 执行 → 验证 → 回滚**。 -默认只读、明确授权、替代SSH管理连接验证、云安全组考虑、幂等与审计、业务端口保护均为前提。 -高风险变更不作无人值守默认动作，也不通过关闭安全保护或放宽权限“修复”。详见 [安全加固设计原则](SECURITY_ROADMAP.md)。 - - -本轮仅更新定位与设计文档，没有实现加固、自动修复或管理UI。任何未来实现都需独立威胁分析、回归与失联恢复实测；不能把计划当成当前安全承诺。 diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md index 31c6b13..b95f1ee 100644 --- a/THIRD_PARTY_NOTICES.md +++ b/THIRD_PARTY_NOTICES.md @@ -1,6 +1,6 @@ # References and acknowledgements / 借鉴来源与致谢 -VPSMaster更名后保留历史版权与引用；API/数据条款及保留边界见 [docs/DATA_SERVICES.md](docs/DATA_SERVICES.md)。本项目MIT不授予第三方数据的任意再分发权。 +VPSMaster更名后保留历史版权与引用；API/数据条款及保留边界见 [docs/DATA_SERVICES.md](docs/guide/DATA_SERVICES.md)。本项目MIT不授予第三方数据的任意再分发权。 VPSMaster's default Python checks are independently implemented. The projects below informed the feature selection and terminal presentation. Their code is @@ -80,3 +80,7 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +## Documentation presentation reference + +[xykt/HardwareQuality](https://github.com/xykt/HardwareQuality) informed the concise README structure and terminal-first presentation. No source, artwork or README text copied; this is a design reference, not a bundled dependency. diff --git a/USER_CHECKLIST_STATUS.md b/USER_CHECKLIST_STATUS.md deleted file mode 100644 index aa39c6a..0000000 --- a/USER_CHECKLIST_STATUS.md +++ /dev/null @@ -1,104 +0,0 @@ -> 历史记录 / Historical record：ProxyDoctor 是项目旧名。以下旧版本、SHA256、测试数量与路径保留原样，不代表 VPSMaster 新构建已通过；当前范围见 README.md、CURRENT_STATUS.md 和新包同 SHA256 验收报告。 - -> 历史 Alpha/问题状态记录：当前 1.0 公测候选请以 CURRENT_STATUS.md 和 PUBLIC_BETA_CHANGE_REPORT.md 为准；新增代码不等于已完成实测。 - -> 最新Alpha优先项状态见 [ALPHA_TASK_STATUS.md](ALPHA_TASK_STATUS.md)。以下包含本轮前历史统计，不能作为最新发布验收结论。 - -# 用户96项清单逐项状态统计 - -更新：2026-11-01。对应本次用户重新贴出的96项清单，编号为“类别-该类条目序号”；不同于原开发任务书101项登记。 -已完成表示当前明确支持范围内已有实现及对应验证，不表示生产环境或所有场景保证。复合需求仍缺关键部分时列部分完成。 -证据：两版Ubuntu最终各239项自动回归；前版各17项实际CLI验收；新报告导出/恢复实际执行，以及IP/PTR/TCP25实网记录。具体限制见CURRENT_STATUS.md和IPQUALITY_COVERAGE.md。 - -| 类别 | 总数 | 已完成 | 部分完成 | 未实现 | -|---|---:|---:|---:|---:| -| 1. VPS本机与硬件检测 | 7 | 1 | 3 | 3 | -| 2. 网络基础与DNS | 7 | 1 | 5 | 1 | -| 3. Traceroute与线路分析 | 9 | 1 | 6 | 2 | -| 4. IP地图、纯净度与信誉 | 9 | 5 | 3 | 1 | -| 5. 流媒体与在线服务 | 8 | 3 | 4 | 1 | -| 6. 多地区测速与长期稳定性 | 9 | 0 | 5 | 4 | -| 7. 基础安全体检 | 8 | 4 | 4 | 0 | -| 8. 检测结果、诊断与报告 | 10 | 3 | 5 | 2 | -| 9. 安装、兼容性与用户体验 | 10 | 3 | 6 | 1 | -| 10. 可靠性、隐私与测试 | 12 | 4 | 8 | 0 | -| 11. 开源项目与未来复用 | 7 | 2 | 4 | 1 | -| 合计 | 96 | 27 | 53 | 16 | - -当前完成27/96（约28%），部分完成53项，未实现16项。该比例只按条目计数，不按工作量；不等于项目剩余时间或生产就绪度。 - -## 对应条目编号 - -### 1. VPS本机与硬件检测 - -- 已完成：01-03 -- 部分完成：01-01、01-02、01-04 -- 未实现：01-05、01-06、01-07 - -### 2. 网络基础与DNS - -- 已完成：02-02 -- 部分完成：02-01、02-03、02-04、02-05、02-07 -- 未实现：02-06 - -### 3. Traceroute与线路分析 - -- 已完成：03-09 -- 部分完成：03-01、03-02、03-03、03-04、03-05、03-08 -- 未实现：03-06、03-07 - -### 4. IP地图、纯净度与信誉 - -- 已完成：04-01、04-02、04-03、04-04、04-07 -- 部分完成：04-06、04-08、04-09 -- 未实现：04-05 - -### 5. 流媒体与在线服务 - -- 已完成：05-01、05-05、05-07 -- 部分完成：05-02、05-03、05-04、05-06 -- 未实现：05-08 - -### 6. 多地区测速与长期稳定性 - -- 已完成：无 -- 部分完成：06-01、06-02、06-03、06-04、06-05 -- 未实现：06-06、06-07、06-08、06-09 - -### 7. 基础安全体检 - -- 已完成：07-01、07-03、07-05、07-06 -- 部分完成：07-02、07-04、07-07、07-08 -- 未实现：无 - -### 8. 检测结果、诊断与报告 - -- 已完成：08-04、08-06、08-07 -- 部分完成：08-01、08-02、08-03、08-05、08-08 -- 未实现：08-09、08-10 - -### 9. 安装、兼容性与用户体验 - -- 已完成：09-06、09-07、09-08 -- 部分完成：09-01、09-02、09-04、09-05、09-09、09-10 -- 未实现：09-03 - -### 10. 可靠性、隐私与测试 - -- 已完成：10-01、10-02、10-05、10-09 -- 部分完成：10-03、10-04、10-06、10-07、10-08、10-10、10-11、10-12 -- 未实现：无 - -### 11. 开源项目与未来复用 - -- 已完成：11-04、11-06 -- 部分完成：11-01、11-02、11-05、11-07 -- 未实现：11-03 - -## 勾选范围说明 - -01-03：系统可见内存/Swap/根文件系统和可见配额；不是独享资源证明。02-02：到固定目标的IPv4/IPv6连接测试已具备，测试返回失败/未知也是有效检测结果，不表示网络可达验收通过。 -04-01~04：查询并保留各来源提供的字段；字段缺失/冲突不伪装成确定结果。05-01：基础请求/可达性检测，不含账号播放；05-07为明确处理不可自动验证的边界。 -07-01：SSH默认配置中的选定设置；07-05：固定重要路径模式/所有者，不包含ACL/完整目录递归。08-06/07：本地JSON/Markdown与分享导出脱敏功能，仍须人工复核，不保证任意文本匿名。 -09-04仍为部分完成：两台现有Ubuntu虚拟机已验证，但未分别证明每种安装形态和运行环境。10-01仅在当前只读流程和已测可读配置哈希范围内；不是整个系统写入审计。10-09是已有Mock/单元/实际CLI测试机制，不表示所有异常路径已覆盖。 -11-04为现有使用/测试/贡献文档能力；一键安装、更新和卸载仍单独未完成。 diff --git a/docs/GITHUB_ABOUT.md b/docs/GITHUB_ABOUT.md deleted file mode 100644 index df4a80c..0000000 --- a/docs/GITHUB_ABOUT.md +++ /dev/null @@ -1,10 +0,0 @@ -# VPSMaster GitHub 设置 - -- Repository: https://github.com/griffinmx/VPSMaster -- Visibility: Private（本轮禁止转为Public） -- Subtitle: VPS Diagnostics & Security Hardening Toolkit -- Description: Open-source Linux VPS diagnostics, security auditing and future safe server hardening toolkit. -- 现在主打可信检测，未来重点Linux安全加固；备份/回滚、持续监控和可视化均Planned。 -- Release: v1.0.0-beta.1 / Pre-release=true / Draft=true / make_latest=false。 - -原032d候选保留。本轮README/工作流等属于包内变更，新的ZIP须独立SHA与验收，不能沿用旧摘要。公开前须所有者最终确认。 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..098c575 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,9 @@ +# VPSMaster 文档 / Documentation + +- **安装与使用 / Guides**：[安装、升级、卸载](guide/INSTALL.md) · [命令与 FAQ](guide/USAGE.md) · [IP 数据字段](guide/IPQUALITY_COVERAGE.md) · [第三方数据条款](guide/DATA_SERVICES.md) +- **安全 / Security**：[安全与隐私](security/SECURITY.md) · [安全加固路线（Planned）](security/ROADMAP.md) +- **开发 / Development**：[架构](development/ARCHITECTURE.md) · [贡献](development/CONTRIBUTING.md) · [测试](development/TESTING.md) · [CI](development/CI.md) · [参考项目](development/REFERENCES.md) +- **发行 / Releases**：[Beta 发行说明](release/RELEASE_NOTES.md) · [已知限制](release/KNOWN_LIMITATIONS.md) · [变更记录](release/CHANGELOG.md) +- **历史 / Archive**：[旧 Alpha 与早期开发记录](archive/README.md)，不代表当前构建的验收结果。 + +[返回首页](../README.md) · [English](../README.en.md) diff --git a/ALPHA_RELEASE_REPORT.md b/docs/archive/ALPHA_RELEASE_REPORT.md similarity index 91% rename from ALPHA_RELEASE_REPORT.md rename to docs/archive/ALPHA_RELEASE_REPORT.md index d83edfc..196f205 100644 --- a/ALPHA_RELEASE_REPORT.md +++ b/docs/archive/ALPHA_RELEASE_REPORT.md @@ -1,6 +1,4 @@ -> 历史记录 / Historical record：ProxyDoctor 是项目旧名。以下旧版本、SHA256、测试数量与路径保留原样，不代表 VPSMaster 新构建已通过；当前范围见 README.md、CURRENT_STATUS.md 和新包同 SHA256 验收报告。 - -> 历史 Alpha/问题状态记录：当前 1.0 公测候选请以 CURRENT_STATUS.md 和 PUBLIC_BETA_CHANGE_REPORT.md 为准；新增代码不等于已完成实测。 +> 历史材料：版本、测试数量与旧路径仅说明当时状态，不是本次构建的验收证据。参见[当前发行说明](../release/RELEASE_NOTES.md)。 # v0.1.0-alpha 发布前报告 diff --git a/ALPHA_TASK_STATUS.md b/docs/archive/ALPHA_TASK_STATUS.md similarity index 86% rename from ALPHA_TASK_STATUS.md rename to docs/archive/ALPHA_TASK_STATUS.md index 8517fea..9092070 100644 --- a/ALPHA_TASK_STATUS.md +++ b/docs/archive/ALPHA_TASK_STATUS.md @@ -1,6 +1,4 @@ -> 历史记录 / Historical record：ProxyDoctor 是项目旧名。以下旧版本、SHA256、测试数量与路径保留原样，不代表 VPSMaster 新构建已通过；当前范围见 README.md、CURRENT_STATUS.md 和新包同 SHA256 验收报告。 - -> 历史 Alpha/问题状态记录：当前 1.0 公测候选请以 CURRENT_STATUS.md 和 PUBLIC_BETA_CHANGE_REPORT.md 为准；新增代码不等于已完成实测。 +> 历史材料：版本、测试数量与旧路径仅说明当时状态，不是本次构建的验收证据。参见[当前发行说明](../release/RELEASE_NOTES.md)。 # v0.1.0-alpha 发布优先项状态 diff --git a/ARCHITECTURE.md b/docs/archive/ARCHITECTURE-alpha.md similarity index 98% rename from ARCHITECTURE.md rename to docs/archive/ARCHITECTURE-alpha.md index 75001f0..00776db 100644 --- a/ARCHITECTURE.md +++ b/docs/archive/ARCHITECTURE-alpha.md @@ -1,3 +1,4 @@ +> 历史材料：版本、测试数量与旧路径仅说明当时状态，不是本次构建的验收证据。参见[当前发行说明](../release/RELEASE_NOTES.md)。 ## v0.1.0-alpha 候选（2026-11-01） diff --git a/OPEN_SOURCE_RESEARCH.md b/docs/archive/OPEN_SOURCE_RESEARCH.md similarity index 94% rename from OPEN_SOURCE_RESEARCH.md rename to docs/archive/OPEN_SOURCE_RESEARCH.md index 56b6066..99a83ba 100644 --- a/OPEN_SOURCE_RESEARCH.md +++ b/docs/archive/OPEN_SOURCE_RESEARCH.md @@ -1,4 +1,4 @@ -> 历史记录 / Historical record：ProxyDoctor 是项目旧名。以下旧版本、SHA256、测试数量与路径保留原样，不代表 VPSMaster 新构建已通过；当前范围见 README.md、CURRENT_STATUS.md 和新包同 SHA256 验收报告。 +> 历史材料：版本、测试数量与旧路径仅说明当时状态，不是本次构建的验收证据。参见[当前发行说明](../release/RELEASE_NOTES.md)。 # 开源源码研究（首轮） diff --git a/PUBLIC_BETA_CHANGE_REPORT.md b/docs/archive/PUBLIC_BETA_CHANGE_REPORT.md similarity index 93% rename from PUBLIC_BETA_CHANGE_REPORT.md rename to docs/archive/PUBLIC_BETA_CHANGE_REPORT.md index f520f74..1f8a9c3 100644 --- a/PUBLIC_BETA_CHANGE_REPORT.md +++ b/docs/archive/PUBLIC_BETA_CHANGE_REPORT.md @@ -1,4 +1,4 @@ -> 历史记录 / Historical record：ProxyDoctor 是项目旧名。以下旧版本、SHA256、测试数量与路径保留原样，不代表 VPSMaster 新构建已通过；当前范围见 README.md、CURRENT_STATUS.md 和新包同 SHA256 验收报告。 +> 历史材料：版本、测试数量与旧路径仅说明当时状态，不是本次构建的验收证据。参见[当前发行说明](../release/RELEASE_NOTES.md)。 ## P0 追加修复 · BETA22-001 diff --git a/docs/archive/README.md b/docs/archive/README.md new file mode 100644 index 0000000..0f164c3 --- /dev/null +++ b/docs/archive/README.md @@ -0,0 +1,7 @@ +# 历史记录 / Archive + +这里保留 Alpha 与早期 Beta 的非私密设计/开发记录。文中的命令、包名、目录、测试数量与结论均对应当时版本，不能证明当前发行包通过验收。 + +当前说明请从[首页](../../README.md)、[发行说明](../release/RELEASE_NOTES.md)、[开发测试](../development/TESTING.md)进入。 + +开发任务书、内部进度表、未脱敏测试日志、连接信息和备份不属于公开文档，保留在维护者本地私有工作区。整理没有改写既有 Git 历史。 diff --git a/TEST_PLAN.md b/docs/archive/TEST_PLAN-alpha.md similarity index 98% rename from TEST_PLAN.md rename to docs/archive/TEST_PLAN-alpha.md index a13005d..98b4e24 100644 --- a/TEST_PLAN.md +++ b/docs/archive/TEST_PLAN-alpha.md @@ -1,4 +1,4 @@ -> 历史记录 / Historical record：ProxyDoctor 是项目旧名。以下旧版本、SHA256、测试数量与路径保留原样，不代表 VPSMaster 新构建已通过；当前范围见 README.md、CURRENT_STATUS.md 和新包同 SHA256 验收报告。 +> 历史材料：版本、测试数量与旧路径仅说明当时状态，不是本次构建的验收证据。参见[当前发行说明](../release/RELEASE_NOTES.md)。 ## 1.0 公测待验收 diff --git a/docs/history-beta-before-p0-20261101.md b/docs/archive/history-beta-before-p0-20261101.md similarity index 78% rename from docs/history-beta-before-p0-20261101.md rename to docs/archive/history-beta-before-p0-20261101.md index b47bbce..27352e6 100644 --- a/docs/history-beta-before-p0-20261101.md +++ b/docs/archive/history-beta-before-p0-20261101.md @@ -1,4 +1,4 @@ -> 历史记录 / Historical record：ProxyDoctor 是项目旧名。以下旧版本、SHA256、测试数量与路径保留原样，不代表 VPSMaster 新构建已通过；当前范围见 README.md、CURRENT_STATUS.md 和新包同 SHA256 验收报告。 +> 历史材料：版本、测试数量与旧路径仅说明当时状态，不是本次构建的验收证据。参见[当前发行说明](../release/RELEASE_NOTES.md)。 # 当前状态：1.0 公测候选，非最终版本 @@ -13,4 +13,4 @@ 96 项表和 Alpha 文档保留历史；本轮没有根据代码接入或测试数量批量打勾。 03-01/03-06/03-07/06-01 等仍不能标为全部完成。没有全国完整三网、双向探针、长期监测或 Web UI。 -详见 [README](README.md) 和 [本轮变更与待测项](PUBLIC_BETA_CHANGE_REPORT.md)。 +详见 [README](../README.md) 和 [本轮变更与待测项](PUBLIC_BETA_CHANGE_REPORT.md)。 diff --git a/docs/pre-alpha-README.en.md b/docs/archive/pre-alpha-README.en.md similarity index 94% rename from docs/pre-alpha-README.en.md rename to docs/archive/pre-alpha-README.en.md index 4159731..1e9d3ef 100644 --- a/docs/pre-alpha-README.en.md +++ b/docs/archive/pre-alpha-README.en.md @@ -1,10 +1,10 @@ -> 历史记录 / Historical record：ProxyDoctor 是项目旧名。以下旧版本、SHA256、测试数量与路径保留原样，不代表 VPSMaster 新构建已通过；当前范围见 README.md、CURRENT_STATUS.md 和新包同 SHA256 验收报告。 +> 历史材料：版本、测试数量与旧路径仅说明当时状态，不是本次构建的验收证据。参见[当前发行说明](../release/RELEASE_NOTES.md)。 -See [current status](CURRENT_STATUS.md) for implemented and outstanding work. Family-specific DNS/TCP/TLS checks now back suite/quality; untested. +See [current status](README.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. +This branch develops an independent Python VPS diagnostics CLI. See [backlog](README.md), [architecture](ARCHITECTURE-alpha.md), [source research](OPEN_SOURCE_RESEARCH.md), [test plan](TEST_PLAN-alpha.md), and [changelog](../release/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. @@ -14,7 +14,7 @@ These changes have not been tested or released. Earlier test results do not vali # ProxyDoctor -[中文](README.md) | [English](README.en.md) +[中文](../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 @@ -159,7 +159,7 @@ python3 -m venv .venv 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). +before repository publication. See [CONTRIBUTING.md](../development/CONTRIBUTING.md) and [SECURITY.md](../security/SECURITY.md). ## Stage 1 and scope @@ -174,7 +174,7 @@ transport. No public plaintext subscription server or automatic SSH/firewall cha 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). +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. diff --git a/docs/pre-alpha-README.md b/docs/archive/pre-alpha-README.md similarity index 91% rename from docs/pre-alpha-README.md rename to docs/archive/pre-alpha-README.md index 57901dc..0d90dce 100644 --- a/docs/pre-alpha-README.md +++ b/docs/archive/pre-alpha-README.md @@ -1,12 +1,12 @@ -> 历史记录 / Historical record：ProxyDoctor 是项目旧名。以下旧版本、SHA256、测试数量与路径保留原样，不代表 VPSMaster 新构建已通过；当前范围见 README.md、CURRENT_STATUS.md 和新包同 SHA256 验收报告。 +> 历史材料：版本、测试数量与旧路径仅说明当时状态，不是本次构建的验收证据。参见[当前发行说明](../release/RELEASE_NOTES.md)。 -最新逐类完成情况和未完成重点见 [当前进度](CURRENT_STATUS.md)。新增双栈 DNS/TCP/TLS 已接入 suite/quality，尚未验证。 +最新逐类完成情况和未完成重点见 [当前进度](README.md)。新增双栈 DNS/TCP/TLS 已接入 suite/quality，尚未验证。 # 当前开发范围（2026-11-01） 资源首页优先显示本进程 CPU 上限、可见内存限额及其依据。已识别的容器如果没有可读限额，不以宿主机总内存充当自己的额度。系统原始值保留在 JSON 详细依据中；CPU/内存是否独享统一标注“无法从本机确认”。容器识别仍有遗漏可能，KVM 中的系统可见内存也不等于已验证商家独享保障。此轮显示调整未测试。 -本分支按新的 [开发任务书](DEVELOPMENT_BRIEF.zh.md) 推进独立 Python VPS 综合诊断 CLI。代理部署、Web UI 不在当前范围。下面原 0.5.0 说明保留作背景；最新实际状态以 [问题追踪](PROBLEM_BACKLOG.md)、[架构](ARCHITECTURE.md)、[源码研究](OPEN_SOURCE_RESEARCH.md)、[测试计划](TEST_PLAN.md) 和 [更新记录](CHANGELOG.md) 为准。 +本分支按新的 [开发任务书](README.md) 推进独立 Python VPS 综合诊断 CLI。代理部署、Web UI 不在当前范围。下面原 0.5.0 说明保留作背景；最新实际状态以 [问题追踪](README.md)、[架构](ARCHITECTURE-alpha.md)、[源码研究](OPEN_SOURCE_RESEARCH.md)、[测试计划](TEST_PLAN-alpha.md) 和 [更新记录](../release/CHANGELOG.md) 为准。 常规 `bash proxydoctor.sh` / `proxydoctor suite` 默认跳过 CPU 和带宽基准。需要测速时，使用 `proxydoctor bandwidth --allow-bandwidth` 或 `proxydoctor suite --allow-bandwidth`；执行前显示请求载荷预算，协议开销与其他模块流量另计。`proxydoctor suite --offline` 跳过联网。第三方脚本/可执行文件包装入口暂时禁用。 @@ -16,7 +16,7 @@ # ProxyDoctor -[中文](README.md) | [English](README.en.md) +[中文](../README.md) | [English](../../README.en.md) 面向 Ubuntu VPS 新手的原生 Python 只读诊断工具。支持 Ubuntu 22.04 及更新版本； 当前优先验收 22.04、24.04，其他版本逐步实测。Python 3.10+，没有第三方运行依赖。 @@ -148,7 +148,7 @@ python3 -m venv .venv Ubuntu 若未安装 venv 支持，需另行安装系统对应组件；程序不会自动安装。 开发测试：`python -m pip install pytest` 后 `python -m pytest -q`。 GitHub Actions 配置已提供，未发布仓库前不宣称远程 CI 已运行。 -贡献规范见 [CONTRIBUTING.md](CONTRIBUTING.md)，安全反馈见 [SECURITY.md](SECURITY.md)。 +贡献规范见 [CONTRIBUTING.md](../development/CONTRIBUTING.md)，安全反馈见 [SECURITY.md](../security/SECURITY.md)。 ## 阶段一验收与后续 @@ -160,7 +160,7 @@ GitHub Actions 配置已提供，未发布仓库前不宣称远程 CI 已运行 ## 开源与来源 原创代码使用 MIT 许可证。感谢 ECS、NodeQuality、NetQuality/IPQuality、NextTrace、RegionRestrictionCheck 的功能和展示设计参考； -默认实现没有打包或复制上游脚本/数据库。来源和许可范围见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。 +默认实现没有打包或复制上游脚本/数据库。来源和许可范围见 [THIRD_PARTY_NOTICES.md](../../THIRD_PARTY_NOTICES.md)。 本地第三方适配器仅在显式指定时运行，第三方行为/输出不保证只读或脱敏。 数据接口：[Cloudflare](https://github.com/cloudflare/speedtest)、[OVHcloud](https://proof.ovh.net/)、 @@ -199,4 +199,4 @@ bash proxydoctor.sh recover --journal reports/example.json.events.jsonl --output bash proxydoctor.sh recover --journal reports/example.json.events.jsonl --output recovered.md --format markdown --lang en ``` -`--show-ip`只改变终端IP显示，文件仍脱敏。顶部是概览，详细数据源在下面。DNSBL与IPMap尚未接入，覆盖和限制见 [IP质量功能表](IPQUALITY_COVERAGE.md)。不要将来源评分或PTR/端口结果视为绝对安全/邮件可投递证明。 +`--show-ip`只改变终端IP显示，文件仍脱敏。顶部是概览，详细数据源在下面。DNSBL与IPMap尚未接入，覆盖和限制见 [IP质量功能表](../guide/IPQUALITY_COVERAGE.md)。不要将来源评分或PTR/端口结果视为绝对安全/邮件可投递证明。 diff --git a/docs/status-history-before-2026-11-01.md b/docs/archive/status-history-before-2026-11-01.md similarity index 96% rename from docs/status-history-before-2026-11-01.md rename to docs/archive/status-history-before-2026-11-01.md index dc559a7..07b3fbe 100644 --- a/docs/status-history-before-2026-11-01.md +++ b/docs/archive/status-history-before-2026-11-01.md @@ -1,5 +1,4 @@ -> 历史记录 / Historical record：ProxyDoctor 是项目旧名。以下旧版本、SHA256、测试数量与路径保留原样，不代表 VPSMaster 新构建已通过；当前范围见 README.md、CURRENT_STATUS.md 和新包同 SHA256 验收报告。 - +> 历史材料：版本、测试数量与旧路径仅说明当时状态，不是本次构建的验收证据。参见[当前发行说明](../release/RELEASE_NOTES.md)。 ## 报告与IP质量更新（2026-11-01） diff --git a/docs/development/ARCHITECTURE.md b/docs/development/ARCHITECTURE.md new file mode 100644 index 0000000..9b24016 --- /dev/null +++ b/docs/development/ARCHITECTURE.md @@ -0,0 +1,15 @@ +# 当前架构 / Architecture + +运行时仅依赖 Python 3.10+ 标准库。品牌 VPSMaster，内部包和导入路径仍为 `proxydoctor`。 + +| 层 | 代码与职责 | +| --- | --- | +| 入口 | `proxydoctor/cli.py` 参数与报告处理；安装器生成两个兼容命令 | +| 本机检测 | `checks.py`、`security.py` 等只读适配器 | +| 网络 | `quality.py`、`routes.py`、`ipquality.py`、`media.py`、`bandwidth.py` 等 | +| 展示与编排 | `console.py`、`suite.py`；部分采集函数仍同时输出终端 | +| 安装与校验 | 根目录 `install.py`、`MANIFEST.sha256.json`，隔离用户目录安装 | + +部分模块提供 Python 函数，但尚未承诺完整稳定的外部管理 API，也未完全分离检测和展示。内部字段/业务结果不可机械地映射为“安全”或“解锁”。不为整理目录改动检测实现或现有 schema。 + +未来 API、Web UI、安全变更执行器及回滚能力见[规划](../security/ROADMAP.md)。早期架构草案保存在[历史目录](../archive/README.md)，不是当前实现承诺。 diff --git a/docs/CI.md b/docs/development/CI.md similarity index 100% rename from docs/CI.md rename to docs/development/CI.md diff --git a/CONTRIBUTING.md b/docs/development/CONTRIBUTING.md similarity index 100% rename from CONTRIBUTING.md rename to docs/development/CONTRIBUTING.md diff --git a/OPEN_SOURCE_REFERENCES.md b/docs/development/REFERENCES.md similarity index 93% rename from OPEN_SOURCE_REFERENCES.md rename to docs/development/REFERENCES.md index 3cf327d..af59f51 100644 --- a/OPEN_SOURCE_REFERENCES.md +++ b/docs/development/REFERENCES.md @@ -2,7 +2,7 @@ The independently implemented stdlib runtime has no third-party Python dependency. No new third-party code, database or binary was copied during final hardening. -Full references and retained MIT notices: THIRD_PARTY_NOTICES.md. +Full references and retained MIT notices: [THIRD_PARTY_NOTICES.md](../../THIRD_PARTY_NOTICES.md). Reviewed 2026-11-01: diff --git a/docs/development/TESTING.md b/docs/development/TESTING.md new file mode 100644 index 0000000..aae06d5 --- /dev/null +++ b/docs/development/TESTING.md @@ -0,0 +1,22 @@ +# 开发测试 / Testing + +从仓库根目录创建独立开发环境；开发依赖不属于产品运行依赖。 + +```bash +python3 -m venv .venv +.venv/bin/python -m pip install 'pytest>=8,<10' 'setuptools>=77,<100' 'wheel>=0.45,<1' +.venv/bin/python -B -m pytest -q +.venv/bin/python -m pip wheel --no-deps --no-build-isolation --wheel-dir dist . +``` + +Windows 使用 `.venv/Scripts/python.exe`。测试避免访问真实第三方服务，使用 Mock/本地服务模拟 DNS/API 异常、超时、中断、报告和安装失败。Windows 的符号链接权限限制可造成明确 skip，不能计为通过。 + +## 发行验收 + +1. 源码和文档变化后重建 manifest 和独立 ZIP，不覆盖旧验收包。 +2. 验证 ZIP SHA256、清单、许可证、链接、敏感信息和全部自动化测试。 +3. Ubuntu 22.04 Desktop / 24.04 Server 受控虚拟机先保存快照，从最终 ZIP 安装至全新目录。 +4. 检查隔离、双入口、重复安装拒绝、篡改拒绝、离线/联网功能、报告恢复、取消与系统配置前后一致。 +5. 原始失败日志和私密环境证据留在维护者本地工作区；只公开脱敏结论。新包不可沿用旧 SHA 或旧 CI 成绩。 + +当前环境范围不包括已全面验证的海外 VPS、ARM、公网 IPv6 或全新 Ubuntu 22.04 Server 镜像。详见[限制](../release/KNOWN_LIMITATIONS.md)和[CI](CI.md)。 diff --git a/docs/DATA_SERVICES.md b/docs/guide/DATA_SERVICES.md similarity index 100% rename from docs/DATA_SERVICES.md rename to docs/guide/DATA_SERVICES.md diff --git a/docs/guide/INSTALL.md b/docs/guide/INSTALL.md new file mode 100644 index 0000000..fcbcd14 --- /dev/null +++ b/docs/guide/INSTALL.md @@ -0,0 +1,42 @@ +# 安装、更新与卸载 / Installation + +需要 Linux、Python 3.10+ 和标准库 venv；Ubuntu 22.04+ 是主要目标。安装器不下载依赖、不调用 pip/sudo/系统包管理器。缺少 Python 或 venv 时明确退出，由用户自行选择系统依赖安装方式。 + +## ZIP 安装 + +从可信的 [Releases](https://github.com/griffinmx/VPSMaster/releases) 渠道取得同一构建的 ZIP 与 `SHA256SUMS.txt`。校验只能验证内容一致性，不能独立证明发布者身份。私有测试期间需访问授权。 + +```bash +sha256sum -c SHA256SUMS.txt +python3 -m zipfile -e VPSMaster-v1.0.0-beta.1.zip . +cd VPSMaster-v1.0.0-beta.1 +python3 -I -B install.py --run +``` + +默认目录为 `~/.local/share/vpsmaster/1.0.0b1`。`--run` 安装后运行离线 suite；检测有发现时可能返回 1，先查看安装器和检测各自的输出。 + +安装器检查根目录 `MANIFEST.sha256.json`，创建不含 pip 的隔离 venv，复制 Python 包并提供 `bin/vpsmaster` 与 `bin/proxydoctor`。不要自行移动清单中的文件。 + +## 自定义目录与重复安装 + +```bash +python3 -I -B install.py --prefix "$HOME/vpsmaster-beta-test" +"$HOME/vpsmaster-beta-test/bin/vpsmaster" --version +``` + +必须指定尚不存在的目录；重复安装拒绝覆盖。安装失败会清理本次新建的安装目录，保留既有安装。 + +## 更新和卸载 + +更新时先核对新包校验和，安装到新的目录并验证，再切换自己使用的启动器路径。没有自动更新、旧报告迁移或自动卸载。卸载前备份报告、核对实际安装路径，然后仅删除自己确认的安装目录；不要删除整个 `~/.local/share`。 + +## 源码运行与兼容 + +```bash +bash vpsmaster.sh check --lang zh +bash proxydoctor.sh check --lang en +``` + +内部 Python 包与发行元数据仍名为 `proxydoctor`；现有 JSON schema、`PROXYDOCTOR_*` 环境变量保留。没有新增 `VPSMASTER_*` 环境变量别名。旧 `~/.local/share/proxydoctor/` 不自动迁移。 + +[使用指南](USAGE.md) · [返回首页](../../README.md) diff --git a/IPQUALITY_COVERAGE.md b/docs/guide/IPQUALITY_COVERAGE.md similarity index 90% rename from IPQUALITY_COVERAGE.md rename to docs/guide/IPQUALITY_COVERAGE.md index 7a30a1c..8d6da2c 100644 --- a/IPQUALITY_COVERAGE.md +++ b/docs/guide/IPQUALITY_COVERAGE.md @@ -1,4 +1,4 @@ -> 历史记录 / Historical record：ProxyDoctor 是项目旧名。以下旧版本、SHA256、测试数量与路径保留原样，不代表 VPSMaster 新构建已通过；当前范围见 README.md、CURRENT_STATUS.md 和新包同 SHA256 验收报告。 +> 历史材料：版本、测试数量与旧路径仅说明当时状态，不是本次构建的验收证据。参见[当前发行说明](../release/RELEASE_NOTES.md)。 # IPQuality 风格功能覆盖与外部资源 diff --git a/docs/guide/USAGE.md b/docs/guide/USAGE.md new file mode 100644 index 0000000..c272688 --- /dev/null +++ b/docs/guide/USAGE.md @@ -0,0 +1,51 @@ +# 使用与常见问题 / Usage & FAQ + +下例先设置 `VM="$HOME/.local/share/vpsmaster/1.0.0b1/bin/vpsmaster"`；自定义安装请使用安装器打印的路径。逐项参数以 `"$VM" --help` 为准。 + +| 命令 | 用途 | +| --- | --- | +| `check --lang zh` | 本机体检；仅显式 `--detect-public-ip` 才查询公网出口 | +| `suite --offline --lang en` | 不发起外部探测的综合检测 | +| `quality` | DNS、TCP/TLS、网络质量观察 | +| `trace --target 1.1.1.1 --method udp --max-hops 30` | 默认30跳，最多64跳的逐跳探测 | +| `trace --target 1.1.1.1 --method tcp --tcp-port 443 --geo` | 可选系统 traceroute；位置是推测，最多查询12个公网跳点 | +| `bgp --target 1.1.1.1` | RIPE RIS 的前缀、ASN 与有限路径样本 | +| `ipquality` / `media` | IP 多来源信息 / 公开网页可达性 | +| `cn-nodes` | 实验性中国候选节点的基础探测 | +| `return-route --method udp --max-hops 30` | VPS 到固定中国目标方向，不等于中国到 VPS 去程 | + +## 输出和报告 + +```bash +"$VM" check --lang zh --theme framed --color always +"$VM" suite --json-output report.json +"$VM" report --input report.json --output report.md +"$VM" recover --journal report.json.events.jsonl --output recovered.json +``` + +主题支持 `default / iprisk / framed`，中英文可选；窄终端推荐 framed。Linux 纯文字控制台默认英文，中文需要字体支持。保存时不覆盖已有文件，默认脱敏；`--show-ip` 只影响终端。中断尝试保存已完成结果，恢复以完整日志事件为准；断电/SIGKILL 不保证尚未落盘的数据。 + +退出码：`0` 完成；`1` 有发现、结果不完整或存储失败；`2` 参数/安装错误；`130` 中断。模块执行结束不代表全部检测成功。未知、缺依赖或权限不足不会写成安全或解锁。 + +`suite` 默认省略值仅为“未知／跳过”的空条目及离线未执行模块的标题；使用 `--show-unavailable` 显示这些条目。实际失败和重要限制仍显示，JSON 和恢复日志始终保留完整状态。 + +## 可选测速（会消耗流量） + +```bash +"$VM" bandwidth --allow-bandwidth --rounds 3 --sample-mib 4 +"$VM" bandwidth --china --allow-bandwidth --rounds 3 --sample-mib 1 +``` + +默认不开启。下载为节点→本机，上传为本机→节点；中国候选主要提供下载。大陆三网仍实验性，不保证覆盖与可用性；香港移动不替代大陆移动。小样本不证明端口上限，节点拥堵会影响结果。`attempted` 统计计划样本槽（含失败后跳过），不是实际请求次数。 + +## 常见问题 + +- **为什么没有安装到 PATH？** 安装器不改 shell 配置；使用打印的完整启动器路径。 +- **为什么不能再次安装？** 保护已有文件；使用新的 `--prefix`。 +- **为什么 ICMP/TCP 跳过？** 需要系统已有 `traceroute` 和相应权限；不会自动提权/安装。 +- **中间跳点超时是否丢包？** 不一定。设备可能只过滤探测响应；不能据单跳延迟判断真实转发拥堵。 +- **为什么媒体是 unknown？** DNS、TLS、HTTP、反爬、账号和地区因素不能总是自动区分；网页成功不等于播放成功。 +- **报告能直接公开吗？** 仍需人工检查。第三方 API 会看到来源 IP，数据保存和分享受[服务条款](DATA_SERVICES.md)约束。 +- **这些 CPU/内存是独享吗？** 只反映来宾可见资源及可见配额，不能证明宿主硬件独享。 + +[安装指南](INSTALL.md) · [已知限制](../release/KNOWN_LIMITATIONS.md) diff --git a/CHANGELOG.md b/docs/release/CHANGELOG.md similarity index 96% rename from CHANGELOG.md rename to docs/release/CHANGELOG.md index 185ad2f..f215231 100644 --- a/CHANGELOG.md +++ b/docs/release/CHANGELOG.md @@ -1,13 +1,13 @@ -> 历史记录 / Historical record：ProxyDoctor 是项目旧名。以下旧版本、SHA256、测试数量与路径保留原样，不代表 VPSMaster 新构建已通过；当前范围见 README.md、CURRENT_STATUS.md 和新包同 SHA256 验收报告。 +> 历史材料：版本、测试数量与旧路径仅说明当时状态，不是本次构建的验收证据。参见[当前发行说明](RELEASE_NOTES.md)。 ## 1.0.0b1 — 2026-11-01 公测候选，非最终版本 -终端、语言和参数修复；流媒体改为可达性；新增可选 ICMP/TCP、三城三运营商追踪、BGP 和候选节点探测。完整大陆三网未验证。详见 PUBLIC_BETA_CHANGE_REPORT.md。 +终端、语言和参数修复；流媒体改为可达性；新增可选 ICMP/TCP、三城三运营商追踪、BGP 和候选节点探测。完整大陆三网未验证。详见 [早期 Beta 变更](../archive/PUBLIC_BETA_CHANGE_REPORT.md)。 ## v0.1.0-alpha 候选（2026-11-01） -隔离离线安装、完整性拒绝、网络worker超时/取消、统一结果schema、独立模块增量保存、路由重复探测统计已实现；两版Ubuntu各248自动测试/23实际验收。全新OS镜像尚缺，建议内部试用、暂缓公开。详情见ALPHA_RELEASE_REPORT.md。无主分支合并。 +隔离离线安装、完整性拒绝、网络worker超时/取消、统一结果schema、独立模块增量保存、路由重复探测统计已实现；两版Ubuntu各248自动测试/23实际验收。全新OS镜像尚缺，建议内部试用、暂缓公开。详情见[Alpha 报告](../archive/ALPHA_RELEASE_REPORT.md)。无主分支合并。 ## 报告与IP质量更新（2026-11-01） @@ -17,7 +17,7 @@ - 分享副本增加敏感键、Bearer凭证、URL用户信息/查询参数脱敏；仍需人工复核，不保证任意文本完全匿名。 - 新增IP概览面板，CJK对齐与长行换行；多来源类型/代理/VPN/Tor证据放在下面，不合成纯净度评分。 - 新增可选 `--mail-probes`：PTR/正向一致性、单目标出站TCP25，默认不启用，不发送邮件。DNSBL明确未查询；IPMap尚未接入。 -- 实际阅读xykt/IPQuality源码与AGPL许可，只参考需求与组织，未复制实现，详见IPQUALITY_COVERAGE.md。 +- 实际阅读xykt/IPQuality源码与AGPL许可，只参考需求与组织，未复制实现，详见[IP 功能范围](../guide/IPQUALITY_COVERAGE.md)。 - 报告/恢复/PTR实网版本两版Ubuntu均237测试通过；最终面板加入后，两版完整离线回归均239测试通过（22：4.04秒；24：4.49秒）。报告导出、恢复JSON/Markdown、中英文离线真实CLI均退出0。IP数据不完整时退出1符合预期。 - 实网：22的单目标出站TCP25可连接，24未确认；两台PTR未取得有效结果，不能据此判断邮件信誉。无付费API、系统依赖安装或完整报告上传。 diff --git a/KNOWN_LIMITATIONS.md b/docs/release/KNOWN_LIMITATIONS.md similarity index 95% rename from KNOWN_LIMITATIONS.md rename to docs/release/KNOWN_LIMITATIONS.md index 0c410b9..f9a6077 100644 --- a/KNOWN_LIMITATIONS.md +++ b/docs/release/KNOWN_LIMITATIONS.md @@ -15,7 +15,7 @@ - Sharing redacts known patterns, not arbitrary text. Review exports; raw journals, inventories, credentials, snapshots and backups must remain private. - Reports do not expire automatically. Third-party data retention/sharing terms - remain applicable; see docs/DATA_SERVICES.md, including IP2Location cache limits. + remain applicable; see [data-service terms](../guide/DATA_SERVICES.md), including IP2Location cache limits. - The manifest detects file changes, not publisher authenticity. Verify the ZIP digest through a trusted independent channel before installation. - Media checks cover public-page reachability only, not unlock or paid playback. diff --git a/RELEASE_NOTES.md b/docs/release/RELEASE_NOTES.md similarity index 81% rename from RELEASE_NOTES.md rename to docs/release/RELEASE_NOTES.md index 84c193c..1a295cb 100644 --- a/RELEASE_NOTES.md +++ b/docs/release/RELEASE_NOTES.md @@ -26,6 +26,10 @@ 旧ProxyDoctor ZIP不能改名充当新版通过。完整回归、新SHA、最终ZIP安装/关键功能证据写入包外VPSMASTER_TEST_REPORT.md；未验证构建必须标UNVERIFIED。 升级使用新目录，保留旧报告。没有自动更新/迁移。 -MIT许可，保留历史版权和第三方来源说明。尚未推送、合并或创建公开Release。 +MIT许可，保留历史版权和第三方来源说明。仅准备 Beta 候选；不代表已经公开发布。 当前不具备一键安全加固或自动修复。未来遵循检测→解释→预览→确认→备份→执行→验证→回滚；回滚不能覆盖所有断网/重启/云安全组/宿主机故障。本轮只更新路线与私有发布准备。 + +## 仓库目录整理 + +README 中英文首页精简；指南、安全、开发、发行和历史材料分别归档。内部过程文档保留在本地备份，Git 历史不重写。Python 包、CLI 兼容入口与安装路径保持一致。目录和截图属于包内变更，因此另行构建、校验并从最终 ZIP 验收；原验收包保持不变。 diff --git a/docs/security/ROADMAP.md b/docs/security/ROADMAP.md new file mode 100644 index 0000000..4a7d91d --- /dev/null +++ b/docs/security/ROADMAP.md @@ -0,0 +1,45 @@ +# Linux VPS 安全诊断与加固路线 / Roadmap + +项目从可信检测逐步发展为 Linux 服务器安全诊断与加固助手。Phase 1 是当前基础，Phase 2–5 均为 Planned，不属于当前 Beta，不承诺固定交付时间。 + +## Phase 1 — VPS 综合检测（当前 Beta） + +系统与可见资源、DNS/IPv4/IPv6/TCP/TLS、原生 UDP 与可选系统 ICMP/TCP 路由、BGP/ASN/IP 信息、基础只读安全体检、本地报告与恢复。系统依赖、权限和第三方数据决定实际覆盖；媒体仅公开网页可达性。[当前限制](../release/KNOWN_LIMITATIONS.md) + +## Phase 2 — 检测能力完善（Planned） + +- CPU、磁盘性能基准，独立明确授权和负载预算。 +- 中国大陆电信、联通、移动测速覆盖和可靠性完善。 +- 扩展 IP 情报交叉验证、网络线路分析与诊断建议。 +- 更完整的 Linux 安全基线、VPS 购买验收和性能分析。 + +## Phase 3 — 一键安全加固（Planned，未来重点） + +- SSH 配置、登录保护、密钥认证策略。 +- UFW/nftables 配置及 Fail2ban 暴力破解防护。 +- 系统更新/补丁检查，用户权限与文件权限加固。 +- 不必要服务与开放端口管理，Linux 安全基线。 +- 可选择的加固方案、风险解释与修改预览。 + +不会默认自动修改服务器配置。执行必须经过用户明确确认；检测到风险不等于获得修改授权。不通过关闭安全保护或放宽权限“修复”。 + +## Phase 4 — 安全备份、回滚与持续监控（Planned） + +- 修改前备份 SSH、防火墙及相关配置，展示变更差异。 +- 验证并保留 SSH 管理通道，考虑业务端口和云安全组，执行后重新验证连接。 +- 在具备可靠机制时提供超时回滚、操作审计及恢复向导。 +- 定期安全体检、配置漂移、异常登录提醒、网络稳定性与历史报告对比。 + +重点避免用户加固 SSH/防火墙时失去管理访问；不能承诺自动恢复全部断网、重启、云安全组或宿主故障。涉及高风险变更不得无人确认执行，必须说明回滚前提与人工恢复入口。 + +## Phase 5 — Web UI 与可视化管理（长期规划） + +本地 Web 面板、服务器状态、安全风险和加固任务、备份/恢复界面、多 VPS 及可选服务部署维护。认证、权限、敏感凭据及访问安全是前提，默认不向公网开放管理入口。 + +## 长期安全原则 + +**检测 → 解释 → 预览 → 确认 → 备份 → 执行 → 验证 → 回滚** + +默认只读、显式授权、幂等与审计、管理连接及业务端口保护。未知不能视为安全；有依据地描述风险，不提供无法解释的绝对安全评分。 + +[首页](../../README.md) · [安全反馈](SECURITY.md) diff --git a/SECURITY.md b/docs/security/SECURITY.md similarity index 100% rename from SECURITY.md rename to docs/security/SECURITY.md diff --git a/proxydoctor/cli.py b/proxydoctor/cli.py index 544ede9..1308751 100644 --- a/proxydoctor/cli.py +++ b/proxydoctor/cli.py @@ -142,6 +142,7 @@ def _main(): suite.add_argument('--no-geo',action='store_true',help=st('不查询路由 IP 位置','Skip route IP geolocation lookups')) suite.add_argument('--color',choices=('auto','always','never'),default='auto') suite.add_argument('--theme', choices=('default','iprisk','framed'), default='default', help=st('终端版式：default/iprisk/framed','Terminal theme: default/iprisk/framed')) + suite.add_argument('--show-unavailable', action='store_true', help=st('显示无数据与跳过的条目（完整报告始终保留）','Show unavailable/skipped rows (always retained in reports)')) suite.add_argument('--route-method',choices=('udp','icmp','tcp'),default='udp') suite.add_argument('--tcp-port',type=int,default=443) suite.add_argument('--china-speed',action='store_true',help=st('启用大陆三运营商候选测速；仍需 --allow-bandwidth','Select mainland carrier speed candidates; requires --allow-bandwidth')) @@ -279,7 +280,7 @@ def _main(): max_hops=args.max_hops,geo=not args.no_geo,color=args.color, bandwidth_rounds=args.bandwidth_rounds,skip_route=args.skip_route,json_output=args.json_output, bandwidth_sources=args.bandwidth_source or (CHINA_SOURCES if args.china_speed else None),port=args.port,show_ip=args.show_ip,ip_enrichment=not args.no_ip_enrichment,allow_bandwidth=args.allow_bandwidth,mail_probes=args.mail_probes,route_probes=args.route_probes,theme=args.theme, - route_method=args.route_method,tcp_port=args.tcp_port,include_return_routes=args.include_return_routes,include_bgp=args.include_bgp) + route_method=args.route_method,tcp_port=args.tcp_port,include_return_routes=args.include_return_routes,include_bgp=args.include_bgp,show_unavailable=args.show_unavailable) except OSError: parser.error(st('无法保存报告，请检查输出目录和文件权限','Unable to save report; check the output directory and file permissions')) sys.exit(code) diff --git a/proxydoctor/console.py b/proxydoctor/console.py index 2db874d..aab1e7b 100644 --- a/proxydoctor/console.py +++ b/proxydoctor/console.py @@ -73,8 +73,9 @@ def can_render_cjk(): class Console: - def __init__(self, lang='zh', color='auto'): + def __init__(self, lang='zh', color='auto', hide_unavailable=False): self.lang = lang + self.hide_unavailable = hide_unavailable self.enabled = color == 'always' or (color == 'auto' and sys.stdout.isatty() and 'NO_COLOR' not in os.environ) self._framed = False # when True, row/keyvalue/section render inside a box @@ -90,6 +91,12 @@ class Console: return f'\033[{code}m{value}\033[0m' def row(self, label, value, status='ok'): + # Hide empty observations only, never a measured failure or a limitation. + if self.hide_unavailable and status == 'unknown' and clean(value).casefold() in { + 'unknown', 'unavailable', 'not available', 'skipped', 'skipped offline', + '未知', '无法判断', '不可用', '未获取', '已跳过', '离线跳过', + }: + return if self._framed: self.frame_keyvalue(label, value, status) return diff --git a/proxydoctor/suite.py b/proxydoctor/suite.py index a77a305..91a2b85 100644 --- a/proxydoctor/suite.py +++ b/proxydoctor/suite.py @@ -25,7 +25,7 @@ def execute_provider(argv, timeout=180): def run_suite(lang='zh',offline=False,sample_mib=4,route_target='1.1.1.1',besttrace=None, region_script=None,max_hops=30,geo=True,color='auto',bandwidth_rounds=3,skip_route=False,json_output=None,bandwidth_sources=None,port=8388,show_ip=False,ip_enrichment=True,allow_bandwidth=False,mail_probes=False,route_probes=3,theme='default', - route_method='udp',tcp_port=443,include_return_routes=False,include_bgp=False): + route_method='udp',tcp_port=443,include_return_routes=False,include_bgp=False,show_unavailable=False): from .cli import redact from .console import Console import re @@ -36,7 +36,7 @@ def run_suite(lang='zh',offline=False,sample_mib=4,route_target='1.1.1.1',besttr if not 1<=route_probes<=3:raise ValueError('Route probe rounds must be 1..3') if route_method not in ('udp','icmp','tcp') or not 1<=tcp_port<=65535 or theme not in ('default','iprisk','framed'): raise ValueError('Invalid route or theme options') - out=Console(lang,color); tr=out.text + out=Console(lang,color,hide_unavailable=not show_unavailable); tr=out.text iprisk = theme == 'iprisk' framed = theme == 'framed' from datetime import datetime,timezone @@ -255,16 +255,16 @@ def run_suite(lang='zh',offline=False,sample_mib=4,route_target='1.1.1.1',besttr runner.run('security', collect_security) runner.run('bandwidth', collect_bandwidth, 'offline' if offline else 'consent_required' if not allow_bandwidth else None) - if offline: + if offline and show_unavailable: heading(2,'节点网络质量','Node network quality') out.row('DNS / TCP / TLS',tr('离线跳过','Skipped offline'),'unknown') runner.run('network', collect_network, 'offline' if offline else None) runner.run('ip_quality', collect_ip_quality, 'offline' if offline else None) - if offline or skip_route: + if (offline or skip_route) and show_unavailable: heading(3,'路由追踪','Route trace') out.row(tr('路由','Route'),tr('已跳过','Skipped'),'unknown') runner.run('route', collect_route, 'offline' if offline else 'user_skipped' if skip_route else None) - if offline: + if offline and show_unavailable: heading(4,'流媒体可达性','Media reachability') out.row(tr('流媒体','Media'),tr('离线跳过','Skipped offline'),'unknown') runner.run('media', collect_media, 'offline' if offline else None) diff --git a/tests/test_compact_display.py b/tests/test_compact_display.py new file mode 100644 index 0000000..0112fbc --- /dev/null +++ b/tests/test_compact_display.py @@ -0,0 +1,40 @@ +"""Display filtering must not hide findings or alter machine-readable evidence.""" +import json +import pytest +from proxydoctor.console import Console + + +@pytest.mark.parametrize('lang,empty', [('zh','未知'), ('en','Unknown')]) +@pytest.mark.parametrize('framed', [False, True]) +def test_only_empty_observations_hidden(capsys, lang, empty, framed): + out=Console(lang,'never',hide_unavailable=True) + if framed:out.frame_open('Test') + out.row('missing-row',empty,'unknown') + out.row('measured-failure','connection refused','bad') + out.row('limit','Exclusivity unconfirmed','unknown') + if framed:out.frame_close() + text=capsys.readouterr().out + assert 'missing-row' not in text + assert 'connection refused' in text + assert 'Exclusivity unconfirmed' in text + + +def test_verbose_display_preserves_unknown(capsys): + Console('en','never').row('missing','Unknown','unknown') + assert 'Unknown' in capsys.readouterr().out + + +def test_offline_compact_report_keeps_skipped_modules(tmp_path, monkeypatch, capsys): + from proxydoctor.suite import run_suite + monkeypatch.chdir(tmp_path) + report=tmp_path/'compact.json' + code=run_suite(lang='en',offline=True,json_output=report,color='never') + assert code in (0,1) + text=capsys.readouterr().out + assert 'Skipped offline' not in text + data=json.loads(report.read_text()) + for name in ('network','route','media','ip_quality'): + assert data['modules'][name]['status']=='skipped' + verbose=tmp_path/'verbose.json' + assert run_suite(lang='en',offline=True,json_output=verbose,color='never',show_unavailable=True) in (0,1) + assert 'Skipped offline' in capsys.readouterr().out diff --git a/tests/test_phase1_delivery.py b/tests/test_phase1_delivery.py index d89865d..2e7a264 100644 --- a/tests/test_phase1_delivery.py +++ b/tests/test_phase1_delivery.py @@ -106,7 +106,7 @@ def test_suite_includes_security_network_and_route_evidence(monkeypatch,tmp_path def trace(*args,**kwargs):kwargs['records'].append({'hop':1,'ip':'8.8.8.8','latency_ms':2});return 0 monkeypatch.setattr(suite,'native_trace',trace) path=tmp_path/'suite.json' - assert suite.run_suite(lang='en',port=2222,json_output=path)==1 + assert suite.run_suite(lang='en',port=2222,json_output=path,show_unavailable=True)==1 result=json.loads(path.read_text(encoding='utf-8')) output=capsys.readouterr().out assert 'SSH port guard' in output and 'Local port 2222' in output diff --git a/tests/test_suite.py b/tests/test_suite.py index 172b5fb..db7e4cc 100644 --- a/tests/test_suite.py +++ b/tests/test_suite.py @@ -27,7 +27,7 @@ def test_offline_suite_never_calls_network_or_providers(monkeypatch,capsys): monkeypatch.setattr(suite,'execute_provider',unexpected) monkeypatch.setattr(suite,'native_trace',unexpected) import platform - assert suite.run_suite(offline=True)==(0 if platform.system()=='Linux' else 1) + assert suite.run_suite(offline=True,show_unavailable=True)==(0 if platform.system()=='Linux' else 1) text=capsys.readouterr().out assert all(f'===== {number}.' in text for number in range(1,5))