使用文档

快速开始

当前项目面向 Windows 本地授权测试。管理端编辑 SQLite 策略；代理只接受显式配置的 HTTP/HTTPS CONNECT 流量，且仅监听本机回环地址。

准备环境

• Windows 与 .NET SDK 9.0（构建解决方案）。
• .NET Framework 4.8（运行当前原型；Legacy Windows 7 目标不能依赖 4.8.1）。
• 首次构建需访问 NuGet 以还原参考程序集和 SQLite 依赖。

构建并运行测试

dotnet build .\NetWard.sln --configuration Release
.\scripts\test.ps1

测试脚本会构建、运行策略/SQLite/代理集成测试并执行代理 CLI 冒烟测试；测试网络使用本机回环服务。

启动显式代理

.\src\WebBlocker.ProxyHost\bin\Release\net48\NetWard.ProxyHost.exe `
  --mode allowlist `
  --rule subdomains:example.com `
  --database "$env:TEMP\NetWard\netward-dev.db"

.\src\WebBlocker.Administrator\bin\Release\net48\NetWard.Administrator.exe `
  --database "$env:TEMP\NetWard\netward-dev.db"

系统要求与兼容性

Windows 7 SP1 仅是 Legacy 版本线的规划兼容目标，不是测试通过声明；不得将其扩展到 Modern 版本线。WinUI 3 的操作系统底线要依据选定的 Windows App SDK 实际核实。浏览器 kiosk 功能也没有实现；Edge、Chrome 或默认浏览器的 kiosk 兼容性尚未验证。

首次配置与运行

首次设置策略

新数据库首次启动代理时，需明确提供白名单/黑名单模式与至少一条域名规则。例如，白名单模式、允许根域及其子域：

--mode allowlist --rule subdomains:example.com

若确实要使用空规则集，需显式追加 --allow-empty-rules。白名单空规则会默认拒绝所有未匹配主机；黑名单空规则会默认允许未匹配主机，请谨慎确认。

选择数据库

默认数据库位于 %LOCALAPPDATA%\WebBlocker\proxy.db。可用 --database <path> 指定路径。管理端和代理需指向同一数据库才能共享本地策略与日志。SQLite 数据包含敏感 HTTP 查询参数，应由设备管理员按组织要求保护并备份。

停止和重新加载

在代理宿主的控制台按 Ctrl+C 正常停止。管理端写入的新策略只在代理下一次启动时加载。

访问规则

规则仅比较规范化后的主机名，不支持通配符、完整 URL 路径或查询串规则。精确规则匹配主机本身；“包含子域名”还匹配以点号边界结束的子域名，例如 www.example.com，但不匹配 notexample.com。

限时类别

限时规则叠加在基础策略上：基础策略先判定，只有基础策略允许的主机才会消耗匹配类别的每日窗口。首次匹配请求启动连续墙钟倒计时；关闭浏览器不暂停；最迟到当地次日零点重置。它不是活跃标签页时长统计。

生效条件与刷新

• 只有手动配置为使用代理的应用请求会进入判断。
• 管理端保存策略后需重启代理，现阶段没有热同步。
• VPN、直连、其他代理、DoH、QUIC/HTTP/3 等路径可能绕过或隐藏请求。
• 分类网站页目前只有禁用状态的类别占位，不参与判定。

访问日志

管理端“访问日志”页支持域名搜索、仅查看拒绝/拦截异常、分页查询。时间以 UTC 显示。策略结果表示代理的决策，不证明目标网页最终成功加载。

访问事件超过 30 天后会在代理启动时和运行期间每小时清理；管理端启动时也会清理。当前没有远程日志同步或日志导出功能。在线 SQLite 备份可使用 --backup-to <destination>，目标文件必须不存在。

设备配对与多设备

当前没有被控端 Agent、配对码、远程管理端监听器或设备注册表。管理端是读取本地 SQLite 数据库的本地 WinForms 工具，不连接局域网中的其他计算机。

未来的设备通信目标包括所有者同意、一次性配对凭据、认证加密传输、设备身份撤销、每设备策略隔离、明确的在线/离线状态、断线重试和日志确认。具体方案和状态见架构说明与产品需求。

故障排查

常见问题