Prune stale docs and update .hermes content
Delete a large set of outdated documentation (many files under docs/ and .hermes/plans/, including audits, design, prd, technical, planning, assets, and todos). Update and consolidate .hermes content: refresh shared-memory pages (decision-log, development-workflow, document-map, pitfalls, project-overview, team-conventions) and several skills/references under .hermes/skills. Also modify AGENTS.md, README.md, UI_CODING_STANDARD.md, docs/README.md and .encoding-check-ignore. Purpose: clean up stale planning/audit material and keep current hermes documentation and related top-level docs in sync.
This commit is contained in:
@@ -1,77 +0,0 @@
|
||||
# 本地 Rust 栈端口冲突预检
|
||||
|
||||
日期：`2026-05-09`
|
||||
|
||||
## 问题
|
||||
|
||||
执行完整本地栈启动命令时：
|
||||
|
||||
```bash
|
||||
node scripts/run-bash-script.mjs scripts/dev-rust-stack.sh --spacetime-port 3101 --skip-spacetime
|
||||
```
|
||||
|
||||
如果本机已有旧的 `api-server`、主站 Vite 或后台 Vite 进程仍在监听默认端口，脚本可能出现混合日志：
|
||||
|
||||
```text
|
||||
Port 3000 is in use, trying another one...
|
||||
Error: Os { code: 10048, kind: AddrInUse }
|
||||
process didn't exit successfully: `server-rs\target\debug\api-server.exe`
|
||||
```
|
||||
|
||||
其中 `wait_for_api_server` 只探测 `http://127.0.0.1:<api-port>/healthz`。当旧 `api-server` 仍监听 `8082` 时，健康检查会命中旧进程并误判新服务已就绪；随后新 `cargo run` 真正绑定 `8082` 时失败。与此同时，Vite 默认会在 `3000` 被占用时漂移到下一个端口，导致浏览器仍可能打开旧前端。
|
||||
|
||||
## 处理
|
||||
|
||||
`scripts/dev-rust-stack.sh` 在进入 SpacetimeDB publish 和 Rust 编译前，先检查三类端口是否可绑定：
|
||||
|
||||
1. Rust `api-server`：默认 `127.0.0.1:8082`。
|
||||
2. 主站 Vite：默认 `0.0.0.0:3000`。
|
||||
3. 后台 Vite：默认 `127.0.0.1:3102`。
|
||||
|
||||
端口被占用时，脚本会直接失败并打印监听进程。Windows 本地会通过 `Get-NetTCPConnection` 与 `Win32_Process` 输出 `pid / name / address / command`，方便精确停止旧进程。
|
||||
|
||||
主站和后台 Vite 也追加 `--strictPort`，避免默认漂移到 `3001`、`3103` 等端口后让浏览器继续访问旧页面。
|
||||
|
||||
`--skip-spacetime` 是复用既有 SpacetimeDB 宿主的模式。该模式下脚本不会再把 SpacetimeDB 端口纳入可用性漂移；如果传入 `--spacetime-port 3101`，后端就会连接 `http://127.0.0.1:3101`。这可以避免 `3101` 已有 SpacetimeDB 在线时，端口工具误把它当作冲突并改到空闲的 `3102`，导致 api-server 连接空端口后 `/api/creation-entry/config`、作品架和公开图库接口同时返回 `502`。
|
||||
|
||||
## 排障步骤
|
||||
|
||||
PowerShell 查看默认端口占用：
|
||||
|
||||
```powershell
|
||||
Get-NetTCPConnection -State Listen -LocalPort 3000,3102,8082,3101 -ErrorAction SilentlyContinue |
|
||||
Select-Object LocalAddress,LocalPort,OwningProcess |
|
||||
Sort-Object LocalPort
|
||||
```
|
||||
|
||||
查看进程命令行：
|
||||
|
||||
```powershell
|
||||
Get-CimInstance Win32_Process |
|
||||
Where-Object { $_.ProcessId -in @(3000端口PID, 8082端口PID) } |
|
||||
Select-Object ProcessId,Name,CommandLine
|
||||
```
|
||||
|
||||
停止确认可丢弃的旧本地开发进程：
|
||||
|
||||
```powershell
|
||||
Stop-Process -Id <pid> -Force
|
||||
```
|
||||
|
||||
如果确实需要保留旧栈，可显式换端口启动新栈：
|
||||
|
||||
```bash
|
||||
node scripts/run-bash-script.mjs scripts/dev-rust-stack.sh \
|
||||
--skip-spacetime \
|
||||
--spacetime-port 3101 \
|
||||
--api-port 8090 \
|
||||
--web-port 3001 \
|
||||
--admin-web-port 3103
|
||||
```
|
||||
|
||||
## 验证
|
||||
|
||||
1. `bash -n scripts/dev-rust-stack.sh` 通过。
|
||||
2. 默认端口被占用时重新运行完整栈，脚本应在 publish 前失败并打印占用进程。
|
||||
3. 清理占用进程或换端口后，重新启动时不再出现 Vite 端口漂移或 `api-server` `AddrInUse`。
|
||||
4. 复用 SpacetimeDB 时执行 `npm run dev -- --skip-spacetime --skip-publish --spacetime-port 3101`，启动日志里的 `[dev:rust] spacetime:` 应保持为 `http://127.0.0.1:3101`，并且 `GET /api/creation-entry/config` 不应因连接 `3102` 这类空端口而失败。
|
||||
Reference in New Issue
Block a user