常见问题

Electron：install 卡在 postinstall / failed to install correctly

原因 1：electron 的 postinstall 正在下载二进制（体积大，可能长时间无输出）。

原因 2：使用了 pnpm install --ignore-scripts，二进制未下载。

原因 3（pnpm 11）：.npmrc 中的 ELECTRON_MIRROR 不会注入 postinstall，会回退到 GitHub 默认源，国内易超时。

解决：

# 不要用 --ignore-scripts（除非只做 Web）
pnpm install

# pnpm 11：显式设置环境变量后再安装/重建
$env:ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
$env:ELECTRON_BUILDER_BINARIES_MIRROR="https://npmmirror.com/mirrors/electron-builder-binaries/"
pnpm rebuild electron

确认存在 node_modules/electron/dist/electron.exe（Windows）。

详见 Monorepo — Electron。

---

Electron：pnpm clean 后 install 很慢

根目录 clean 仅 turbo run clean（删各包 dist），不会删 node_modules。若曾手动删除 node_modules，pnpm install 会重新安装全部依赖并触发 electron postinstall，属正常现象。

---

构建：Rolldown [INVALID_ANNOTATION]（@vueuse/core）

现象（web / desktop build）：

[INVALID_ANNOTATION] A comment "/* #__PURE__ */" in "@vueuse/core/dist/index.js" ...

原因：Vite 8 使用 Rolldown；@vueuse/core@14.3.0（element-plus 传递依赖）中部分 PURE 注释位置不合法。

影响：仅为警告，构建可成功；Rolldown 会移除无效注释，一般不影响运行与体积。

处理：可忽略；或等 @vueuse/core 发布修复版后在根 package.json 的 pnpm.overrides 中统一升级。

---

Python：数据库连接失败 / getaddrinfo

原因 1：.env 中 DB_HOST 不可达（如远程 IP 未连 VPN）。

原因 2：密码含 @ 等特殊字符，未 URL 编码（已在 config.py 用 quote_plus 处理，.env 写原始密码即可）。

排查：

python -c "from app.core.config import get_settings; s=get_settings(); print(s.db_host, s.database_url)"

---

Python：bcrypt / passlib about 错误

原因：passlib 与新版 bcrypt 不兼容。

现状：项目已改用 bcrypt 直接哈希，执行 pip install -e . 重装依赖。

---

Mobile：AppID 不能为空

原因：packages/mobile/src/manifest.json 中 appid 为空。

平台	填哪里	格式
Android App	根字段 appid	DCloud 应用 ID，如 __UNI__XXXXXXX
微信小程序	mp-weixin.appid	微信 AppID，如 wx...

• Android：在 DCloud 开发者中心 创建应用获取
• 小程序：在 微信公众平台 获取
• 仅 H5 开发（dev:h5）可不填 AppID

---

Mobile：wgt 与基座 SDK 版本不一致

现象：

wgt文件由HBuilderX x.xx 版本生成，运行的基座sdk也需配套相同版本...

原因：「生成本地打包 App 资源」只产出前端资源包，手机上的基座 APK 与 wgt 不是同一 HBuilderX 版本。

解决：

1. 统一使用同一版本 HBuilderX（如 5.07）完成全流程
2. 真机调试：运行 → 制作自定义调试基座 → 安装到手机 → 使用自定义基座运行
3. 正式 APK：资源生成后 → 发行 → 原生 App-云打包（或本地打包），安装完整 APK，勿用旧标准基座 + 新 wgt

详见 Mobile — Android 打包。

---

Mobile：打包后 API 仍指向 localhost

原因：Vite 不会读取 .env.example；生产构建读 .env.production（或 .env）。未配置时回退为 http://localhost:8080。

解决：在 packages/mobile/ 创建 .env.production（可从 .env.example 复制并改地址），然后重新 build:app-android 再打资源/云打包。

---

前端：401 后无限刷新

检查 api-client 的 onUnauthorized 回调是否正确跳转登录；改密成功后应 logout 并跳转 /login。

---

Web：curl 能登录，页面登录失败

现象：curl -X POST http://localhost:8080/api/v1/auth/login 正常，但 http://localhost:5173 登录报「Network Error」或「网络请求失败」。

原因 1（常见）：.env.development 设为 VITE_API_BASE_URL=http://localhost:8080，浏览器从 :5173 跨域请求 :8080。micro-java 须在 Gateway 配置 CORS（GatewayCorsConfig）；或改用 Vite 代理。

解决：

# packages/web/.env.development — 推荐
VITE_API_BASE_URL=

确认 main.ts 使用 import.meta.env.VITE_API_BASE_URL ?? 'http://localhost:8080'（?? 而非 ||）。修改后重启 pnpm --filter web dev。

原因 2：在浏览器地址栏直接打开 /api/v1/auth/login — 该接口仅 POST，会 404/405，不代表后端故障。

排查：DevTools → Network 查看 login 请求；Console 若出现 CORS policy 即为跨域问题。

---

shared 包改了不生效

types / auth / api-client 需要重新 build：

pnpm --filter @xichen-full-stack/types build
pnpm --filter @xichen-full-stack/api-client build

---

Web 与 Desktop 端口冲突

应用	端口
web	5173
desktop	5174
device-agent	19721
VitePress docs	5199

---

device-agent：Desktop 设备页无法连接

现象：/#/instrument 报 Agent 不可用或 fetch 失败。

排查：

1. 确认已安装 .NET 8 SDK：dotnet --version
2. 手动启动 Agent：pnpm device-agent:dev，访问 http://127.0.0.1:19721/health
3. 若主进程未自动拉起，设置 DEVICE_AGENT_AUTO_START=true 后重启 desktop dev
4. 首次使用需 build TS 客户端：pnpm --filter @xichen-full-stack/instrument build
5. 确认 VITE_DEVICE_AGENT_URL 与 Agent 实际端口一致（默认 19721）

生产打包（仪器版）：pnpm desktop:build:instrument（或先 device-agent:build 再 desktop build:instrument）。

详见 device-agent、Desktop。

---

micro-java：Gateway 503 或服务起不来

现象：curl http://localhost:8080/api/v1/health 返回 503，或 gateway 日志出现 Unable to find instance for auth-service。

原因 1：Nacos 未启动或 auth / system / monitor 未注册。

原因 2：启动顺序错误（应先 auth、system、monitor，最后 gateway）。

原因 3：RabbitMQ 未启动，system-service 启动失败，导致 half 链路不可用。

排查：

# Nacos 控制台
http://localhost:8848/nacos

# 各服务直连（绕过网关）
curl http://localhost:8081/api/v1/health
curl http://localhost:8082/actuator/health
curl http://localhost:8083/actuator/health

解决：

1. 按 micro-java 本地启动 拉起 Nacos、RabbitMQ
2. cd packages/micro-java && mvn install -DskipTests
3. 依次启动 auth-service → system-service → monitor-service → gateway
4. 无 Seata 时：$env:SEATA_ENABLED="false" 再启 system-service
5. 空库须 POST /api/v1/system/database/init；init 后重启 monitor-service

与 server-java 端口冲突：两者均占用 8080，同时只能运行其一。

详见 micro-java 中间件。

---

后端：仅有 schema、未 init 时的启动 WARN

现象（server-java / server-python）：MySQL 已建表（如 docker-compose 首次 up），但尚未调用 POST /api/v1/system/database/init，日志出现：

Failed to load scheduled jobs on startup (missing sys_job? run POST /api/v1/system/database/init)
Failed to seed on startup (missing tables? run POST /api/v1/system/database/init)   # Python

原因：Docker MySQL 只自动执行 schema.sql；旧库缺 sys_job 等表时，启动阶段加载定时任务也会失败。

影响：不阻断启动（Java SysJobService、Python init_from_db / seed_data 均已容错）。Swagger / health 可访问，但登录可能失败（无 admin 用户）。

解决：

curl -X POST http://localhost:8080/api/v1/system/database/init   # Java
curl -X POST http://localhost:8000/api/v1/system/database/init   # Python

详见 数据库初始化。

---

菜单为空或 403

• 确认用户角色已分配权限
• 确认 sys_menu.permission 与权限码一致
• 后端 login/me 返回的 menus 应已按权限过滤（非管理端全量树）

相关文档

• 快速开始
• 数据库初始化
• Java 后端概览
• Python 后端概览
• Desktop
• Mobile