@tool-bridge/server 0.7.0 → 0.10.0

package/dist/{chunk-7ASYWVYP.js → chunk-Q7YHZ2SD.js}

@@ -18,6 +18,12 @@ import {
   NEVER,
   NodeRegistryStore,
   OAUTH_CLIENT_FIELDS,
+  PG_SEARCH_INSERT_ROWS_MAX,
+  PG_SEARCH_SNAPSHOTS_COLUMNS,
+  PG_SEARCH_SNAPSHOTS_TABLE,
+  PG_SEARCH_TOOLS_COLUMNS,
+  PG_SEARCH_TOOLS_TABLE,
+  PG_SEARCH_WRITE_LOCK_KEY,
   PRESIGN_TTL_SEC_DEFAULT,
   RemoteAllowlistStore,
   SKILLHUB_CAPABILITIES,
@@ -106,6 +112,8 @@ import {
   parseNodeInput,
   parseTokenResponse,
   parseVia,
+  pgBulkInsertSql,
+  pgSearchDialect,
   pluginTokenSecretName,
   preprocess,
   record,
@@ -132,7 +140,7 @@ import {
   url,
   validatePath,
   virtualizeTools
-} from "./chunk-76YX7XSX.js";
+} from "./chunk-TPGTA43F.js";
 
 // src/config.ts
 var DEFAULT_PORT = 8787;
@@ -151,7 +159,9 @@ function configFromEnv(env = process.env) {
   const allowInsecure = env.TB_ALLOW_INSECURE_HTTP === "true";
   const allowlist = (env.TB_REMOTE_ALLOWLIST ?? "").split(",").map((s) => s.trim()).filter((s) => s.length > 0);
   const config = {
-    port: portEnv(env.TB_PORT) ?? DEFAULT_PORT,
+    // TB_PORT 优先,PORT 兜底:Railway / Fly / Cloud Run / CF Container 等 PaaS 只注入
+    // PORT,不认识 TB_PORT —— 不兜底的话容器会监听 8787 而平台探活另一个端口,部署直接失败。
+    port: portEnv(env.TB_PORT) ?? portEnv(env.PORT) ?? DEFAULT_PORT,
     host: env.TB_HOST !== void 0 && env.TB_HOST.length > 0 ? env.TB_HOST : "0.0.0.0",
     dataDir: env.TB_DATA_DIR !== void 0 && env.TB_DATA_DIR.length > 0 ? env.TB_DATA_DIR : "./data",
     allowInsecureHttp: allowInsecure,
@@ -162,9 +172,45 @@ function configFromEnv(env = process.env) {
       ...env.TB_INSTANCE_ID !== void 0 && env.TB_INSTANCE_ID.length > 0 ? { instanceId: env.TB_INSTANCE_ID } : {},
       allowInsecure
     },
-    deviceReclaimSec: positiveIntEnv(env.TB_DEVICE_RECLAIM_SEC) ?? DEFAULT_DEVICE_RECLAIM_SEC
+    deviceReclaimSec: positiveIntEnv(env.TB_DEVICE_RECLAIM_SEC) ?? DEFAULT_DEVICE_RECLAIM_SEC,
+    // 0 合法(立即关停,本地/单机默认);positiveIntEnv 拒 0,故单独解析。
+    shutdownDrainSec: (() => {
+      const n = Number(env.TB_SHUTDOWN_DRAIN_SEC);
+      return Number.isInteger(n) && n >= 0 ? n : 0;
+    })()
   };
   if (env.TB_UI_DIR !== void 0 && env.TB_UI_DIR.length > 0) config.uiDir = env.TB_UI_DIR;
+  if (env.TB_DATABASE_URL !== void 0 && env.TB_DATABASE_URL.length > 0) {
+    config.databaseUrl = env.TB_DATABASE_URL;
+  }
+  if (env.TB_REDIS_URL !== void 0 && env.TB_REDIS_URL.length > 0) {
+    config.redisUrl = env.TB_REDIS_URL;
+  }
+  if (env.TB_REPLICA_ID !== void 0 && env.TB_REPLICA_ID.length > 0) {
+    config.replicaId = env.TB_REPLICA_ID;
+  }
+  const s3Vars = [
+    ["TB_OBJECT_STORE_ENDPOINT", env.TB_OBJECT_STORE_ENDPOINT],
+    ["TB_OBJECT_STORE_BUCKET", env.TB_OBJECT_STORE_BUCKET],
+    ["TB_OBJECT_STORE_ACCESS_KEY_ID", env.TB_OBJECT_STORE_ACCESS_KEY_ID],
+    ["TB_OBJECT_STORE_SECRET_ACCESS_KEY", env.TB_OBJECT_STORE_SECRET_ACCESS_KEY]
+  ];
+  const present = s3Vars.filter(([, value]) => value !== void 0 && value.length > 0);
+  if (present.length > 0) {
+    if (present.length < s3Vars.length) {
+      const missing = s3Vars.filter(([, value]) => value === void 0 || value.length === 0).map(([name]) => name);
+      throw new Error(
+        `\u5E73\u53F0\u5BF9\u8C61\u5B58\u50A8\u914D\u7F6E\u4E0D\u5B8C\u6574(\u7ED9\u4E86 ${present.length}/${s3Vars.length} \u9879),\u7F3A\u5C11:${missing.join(", ")}`
+      );
+    }
+    config.objectStore = {
+      accessKeyId: env.TB_OBJECT_STORE_ACCESS_KEY_ID,
+      bucket: env.TB_OBJECT_STORE_BUCKET,
+      endpoint: env.TB_OBJECT_STORE_ENDPOINT,
+      secretAccessKey: env.TB_OBJECT_STORE_SECRET_ACCESS_KEY,
+      ...env.TB_OBJECT_STORE_REGION !== void 0 && env.TB_OBJECT_STORE_REGION.length > 0 ? { region: env.TB_OBJECT_STORE_REGION } : {}
+    };
+  }
   if (env.TB_BOOTSTRAP_ADMIN_SK !== void 0 && env.TB_BOOTSTRAP_ADMIN_SK.length > 0) {
     config.adminSk = env.TB_BOOTSTRAP_ADMIN_SK;
   }
@@ -396,8 +442,15 @@ var BUILTIN_DESCRIPTIONS = {
 async function mintAdminWithPlaintext(store, plaintext, now) {
   const { key } = await mintKey(adminBootstrapInput(), now);
   const adminKey = { ...key, hash: await sha256Hex(plaintext) };
-  await store.put(KEY_SK_HASH + adminKey.hash, adminKey);
-  await store.put(KEY_SK_ID + adminKey.id, adminKey.hash);
+  const hashKey = KEY_SK_HASH + adminKey.hash;
+  let won;
+  if (store.putIfAbsent !== void 0) {
+    won = await store.putIfAbsent(hashKey, adminKey);
+  } else {
+    won = await store.get(hashKey) === null;
+    if (won) await store.put(hashKey, adminKey);
+  }
+  if (won) await store.put(KEY_SK_ID + adminKey.id, adminKey.hash);
 }
 async function ensureBuiltinNodes(registry, now) {
   const ensure = async (node) => {
@@ -14208,8 +14261,8 @@ function applyPostAuth(clientId, clientSecret, params) {
 function applyPublicAuth(clientId, params) {
   params.set("client_id", clientId);
 }
-function isLoopbackHost(hostname) {
-  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1";
+function isLoopbackHost(hostname2) {
+  return hostname2 === "localhost" || hostname2 === "127.0.0.1" || hostname2 === "[::1]" || hostname2 === "::1";
 }
 function assertSecureTokenEndpoint(tokenEndpoint) {
   const url2 = new URL(String(tokenEndpoint));
@@ -36477,6 +36530,17 @@ function registerPublicRoutes(app, env) {
       ...catalog !== void 0 && digest !== void 0 ? { catalog: { count: Object.keys(catalog).length, digest } } : {}
     });
   });
+  app.get("/livez", (c) => c.json({ live: true }));
+  app.get("/readyz", async (c) => {
+    const probe = deps.readiness;
+    if (probe === void 0) return c.json({ checks: {}, ready: true });
+    try {
+      const report = await probe();
+      return c.json(report, report.ready ? 200 : 503);
+    } catch {
+      return c.json({ checks: {}, ready: false }, 503);
+    }
+  });
   app.get(
     "/~ref/:token",
     (c) => runHandler(async () => {
@@ -37711,14 +37775,26 @@ var DeviceHub = class {
   connections = /* @__PURE__ */ new Set();
   reclaimTimers = /* @__PURE__ */ new Map();
   heartbeat;
+  /** 多副本路由;缺省(单副本)时所有跨副本逻辑短路,行为与之前完全一致。 */
+  router;
   constructor(opts) {
     this.store = opts.store;
     this.search = opts.search;
     this.reclaimSec = opts.reclaimSec;
+    this.router = opts.router?.(
+      async (deviceId, req) => await this.invokeLocal(deviceId, req)
+    );
     const heartbeatMs = opts.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
     this.heartbeat = setInterval(() => this.pingConnections(), heartbeatMs);
     this.heartbeat.unref?.();
   }
+  /**
+   * 启动多副本路由(订阅本副本频道 + 路由续期)。单副本时是 no-op。
+   * 必须在开始服务前完成:订阅没建好时转发进来的调用会丢。
+   */
+  async startRouter() {
+    await this.router?.start();
+  }
   /** 挂到 http.Server 的 'upgrade' 事件(仅处理 DEVICE_WS_PATH,其余 404)。 */
   attach(server) {
     server.on("upgrade", (req, socket, head) => {
@@ -37730,8 +37806,26 @@ var DeviceHub = class {
       });
     });
   }
-  /** DeviceChannel.invoke:HTTP→WS 调用转发(无活连接 → deviceOffline)。 */
+  /**
+   * DeviceChannel.invoke:HTTP→WS 调用转发。
+   *
+   * 本副本持有该设备 → 直接走本地 socket(单副本部署恒走这条,零额外开销)。
+   * 本地没有但配了 router → 问路由表并转发给持有者副本(socket 不可序列化,
+   * 只能把调用送到 socket 所在进程)。都没有 → deviceOffline。
+   */
   async invoke(deviceId, req) {
+    if (this.activeByDevice.has(deviceId)) return await this.invokeLocal(deviceId, req);
+    const offline = { ok: false, error: TBError.deviceOffline().toJSON() };
+    if (this.router === void 0) return offline;
+    return await this.router.forward(deviceId, req) ?? offline;
+  }
+  /**
+   * 只走本副本 socket 的调用执行。
+   *
+   * router 收到转发来的调用时回调这里 —— **不能**回调 `invoke`:本地连接刚断时
+   * 那会再次查路由并转发,在两个副本间弹来弹去。这里没有连接就直接 offline。
+   */
+  async invokeLocal(deviceId, req) {
     const offline = { ok: false, error: TBError.deviceOffline().toJSON() };
     const conn = this.activeByDevice.get(deviceId);
     if (conn === void 0) return offline;
@@ -37769,6 +37863,9 @@ var DeviceHub = class {
         if (!isDeviceMeta(item.value)) continue;
         const meta = item.value;
         if (this.activeByDevice.has(meta.deviceId)) continue;
+        if (this.router !== void 0 && await this.router.isOnlineAnywhere(meta.deviceId)) {
+          continue;
+        }
         if (meta.disconnectedAt === void 0) {
           const now = (/* @__PURE__ */ new Date()).toISOString();
           try {
@@ -37794,6 +37891,10 @@ var DeviceHub = class {
     for (const conn of this.connections) conn.ws.terminate();
     this.connections.clear();
     this.activeByDevice.clear();
+    const router = this.router;
+    this.router = void 0;
+    await router?.close().catch(() => {
+    });
     await new Promise((resolve3) => this.wss.close(() => resolve3()));
   }
   async handleUpgrade(req, socket, head) {
@@ -37880,6 +37981,8 @@ var DeviceHub = class {
     const prev = this.activeByDevice.get(conn.deviceId);
     if (prev !== void 0 && prev !== conn) prev.ws.close(1e3, "replaced");
     this.activeByDevice.set(conn.deviceId, conn);
+    await this.router?.claim(conn.deviceId).catch(() => {
+    });
     conn.session.accept(mountPath);
   }
   /** 连接失效收尾(对位 DO markDisconnected):registry 下线 + meta 记断线 + 排回收。 */
@@ -37888,6 +37991,8 @@ var DeviceHub = class {
     this.connections.delete(conn);
     if (this.activeByDevice.get(conn.deviceId) !== conn) return;
     this.activeByDevice.delete(conn.deviceId);
+    await this.router?.release(conn.deviceId).catch(() => {
+    });
     const raw = await this.store.get(KEY_DEVICE_META + conn.deviceId);
     if (!isDeviceMeta(raw)) return;
     const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -37918,6 +38023,13 @@ var DeviceHub = class {
   async reclaim(deviceId) {
     this.reclaimTimers.delete(deviceId);
     if (this.activeByDevice.has(deviceId)) return;
+    if (this.router !== void 0) {
+      try {
+        if (await this.router.isOnlineAnywhere(deviceId)) return;
+      } catch {
+        return;
+      }
+    }
     const raw = await this.store.get(KEY_DEVICE_META + deviceId);
     if (!isDeviceMeta(raw)) return;
     const searchSync = this.search === void 0 ? void 0 : new SearchSynchronizer(this.store, this.search);
@@ -37942,6 +38054,146 @@ var DeviceHub = class {
   }
 };
 
+// src/deviceRouter.ts
+var DEVICE_ROUTE_TTL_SEC = 30;
+var DEVICE_FORWARD_TIMEOUT_MS = 65e3;
+var deviceRouteKey = (deviceId) => `tb:device:route:${deviceId}`;
+var deviceCallChannel = (replicaId) => `tb:device:call:${replicaId}`;
+var deviceReplyChannel = (replicaId) => `tb:device:reply:${replicaId}`;
+var DeviceRouter = class _DeviceRouter {
+  constructor(replicaId, backend, opts) {
+    this.replicaId = replicaId;
+    this.backend = backend;
+    this.opts = opts;
+  }
+  replicaId;
+  backend;
+  opts;
+  pending = /* @__PURE__ */ new Map();
+  renewTimer;
+  /** 本副本当前持有的设备(需周期续期路由条目)。 */
+  owned = /* @__PURE__ */ new Set();
+  get ttlSec() {
+    return this.opts.ttlSec ?? DEVICE_ROUTE_TTL_SEC;
+  }
+  /** 订阅本副本的两个频道并启动路由续期。 */
+  async start() {
+    await this.backend.subscribe(deviceCallChannel(this.replicaId), (payload) => {
+      void this.handleForwardedCall(payload);
+    });
+    await this.backend.subscribe(deviceReplyChannel(this.replicaId), (payload) => {
+      this.handleReply(payload);
+    });
+    const renewMs = Math.max(1e3, Math.floor(this.ttlSec * 1e3 / 3));
+    this.renewTimer = setInterval(() => {
+      void this.renewOwned();
+    }, renewMs);
+    this.renewTimer.unref?.();
+  }
+  /** 本副本接受了某设备的连接:声明所有权。 */
+  async claim(deviceId) {
+    this.owned.add(deviceId);
+    await this.backend.setRoute(deviceId, this.replicaId, this.ttlSec);
+  }
+  /** 本副本失去某设备的连接:释放所有权。 */
+  async release(deviceId) {
+    this.owned.delete(deviceId);
+    await this.backend.clearRoute(deviceId, this.replicaId);
+  }
+  /** 某设备当前是否在**任一**副本上在线(reclaim 判定用,不能只看本副本)。 */
+  async isOnlineAnywhere(deviceId) {
+    return await this.backend.lookupRoute(deviceId) !== null;
+  }
+  /**
+   * 把调用转发给持有该设备的副本并等结果。
+   * 无人持有 → null(调用方按 deviceOffline 处理)。
+   */
+  async forward(deviceId, req) {
+    const owner = await this.backend.lookupRoute(deviceId);
+    if (owner === null) return null;
+    if (owner === this.replicaId) return null;
+    const correlationId = `${this.replicaId}:${deviceId}:${++_DeviceRouter.seq}`;
+    const call = {
+      correlationId,
+      deviceId,
+      replyTo: this.replicaId,
+      req
+    };
+    return await new Promise((resolve3) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(correlationId);
+        resolve3({ ok: false, error: new TBError("unavailable", "\u8BBE\u5907\u8C03\u7528\u8F6C\u53D1\u8D85\u65F6").toJSON() });
+      }, this.opts.forwardTimeoutMs ?? DEVICE_FORWARD_TIMEOUT_MS);
+      timer.unref?.();
+      this.pending.set(correlationId, { resolve: resolve3, timer });
+      void this.backend.publish(deviceCallChannel(owner), JSON.stringify(call)).catch(() => {
+        const waiter = this.pending.get(correlationId);
+        if (waiter === void 0) return;
+        this.pending.delete(correlationId);
+        clearTimeout(waiter.timer);
+        waiter.resolve({
+          ok: false,
+          error: new TBError("unavailable", "\u8BBE\u5907\u8C03\u7528\u8F6C\u53D1\u5931\u8D25").toJSON()
+        });
+      });
+    });
+  }
+  async close() {
+    if (this.renewTimer !== void 0) clearInterval(this.renewTimer);
+    this.renewTimer = void 0;
+    for (const [, waiter] of this.pending) {
+      clearTimeout(waiter.timer);
+      waiter.resolve({ ok: false, error: new TBError("unavailable", "\u7F51\u5173\u6B63\u5728\u5173\u95ED").toJSON() });
+    }
+    this.pending.clear();
+    await Promise.all([...this.owned].map(async (id) => await this.release(id)));
+    await this.backend.close();
+  }
+  /** correlationId 的进程内序号(与 replicaId 组合后全局唯一)。 */
+  static seq = 0;
+  async renewOwned() {
+    for (const deviceId of this.owned) {
+      try {
+        await this.backend.setRoute(deviceId, this.replicaId, this.ttlSec);
+      } catch {
+      }
+    }
+  }
+  /** 作为持有者:执行本地调用并回执。 */
+  async handleForwardedCall(payload) {
+    let call;
+    try {
+      call = JSON.parse(payload);
+    } catch {
+      return;
+    }
+    if (typeof call?.correlationId !== "string" || typeof call?.replyTo !== "string") return;
+    let result;
+    try {
+      result = await this.opts.onLocalCall(call.deviceId, call.req);
+    } catch {
+      result = { ok: false, error: new TBError("internal", "\u8BBE\u5907\u8C03\u7528\u6267\u884C\u5931\u8D25").toJSON() };
+    }
+    const reply = { correlationId: call.correlationId, result };
+    await this.backend.publish(deviceReplyChannel(call.replyTo), JSON.stringify(reply)).catch(() => {
+    });
+  }
+  /** 作为发起方:收到回执,唤醒等待者。 */
+  handleReply(payload) {
+    let reply;
+    try {
+      reply = JSON.parse(payload);
+    } catch {
+      return;
+    }
+    const waiter = this.pending.get(reply?.correlationId);
+    if (waiter === void 0) return;
+    this.pending.delete(reply.correlationId);
+    clearTimeout(waiter.timer);
+    waiter.resolve(reply.result);
+  }
+};
+
 // ../core/src/node/fsObjectStore.ts
 import { mkdir, readdir, readFile, realpath, rm, stat, writeFile } from "fs/promises";
 import { basename, dirname, join, resolve, sep } from "path";
@@ -38226,6 +38478,219 @@ function createDataObjectStore(dataDir) {
   };
 }
 
+// src/pgSearchIndex.ts
+var PgSearchDriver = class {
+  constructor(sql) {
+    this.sql = sql;
+  }
+  sql;
+  schemaReady;
+  async all(statement) {
+    return await this.sql.unsafe(statement.sql, statement.params);
+  }
+  async initializeSchema() {
+    try {
+      await this.sql.begin(async (tx) => {
+        for (const ddl of pgSearchDialect.schemaStatements) {
+          await tx.unsafe(ddl);
+        }
+      });
+    } catch (error) {
+      this.schemaReady = void 0;
+      throw error;
+    }
+  }
+  ensureSchema() {
+    this.schemaReady ??= this.initializeSchema();
+    return this.schemaReady;
+  }
+  async first(statement) {
+    const rows = await this.sql.unsafe(statement.sql, statement.params);
+    return rows[0] ?? null;
+  }
+  /**
+   * 攒成多行 VALUES 批量插入,而非逐条。
+   * 逐条对 4000 行需 ~920ms(每行一次事务内往返),批量后 ~12ms。
+   */
+  bulk(items, table, columns, toParams) {
+    const statements = [];
+    for (let i = 0; i < items.length; i += PG_SEARCH_INSERT_ROWS_MAX) {
+      const chunk = items.slice(i, i + PG_SEARCH_INSERT_ROWS_MAX);
+      statements.push({
+        params: chunk.flatMap(toParams),
+        sql: pgBulkInsertSql(table, columns, chunk.length)
+      });
+    }
+    return statements;
+  }
+  insertRecords(records) {
+    return this.bulk(
+      records,
+      PG_SEARCH_TOOLS_TABLE,
+      PG_SEARCH_TOOLS_COLUMNS,
+      (record2) => [record2.path, record2.name, record2.description, record2.feedback]
+    );
+  }
+  insertSnapshots(digests) {
+    return this.bulk(
+      [...digests],
+      PG_SEARCH_SNAPSHOTS_TABLE,
+      PG_SEARCH_SNAPSHOTS_COLUMNS,
+      ([path, digest]) => [path, digest]
+    );
+  }
+  async write(statements) {
+    await this.sql.begin(async (tx) => {
+      await tx`SELECT pg_advisory_xact_lock(${PG_SEARCH_WRITE_LOCK_KEY})`;
+      for (const statement of statements) {
+        await tx.unsafe(statement.sql, statement.params);
+      }
+    });
+  }
+};
+var PgSearchIndex = class extends SqlSearchIndex {
+  constructor(sql) {
+    super(new PgSearchDriver(sql), pgSearchDialect);
+  }
+};
+
+// src/pgStateStore.ts
+var DEFAULT_LIST_LIMIT = 1e3;
+var MAX_CODE_POINT = 1114111;
+var SURROGATE_START = 55296;
+var SURROGATE_END = 57343;
+function prefixUpperBound(prefix) {
+  const points = [...prefix];
+  for (let i = points.length - 1; i >= 0; i--) {
+    const code = points[i]?.codePointAt(0);
+    if (code === void 0 || code >= MAX_CODE_POINT) continue;
+    let next = code + 1;
+    if (next >= SURROGATE_START && next <= SURROGATE_END) next = SURROGATE_END + 1;
+    return points.slice(0, i).join("") + String.fromCodePoint(next);
+  }
+  return void 0;
+}
+var PgStateStore = class {
+  constructor(sql) {
+    this.sql = sql;
+  }
+  sql;
+  /** 建表(幂等)。key COLLATE "C" 是字节序正确性的前提,不能省。 */
+  async ensureSchema() {
+    await this.sql`
+      CREATE TABLE IF NOT EXISTS tb_kv (
+        key text COLLATE "C" PRIMARY KEY,
+        value jsonb NOT NULL
+      )
+    `;
+  }
+  async get(key) {
+    const rows = await this.sql`
+      SELECT value FROM tb_kv WHERE key = ${key}
+    `;
+    const row = rows[0];
+    return row === void 0 ? null : row.value;
+  }
+  async getMany(keys) {
+    const unique = [...new Set(keys)];
+    if (unique.length === 0) return /* @__PURE__ */ new Map();
+    const rows = await this.sql`
+      SELECT key, value FROM tb_kv WHERE key = ANY(${this.sql.array(unique)})
+    `;
+    const byKey = new Map(rows.map((row) => [row.key, row.value]));
+    const out = /* @__PURE__ */ new Map();
+    for (const key of unique) {
+      if (byKey.has(key)) out.set(key, byKey.get(key));
+    }
+    return out;
+  }
+  async put(key, value) {
+    await this.sql`
+      INSERT INTO tb_kv (key, value) VALUES (${key}, ${this.sql.json(value)})
+      ON CONFLICT (key) DO UPDATE SET value = excluded.value
+    `;
+  }
+  async putIfAbsent(key, value) {
+    const result = await this.sql`
+      INSERT INTO tb_kv (key, value) VALUES (${key}, ${this.sql.json(value)})
+      ON CONFLICT (key) DO NOTHING
+    `;
+    return result.count > 0;
+  }
+  async delete(key) {
+    await this.sql`DELETE FROM tb_kv WHERE key = ${key}`;
+  }
+  async list(prefix, opts) {
+    const limit = opts?.limit ?? DEFAULT_LIST_LIMIT;
+    const lowerByCursor = opts?.cursor !== void 0 && opts.cursor >= prefix;
+    const upper = prefix === "" ? void 0 : prefixUpperBound(prefix);
+    const rows = await this.sql`
+      SELECT key, value FROM tb_kv
+      WHERE ${lowerByCursor ? this.sql`key > ${opts?.cursor ?? ""}` : this.sql`key >= ${prefix}`}
+      ${upper !== void 0 ? this.sql`AND key < ${upper}` : this.sql``}
+      ORDER BY key
+      LIMIT ${limit + 1}
+    `;
+    const matched = rows.filter((r) => r.key.startsWith(prefix));
+    const hasMore = matched.length > limit;
+    const page = hasMore ? matched.slice(0, limit) : matched;
+    const items = page.map((r) => ({ key: r.key, value: r.value }));
+    const last = page[page.length - 1];
+    return hasMore && last !== void 0 ? { items, cursor: last.key } : { items };
+  }
+};
+
+// src/redisDeviceRouter.ts
+import { Redis } from "ioredis";
+var CLEAR_IF_OWNER = `
+if redis.call('get', KEYS[1]) == ARGV[1] then
+  return redis.call('del', KEYS[1])
+end
+return 0
+`;
+var RedisDeviceRouterBackend = class {
+  /** 命令连接(GET/SET/DEL/PUBLISH)。 */
+  commands;
+  /** 订阅连接(进入 subscribe 模式后不能发普通命令)。 */
+  subscriber;
+  handlers = /* @__PURE__ */ new Map();
+  constructor(url2) {
+    this.commands = new Redis(url2, { maxRetriesPerRequest: 2 });
+    this.subscriber = new Redis(url2, { maxRetriesPerRequest: 2 });
+    this.subscriber.on("message", (channel, payload) => {
+      this.handlers.get(channel)?.(payload);
+    });
+    this.commands.on("error", () => {
+    });
+    this.subscriber.on("error", () => {
+    });
+  }
+  async setRoute(deviceId, replicaId, ttlSec) {
+    await this.commands.set(deviceRouteKey(deviceId), replicaId, "EX", ttlSec);
+  }
+  async lookupRoute(deviceId) {
+    return await this.commands.get(deviceRouteKey(deviceId));
+  }
+  async clearRoute(deviceId, replicaId) {
+    await this.commands.eval(CLEAR_IF_OWNER, 1, deviceRouteKey(deviceId), replicaId);
+  }
+  async publish(channel, payload) {
+    await this.commands.publish(channel, payload);
+  }
+  /** 就绪探测(/readyz):命令连接 PING 一次。断连时 ioredis 会抛/挂起,由调用方限时。 */
+  async ping() {
+    await this.commands.ping();
+  }
+  async subscribe(channel, handler) {
+    this.handlers.set(channel, handler);
+    await this.subscriber.subscribe(channel);
+  }
+  async close() {
+    this.handlers.clear();
+    await Promise.allSettled([this.subscriber.quit(), this.commands.quit()]);
+  }
+};
+
 // src/sqliteSearchIndex.ts
 import Database from "better-sqlite3";
 var SCHEMA_SQL = TOOL_SEARCH_SCHEMA_STATEMENTS.map((sql) => `${sql};`).join("\n");
@@ -38287,13 +38752,18 @@ var SqliteSearchIndex = class extends SqlSearchIndex {
 
 // src/sqliteStateStore.ts
 import Database2 from "better-sqlite3";
-var DEFAULT_LIST_LIMIT = 1e3;
-function prefixUpperBound(prefix) {
-  for (let i = prefix.length - 1; i >= 0; i--) {
-    const code = prefix.charCodeAt(i);
-    if (code < 65535) {
-      return prefix.slice(0, i) + String.fromCharCode(code + 1);
-    }
+var DEFAULT_LIST_LIMIT2 = 1e3;
+var MAX_CODE_POINT2 = 1114111;
+var SURROGATE_START2 = 55296;
+var SURROGATE_END2 = 57343;
+function prefixUpperBound2(prefix) {
+  const points = [...prefix];
+  for (let i = points.length - 1; i >= 0; i--) {
+    const code = points[i]?.codePointAt(0);
+    if (code === void 0 || code >= MAX_CODE_POINT2) continue;
+    let next = code + 1;
+    if (next >= SURROGATE_START2 && next <= SURROGATE_END2) next = SURROGATE_END2 + 1;
+    return points.slice(0, i).join("") + String.fromCodePoint(next);
   }
   return void 0;
 }
@@ -38336,13 +38806,17 @@ var SqliteStateStore = class {
   async put(key, value) {
     this.stmtPut.run(key, JSON.stringify(value));
   }
+  async putIfAbsent(key, value) {
+    const info = this.db.prepare("INSERT OR IGNORE INTO kv (key, value) VALUES (?, ?)").run(key, JSON.stringify(value));
+    return info.changes > 0;
+  }
   async delete(key) {
     this.stmtDelete.run(key);
   }
   async list(prefix, opts) {
-    const limit = opts?.limit ?? DEFAULT_LIST_LIMIT;
+    const limit = opts?.limit ?? DEFAULT_LIST_LIMIT2;
     const lowerByCursor = opts?.cursor !== void 0 && opts.cursor >= prefix;
-    const upper = prefix === "" ? void 0 : prefixUpperBound(prefix);
+    const upper = prefix === "" ? void 0 : prefixUpperBound2(prefix);
     const conditions = [];
     const params = { n: limit + 1 };
     if (lowerByCursor) {
@@ -38371,14 +38845,16 @@ var SqliteStateStore = class {
 
 // src/server.ts
 import { serve } from "@hono/node-server";
+import postgres from "postgres";
 import { mkdirSync as mkdirSync2 } from "fs";
+import { hostname } from "os";
 import { join as join4 } from "path";
 
 // package.json
 var package_default = {
   name: "@tool-bridge/server",
-  version: "0.7.0",
-  description: "tool-bridge self-hosted server: run the HTBP gateway on Node with SQLite persistence, filesystem object storage and WebSocket device channel \u2014 single container via docker run",
+  version: "0.10.0",
+  description: "tool-bridge self-hosted server: run the HTBP gateway on Node with SQLite or PostgreSQL persistence, filesystem object storage and WebSocket device channel \u2014 single container via docker run",
   type: "module",
   license: "MIT",
   main: "src/index.ts",
@@ -38426,6 +38902,8 @@ var package_default = {
     aws4fetch: "catalog:",
     "better-sqlite3": "^12.6.0",
     hono: "catalog:",
+    ioredis: "^6.0.0",
+    postgres: "^3.4.9",
     ws: "catalog:"
   },
   devDependencies: {
@@ -38490,24 +38968,116 @@ function resolveUiAssets(uiDirOverride) {
 }
 
 // src/server.ts
-function createTbServer(config) {
-  mkdirSync2(config.dataDir, { recursive: true });
-  const dbPath = join4(config.dataDir, "state.sqlite3");
-  const state = new SqliteStateStore(dbPath);
-  let search;
+function pgBackends(databaseUrl) {
+  const sql = postgres(databaseUrl, { onnotice: () => {
+  } });
+  const state = new PgStateStore(sql);
+  const search = new PgSearchIndex(sql);
+  return {
+    state: {
+      value: state,
+      ensureReady: async () => await state.ensureSchema(),
+      ping: async () => {
+        await sql`SELECT 1`;
+      },
+      close: async () => await sql.end({ timeout: 5 })
+    },
+    search: {
+      value: search,
+      ensureReady: async () => {
+        await search.initialized();
+      },
+      close: async () => {
+      }
+    }
+  };
+}
+function sqliteStateBackend(dataDir) {
+  const store = new SqliteStateStore(join4(dataDir, "state.sqlite3"));
+  return {
+    value: store,
+    ensureReady: async () => {
+    },
+    close: async () => store.close()
+  };
+}
+function sqliteSearchBackend(dataDir) {
+  const index = new SqliteSearchIndex(join4(dataDir, "state.sqlite3"));
+  return {
+    value: index,
+    ensureReady: async () => {
+    },
+    close: async () => index.close()
+  };
+}
+function resolveBackends(config) {
+  if (config.databaseUrl !== void 0) return pgBackends(config.databaseUrl);
+  const state = sqliteStateBackend(config.dataDir);
   try {
-    search = new SqliteSearchIndex(dbPath);
+    return { search: sqliteSearchBackend(config.dataDir), state };
   } catch (error) {
-    state.close();
+    state.close().catch(() => {
+    });
     throw error;
   }
+}
+function createTbServer(config) {
+  mkdirSync2(config.dataDir, { recursive: true });
+  const backends = resolveBackends(config);
+  const state = backends.state.value;
+  const search = backends.search.value;
   const secrets = new SecretStoreImpl(state, config.encryptionKey);
-  const objects = createDataObjectStore(config.dataDir);
+  const objects = config.objectStore === void 0 ? createDataObjectStore(config.dataDir) : createS3ObjectStore(config.objectStore, { allowInsecure: config.allowInsecureHttp });
+  const redisBackend = config.redisUrl === void 0 ? void 0 : new RedisDeviceRouterBackend(config.redisUrl);
   const hub = new DeviceHub({
     store: state,
     search,
-    reclaimSec: config.deviceReclaimSec
-  });
+    reclaimSec: config.deviceReclaimSec,
+    // 配了 Redis 才启用多副本路由;缺省单副本,设备调用恒走本地 socket。
+    ...redisBackend === void 0 ? {} : {
+      router: (onLocalCall) => new DeviceRouter(
+        config.replicaId ?? hostname(),
+        redisBackend,
+        { onLocalCall }
+      )
+    }
+  });
+  let draining = false;
+  const probeOne = async (fn) => {
+    let timer;
+    try {
+      await Promise.race([
+        fn(),
+        new Promise((_, reject) => {
+          timer = setTimeout(() => reject(new Error("timeout after 1000ms")), 1e3);
+          timer.unref?.();
+        })
+      ]);
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, detail: err instanceof Error ? err.message : "probe failed" };
+    } finally {
+      if (timer !== void 0) clearTimeout(timer);
+    }
+  };
+  const readiness = async () => {
+    const checks = {};
+    const probes = [];
+    const statePing = backends.state.ping;
+    if (statePing !== void 0) {
+      probes.push(probeOne(statePing).then((r) => {
+        checks.state = r;
+      }));
+    }
+    if (redisBackend !== void 0) {
+      probes.push(probeOne(async () => await redisBackend.ping()).then((r) => {
+        checks.redis = r;
+      }));
+    }
+    await Promise.all(probes);
+    if (draining) checks.draining = { ok: false, detail: "shutting down" };
+    return { checks, ready: !draining && Object.values(checks).every((c) => c.ok) };
+  };
   const deps = {
     state,
     secrets,
@@ -38516,7 +39086,8 @@ function createTbServer(config) {
     search,
     allowInsecureHttp: config.allowInsecureHttp,
     objects: () => objects,
-    device: hub
+    device: hub,
+    readiness
   };
   if (config.encryptionKey !== void 0) deps.encryptionKey = config.encryptionKey;
   if (config.pluginBindings !== void 0) deps.pluginBindings = config.pluginBindings;
@@ -38535,6 +39106,9 @@ function createTbServer(config) {
     state,
     deviceHub: hub,
     async start() {
+      await backends.state.ensureReady();
+      await backends.search.ensureReady();
+      await hub.startRouter();
       await runBootstrap(state, {
         ...config.adminSk !== void 0 ? { adminSk: config.adminSk } : {},
         requireAdminSk: !config.allowInsecureBootstrap
@@ -38547,16 +39121,24 @@ function createTbServer(config) {
         hub.attach(server);
       });
     },
+    startDraining() {
+      draining = true;
+    },
     async close() {
-      await hub.close();
+      draining = true;
+      let closed;
       if (server !== void 0) {
-        await new Promise((resolve3, reject) => {
-          server?.close((err) => err ? reject(err) : resolve3());
+        const s = server;
+        closed = new Promise((resolve3, reject) => {
+          s.close((err) => err ? reject(err) : resolve3());
         });
-        server = void 0;
+        s.closeIdleConnections?.();
       }
-      search.close();
-      state.close();
+      await hub.close();
+      if (closed !== void 0) await closed;
+      server = void 0;
+      await backends.search.close();
+      await backends.state.close();
     }
   };
 }
@@ -38565,7 +39147,13 @@ export {
   configFromEnv,
   DEVICE_WS_PATH,
   DeviceHub,
+  DEVICE_ROUTE_TTL_SEC,
+  DEVICE_FORWARD_TIMEOUT_MS,
+  DeviceRouter,
   createDataObjectStore,
+  PgSearchIndex,
+  PgStateStore,
+  RedisDeviceRouterBackend,
   SqliteSearchIndex,
   SqliteStateStore,
   createTbServer