Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -211,6 +211,22 @@ When `admin_key` is configured, management APIs require `Authorization: Bearer <

The macOS App and Web UI keep their interface language preferences locally and no longer modify the server `locale`. The server locale controls server logs and backend messages only.

### Reverse-proxy paths

The Web UI derives its reverse-proxy prefix from the current `/admin` page URL. For example, publishing the service below `/llm-proxy/` only requires ordinary Nginx path forwarding:

```nginx
location /llm-proxy/ {
proxy_pass http://127.0.0.1:9000/;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Authorization $http_authorization;
proxy_buffering off;
}
```

Do not use `sub_filter` to globally replace `/admin`. It also rewrites regular expressions inside the inline JavaScript bundle and causes a syntax error before the Web UI can start.

## Protocol Translation Matrix

| Source | Target | Non-streaming | Streaming (SSE) |
Expand Down
16 changes: 16 additions & 0 deletions README.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -197,6 +197,22 @@ llm-proxy status # 查看状态

macOS App 与 Web UI 的界面语言分别保存在本机和当前浏览器,不再修改服务端 `locale`。服务端 `locale` 仅控制服务日志和后端消息语言。

### 反向代理路径

Web UI 会根据当前 `/admin` 页面路径自动解析反向代理前缀。例如将服务发布到 `/llm-proxy/` 时,Nginx 只需正常转发路径:

```nginx
location /llm-proxy/ {
proxy_pass http://127.0.0.1:9000/;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Authorization $http_authorization;
proxy_buffering off;
}
```

不要使用 `sub_filter` 全局替换 `/admin`。它会同时改写内联 JavaScript 的正则表达式,导致 Web UI 在加载时出现语法错误。

## 协议转换矩阵

| 源 | 目标 | 非流式 | 流式 (SSE) |
Expand Down
107 changes: 78 additions & 29 deletions app/Sources/MenuBarController.swift
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,23 @@ enum ServiceState {
case stopped // 未运行
}

enum LocalServiceControl {
static func resolvedPort(pidFileContents: String?, storedPort: Int) -> Int {
guard let pidFileContents,
let data = pidFileContents.data(using: .utf8),
let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
let port = json["port"] as? Int,
(1...65535).contains(port) else {
return storedPort
}
return port
}

static func healthURL(port: Int) -> URL {
URL(string: "http://127.0.0.1:\(port)/admin/health")!
}
}

class MenuBarController: NSObject, NSMenuDelegate {
let statusItem: NSStatusItem
let client = APIClient()
Expand All @@ -22,9 +39,17 @@ class MenuBarController: NSObject, NSMenuDelegate {
private var currentLogLevel: String = "info"
/// 菜单栏显示的端口(从 UserDefaults 读取,用户意图端口)
private var currentPort: Int = APIClient.storedPort()
/// 用于 stop 兜底查找的实际连接端口;PID 文件冲突时可能与显示端口不同。
private var serviceControlPort: Int {
URL(string: client.baseURL)?.port ?? currentPort
/// 生命周期控制始终指向本机代理,与当前管理连接(本地或远程)无关。
/// PID 文件记录端口冲突自动递增后的真实端口;读取失败时回退到本地配置端口。
private var localServiceControlPort: Int {
let pidFileContents = try? String(
contentsOfFile: "/tmp/llm-proxy.pid",
encoding: .utf8
).trimmingCharacters(in: .whitespacesAndNewlines)
return LocalServiceControl.resolvedPort(
pidFileContents: pidFileContents,
storedPort: APIClient.storedPort()
)
}
private var pollTimer: Timer?
private var updateCheckTimer: Timer?
Expand Down Expand Up @@ -191,13 +216,16 @@ class MenuBarController: NSObject, NSMenuDelegate {
todayHitRateText = nil
recentUsage = []
}
// 从服务端同步端口(仅当服务端可达时才更新,不覆盖用户意图)
if let sp = try? await client.fetchPort() {
currentPort = sp
client.updatePort(sp)
} else {
// 服务端连不上 → 可能是端口冲突递增了,尝试从 PID 文件发现实际端口,但只更新连接不更新显示
discoverActualPort()
// currentPort 仅表示本机代理端口。远程服务的 /admin/port 不得进入
// 本地生命周期缓存,否则切回本地后启动/重启可能误用远端端口。
if !client.usesCustomManagementURL {
if let sp = try? await client.fetchPort() {
currentPort = sp
client.updatePort(sp)
} else {
// 服务端连不上 → 可能是端口冲突递增了,尝试从 PID 文件发现实际端口,但只更新连接不更新显示
discoverActualPort()
}
}
rebuildMenu()
}
Expand Down Expand Up @@ -234,18 +262,16 @@ class MenuBarController: NSObject, NSMenuDelegate {
menu.addItem(usageItem)
}

// 自定义管理地址只负责远程管理,绝不能把远端健康状态映射为本机
// CLI 的启停操作。远程配置重载仍可从控制台 Settings 执行。
if !client.usesCustomManagementURL {
let controlsCard = LiveServiceControlCardView(
state: menuCardState,
onStart: { [weak self] in self?.startService() },
onStop: { [weak self] in self?.stopService() },
onRestart: { [weak self] in self?.restartService() },
onReload: { [weak self] in self?.reloadConfig() }
)
menu.addItem(makeCardItem(controlsCard, interactive: true))
}
// 始终保留同一张响应式控制卡:切换到远程连接时,已经展开的菜单
// 会立即移除本地生命周期按钮并显示服务器端管理提示。
let controlsCard = LiveServiceControlCardView(
state: menuCardState,
onStart: { [weak self] in self?.startService() },
onStop: { [weak self] in self?.stopService() },
onRestart: { [weak self] in self?.restartService() },
onReload: { [weak self] in self?.reloadConfig() }
)
menu.addItem(makeCardItem(controlsCard, interactive: statusModel.allowsLocalServiceControl))
menu.addItem(.separator())

// 界面组:控制台 + Web UI
Expand Down Expand Up @@ -701,7 +727,7 @@ class MenuBarController: NSObject, NSMenuDelegate {
setTransientStatus(loc("status.stopping"))
serviceOperationTask = Task { @MainActor [weak self] in
guard let self else { return }
let result = await self.runCLIAndWait("stop", port: self.serviceControlPort)
let result = await self.runCLIAndWait("stop", port: self.localServiceControlPort)
if result.exitCode != 0 {
NSLog("[LLMProxy] ❌ 菜单栏停止服务失败 (exit=\(result.exitCode)): \(result.output)")
self.isServiceOperationInProgress = false
Expand Down Expand Up @@ -1150,7 +1176,7 @@ class MenuBarController: NSObject, NSMenuDelegate {
await operation.value
}

let result = await self.runCLIAndWait("stop", port: self.serviceControlPort)
let result = await self.runCLIAndWait("stop", port: self.localServiceControlPort)
if result.exitCode != 0 {
self.isQuitting = false
let alert = NSAlert()
Expand Down Expand Up @@ -1505,9 +1531,10 @@ class MenuBarController: NSObject, NSMenuDelegate {
if let operation = serviceOperationTask {
await operation.value
}
// 安装前沿用与菜单栏退出相同的可等待停止流程,不能只发信号后
// 立即让 helper 替换 app,否则旧服务可能继续占用端口。
let stopResult = await runCLIAndWait("stop", port: serviceControlPort)
// 更新 App 只停止本机代理。当前管理连接可能指向远程服务,因此端口
// 和停止确认都必须使用独立的 loopback 路径,不能读取 client.baseURL。
let localPort = localServiceControlPort
let stopResult = await runCLIAndWait("stop", port: localPort)
guard stopResult.exitCode == 0 else {
let alert = NSAlert()
alert.messageText = loc("app.title")
Expand All @@ -1518,8 +1545,7 @@ class MenuBarController: NSObject, NSMenuDelegate {
alert.runModal()
return
}
await waitForStoppedAndRefresh()
if (try? await client.fetchHealth()) == true {
if !(await waitForLocalServiceStopped(port: localPort)) {
let alert = NSAlert()
alert.messageText = loc("app.title")
alert.informativeText = loc("quit.serviceStopFailed.body")
Expand All @@ -1545,6 +1571,29 @@ class MenuBarController: NSObject, NSMenuDelegate {
exit(0)
}

/// 只探测本机 loopback。任何 HTTP 响应(包括管理 API 的 401)都说明
/// 端口上的进程仍在;连接失败才表示本机代理已经退出。
private func isLocalServiceRunning(port: Int) async -> Bool {
var request = URLRequest(url: LocalServiceControl.healthURL(port: port))
request.timeoutInterval = 1
do {
let (_, response) = try await URLSession.shared.data(for: request)
return response is HTTPURLResponse
} catch {
return false
}
}

private func waitForLocalServiceStopped(port: Int) async -> Bool {
for _ in 0..<20 {
if !(await isLocalServiceRunning(port: port)) {
return true
}
try? await Task.sleep(nanoseconds: 250_000_000)
}
return !(await isLocalServiceRunning(port: port))
}



func showError(_ msg: String) {
Expand Down
28 changes: 21 additions & 7 deletions app/Sources/MenuCardViews.swift
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,11 @@ struct StatusCardModel {
case .stopped: return .secondary
}
}

/// 远程管理连接只允许操作管理 API;进程生命周期始终由服务器端负责。
var allowsLocalServiceControl: Bool {
!usesRemoteManagement
}
}

/// 菜单栏迷你用量图的数据点。
Expand Down Expand Up @@ -226,17 +231,26 @@ struct ServiceControlCardView: View {
let onReload: () -> Void

var body: some View {
HStack(spacing: 8) {
if model.state == .running {
CardButton(title: loc("menu.btn.stop"), systemImage: "stop", tint: .red, action: onStop)
CardButton(title: loc("menu.btn.restart"), systemImage: "arrow.clockwise", tint: .orange, action: onRestart)
CardButton(title: loc("menu.btn.reload"), systemImage: "arrow.triangle.2.circlepath", tint: .blue, action: onReload)
Group {
if model.allowsLocalServiceControl {
HStack(spacing: 8) {
if model.state == .running {
CardButton(title: loc("menu.btn.stop"), systemImage: "stop", tint: .red, action: onStop)
CardButton(title: loc("menu.btn.restart"), systemImage: "arrow.clockwise", tint: .orange, action: onRestart)
CardButton(title: loc("menu.btn.reload"), systemImage: "arrow.triangle.2.circlepath", tint: .blue, action: onReload)
} else {
CardButton(title: loc("menu.btn.start"), systemImage: "play", tint: Color(red: 0.20, green: 0.68, blue: 0.30), action: onStart)
}
}
.disabled(model.isOperationInProgress)
} else {
CardButton(title: loc("menu.btn.start"), systemImage: "play", tint: Color(red: 0.20, green: 0.68, blue: 0.30), action: onStart)
Label(loc("menu.management.remoteProcessHint"), systemImage: "server.rack")
.font(.system(size: 10))
.foregroundStyle(.secondary)
.frame(maxWidth: .infinity, alignment: .leading)
}
}
.frame(maxWidth: .infinity)
.disabled(model.isOperationInProgress)
.padding(.horizontal, 14)
.padding(.top, 8)
.padding(.bottom, 10)
Expand Down
49 changes: 34 additions & 15 deletions app/Sources/Views/SettingsView.swift
Original file line number Diff line number Diff line change
Expand Up @@ -105,9 +105,9 @@ struct SettingsView: View {
.textFieldStyle(.roundedBorder)
.frame(minWidth: 140, idealWidth: 280, maxWidth: 360)
.help(loc("settings.managementURLHint"))
.onSubmit { saveManagementURL() }
.onSubmit { Task { await saveManagementURL() } }
Button(loc("action.save")) {
saveManagementURL()
Task { await saveManagementURL() }
}
.buttonStyle(.borderedProminent)
.controlSize(.small)
Expand All @@ -116,11 +116,19 @@ struct SettingsView: View {

if APIClient.configuredManagementURL() != nil {
Button(loc("settings.managementURLReset")) {
resetManagementURL()
Task { await switchToLocalManagement() }
}
.buttonStyle(.bordered)
.controlSize(.small)
.fixedSize(horizontal: true, vertical: false)
} else if let remoteURL = APIClient.lastRemoteManagementURL() {
Button(loc("settings.managementURLUseRemote")) {
Task { await switchToRemoteManagement() }
}
.buttonStyle(.bordered)
.controlSize(.small)
.fixedSize(horizontal: true, vertical: false)
.help(remoteURL)
}
}
}
Expand Down Expand Up @@ -452,16 +460,19 @@ struct SettingsView: View {
private func loadSettings() async {
managementURL = APIClient.storedManagementURL()
hasManagementAPIKey = APIClient.configuredManagementAPIKey() != nil
originalPort = nil
port = ""
hasProxyKey = false
proxyKeyLoadState = .loading
visionConfig = nil
visionProviders = []
if APIClient.configuredManagementURL() == nil {
do {
if let p = try await api.fetchPort() {
originalPort = p
port = String(p)
}
} catch {}
} else {
originalPort = nil
port = ""
}
do {
hasProxyKey = try await api.fetchProxyKey()
Expand All @@ -479,27 +490,35 @@ struct SettingsView: View {

// MARK: - Management URL

private func saveManagementURL() {
private func saveManagementURL() async {
guard api.updateManagementURL(managementURL) else {
showToast(loc("settings.managementURLInvalid"), type: "error")
return
}
managementURL = APIClient.storedManagementURL()
managementAPIKey = ""
hasManagementAPIKey = APIClient.configuredManagementAPIKey() != nil
await refreshManagementConnection()
showToast(loc("settings.managementURLSaved"), type: "success")
NotificationCenter.default.post(name: .configDidChange, object: nil)
}

private func resetManagementURL() {
_ = api.updateManagementURL("")
managementURL = APIClient.storedManagementURL()
managementAPIKey = ""
hasManagementAPIKey = APIClient.configuredManagementAPIKey() != nil
private func switchToLocalManagement() async {
api.switchToLocalManagement()
await refreshManagementConnection()
showToast(loc("settings.managementURLResetDone"), type: "success")
NotificationCenter.default.post(name: .configDidChange, object: nil)
}

private func switchToRemoteManagement() async {
guard api.switchToRemoteManagement() else { return }
await refreshManagementConnection()
showToast(loc("settings.managementURLUseRemoteDone"), type: "success")
NotificationCenter.default.post(name: .configDidChange, object: nil)
}

private func refreshManagementConnection() async {
managementAPIKey = ""
await loadSettings()
}

// MARK: - Management API Key

private func saveManagementAPIKey() {
Expand Down
3 changes: 3 additions & 0 deletions app/Sources/en.lproj/Localizable.strings
Original file line number Diff line number Diff line change
Expand Up @@ -278,6 +278,8 @@
"settings.managementURLSaved" = "Management service saved";
"settings.managementURLReset" = "Use Local";
"settings.managementURLResetDone" = "Switched to the local service";
"settings.managementURLUseRemote" = "Use Remote";
"settings.managementURLUseRemoteDone" = "Switched to the remote service";
"settings.managementAPIKey" = "Management API Key";
"settings.managementAPIKeyPlaceholder" = "Enter management API key";
"settings.managementAPIKeyConfiguredPlaceholder" = "•••••••• (enter a new key to replace)";
Expand Down Expand Up @@ -347,6 +349,7 @@
"menu.management.remote" = "Remote";
"menu.management.switchToLocal" = "Use Local";
"menu.management.switchToRemote" = "Use Remote";
"menu.management.remoteProcessHint" = "Manage the remote process on its server";
"menu.usage.last30Total" = "Last 30 days total";
"menu.usage.requests" = "%d requests";
"menu.usage.input" = "Input";
Expand Down
3 changes: 3 additions & 0 deletions app/Sources/zh.lproj/Localizable.strings
Original file line number Diff line number Diff line change
Expand Up @@ -300,6 +300,8 @@
"settings.managementURLSaved" = "管理服务地址已保存";
"settings.managementURLReset" = "使用本地";
"settings.managementURLResetDone" = "已切换到本地服务";
"settings.managementURLUseRemote" = "使用远程";
"settings.managementURLUseRemoteDone" = "已切换到远程服务";
"settings.managementAPIKey" = "管理 API 密钥";
"settings.managementAPIKeyPlaceholder" = "输入管理 API 密钥";
"settings.managementAPIKeyConfiguredPlaceholder" = "••••••••(输入新密钥可替换)";
Expand Down Expand Up @@ -373,6 +375,7 @@
"menu.management.remote" = "远程";
"menu.management.switchToLocal" = "切到本地";
"menu.management.switchToRemote" = "切到远程";
"menu.management.remoteProcessHint" = "远程进程请在服务器端管理";
"menu.usage.last30Total" = "近 30 天总量";
"menu.usage.requests" = "%d 次请求";
"menu.usage.input" = "输入";
Expand Down
Loading
Loading