Docs Hub

主题

启动与编码排障 ​

本项目源码、配置和文档统一按 UTF-8 保存。若在 Windows PowerShell 里看到中文乱码，通常是终端输出编码不匹配，而不是文件内容损坏。

Windows 终端中文乱码 ​

临时修复当前窗口：

powershell
chcp 65001
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8

读取文件时显式指定编码：

powershell
Get-Content -Encoding utf8 README.md
Get-Content -Encoding utf8 backend\configs\config.example.yaml

写入或批量修改文件时也要保持 UTF-8。含中文的 Markdown、YAML 站点定义、配置文件不要用 PowerShell 默认编码整文件重写；避免未指定编码的 Set-Content、Add-Content、Out-File、> 重定向。代码修改优先使用局部补丁；若必须脚本写文件，显式指定 UTF-8，并修改后立即运行定义/测试校验。

安全写入示例：

powershell
# PowerShell 7+
Set-Content -LiteralPath $path -Value $text -Encoding utf8NoBOM

# Windows PowerShell 5.1
[System.IO.File]::WriteAllText($path, $text, [System.Text.UTF8Encoding]::new($false))

提交前可以扫描常见乱码特征：

powershell
rg -n "�|Ã|Â|锛|绋|涓|乱码" README backend frontend mobile

建议使用 Windows Terminal、VS Code 终端或 PowerShell 7，并把终端字体设置为支持中文的字体。

Web 前端端口被占用 ​

默认开发端口是 5173。如果本机已有其他 Vite/前端项目占用端口，请显式指定端口：

powershell
cd frontend
npm run dev -- --host 127.0.0.1 --port 5188 --strictPort

检查端口占用：

powershell
Get-NetTCPConnection -LocalPort 5173 -State Listen |
  ForEach-Object { Get-Process -Id $_.OwningProcess }

Web 打开后白屏（第一次正常，再进去 / 刷新就白） ​

典型根因：后端限流把静态资源也计了数。浏览器刷新 SPA 时并发拉 ~30 个 /assets/*.js chunk，打爆 GLOBAL_RATE_PER_SEC（默认 20）的令牌桶 → 后续 chunk 返 429 → Vue 拿不到 JS 崩成白屏。

确认：F12 → Network，看 /assets/*.js 是否 429 Too Many Requests（响应体 {"error":"rate limit exceeded"}）。

修复（2026/07/05 之后版本已含）：限流中间件只作用于 /api/，静态资源放行。旧版本应急可把 GLOBAL_RATE_PER_SEC 调到 60+（临时缓解，会削弱 API 防爆破强度）。

后端健康检查 ​

powershell
Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8088/api/v1/system/health

正常返回：

json
{"service":"ptpatronus","status":"ok"}

Web 开发服务通过 Vite 代理访问 /api/v1，生产 Docker 则由后端同源提供 Web 和 API。

移动端后端地址 ​

移动端首次启动需要填写后端根地址，不要带 /api/v1：

text
http://192.168.1.10:8088

手机或平板访问电脑/NAS 上的后端时，不要填写 localhost 或 127.0.0.1，它们只指向移动设备自身。