Desktop Staging 连接远程后端

Desktop Staging 启动配置、同域 vs api. 子域、ws/wss 区别，以及 Origin 头被后端 WS 白名单拒掉的排查。

by 于尘 ·
DesktopStaging配置WebSocketMultica

1. 如何配置并启动

pnpm dev:desktop:staging 会跑 electron-vite dev --mode staging，读取 apps/desktop/.env.staging（gitignore，需本地创建）。

配置文件 apps/desktop/.env.staging：

VITE_API_URL=https://jiulou.yuchengji.com
VITE_APP_URL=https://jiulou.yuchengji.com
# VITE_WS_URL 可省略，自动推导为 wss://jiulou.yuchengji.com/ws

启动（仓库根目录）：

pnpm install          # 首次
pnpm dev:desktop:staging

不需要 make dev，不需要本地后端。首次会自动编译 CLI 到 apps/desktop/resources/bin/multica。

注意：

项 说明
守护进程 自动启动，profile 为 ~/.multica/profiles/desktop-jiulou.yuchengji.com/，与本地 dev 隔离
登录 邮箱验证码在 Desktop 内完成；Google 登录会打开浏览器，回调 multica:// 回传 token
端口 renderer 默认 5173；冲突时 DESKTOP_RENDERER_PORT=5174 pnpm dev:desktop:staging
WS Origin 若实时更新不工作，见第 4 节

2. 同域 vs api.xxx 子域

你的部署：API 和 Web 都在 jiulou.yuchengji.com（同域）。

官方默认约定（Multica Cloud）：api.multica.ai（API）+ multica.ai（Web）。Desktop 会从 apiUrl 自动去掉 api. 前缀推导 appUrl。

同域的实际影响：

  • 功能上没问题，API 和 Web 本来就可以同域部署。
  • Desktop 无法从 VITE_API_URL 自动区分「API 地址」和「Web 地址」——推导结果都是同一个域名。
  • 因此 必须显式设 VITE_APP_URL，否则 Google 登录跳转、分享链接等可能指向错误地址。

官方文档示例（desktop-app.zh.mdx）假设 API/Web 分域，分域时只填 apiUrl 即可；分域时必须额外填 appUrl。同域等价于「API 和 Web 是同一个 URL」，也要显式设 VITE_APP_URL。

代价：多写一行配置，无其他运行时代价。

3. ws 和 wss 的区别

和 HTTP / HTTPS 的关系一样：

协议 对应 场景
ws:// HTTP 明文，本地开发（如 ws://localhost:8080/ws）
wss:// HTTPS 加密，生产/远程 HTTPS 部署

你的后端是 https://jiulou.yuchengji.com，WebSocket 必须用 wss://jiulou.yuchengji.com/ws。代码里 deriveWsUrl() 会自动把 https 换成 wss，一般不用手动写 VITE_WS_URL。

4. Origin: http://localhost:5173 是什么

Origin = 发起请求的页面来源（协议 + 主机 + 端口）。

Desktop dev 模式下，Electron renderer 由 electron-vite 本地开发服务器提供，地址是 http://localhost:5173。所有从 renderer 发出的 API / WebSocket 请求，浏览器/Electron 都会带上：

Origin: http://localhost:5173

后端用这个头做 跨域校验（CORS 和 WebSocket Origin 白名单）。

默认行为（未设 FRONTEND_ORIGIN 时）：后端允许 localhost:3000 / 5173 / 5174。

你的远程部署若设置了 FRONTEND_ORIGIN=https://jiulou.yuchengji.com，白名单只剩生产域名，localhost:5173 会被拒——表现是 WebSocket 连不上，实时更新失效（issue 状态、inbox 等不刷新）。

修复（服务端 .env，重启后端）：

CORS_ALLOWED_ORIGINS=https://jiulou.yuchengji.com,http://localhost:5173,http://localhost:5174

HTTP API 在 Electron dev 里因 webSecurity: false 受 CORS 影响较小；实时功能主要卡在 WS Origin 校验。

← 所有文章