admin/Hermes-ui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: default to 0.0.0.0 to fix WSL2 health check failure (#520)

Browse Source 
PR #470 changed the default listen host to undefined, letting Node.js
bind to IPv6 :: on systems that support it. This broke WSL2 where IPv6
dual-stack is unreliable — the server binds to :: but IPv4 127.0.0.1
connections fail, causing the health check to time out.

Revert to 0.0.0.0 as the default. Users who need IPv6 can set
BIND_HOST=:: explicitly.

Fixes #518

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
ekko
2026-05-07 19:11:32 +08:00
committed by GitHub
parent 8f6a6ec782
commit f1839db473
8 changed files with 171 additions and 130 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/client/src/components/hermes/chat/TerminalPanel.vue
+8 -1
View File
@@ -121,6 +121,13 @@ const terminalBg = computed(
// ─── WebSocket ──────────────────────────────────────────────────
function formatHostForPort(hostname: string, port: number): string {
if (hostname.startsWith("[") && hostname.endsWith("]")) {
return `${hostname}:${port}`;
}
return hostname.includes(":") ? `[${hostname}]:${port}` : `${hostname}:${port}`;
}
function buildWsUrl(): string {
const token = getApiKey();
const base = getBaseUrlValue();
@@ -137,7 +144,7 @@ function buildWsUrl(): string {
}
const host = import.meta.env.DEV
? `${location.hostname}:8648`
? formatHostForPort(location.hostname, 8648)
: location.host;
return `${wsProtocol}//${host}/api/hermes/terminal${token ? `?token=${encodeURIComponent(token)}` : ""}`;
}
packages/client/src/views/hermes/TerminalView.vue
+8 -1
View File
@@ -265,6 +265,13 @@ const terminalBg = computed(
// ─── WebSocket ──────────────────────────────────────────────────
function formatHostForPort(hostname: string, port: number): string {
if (hostname.startsWith("[") && hostname.endsWith("]")) {
return `${hostname}:${port}`;
}
return hostname.includes(":") ? `[${hostname}]:${port}` : `${hostname}:${port}`;
}
function buildWsUrl(): string {
const token = getApiKey();
const base = getBaseUrlValue();
@@ -282,7 +289,7 @@ function buildWsUrl(): string {
// Dev mode: connect directly to backend port; Production: same host
const host = import.meta.env.DEV
? `${location.hostname}:8648`
? formatHostForPort(location.hostname, 8648)
: location.host;
return `${wsProtocol}//${host}/api/hermes/terminal${token ? `?token=${encodeURIComponent(token)}` : ""}`;
}
packages/server/src/config.ts
+1 -2
View File
@@ -8,8 +8,7 @@ export function getListenHost(env: Record<string, string | undefined> = process.
export const config = {
port: parseInt(process.env.PORT || '8648', 10),
// Leave host undefined by default so Node binds to IPv6 when available,
// falling back to IPv4 on systems without IPv6 support.
// Default undefined: listenWithFallback tries :: first, falls back to 0.0.0.0
host: getListenHost(),
upstream: process.env.UPSTREAM || 'http://127.0.0.1:8642',
uploadDir: process.env.UPLOAD_DIR || resolve(homedir(), '.hermes-web-ui', 'upload'),
packages/server/src/index.ts
+105 -28
View File
@@ -37,8 +37,84 @@ process.on('unhandledRejection', (reason) => {
})
let server: any = null
let servers: any[] = []
let chatRunServer: any = null
interface ListenResult {
primary: any
servers: any[]
}
function listen(app: Koa, port: number, host: string): Promise<any> {
return new Promise((resolve, reject) => {
const s = app.listen(port, host)
s.once('listening', () => resolve(s))
s.once('error', reject)
})
}
function probeIPv4(port: number): Promise<boolean> {
return new Promise((resolve) => {
// eslint-disable-next-line @typescript-eslint/no-require-imports
const req = require('http').get(`http://127.0.0.1:${port}/health`, (res: any) => {
res.resume()
resolve(true)
})
req.once('error', () => resolve(false))
req.setTimeout(1000, () => {
req.destroy()
resolve(false)
})
})
}
/**
* Try listening on IPv6 dual-stack (::) first. If IPv4 is not reachable through
* that socket, keep IPv6 and add a separate IPv4 listener. Fall back to IPv4
* only when IPv6 is unavailable. Skips fallback when BIND_HOST is explicitly set.
*
* On some systems (e.g. WSL2), binding to :: succeeds but the dual-stack
* doesn't actually accept IPv4 connections. We detect this by probing
* 127.0.0.1 after binding.
*/
async function listenWithFallback(app: Koa, port: number, host?: string): Promise<ListenResult> {
// Explicit host: use it directly.
if (host) {
console.log(`[bootstrap] listening on ${host}:${port}`)
const explicit = await listen(app, port, host)
return { primary: explicit, servers: [explicit] }
}
console.log(`[bootstrap] trying IPv6 dual-stack on ::${port}`)
try {
const s6 = await listen(app, port, '::')
if (await probeIPv4(port)) {
console.log(`[bootstrap] IPv6 dual-stack verified (IPv4 probe ok) on ::${port}`)
return { primary: s6, servers: [s6] }
}
console.log('[bootstrap] IPv6 listener is IPv6-only, adding IPv4 listener on 0.0.0.0')
try {
const s4 = await listen(app, port, '0.0.0.0')
console.log(`[bootstrap] listening on ::${port} and 0.0.0.0:${port}`)
return { primary: s6, servers: [s6, s4] }
} catch (err) {
console.log('[bootstrap] IPv4 listener failed; keeping IPv6 listener')
logger.warn({ err }, 'Could not add IPv4 listener after IPv6-only bind')
return { primary: s6, servers: [s6] }
}
} catch (err: any) {
if (err.code !== 'EADDRNOTAVAIL' && err.code !== 'EAFNOSUPPORT' && err.code !== 'EPROTONOSUPPORT') {
throw err
}
console.log(`[bootstrap] IPv6 not available (${err.code}), falling back to 0.0.0.0`)
const s4 = await listen(app, port, '0.0.0.0')
console.log(`[bootstrap] listening on 0.0.0.0:${port}`)
return { primary: s4, servers: [s4] }
}
}
/**
* 安全获取网络接口信息（兼容 Termux/proot 环境）
* 在 proot 环境中 os.networkInterfaces() 会抛出权限错误（errno 13）
@@ -101,18 +177,17 @@ export async function bootstrap() {
})
console.log('[bootstrap] SPA fallback registered')
// Start server
console.log(`[bootstrap] listening on ${config.host || 'default host'}:${config.port}`)
server = config.host
? app.listen(config.port, config.host)
: app.listen(config.port)
// Start server — try IPv6 dual-stack first, fall back to IPv4
const listenResult = await listenWithFallback(app, config.port, config.host)
server = listenResult.primary
servers = listenResult.servers
console.log('[bootstrap] app.listen called')
setupTerminalWebSocket(server)
setupTerminalWebSocket(servers)
console.log('[bootstrap] terminal websocket setup')
// Group chat Socket.IO (must be after server is created)
const groupChatServer = new GroupChatServer(server)
const groupChatServer = new GroupChatServer(servers)
setGroupChatServer(groupChatServer)
groupChatServer.setGatewayManager(getGatewayManagerInstance())
@@ -129,32 +204,34 @@ export async function bootstrap() {
console.log('[bootstrap] session deleter started, profile=%s', activeProfile)
// Catch-all: destroy upgrade requests not handled by terminal or Socket.IO
server.on('upgrade', (req: any, socket: any) => {
const url = new URL(req.url || '', `http://${req.headers.host}`)
if (url.pathname !== '/api/hermes/terminal' && !url.pathname.startsWith('/socket.io/')) {
socket.destroy()
}
servers.forEach((httpServer) => {
httpServer.on('upgrade', (req: any, socket: any) => {
const url = new URL(req.url || '', `http://${req.headers.host}`)
if (url.pathname !== '/api/hermes/terminal' && !url.pathname.startsWith('/socket.io/')) {
socket.destroy()
}
})
})
server.on('listening', () => {
const interfaces = safeNetworkInterfaces()
const localIp = Object.values(interfaces).flat().find(i => i?.family === 'IPv4' && !i?.internal)?.address || 'localhost'
console.log(`Server: http://localhost:${config.port} (LAN: http://${localIp}:${config.port})`)
console.log(`Upstream: ${config.upstream}`)
console.log(`Log: ~/.hermes-web-ui/logs/server.log`)
logger.info('Server: http://localhost:%d (LAN: http://%s:%d)', config.port, localIp, config.port)
logger.info('Upstream: %s', config.upstream)
const interfaces = safeNetworkInterfaces()
const localIp = Object.values(interfaces).flat().find(i => i?.family === 'IPv4' && !i?.internal)?.address || 'localhost'
console.log(`Server: http://localhost:${config.port} (LAN: http://${localIp}:${config.port})`)
console.log(`Upstream: ${config.upstream}`)
console.log(`Log: ~/.hermes-web-ui/logs/server.log`)
logger.info('Server: http://localhost:%d (LAN: http://%s:%d)', config.port, localIp, config.port)
logger.info('Upstream: %s', config.upstream)
// Restore group chat agents after server is ready
groupChatServer.restoreWhenReady()
// Restore group chat agents after server is ready.
groupChatServer.restoreWhenReady()
servers.forEach((httpServer) => {
httpServer.on('error', (err: any) => {
console.error('[bootstrap] server error:', err.code || err.message)
logger.error({ err }, 'Server error')
})
})
server.on('error', (err: any) => {
console.error('[bootstrap] server error:', err.code || err.message)
logger.error({ err }, 'Server error')
})
bindShutdown(server, groupChatServer, chatRunServer)
bindShutdown(servers, groupChatServer, chatRunServer)
startVersionCheck()
}
packages/server/src/routes/hermes/terminal.ts
+20 -17
View File
@@ -110,7 +110,7 @@ function createSession(shell: string): PtySession {
// ─── WebSocket server setup ─────────────────────────────────────
export function setupTerminalWebSocket(httpServer: HttpServer) {
export function setupTerminalWebSocket(httpServers: HttpServer | HttpServer[]) {
if (!pty) {
logger.warn('node-pty not available, skipping terminal WebSocket setup')
return
@@ -118,26 +118,29 @@ export function setupTerminalWebSocket(httpServer: HttpServer) {
const wss = new WebSocketServer({ noServer: true })
const defaultShell = findShell()
const servers = Array.isArray(httpServers) ? httpServers : [httpServers]
httpServer.on('upgrade', async (req, socket, head) => {
const url = new URL(req.url || '', `http://${req.headers.host}`)
if (url.pathname !== '/api/hermes/terminal') {
return
}
// Auth check
const authToken = await getToken()
if (authToken) {
const token = url.searchParams.get('token') || ''
if (token !== authToken) {
socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n')
socket.destroy()
servers.forEach((httpServer) => {
httpServer.on('upgrade', async (req, socket, head) => {
const url = new URL(req.url || '', `http://${req.headers.host}`)
if (url.pathname !== '/api/hermes/terminal') {
return
}
}
wss.handleUpgrade(req, socket, head, (ws) => {
wss.emit('connection', ws, req)
// Auth check
const authToken = await getToken()
if (authToken) {
const token = url.searchParams.get('token') || ''
if (token !== authToken) {
socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n')
socket.destroy()
return
}
}
wss.handleUpgrade(req, socket, head, (ws) => {
wss.emit('connection', ws, req)
})
})
})
packages/server/src/services/hermes/gateway-manager.ts
+13 -4
View File
@@ -120,6 +120,15 @@ interface ManagedGateway {
process?: ChildProcess
}
function formatHostForUrl(host: string): string {
if (host.startsWith('[') && host.endsWith(']')) return host
return host.includes(':') ? `[${host}]` : host
}
function buildHttpUrl(host: string, port: number): string {
return `http://${formatHostForUrl(host)}:${port}`
}
// ============================
// GatewayManager
// ============================
@@ -360,7 +369,7 @@ export class GatewayManager {
const gw = this.gateways.get(name)
if (gw?.url) return gw.url
const { port, host } = this.readProfilePort(name)
return `http://${host}:${port}`
return buildHttpUrl(host, port)
}
/** 读取 profile 的 API_SERVER_KEY（从 .env 文件） */
@@ -426,7 +435,7 @@ export class GatewayManager {
async detectStatus(name: string): Promise<GatewayStatus> {
const pid = this.readPidFile(name)
const { port, host } = this.readProfilePort(name)
const url = `http://${host}:${port}`
const url = buildHttpUrl(host, port)
if (pid && this.isProcessAlive(pid) && await this.checkHealth(url)) {
this.gateways.set(name, { pid, port, host, url })
@@ -456,7 +465,7 @@ export class GatewayManager {
async start(name: string): Promise<GatewayStatus> {
const { port, host } = await this.resolvePort(name)
const hermesHome = this.profileDir(name)
const url = `http://${host}:${port}`
const url = buildHttpUrl(host, port)
if (needsRunMode) {
// WSL / Docker：无 systemd/launchd，用 "gateway run" 作为 detached 子进程
@@ -534,7 +543,7 @@ export class GatewayManager {
const gw = this.gateways.get(name)
const url = gw?.url || (() => {
const { port, host } = this.readProfilePort(name)
return `http://${host}:${port}`
return buildHttpUrl(host, port)
})()
if (!needsRunMode) {
packages/server/src/services/hermes/group-chat/index.ts
+4 -71
View File
@@ -3,7 +3,6 @@ import type { Server as HttpServer } from 'http'
import { getToken } from '../../../services/auth'
import { logger } from '../../../services/logger'
import { getDb } from '../../../db'
import { GC_ROOMS_TABLE, GC_MESSAGES_TABLE, GC_ROOM_AGENTS_TABLE, GC_CONTEXT_SNAPSHOTS_TABLE, GC_ROOM_MEMBERS_TABLE, GC_PENDING_SESSION_DELETES_TABLE, GC_SESSION_PROFILES_TABLE } from '../../../db/hermes/schemas'
import { AgentClients } from './agent-clients'
import { ContextEngine } from '../context-engine/compressor'
import { SessionDeleter } from '../session-deleter'
@@ -39,74 +38,6 @@ interface Member {
socketId: string
}
// ─── SQLite Storage (global DB) ──────────────────────────────
const GC_PENDING_SESSION_DELETES_SCHEMA: Record<string, string> = {
session_id: 'TEXT PRIMARY KEY',
profile_name: 'TEXT NOT NULL',
status: "TEXT NOT NULL DEFAULT 'pending'",
attempt_count: 'INTEGER NOT NULL DEFAULT 0',
last_error: 'TEXT',
created_at: 'INTEGER NOT NULL',
updated_at: 'INTEGER NOT NULL',
next_attempt_at: 'INTEGER NOT NULL DEFAULT 0',
}
const GC_SESSION_PROFILES_SCHEMA: Record<string, string> = {
session_id: 'TEXT PRIMARY KEY',
room_id: 'TEXT NOT NULL',
agent_id: 'TEXT NOT NULL',
profile_name: 'TEXT NOT NULL',
created_at: 'INTEGER NOT NULL',
}
const GC_ROOMS_SCHEMA: Record<string, string> = {
id: 'TEXT PRIMARY KEY',
name: 'TEXT NOT NULL',
inviteCode: 'TEXT UNIQUE',
triggerTokens: 'INTEGER NOT NULL DEFAULT 100000',
maxHistoryTokens: 'INTEGER NOT NULL DEFAULT 32000',
tailMessageCount: 'INTEGER NOT NULL DEFAULT 20',
totalTokens: 'INTEGER NOT NULL DEFAULT 0',
}
const GC_MESSAGES_SCHEMA: Record<string, string> = {
id: 'TEXT PRIMARY KEY',
roomId: 'TEXT NOT NULL',
senderId: 'TEXT NOT NULL',
senderName: 'TEXT NOT NULL',
content: 'TEXT NOT NULL',
timestamp: 'INTEGER NOT NULL',
}
const GC_ROOM_AGENTS_SCHEMA: Record<string, string> = {
id: 'TEXT PRIMARY KEY',
roomId: 'TEXT NOT NULL',
agentId: 'TEXT NOT NULL',
profile: 'TEXT NOT NULL',
name: 'TEXT NOT NULL',
description: "TEXT NOT NULL DEFAULT ''",
invited: 'INTEGER NOT NULL DEFAULT 0',
}
const GC_CONTEXT_SNAPSHOTS_SCHEMA: Record<string, string> = {
roomId: 'TEXT PRIMARY KEY',
summary: 'TEXT NOT NULL DEFAULT \'\'',
lastMessageId: 'TEXT NOT NULL',
lastMessageTimestamp: 'INTEGER NOT NULL',
updatedAt: 'INTEGER NOT NULL',
}
const GC_ROOM_MEMBERS_SCHEMA: Record<string, string> = {
id: 'TEXT PRIMARY KEY',
roomId: 'TEXT NOT NULL',
userId: 'TEXT NOT NULL',
userName: 'TEXT NOT NULL',
description: "TEXT NOT NULL DEFAULT ''",
joinedAt: 'INTEGER NOT NULL',
updatedAt: 'INTEGER NOT NULL',
}
let _tablesEnsured = false
interface PendingSessionDelete {
@@ -487,13 +418,15 @@ export class GroupChatServer {
}
}
constructor(httpServer: HttpServer) {
constructor(httpServers: HttpServer | HttpServer[]) {
this.storage = new ChatStorage()
this.storage.init()
const servers = Array.isArray(httpServers) ? httpServers : [httpServers]
this.io = new Server(httpServer, {
this.io = new Server(servers[0], {
cors: { origin: '*' }
})
servers.slice(1).forEach((httpServer) => this.io.attach(httpServer))
this.nsp = this.io.of('/group-chat')
this.nsp.use(this.authMiddleware.bind(this))
this.nsp.on('connection', this.onConnection.bind(this))
packages/server/src/services/shutdown.ts
+12 -6
View File
@@ -8,6 +8,9 @@ export function bindShutdown(server: any, groupChatServer?: any, chatRunServer?:
if (isShuttingDown) return
isShuttingDown = true
// Force exit after 3s no matter what
setTimeout(() => process.exit(0), 3000)
logger.info('Shutting down (%s)...', signal)
try {
@@ -24,13 +27,16 @@ export function bindShutdown(server: any, groupChatServer?: any, chatRunServer?:
logger.info('Socket.IO closed')
}
if (server) {
await new Promise<void>((resolve) => {
server.close(() => {
logger.info('HTTP server closed')
resolve()
const servers = Array.isArray(server) ? server : [server].filter(Boolean)
if (servers.length) {
await Promise.all(servers.map((httpServer) => (
new Promise<void>((resolve) => {
httpServer.close(() => {
logger.info('HTTP server closed')
resolve()
})
})
})
)))
}
} catch (err) {
logger.error(err, 'Shutdown error')