常见问题

Electron：Electron failed to install correctly

原因：electron 的 postinstall 未执行，二进制未下载。

解决：

bash

# 不要用 --ignore-scripts
pnpm install

# 或单独重建
pnpm rebuild electron

项目 .npmrc 已配置国内镜像：

ini

ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/

确认存在 node_modules/electron/dist/electron.exe。

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

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

排查：

bash

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

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

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

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

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

bash

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

应用	端口
web	5173
desktop	5174