企业官网建设流程全解析

• 桌面应用
• 开发工具

本篇技术指南以 MooTool Next（Electron 重构版）的 P5 网络与系统工具 Parity Checklist 为骨架，系统讲解 HTTP 请求、翻译、Host、网络/IP、环境变量、系统信息六大工具在与 Java 基线对齐过程中的完整实现：从主进程服务、IPC 校验边界、统一代理与密钥隔离，到跨平台提权写入、SQLite 持久化和自动化验证。读完你将掌握 MooTool Next 网络与系统工具的可复现配置、源码级调用链与发布前验收口径。

1. P5 工具全景：六项工具的能力基线

P5 阶段以当前 Java 版（github-develop-ts分支）为基线，将六项网络与系统工具迁移到 Electron 重构版（Next），每一项目标均是"功能完整 + 布局一致 + 数据兼容"。清单与状态如下：

从源码结构看，六项工具的 Renderer 页面分布在 src/features/http/HttpTool.tsx、src/features/translation/TranslationTool.tsx、src/features/host/HostTool.tsx、src/features/net/NetTool.tsx、src/features/variables/VariablesTool.tsx 与 src/features/hardware/HardwareTool.tsx 中，均统一使用tool-page p5-tool页面容器。

2. 架构边界：主进程集中执行与 Renderer 隔离

P5 实现遵循一条严格边界：Renderer 只使用 typed preload API，HTTP、翻译、SQLite、Hosts、DNS、WHOIS、系统命令和硬件采集全部在 Electron 主进程执行。

• typed preload 桥接：所有 P5 能力以 IPC channel 形式暴露在window.mootool上，见 next/electron/preload/index.ts。例如sendHttpRequest、translate、readSystemHosts/writeSystemHosts、runNetworkCommand/cancelSystemCommand、getEnvironmentSnapshot、getSystemInfo等。
• IPC 注册与校验：主进程入口 next/electron/main/index.ts 中http:send、translation:send、host:write-system、system:network-command、system:environment-set等 handler 均先经过 p5Validation.ts 的归一化校验再交给服务执行。校验覆盖：请求方法（仅GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS）、URL 长度上限 8192、Body 上限 5 MB、Param/Header/Cookie 每类最多 100 条、翻译文本上限 50000、语言对归一化、Host 内容上限 2 MB、超时钳制在 1000~120000 ms（缺省 30000）、请求 ID 白名单字符，以及系统命令 action 枚举。
• 环境变量写入校验：normalizeEnvironmentVariableInput强制 scope 只能是user/system，变量名必须匹配^[A-Za-z_][A-Za-z0-9_]*$，值长度 ≤ 65535 且不允许包含 NUL 与换行（见 p5Validation.ts）。
• 统一代理设置：HTTP 与翻译共用一套代理配置。代理密码通过safeStorage.encryptString加密后以 base64 存入secrets，只有主进程用safeStorage.decryptString读取，不进入 Renderer 和普通设置 JSON（见 index.ts）。翻译另有一条"系统代理兜底"逻辑：应用未启用代理时，调用session.defaultSession.resolveProxy解析 Chromium/系统代理并提取首个 HTTP CONNECT 条目，以此对齐 Java 版 JVM 自动拾取系统代理的行为（getTranslationProxyConfiguration，配合parseChromiumProxyDirective实现，networkService.ts）。
• 设置项：设置 Schema 自 P5 起升级，提供 HTTP 请求超时、翻译超时、默认翻译器和源/目标语言。当前 contracts/settings.ts 中appSettingsSchemaVersion已迭代至 14，相关字段仍稳定存在：network.requestTimeoutMs（默认 30000）、network.translationTimeoutMs（默认 15000）、network.proxyEnabled/proxyHost/proxyPort/proxyUsername、tools.translationProvider（默认google）、tools.translationSourceLang（默认auto）、tools.translationTargetLang（默认zh-CN）。
• 可取消请求生命周期：HTTP 与翻译共享AbortController集合；网络命令走spawn+SIGTERM。网络命令参数一律使用白名单参数数组，绝不执行 Renderer 传入的脚本或 Shell 字符串（见 systemService.ts 中networkCommand的按平台参数构造）。
• 数据层：HTTP 请求、请求历史、Host 方案、翻译单词本和翻译历史五类数据使用表名与 Java 版一致的 SQLite Repository，见下节。

3. 持久化：Java 兼容表名的 SQLite Repository

P5Repository 基于 Node 内置node:sqlite的DatabaseSync，初始化时开启PRAGMA journal_mode = WAL与busy_timeout = 3000，并创建五张 Java 兼容表：

集成测试 p5Repository.integration.test.ts 使用临时目录MooToolNext.db覆盖了五张表的写入/更新/查询：HTTP 请求按名字 upsert、更新后响应体同步刷新；Host 方案支持按名称和内容搜索（includeContent=false时仅按名称）；单词本重复保存同一(source, lang)组合会走更新分支。历史表通过DELETE ... WHERE id NOT IN (SELECT id ... LIMIT 500)控制行数上限，防止无限膨胀。

4. HTTP 请求工具：主进程 Undici 客户端的完整请求链路

4.1 布局对齐

HTTP 页面保留 Java 版"左侧请求集合 + 上方 URL/Method + 请求/响应上下分区"的工作流。页面截图见 p5-http-1440-light.png（1440 x 920 浅色），深色视口对应 p5-http-1080-dark.png。

4.2 请求构造与发送

核心实现在 networkService.ts 的sendHttp：

• URL 归一化：buildRequestUrl对无协议头的地址自动补http://，并在 GET/HEAD/OPTIONS 时把启用的 Params 拼入 query string；禁用条目（enabled=false）被enabledEntries过滤掉。
• Header/Cookie 合并：buildHeaders将启用的 Header 键值对转为对象，再把启用的 Cookie 按name=value以;连接写入Cookie头。
• Body 策略：buildRequestBody对 GET/HEAD/OPTIONS 不发送 body；有显式 body 时按bodyType设置Content-Type（缺省text/plain）；无 body 但有 Params 时自动编码为application/x-www-form-urlencoded表单。
• 传输层：使用undici的fetch，redirect: 'follow'；代理开启时通过按host|port|username|password缓存的ProxyAgentdispatcher 发送。
• 响应处理：响应按Content-Type声明的 charset 解码（缺省 UTF-8），body 若可解析为 JSON 则自动JSON.stringify(..., null, 2)美化；响应 Header 逐行格式化，set-cookie单独归入 Cookie 区。
• 10 MB 上限：maxResponseBytes = 10 * 1024 * 1024，readLimitedResponse先查content-length再验实际字节数，超限抛RESPONSE_TOO_LARGE。
• 错误分类：classifyNetworkError把失败归结为ABORTED、TIMEOUT、NETWORK、INVALID_REQUEST、RESPONSE_TOO_LARGE五类，写入HttpResponseResult.errorCode（契约见 contracts/network.ts）。

4.3 超时/取消与自动历史

begin(requestId, timeoutMs)为每个请求创建独立的AbortController并挂setTimeout（timerunref()），同 ID 发起新请求会先取消旧请求；cancel(requestId)显式中断。主进程http:sendhandler 在发送成功后自动把请求与响应写入历史表再返回（index.ts），Renderer 无需额外调用。

4.4 cURL 导入导出

前端 httpTools.ts 提供parseCurlCommand/toCurlCommand：支持-X/--request、-H/--header（含 Content-Type 识别）、-d/--data*（自动把 GET 升级为 POST）、-b/--cookie、--url；带引号与转义的状态机分词器保证 shell 风格参数正确解析。

4.5 集成验证

networkService.integration.test.ts 起本地 HTTP 服务覆盖：GET Query 参数拼装、自定义 Header 透传、Cookie 发送与set-cookie回读、无显式 body 时表单参数编码、响应 JSON 格式化，以及翻译长文本切分与语言码映射。

5. 翻译工具：500 ms 自动翻译与双引擎 fallback

5.1 布局与自动翻译

翻译页面保留"翻译/单词本/历史"Tab 顺序。TranslationTool.tsx 中源码变化通过useEffect触发500 ms debounce自动翻译（对engine.automatic的引擎），每次输入先取消上一个在途请求，并用自增requestSequence保证旧响应不会覆盖新结果；从单词本或历史回填（restore）不会触发重新在线翻译。

5.2 引擎实现

三套引擎均为轻量直接实现，注册在 translation/index.ts：

• Google（google.ts）：调用translate.googleapis.com/translate_a/single（client=gtx），长文本按 1800 字符切块、并发 3 拼接结果；语言码通过googleLanguage把 MooTool 内部码（如jp→ja、wyw→lzh、cht→zh-TW）映射为 Google 码。
• Bing（bing.ts）：先从cn.bing.com/translator抓取IG与params_AbusePreventionHelper令牌建立会话（带过期时间），再单次 POST 到ttranslatev3，与 Java 版保持一致——不做客户端切块。
• DeepL（deepl.ts）：API Key 以safeStorage加密保存、仅主进程读取；按:fx结尾自动选择api-free.deepl.com或api.deepl.com；为控制转义膨胀每块 ≤ 12000 字符、保证单个请求 body 低于 128 KiB；错误码规范化（DEEPL_INVALID_KEY、DEEPL_QUOTA_EXCEEDED、DEEPL_RATE_LIMITED），并主动丢弃远程响应体以防回显凭证。

5.3 fallback 顺序与冷却

translationProviderOrder（networkService.ts）决定：首选 Google 时顺序为google → bing，首选 Bing 时反之；deepl 不参与 fallback（互不支持的翻译器组合避免误判）。某个 provider 失败后进入10 分钟冷却（providerCooldownMs），期间shouldSkipProvider直接跳过他，避免每次击键都阻塞在死掉的端点上；成功后清除冷却。连接/body 超时对齐 Java 的GoogleTranslatorUtil：connect 5 秒、body 10 秒。

5.4 长文本切分与命名辅助

translation/text.ts 的splitTranslationText在切块时优先在自然断点（空白、标点）处断开，并回退代理对（surrogate pair）保证 emoji 不被截断——集成测试专门断言了 emoji 场景。翻译为英文时，translationNaming.ts 还提供标识符拆分与camelCase/PascalCase/snake_case/UPPER_SNAKE_CASE/kebab-case五种命名格式转换，便于把译文直接用作代码命名。

6. Host 工具：方案管理与跨平台提权写入

6.1 布局与方案 CRUD

Host 页面为"左侧方案 + 右侧工具栏/编辑器"结构，系统 Hosts 通过独立对话框（含路径与可写状态）查看。方案支持新建、重命名、删除、按名称或内容搜索（开关控制）、导入文本文件与导出hosts.txt；编辑器集成查找/替换栏（Cmd/Ctrl+F或R唤起，支持前后定位、全部替换）。编辑后 250 ms 空闲自动保存，保存队列串行化避免并发写覆盖。

6.2 系统 Hosts 写入矩阵

systemService.ts 的写入策略为：先readHosts读取/etc/hosts（Windows 为SystemRoot\System32\drivers\etc\hosts）并探测可写性；writeHosts先尝试普通写入，遭遇EACCES/EPERM时按平台提权：

• macOS：osascript执行do shell script ... with administrator privileges，复制临时文件后chmod 644并dscacheutil -flushcache；
• Windows：powershell.exe -Verb RunAs拉起提权进程执行Copy-Item ... -Force；
• Linux：pkexec执行cp+chmod 644。

写入前normalizeHostsContent统一 CRLF→LF、补齐末尾换行、拒绝 NUL（上限 2 MB）。提权临时文件以0600权限创建、finally中清理。写入成功后主进程会记录activeHostId并刷新托盘菜单（index.ts）。DNS 刷新动作由提权命令携带完成（macOSdscacheutil -flushcache，Windowsipconfig /flushdns，Linuxresolvectl flush-caches）。

7. 网络/IP 工具：白名单命令与扫描能力

7.1 布局

网络/IP 保留"左侧命令结果 + 右侧功能区"的桌面宽屏结构。截图见 p5-net-1440-light.png（浅色）与 p5-net-1080-dark.png（深色）。右侧功能区包含 IPv4/Long 双向转换、PING、网段扫描、端口扫描、DNS 解析、WHOIS、DNS 刷新与本机 IPv4/IPv6 地址。

7.2 命令执行安全

runNetwork支持interfaces、connections、ping、ping-range、port-scan、flush-dns、resolve、whois八个 action（契约见 contracts/system.ts）。其中系统命令经networkCommand生成固定参数数组：

resolve与whois不依赖 shell：前者走node:dns/promises的lookup(..., { all: true })返回全部地址；后者用createConnection直连whois.iana.org:43，解析refer/whois:头后跟进授权服务器二次查询。输出上限 2 MB，超时由clampTimeout（1000~120000，缺省 15000）控制，cancel对子进程发SIGTERM。错误码含ABORTED/TIMEOUT/PERMISSION/UNSUPPORTED/COMMAND_FAILED/INVALID_TARGET。

7.3 网段扫描与端口扫描

• parseIpv4Range('192.168.10')展开为192.168.10.1~.254共 254 个地址，concurrentMap并发 32 个 ping（单次上限 800 ms），输出可达主机列表；
• parsePortSpec支持3306,80-82,22形式与start-end区间，未填写时默认扫描 60+ 个常见端口（ssh/mysql/redis/kafka/elasticsearch 等带服务名标注），自定义端口上限 4096；TCP 探测并发 96，createConnection一次 connect 判断开/关，超时下限 100 ms。

7.4 IPv4/Long 双向转换

ipv4ToLong严格校验四段 0~255，longToIpv4校验0xFFFFFFFF上界（0 右移处理无符号语义），前端 netTools.ts 与主进程实现保持一致，systemService.test.ts验证了192.168.1.1 ⇄ 3232235777及非法输入拒绝。

8. 环境变量工具：用户/系统变量直改与运行时只读视图

8.1 布局

环境变量页面保留 Java 版 Tab、表格/键值结构与刷新、复制、导出操作；第二个 Tab 展示当前进程/Electron 运行属性只读视图（process.version、process.versions.electron/chrome/node、process.execPath、process.platform/arch、process.cwd、locale 与 timeZone），替代 Java Properties Tab——这是已批准差异之一，保留相同的"运行时属性检查"心智。

8.2 持久化写入

setEnvironmentVariable/deleteEnvironmentVariable（systemService.ts）：

• Windows：通过 PowerShell[Environment]::GetEnvironmentVariables([EnvironmentVariableTarget]::User/Machine)读写；system作用域用-Verb RunAs提权（脚本以 UTF-16LE 编码做-EncodedCommand，规避引号注入）。
• macOS/Linux 用户级：写入~/.MooTool/environment（0600权限，export KEY='value'语法），并自动在~/.profile（Linux）或~/.zshenv（macOS）追加带# >>> MooTool environment >>>标记的 source 块；macOS 额外调用launchctl setenv/unsetenv同步到当前登录会话。
• macOS 系统级：写入/etc/zshenv；Linux 系统级：写入/etc/environment（无export的KEY="value"语法）；权限不足时走pkexec/osascript提权复制。

写入后syncCurrentProcessEnvironment按 user→system 优先级把变更合并进当前进程process.env，使正在运行的应用立即生效。解析与序列化对单引号、反斜杠、双引号做了对称转义，systemService.test.ts断言了含'的 JAVA_HOME 往返一致。校验层拒绝非法变量名与含换行的值。

9. 系统信息工具：systeminformation结构化采集

getSystemInfo（systemService.ts）并行调用si.osInfo/system/cpu/currentLoad/mem/time/diskLayout/fsSize/networkInterfaces/networkStats，产出五个 Tab 分组：系统、CPU、内存、存储、网络。关键实现细节：

• 系统：平台、发行版、内核、架构、主机名、厂商/型号、运行时长（1d 2h 30m格式）、时区，以及脱敏后的序列号——mask()只保留前 2 位与后 2 位（ab****cd），防止硬件序列号泄漏；
• CPU：物理/逻辑核数、性能核与能效核、基础/最大频率、当前负载百分比；
• 内存：总量/已用/可用/活跃、使用率、Swap 统计，formatBytes统一按 1024 进制格式化；
• 存储：磁盘布局（设备、类型、接口、序列号脱敏、容量）与文件系统（类型、总量、已用、可用、使用率）两组；
• 网络：每张网卡的 IPv4/IPv6/MAC/MTU/速率/状态，以及从networkStats关联的收/发字节数。

字段文案与 Java OSHI 结果允许"平台等价"——即核心数据一致、命名可以不同（已批准差异）。前端 HardwareTool.tsx 支持按 Tab 复制当前分组的纯文本，并在英文标签与简中/英文/日文文案之间做映射。

10. 布局与行为对齐清单

原文案清单在 p5-network-system.md 中逐项打勾确认，汇总如下：

• 六个页面仅保留主标题，无小标题和面包屑；
• HTTP 保留"左侧请求集合 + 上方 URL/Method + 请求/响应上下分区"的 Java 工作流；
• 翻译保留翻译/单词本/历史 Tab 顺序，单词本或历史回填不触发重复在线翻译；
• Host 保留"左侧方案 + 右侧工具栏/编辑器"，系统 Hosts 通过独立对话框查看；
• 网络/IP 保留"左侧命令结果 + 右侧功能区"的桌面宽屏结构；
• 环境变量和系统信息保留 Tab、表格/键值结构与刷新、复制、导出操作；两版均支持直接修改用户/系统环境变量；
• 所有页面具有简体中文、英文、日文文案，并跟随系统明暗主题；
• 1440 x 920 浅色与 1080 x 720 深色共 12 张页面截图已建立，位于next/doc/screenshots/p5-<tool>-<viewport-theme>.png（如 p5-host-1440-light.png、p5-variables-1080-dark.png、p5-hardware-1440-light.png、p5-translation-1080-dark.png）；
• 两组视口下六页均无窗口级或工作区级横向溢出、控件遮挡和空白渲染。

11. 自动化验证与测试证据

P5 的自动化证据（对应 第 4 节）：

• networkService.integration.test.ts：本地 HTTP 服务覆盖 Query、Header、Cookie、表单 Body、响应格式化，以及翻译长文本切分（含自然断点、空白收尾、emoji 代理对）与语言码映射；
• p5Repository.integration.test.ts：临时 SQLite 覆盖 HTTP 新增/更新、请求历史、Host、单词本（判重更新）和翻译历史；
• systemService.test.ts：覆盖 IPv4/Long 双向边界、Hosts 换行归一化与 NUL 校验、/24网段展开（254 个地址）、端口规格解析（3306,80-82,22与默认常见端口、越界拒绝）、环境变量文件解析/更新/删除，以及真实 TCP 监听端口探测；HTTP 与网络页面纯逻辑另有单元测试；
• Electron E2E：使用本地 HTTP 服务覆盖真实主进程请求、保存集合与历史，并覆盖 Host 方案持久化、单词本、DNS 解析、环境变量和硬件信息；
• 全量 Vitest：28 个测试文件、83 项测试通过；Electron Playwright：10 项 E2E 通过；TypeScript 类型检查、Electron/Vite 生产构建和git diff --check通过；React Doctor：100 / 100，无诊断问题。

注：以上数量为 Parity Checklist 在 2026-07-16 更新时点的验收记录，后续代码演进可能使具体数字发生变化。

12. 已批准差异

13. 发布前共享验收跟踪

以下项目属于发布前共享 parity、外部服务和跨平台验收，不阻塞 P5 实现范围已完成的结论：

• 使用 Java 版同尺寸截图完成六个工具的逐页人工 parity sign-off；
• 在 Windows 与 Linux 安装包中复测ipconfig/ip、ping、DNS flush、Hosts 提权和系统信息字段；
• 使用真实代理账号验证 HTTP 与两个翻译服务的代理、认证、超时和 fallback；
• 为保护开发机和 CI，自动化不实际覆盖系统 Hosts 写入和 DNS flush；发布前需在隔离环境执行权限矩阵；
• 用旧版真实数据库样本验证五张 P5 业务表迁移（统一放在 P7 数据迁移阶段完成）。

验收方法论上，建议按此清单逐项执行：先跑通 网络工具集成测试 与 Repository 集成测试 作为自动化基线，再在 Windows/Linux 隔离环境手工复测提权矩阵与 DNS 刷新，最后用真实代理账号校验 HTTP/翻译的认证与 fallback 行为。

• 桌面应用
• 开发工具