pandora0667/netlab

# Netlab Netlab 是一个基于单个 Express 服务器构建的 TypeScript 全栈网络实用工具应用。 在开发环境中，服务器以中间件模式运行 Vite，并在同一进程中提供 React 客户端服务。 在生产环境中，服务器从 `dist/public` 提供已构建的客户端。 ## 当前技术栈 - Frontend: React 18, Wouter, SWR, React Hook Form, Zod, Tailwind CSS, shadcn/ui - Backend: Express, `ws`, SSE, Node DNS/socket APIs - 工具链: Vite, TypeScript, tsx, esbuild, pnpm ## 已实现的工具 - IP 检查器 - 具有可选公共解析器和自定义解析器验证的 DNS 查询 - 具有请求级 WebSocket 更新的 DNS 传播检查器 - 子网计算器 - 具有 WebSocket 进度显示的 Ping 工具 - WHOIS 查询 - 具有 SSE 进度显示和 JSON/CSV 导出的端口扫描器 ## 仓库结构 ``` . ├── client/ │ ├── public/ │ └── src/ │ ├── components/ │ ├── domains/ │ └── lib/ ├── server/ │ ├── common/ │ ├── config/ │ ├── data/ │ ├── lib/ │ ├── middleware/ │ ├── modules/ │ └── src/lib/ ├── dist/ ├── package.json ├── pnpm-lock.yaml ├── .nvmrc ├── tsconfig.json └── vite.config.ts ``` ## 前置条件 - Node.js 24.x LTS - pnpm 10.x 以下示例使用 `pnpm`。 你可以使用 `.nvmrc` 固定本地 Node 运行时。 ## 安装 ``` pnpm install ``` 对于本地开发，`.env` 文件是可选的。对于生产环境，请将 `.env.example` 复制到 `.env`，并根据你的部署调整运行时限制。 ## 开发 ``` pnpm run dev ``` Express 服务器在 `http://localhost:8080` 上启动。 ## 测试 ``` pnpm run test pnpm run typecheck ``` 当前的自动化测试涵盖验证工具，以及针对旧版 `/api/*` 端点和新版基于 envelope 的 `/api/v1/*` 端点的 HTTP 路由回归测试。浏览器流程尚未覆盖。 ## 构建 ``` pnpm run build pnpm run start ``` ## Docker 生产容器现在遵循与本地开发相同的运行时标准： - `node:24-bookworm-slim` - 通过 Corepack 安装的 `pnpm` - 多阶段构建 - 最终镜像中仅包含生产环境依赖 构建并运行： ``` docker build -t netlab:latest . docker run --rm -p 8080:8080 --env-file .env netlab:latest ``` ## API 版本控制 - 旧版端点仍保留在 `/api/*` 下以保持兼容性。 - 新的后端工作应面向 `/api/v1/*`。 - 前端 HTTP 调用现在通过 `client/src/domains/*` 路由，并默认指向 `/api/v1/*`。 - `/api/v1/*` 响应使用统一的 envelope： ``` { "success": true, "data": {}, "error": null, "requestId": "req_..." } ``` ``` { "success": false, "data": null, "error": { "code": "SOME_ERROR_CODE", "message": "Human-readable message" }, "requestId": "req_..." } ``` 当前的 v1 模块： - `/api/v1/network` - `/api/v1/dns` - `/api/v1/dns-propagation` - `/api/v1/port-scans` 传输层例外： - WebSocket 端点仍为 `/ws/ping` 和 `/ws/dns-propagation` - 端口扫描进度流使用 `/api/v1/port-scans/stream` ## 运行时说明 - DNS 传播使用 WebSocket 流式传输结果、进度和完成事件。 - Ping 使用 WebSocket，并在执行前在服务器端验证输入。 - 端口扫描目前使用 Server-Sent Events，而非 worker threads。 - 应用在 `logs/` 下写入结构化日志。 - 每个 HTTP 响应都包含一个 `X-Request-Id` 标头。相同的请求 ID 会被写入应用日志以便追溯。 - 与滥用相关的事件，如触发速率限制和被阻止的非公共目标，会写入 `logs/abuse.log`。 - DNS 传播服务器元数据在本地和容器运行时路径中均从 `server/data/dns-servers.csv` 加载。 ## 生产环境说明 ### 反向代理 `trust proxy` 可通过 `TRUST_PROXY` 配置。 - `TRUST_PROXY=1` 当 Express 位于单个受信任的反向代理（如 Nginx 或平台 ingress）之后时使用此设置。 - `TRUST_PROXY=true` 信任所有代理。这很方便，但应仅在上游标头受到严格控制时使用。 - `TRUST_PROXY=loopback,linklocal,uniquelocal` 当你需要更精细的控制时，使用与 Express 兼容的代理信任列表。 如果此设置错误，`req.ip`、速率限制和滥用日志可能会使用错误的客户端 IP。 ### 请求追踪 - 如果 `X-Request-Id` 符合格式要求，服务器将接受该标头，否则服务器会生成一个新 ID。 - 生成的请求 ID 会在响应标头中返回，并包含在结构化日志中。 - `healthz` 和 `readyz` 也会返回活动的请求 ID，以便快速诊断。 ### 出站安全策略 - `ping`、自定义 DNS 服务器验证和端口扫描仅允许公共目标。 - 私有、环回、链路本地、多播和保留地址范围将被阻止。 - 主机名会先进行解析，如果任何解析出的地址是非公共的，则会被拒绝。 ### 运行时限制 默认值旨在适用于公共工具，但仍然是有界的。 - 全局 API 限制：每个 IP 每 `15` 分钟 `300` 次请求 - Ping：每 `15` 分钟 `90` 次请求，全局 `20` 个并发，每个 IP `2` 个并发 - DNS 查询和验证：每个 IP 每 `15` 分钟 `60` 次请求 - DNS 传播：每 `15` 分钟 `30` 次请求，全局 `8` 个并发，每个 IP `2` 个并发 - 端口扫描：每 `15` 分钟 `20` 次请求，每次请求最多 `256` 个端口，最大超时 `2000ms`，全局 `4` 个并发，每个 IP `1` 个并发 所有这些值都可以通过 `.env.example` 中的环境变量进行配置。 ### 依赖项卫生 - `pnpm run audit:deps` 审计已安装的包是否存在已知漏洞 - `pnpm run deps:outdated` 在升级工作之前检查依赖项版本滞后情况 ### 运维日志 - `logs/info.log` 正常的生产活动 - `logs/error.log` 应用程序错误 - `logs/debug.log` 仅用于开发的详细日志 - `logs/abuse.log` 速率限制触发、被阻止的公共目标违规以及其他与滥用相关的事件 ## 已知的维护优先级 - 将大型前端包拆分为路由级块 - 继续移除遗留的重复文件和死代码 - 扩展服务端和集成测试覆盖率 - 为你的实际反向代理和托管设置添加特定部署文档

标签：CDN识别, DNS传播检查, DNS枚举, DNS查询, DNS解析, DNS解析器, Docker 部署, Express, GNU通用公共许可证, IP查询, MITM代理, Node.js, Ping工具, React, shadcn/ui, SSE, SSL检查, Syscalls, Tailwind CSS, Traceroute, TypeScript, Vite, WebSocket, WHOIS查询, 依赖分析, 协议探测, 单页应用, 子网计算器, 安全插件, 开源项目, 情报分析, 数据统计, 端口扫描, 系统分析, 网络分析, 网络安全工具, 网络工具, 网络诊断, 网络运维, 自动化攻击, 请求拦截, 通信测试