diff --git a/cmd/desktop/app.go b/cmd/desktop/app.go
index 70c168d1..2c28daf7 100644
--- a/cmd/desktop/app.go
+++ b/cmd/desktop/app.go
@@ -36,3 +36,13 @@ func (a *App) GetAPIBaseURL() string {
}
return strings.TrimRight(a.backendURL, "/") + "/api/v1"
}
+
+// GetDesktopHTTPPortSetting returns the saved local API port (0 = random port each launch).
+func (a *App) GetDesktopHTTPPortSetting() int {
+ return LoadDesktopPrefsHTTPPort()
+}
+
+// SetDesktopHTTPPortSetting saves the preferred local API port to application support. Restart the app for it to take effect unless it matches the current listener.
+func (a *App) SetDesktopHTTPPortSetting(port int) error {
+ return SaveDesktopHTTPPortPreference(port)
+}
diff --git a/cmd/desktop/main.go b/cmd/desktop/main.go
index ee82fefc..682b65d5 100644
--- a/cmd/desktop/main.go
+++ b/cmd/desktop/main.go
@@ -214,18 +214,15 @@ func main() {
) error {
server := &http.Server{Handler: router}
- // Use port 0 to assign a random free port for the desktop app
- // Force localhost binding to prevent firewall popups on macOS
- addr := "127.0.0.1:0"
+ // 127.0.0.1 + saved port from settings (desktop-prefs.json), or :0 for random free port.
+ addr := desktopBackendListenAddr()
listener, err := listenWithRetry(addr, 10, 300*time.Millisecond)
if err != nil {
return fmt.Errorf("failed to start server: %v", err)
}
- // Get the actual assigned port
- actualPort := listener.Addr().(*net.TCPAddr).Port
- actualAddr := fmt.Sprintf("127.0.0.1:%d", actualPort)
+ actualAddr := listener.Addr().(*net.TCPAddr).String()
// Store the backend URL so Wails can load it
app.backendURL = fmt.Sprintf("http://%s", actualAddr)
@@ -413,6 +410,17 @@ func resolveDesktopDataPath(rawPath, defaultRelativePath, appSupportDir string)
return filepath.Join(appSupportDir, filepath.Clean(trimmed))
}
+// desktopBackendListenAddr returns the TCP address for the embedded Gin server (Wails desktop).
+// Always binds loopback 127.0.0.1. Uses saved UI preference (desktop-prefs.json) when set, else ephemeral port :0.
+func desktopBackendListenAddr() string {
+ const host = "127.0.0.1"
+ pref := LoadDesktopPrefsHTTPPort()
+ if pref >= 1 && pref <= 65535 {
+ return net.JoinHostPort(host, strconv.Itoa(pref))
+ }
+ return net.JoinHostPort(host, "0")
+}
+
func migrateLegacyDesktopData(resourcesDir, targetDataDir string) {
legacyDataDir := filepath.Join(resourcesDir, "data")
if info, err := os.Stat(legacyDataDir); err != nil || !info.IsDir() {
diff --git a/cmd/desktop/prefs.go b/cmd/desktop/prefs.go
new file mode 100644
index 00000000..520270e5
--- /dev/null
+++ b/cmd/desktop/prefs.go
@@ -0,0 +1,71 @@
+package main
+
+import (
+ "encoding/json"
+ "fmt"
+ "os"
+ "path/filepath"
+)
+
+const desktopPrefsFileName = "desktop-prefs.json"
+
+type desktopPrefs struct {
+ HTTPPort int `json:"http_port"`
+}
+
+func desktopPrefsDir() (string, error) {
+ cfg, err := os.UserConfigDir()
+ if err != nil {
+ return "", err
+ }
+ dir := filepath.Join(cfg, "WeKnora Lite")
+ if err := os.MkdirAll(dir, 0o755); err != nil {
+ return "", err
+ }
+ return dir, nil
+}
+
+func desktopPrefsFilePath() (string, error) {
+ dir, err := desktopPrefsDir()
+ if err != nil {
+ return "", err
+ }
+ return filepath.Join(dir, desktopPrefsFileName), nil
+}
+
+// LoadDesktopPrefsHTTPPort returns http_port from prefs file, or 0 if unset / invalid (ephemeral port on each launch).
+func LoadDesktopPrefsHTTPPort() int {
+ path, err := desktopPrefsFilePath()
+ if err != nil {
+ return 0
+ }
+ data, err := os.ReadFile(path)
+ if err != nil {
+ return 0
+ }
+ var p desktopPrefs
+ if json.Unmarshal(data, &p) != nil {
+ return 0
+ }
+ if p.HTTPPort < 0 || p.HTTPPort > 65535 {
+ return 0
+ }
+ return p.HTTPPort
+}
+
+// SaveDesktopHTTPPortPreference persists listen port preference. port 0 means use a random free port on each launch.
+func SaveDesktopHTTPPortPreference(port int) error {
+ if port < 0 || port > 65535 {
+ return fmt.Errorf("invalid port")
+ }
+ path, err := desktopPrefsFilePath()
+ if err != nil {
+ return err
+ }
+ p := desktopPrefs{HTTPPort: port}
+ data, err := json.MarshalIndent(p, "", " ")
+ if err != nil {
+ return err
+ }
+ return os.WriteFile(path, data, 0o600)
+}
diff --git a/docs/LITE.md b/docs/LITE.md
index deb48caf..a5914f81 100644
--- a/docs/LITE.md
+++ b/docs/LITE.md
@@ -163,3 +163,16 @@ data/
```
备份只需复制整个 `data/` 目录。
+
+## 桌面版(Wails)与 Chrome 扩展
+
+桌面 **WeKnora Lite** 内置的 HTTP API 默认监听 **`127.0.0.1` 上的随机端口**(避免每次启动占用固定端口、并减少系统防火墙提示)。浏览器里的 **Chrome 扩展**与网页不同,需要你在扩展里填写明确的 API 地址(例如 `http://127.0.0.1:<端口>/api/v1`),因此会遇到两类问题:
+
+1. **端口每次变**:重启桌面应用后端口可能变化,扩展里保存的地址会失效。
+2. **扩展权限**:上架的扩展须在 `manifest.json` 的 `host_permissions`(或同类字段)中声明对 **`http://127.0.0.1/*`** 和/或 **`http://localhost/*`** 的访问,否则无法请求本机 Lite服务。
+
+**推荐做法**
+
+- 在桌面应用内打开 **设置 → API 信息**,在 **「本地 API 端口(桌面版)」** 中填写固定端口(如 `37841`)并保存,**重启应用** 后端口即固定;配置会写入用户配置目录下的 `desktop-prefs.json`。
+- 启动桌面应用后,在同一页复制 **API 根路径**(与 `http://127.0.0.1:<端口>/api/v1` 一致),粘贴到扩展配置;扩展侧 API Key 与网页版租户 API Key 相同。
+- 若扩展仍无法连接:确认扩展已声明上述 `host_permissions`;可尝试把地址里的主机从 `localhost` 改成 **`127.0.0.1`**(或反之)以排除解析差异。
diff --git a/frontend/src/components/UserMenu.vue b/frontend/src/components/UserMenu.vue
index 653c3afa..c152247d 100644
--- a/frontend/src/components/UserMenu.vue
+++ b/frontend/src/components/UserMenu.vue
@@ -22,10 +22,6 @@
{{ $t('tenant.api.desktopPortDescription') }}
+{{ $t('modelSettings.description') }}
- - -{{ $t('modelSettings.builtinModels.description') }}
- -{{ $t('modelSettings.builtinModels.title') }}
+{{ $t('modelSettings.builtinModels.description') }}
+ + {{ $t('modelSettings.builtinModels.viewGuide') }} +{{ $t('modelSettings.chat.desc') }}
+{{ $t('modelSettings.chat.desc') }}
{{ $t('modelSettings.chat.empty') }}
-{{ $t('modelSettings.chat.empty') }}
+{{ $t('modelSettings.embedding.desc') }}
+{{ $t('modelSettings.embedding.desc') }}
{{ $t('modelSettings.embedding.empty') }}
-{{ $t('modelSettings.embedding.empty') }}
+{{ $t('modelSettings.rerank.desc') }}
+{{ $t('modelSettings.rerank.desc') }}
{{ $t('modelSettings.rerank.empty') }}
-{{ $t('modelSettings.rerank.empty') }}
+{{ $t('modelSettings.vllm.desc') }}
+{{ $t('modelSettings.vllm.desc') }}
{{ $t('modelSettings.vllm.empty') }}
-{{ $t('modelSettings.vllm.empty') }}
+{{ $t('modelSettings.asr.desc') }}
+{{ $t('modelSettings.asr.desc') }}
{{ $t('modelSettings.asr.empty') }}
-{{ $t('modelSettings.asr.empty') }}
+