修复固件哈希兼容性并完善部署配置

README.zh-CN.md

@@ -86,12 +86,18 @@ CHANGELOG.md                 版本变更、修复和验证记录
 docker compose up -d --build
 ```
 
-默认访问地址：`http://服务器地址:8080`
+默认访问地址：`http://服务器地址:9000`
 
-自定义端口：
+自定义宿主机端口时，在项目根目录创建 `.env`（可从 `.env.example` 复制），例如改为 `9100`：
+
+```dotenv
+WEB_TOOLS_PORT=9100
+```
+
+然后正常启动：
 
 ```bash
-WEB_TOOLS_PORT=9000 docker compose up -d --build
+docker compose up -d --build
 ```
 
 检查状态：
@@ -109,7 +115,7 @@ docker compose down
 
 导航配置保存在 Docker 卷 `web-tools-data` 中的 `/data/navigation.json`。全新部署且从未保存过排序时，应用直接使用内置默认配置，该文件可能尚不存在；首次保存后会创建。删除或重建容器不会丢失已有配置，执行 `docker compose down -v` 才会删除该卷。
 
-健康检查地址：`http://服务器地址:8080/healthz`
+健康检查地址：`http://服务器地址:9000/healthz`
 
 ## Windows Server 部署（不使用 Docker）
 
@@ -134,10 +140,19 @@ powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\web-tools.ps1 start
 ```powershell
 powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\web-tools.ps1 start `
   -ListenAddress 127.0.0.1 `
-  -Port 8080 `
+  -Port 9100 `
   -DataDir C:\ProgramData\WebTools\data
 ```
 
+脚本不会自动修改 Windows 防火墙。需要从局域网访问默认端口时，可由管理员仅对专用网络配置入站规则：
+
+```powershell
+New-NetFirewallRule -DisplayName 'Web Tools 9000' -Direction Inbound -Action Allow `
+  -Protocol TCP -LocalPort 9000 -Profile Private
+```
+
+只允许本机或由反向代理访问时，使用 `-ListenAddress 127.0.0.1`，无需开放该端口。
+
 从 Git `main` 分支更新时，先在运行窗口按 `Ctrl+C` 停止服务，再执行：
 
 ```powershell
@@ -148,12 +163,19 @@ powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\web-tools.ps1 update
 
 脚本不会读取、覆盖或删除 `C:\ProgramData\WebTools\data`。PowerShell 窗口关闭后前台服务会停止；如使用 Windows 计划任务，应让任务执行 `web-tools.ps1 start`，更新时停止任务、运行 `web-tools.ps1 update -NoStart`，然后重新启动任务。
 
+## 启动故障排查
+
+- `ENOENT ... dist\\index.html`：当前目录只有源码或尚未生成生产前端。先执行 `npm.cmd ci --include=dev` 和 `npm.cmd run build`，再启动服务；直接执行 `node server\\index.mjs` 不会替代构建步骤。
+- 页面能打开但左侧没有新工具：仅重新构建 `dist` 不会更新已经运行的 Node 进程。停止旧进程后重新启动，并在浏览器执行一次强制刷新（`Ctrl+F5`）。
+- 新工具仍未出现：确认服务输出的 `Navigation config` 路径与实际数据目录一致。旧的 `navigation.json` 会保留用户排序，只在服务重启后首次读取 API 时补入新工具。
+- 关闭 PowerShell 窗口后服务消失：前台启动是预期行为。需要长期运行时使用 Windows 计划任务或服务管理器，让任务执行 `web-tools.ps1 start`，不要依赖打开的交互窗口。
+
 ## 工具管理
 
 管理入口不显示在页面中，直接访问：
 
 ```text
-http://服务器地址:8080/setting
+http://服务器地址:9000/setting
 ```
 
 可以调整分类顺序、分类内工具顺序及工具所属分类。保存时采用同目录临时文件和原子替换。
@@ -192,7 +214,15 @@ docker compose up -d --no-build
 npm ci
 ```
 
-终端一运行配置服务：
+终端一运行开发配置服务。这里的 `8081` 仅用于 Vite 开发代理，不是生产默认端口。PowerShell：
+
+```powershell
+$env:PORT = '8081'
+$env:DATA_DIR = (Join-Path (Get-Location) 'data')
+node .\server\index.mjs
+```
+
+Bash：
 
 ```bash
 PORT=8081 DATA_DIR=./data node server/index.mjs
@@ -211,7 +241,9 @@ npm run build
 npm start
 ```
 
-生产服务默认监听 `0.0.0.0:8080`。
+生产服务默认监听 `0.0.0.0:9000`。
+
+新增工具或修改 `shared/tool-catalog.json`、`shared/default-navigation.json` 后，不能只执行 `npm run build`。Node 服务会在启动时加载工具目录；必须先停止旧进程，再重新执行 `npm start`（Windows Server 使用 `web-tools.ps1 start`，Docker 使用 `docker compose up -d --build`）。服务重启后，已打开的浏览器页面还需要刷新，才会重新读取导航 API；已有 `data/navigation.json` 不会被覆盖，只会自动补入缺少的新工具。
 
 完整工程检查：
 
@@ -230,6 +262,8 @@ npm audit --audit-level=low
 
 固件 Hash 与 CRC 共用经过校验的 Intel HEX 解析器，但使用独立纯逻辑、Worker 和 Vue 页面。解析器处理扩展段/线性地址，将数据按 32 位绝对地址排序，合并连续记录，去重内容一致的重叠记录，并拒绝冲突或越过 `0xFFFFFFFF` 的数据。记录文本、记录校验和、EOF 和启动地址不参与 Hash。
 
+摘要计算优先使用浏览器原生 Web Crypto；通过普通 HTTP 局域网地址访问而无法使用 `SubtleCrypto` 时，自动回退到项目内已有的 `node-forge` SHA-256/SHA-512 实现。两条路径都在 Web Worker 中本地处理，不会把固件数据发送到服务端。
+
 “有效数据”模式的总输入为所有 block 数据按地址升序直接拼接，不填充地址空洞。“Block 校验头”模式在每个 block 前加入 8 个二进制字节：
 
 ```text
@@ -311,7 +345,7 @@ npm audit --audit-level=low
 
 - 新工具的默认路径 `/tools/<id>` 可以直接打开和刷新。
 - 左侧导航、搜索和 `/setting` 正常显示新工具。
-- 已保存的旧 `navigation.json` 启动后会自动补入新工具。
+- 已保存的旧 `navigation.json` 在服务重启并首次读取后会自动补入新工具；仅重新构建 `dist` 不会刷新已经运行的 Node 进程。
 - 桌面端和约 `390 x 844` 的移动端竖屏布局正常。
 - 浏览器控制台无错误，工具内容没有发往服务端。