Skip to content

armgit / dbx

Public Imported from GitHub
0

25 MB lightweight cross-platform database client for 100+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 100+ 数据库,提供桌面端、Docker、CLI、内置 AI 助手和 MCP。

fix(ssh): treat a non-numeric local port as unset

HabibAlmaula414ececba28d
diff --git a/apps/desktop/src/components/connection/ConnectionDialog.vue b/apps/desktop/src/components/connection/ConnectionDialog.vue
index 44d72a12dd..6bd7926db3 100644
--- a/apps/desktop/src/components/connection/ConnectionDialog.vue
+++ b/apps/desktop/src/components/connection/ConnectionDialog.vue
@@ -6793,7 +6793,7 @@ function validateTransportLayers(config: LegacyConnectionConfig) {
const localPortState = sshLocalPortState(layer.local_port);
if (localPortState === "invalid") throw new Error(t("connection.sshHopInvalidLocalPort", { hop: label }));
if (localPortState === "valid" && index !== lastEnabledIndex) throw new Error(t("connection.sshHopLocalPortNotLast", { hop: label }));
- if (localPortState === "valid" && !sshLocalPortSupportedForConnection(config, mqSystemKind.value)) throw new Error(t("connection.sshHopLocalPortUnsupported", { hop: label }));
+ if (localPortState === "valid" && !sshLocalPortSupportedForConnection(config, mqSystemKind.value, selectedPluginProvider.value?.contribution.proxy_route)) throw new Error(t("connection.sshHopLocalPortUnsupported", { hop: label }));
}
});
}
diff --git a/apps/desktop/src/components/connection/__tests__/ConnectionDialog.sshLocalPort.spec.ts b/apps/desktop/src/components/connection/__tests__/ConnectionDialog.sshLocalPort.spec.ts
index c3dc769fc9..170484cc65 100644
--- a/apps/desktop/src/components/connection/__tests__/ConnectionDialog.sshLocalPort.spec.ts
+++ b/apps/desktop/src/components/connection/__tests__/ConnectionDialog.sshLocalPort.spec.ts
@@ -3,7 +3,7 @@
import { createApp, defineComponent, h, nextTick, reactive, type App } from "vue";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import i18n from "@/i18n";
-import type { ConnectionConfig, SshTunnelConfig, TransportLayerConfig } from "@/types/database";
+import type { ConnectionConfig, InstalledPlugin, SshTunnelConfig, TransportLayerConfig } from "@/types/database";
const { store, settings, backend } = vi.hoisted(() => ({
store: {
@@ -149,6 +149,22 @@ function tunnelled(layers: TransportLayerConfig[], overrides: Partial<Connection
return { id: "pg-1", name: "Postgres", db_type: "postgres", driver_profile: "postgres", driver_label: "PostgreSQL", host: "db.internal", port: 5432, username: "app", password: "secret", database: "app", save_password: true, transport_layers: layers, ...overrides };
}
+function pluginWithProvider(proxyRoute: boolean): InstalledPlugin {
+ return {
+ manifest: {
+ id: "sample.kafka",
+ name: "Sample Kafka",
+ drivers: [],
+ contributions: [{ type: "connection-provider", id: "sample.connection", label: "Sample Kafka", database_type: "sample", fields: [], capabilities: ["connect"], proxy_route: proxyRoute }],
+ },
+ compatibility: { compatible: true },
+ };
+}
+
+function pluginConnection(layers: TransportLayerConfig[]): ConnectionConfig {
+ return { id: "plugin-1", name: "Sample", db_type: "plugin", plugin_id: "sample.kafka", plugin_connection_provider: "sample.connection", plugin_connection_type: "sample", host: "", port: 0, username: "", password: "", transport_layers: layers };
+}
+
async function settle() {
for (let i = 0; i < 8; i++) await nextTick();
}
@@ -239,6 +255,32 @@ describe("ConnectionDialog SSH fixed local port", () => {
expect("local_port" in JSON.parse(JSON.stringify(layer))).toBe(expected !== undefined);
});
+ it.each([
+ ["NaN", Number.NaN],
+ ["text", "abc"],
+ ])("saves no port for a saved non-numeric %s value instead of failing validation", async (_name, saved) => {
+ await mountDialog(tunnelled([sshLayer("bastion", { local_port: saved as number })]));
+
+ await save();
+
+ expect(document.body.textContent).not.toContain("Local port must be between 1 and 65535");
+ const layer = savedLayers()[0] as SshTunnelConfig;
+ expect(layer.local_port).toBeUndefined();
+ expect("local_port" in JSON.parse(JSON.stringify(layer))).toBe(false);
+ });
+
+ it("saves no port when the field emits a non-numeric value", async () => {
+ await mountDialog(tunnelled([sshLayer("bastion", { local_port: 4059 })]));
+ // A number input sanitizes text to "", so the raw string only reaches the handler through a text input.
+ localPortInput()!.type = "text";
+
+ await typeLocalPort("abc");
+ await save();
+
+ expect(document.body.textContent).not.toContain("Local port must be between 1 and 65535");
+ expect((savedLayers()[0] as SshTunnelConfig).local_port).toBeUndefined();
+ });
+
it.each([
["70000", "70000"],
["0", "0"],
@@ -326,6 +368,34 @@ describe("ConnectionDialog SSH fixed local port", () => {
expect(savedLayers()).toEqual([expect.objectContaining({ id: "bastion", local_port: 4059 })]);
});
+ it("refuses a port on a plugin connection whose provider declares proxy_route", async () => {
+ backend.listPlugins.mockResolvedValue([pluginWithProvider(true)]);
+ await mountDialog(pluginConnection([sshLayer("bastion", { local_port: 4059 })]));
+
+ await save();
+
+ expect(store.updateConnection).not.toHaveBeenCalled();
+ expect(document.body.textContent).toContain("Layer bastion: Local port is not supported for this connection type");
+ });
+
+ it("saves a plugin connection with proxy_route when the layer has no port", async () => {
+ backend.listPlugins.mockResolvedValue([pluginWithProvider(true)]);
+ await mountDialog(pluginConnection([sshLayer("bastion")]));
+
+ await save();
+
+ expect((savedLayers()[0] as SshTunnelConfig).local_port).toBeUndefined();
+ });
+
+ it("accepts a port on a plugin connection whose provider does not declare proxy_route", async () => {
+ backend.listPlugins.mockResolvedValue([pluginWithProvider(false)]);
+ await mountDialog(pluginConnection([sshLayer("bastion", { local_port: 4059 })]));
+
+ await save();
+
+ expect(savedLayers()).toEqual([expect.objectContaining({ id: "bastion", local_port: 4059 })]);
+ });
+
it("does not offer a port on a layer that is not SSH", async () => {
await mountDialog(tunnelled([proxyLayer]));
diff --git a/apps/desktop/src/lib/connection/__tests__/sshLocalPort.spec.ts b/apps/desktop/src/lib/connection/__tests__/sshLocalPort.spec.ts
index 52d29f6e0c..a5f8270a5b 100644
--- a/apps/desktop/src/lib/connection/__tests__/sshLocalPort.spec.ts
+++ b/apps/desktop/src/lib/connection/__tests__/sshLocalPort.spec.ts
@@ -15,17 +15,20 @@ const CASES: { name: string; value: unknown; normalized: number | undefined; sta
{ name: "zero", value: 0, normalized: undefined, state: "invalid", editable: 0 },
{ name: "zero string", value: "0", normalized: undefined, state: "invalid", editable: 0 },
{ name: "negative", value: -1, normalized: undefined, state: "invalid", editable: -1 },
- { name: "negative string", value: "-1", normalized: undefined, state: "invalid", editable: Number.NaN },
+ { name: "negative string", value: "-1", normalized: undefined, state: "invalid", editable: -1 },
{ name: "above range", value: 65536, normalized: undefined, state: "invalid", editable: 65536 },
{ name: "far above range", value: 70000, normalized: undefined, state: "invalid", editable: 70000 },
{ name: "above range string", value: "70000", normalized: undefined, state: "invalid", editable: 70000 },
{ name: "fraction", value: 4059.5, normalized: undefined, state: "invalid", editable: 4059.5 },
- { name: "fraction string", value: "4059.5", normalized: undefined, state: "invalid", editable: Number.NaN },
- { name: "NaN", value: Number.NaN, normalized: undefined, state: "invalid", editable: Number.NaN },
- { name: "Infinity", value: Number.POSITIVE_INFINITY, normalized: undefined, state: "invalid", editable: Number.POSITIVE_INFINITY },
- { name: "hex string", value: "0x10", normalized: undefined, state: "invalid", editable: Number.NaN },
- { name: "text", value: "abc", normalized: undefined, state: "invalid", editable: Number.NaN },
- { name: "boolean", value: true, normalized: undefined, state: "invalid", editable: Number.NaN },
+ { name: "fraction string", value: "4059.5", normalized: undefined, state: "invalid", editable: 4059.5 },
+ { name: "NaN", value: Number.NaN, normalized: undefined, state: "invalid", editable: undefined },
+ { name: "Infinity", value: Number.POSITIVE_INFINITY, normalized: undefined, state: "invalid", editable: undefined },
+ { name: "hex string", value: "0x10", normalized: undefined, state: "invalid", editable: undefined },
+ { name: "exponent string", value: "1e3", normalized: undefined, state: "invalid", editable: 1000 },
+ { name: "explicit plus string", value: "+4059", normalized: undefined, state: "invalid", editable: undefined },
+ { name: "text", value: "abc", normalized: undefined, state: "invalid", editable: undefined },
+ { name: "number followed by text", value: "4059abc", normalized: undefined, state: "invalid", editable: undefined },
+ { name: "boolean", value: true, normalized: undefined, state: "invalid", editable: undefined },
];
describe("ssh local port helpers", () => {
@@ -37,20 +40,21 @@ describe("ssh local port helpers", () => {
expect(sshLocalPortState(value)).toBe(state);
});
- it.each(CASES)("keeps $name reportable in the form", ({ value, editable }) => {
+ it.each(CASES)("maps $name to the form value", ({ value, editable }) => {
expect(editableSshLocalPort(value)).toBe(editable);
});
- it("keeps an out-of-range value classified as invalid after the form round trip", () => {
+ it("keeps out-of-range and fractional values invalid after the form round trip, and non-numbers unset", () => {
expect(sshLocalPortState(editableSshLocalPort("70000"))).toBe("invalid");
- expect(sshLocalPortState(editableSshLocalPort("abc"))).toBe("invalid");
+ expect(sshLocalPortState(editableSshLocalPort("4059.5"))).toBe("invalid");
+ expect(sshLocalPortState(editableSshLocalPort("abc"))).toBe("unset");
expect(sshLocalPortState(editableSshLocalPort(""))).toBe("unset");
});
});
describe("sshLocalPortSupportedForConnection", () => {
type Connection = Parameters<typeof sshLocalPortSupportedForConnection>[0];
- const CASES: { name: string; config: Connection; mqSystemKind?: string; supported: boolean }[] = [
+ const CASES: { name: string; config: Connection; mqSystemKind?: string; pluginProxyRoute?: boolean; supported: boolean }[] = [
{ name: "postgres", config: { db_type: "postgres" }, supported: true },
{ name: "mysql", config: { db_type: "mysql" }, supported: true },
{ name: "redis without a mode", config: { db_type: "redis" }, supported: true },
@@ -71,10 +75,15 @@ describe("sshLocalPortSupportedForConnection", () => {
{ name: "rocketmq picked in the form", config: { db_type: "mq", driver_profile: "kafka", external_config: { systemKind: "kafka" } }, mqSystemKind: "rocketmq", supported: false },
{ name: "kafka picked in the form over a saved rocketmq kind", config: { db_type: "mq", driver_profile: "rocketmq", external_config: { systemKind: "rocketmq" } }, mqSystemKind: "kafka", supported: true },
{ name: "form kind ignored for other database types", config: { db_type: "postgres" }, mqSystemKind: "rocketmq", supported: true },
+ { name: "a plugin whose provider declares proxy_route", config: { db_type: "plugin" }, pluginProxyRoute: true, supported: false },
+ { name: "a plugin whose provider does not declare proxy_route", config: { db_type: "plugin" }, pluginProxyRoute: false, supported: true },
+ { name: "a plugin with no provider flag", config: { db_type: "plugin" }, supported: true },
+ { name: "proxy_route ignored for other database types", config: { db_type: "postgres" }, pluginProxyRoute: true, supported: true },
+ { name: "proxy_route ignored for message queues", config: { db_type: "mq", driver_profile: "kafka" }, mqSystemKind: "kafka", pluginProxyRoute: true, supported: true },
];
- it.each(CASES)("reports $name as supported: $supported", ({ config, mqSystemKind, supported }) => {
- expect(sshLocalPortSupportedForConnection(config, mqSystemKind)).toBe(supported);
+ it.each(CASES)("reports $name as supported: $supported", ({ config, mqSystemKind, pluginProxyRoute, supported }) => {
+ expect(sshLocalPortSupportedForConnection(config, mqSystemKind, pluginProxyRoute)).toBe(supported);
});
});
diff --git a/apps/desktop/src/lib/connection/sshLocalPort.ts b/apps/desktop/src/lib/connection/sshLocalPort.ts
index 5de1b8e8b3..acb9c99f51 100644
--- a/apps/desktop/src/lib/connection/sshLocalPort.ts
+++ b/apps/desktop/src/lib/connection/sshLocalPort.ts
@@ -19,9 +19,16 @@ export function sshLocalPortState(value: unknown): SshLocalPortState {
return normalizeSshLocalPort(value) === undefined ? "invalid" : "valid";
}
-/** Like `normalizeSshLocalPort`, but keeps an out-of-range value as a number so form validation can report it. */
+// The HTML number input grammar (a valid floating-point number), so anything the field can display parses as a number.
+const FLOATING_POINT_NUMBER = /^\s*-?(?:\d+(?:\.\d+)?|\.\d+)(?:[eE][+-]?\d+)?\s*$/;
+
+/**
+ * Keeps a finite number, even an out-of-range one, so form validation can report it. Anything else is unset: a number
+ * input shows it as empty, and an empty-looking field must not fail validation.
+ */
export function editableSshLocalPort(value: unknown): number | undefined {
- return sshLocalPortState(value) === "unset" ? undefined : toPortNumber(value);
+ const port = typeof value === "string" && FLOATING_POINT_NUMBER.test(value) ? Number(value) : value;
+ return typeof port === "number" && Number.isFinite(port) ? port : undefined;
}
// These types never bind the static tunnel on their primary path: SQLite reaches its remote worker over SSH, and
@@ -39,9 +46,11 @@ function isRocketMqConnection(config: SshLocalPortConnection, mqSystemKind?: str
/**
* Whether the connection's primary tunnel can listen on a fixed local port (Redis Cluster and Sentinel route per node).
* `mqSystemKind` is the message-queue kind picked in the form, which the backend reads from `external_config.systemKind`.
+ * `pluginProxyRoute` is the selected plugin provider's `proxy_route` flag: those providers connect through a SOCKS5 route.
*/
-export function sshLocalPortSupportedForConnection(config: SshLocalPortConnection, mqSystemKind?: string): boolean {
+export function sshLocalPortSupportedForConnection(config: SshLocalPortConnection, mqSystemKind?: string, pluginProxyRoute?: boolean): boolean {
if (NO_STATIC_TUNNEL_DB_TYPES.has(config.db_type) || isCloudflareD1Connection(config) || isRocketMqConnection(config, mqSystemKind)) return false;
+ if (config.db_type === "plugin" && pluginProxyRoute === true) return false;
return config.db_type !== "redis" || (config.redis_connection_mode !== "cluster" && config.redis_connection_mode !== "sentinel");
}
diff --git a/crates/dbx-core/src/connection/mod.rs b/crates/dbx-core/src/connection/mod.rs
index d0c0bb8dac..45e982c19d 100644
--- a/crates/dbx-core/src/connection/mod.rs
+++ b/crates/dbx-core/src/connection/mod.rs
@@ -499,13 +499,92 @@ fn primary_tunnel_fixed_local_port(
last_ssh_layer_local_port(transport_layers)
}
-fn last_ssh_layer_local_port(transport_layers: &[TransportLayerConfig]) -> Option<u16> {
- match transport_layers.last() {
- Some(TransportLayerConfig::Ssh(ssh)) if ssh.profile_id.is_empty() => ssh.local_port.filter(|port| *port != 0),
+fn ssh_layer_local_port(layer: &TransportLayerConfig) -> Option<u16> {
+ match layer {
+ TransportLayerConfig::Ssh(ssh) if ssh.profile_id.is_empty() => ssh.local_port.filter(|port| *port != 0),
_ => None,
}
}
+fn last_ssh_layer_local_port(transport_layers: &[TransportLayerConfig]) -> Option<u16> {
+ transport_layers.last().and_then(ssh_layer_local_port)
+}
+
+/// Connection kinds whose primary path never listens on the static SSH tunnel,
+/// as `(kind, route)` for the error message. `plugin_proxy_route` carries the
+/// provider label of a plugin that declared `proxy_route`.
+fn static_tunnel_bypass(config: &ConnectionConfig, plugin_proxy_route: Option<&str>) -> Option<(String, &'static str)> {
+ let (kind, route) = match config.db_type {
+ DatabaseType::Sqlite => ("SQLite", "a remote worker over SSH"),
+ DatabaseType::ClickHouse => ("ClickHouse", "a SOCKS5 route"),
+ DatabaseType::Turso => ("Turso", "a SOCKS5 route"),
+ DatabaseType::Redis if config.uses_redis_cluster() => ("Redis Cluster", "per-node tunnels"),
+ DatabaseType::Redis if config.uses_redis_sentinel() => ("Redis Sentinel", "per-node tunnels"),
+ DatabaseType::MessageQueue if connection_secrets::is_rocketmq_connection(config) => {
+ ("RocketMQ", "a SOCKS5 route")
+ }
+ DatabaseType::Plugin => {
+ let label = plugin_proxy_route?.trim();
+ return Some((if label.is_empty() { "this plugin's" } else { label }.to_string(), "a SOCKS5 route"));
+ }
+ _ => return None,
+ };
+ Some((kind.to_string(), route))
+}
+
+/// The dialog has no tunnel settings for Cloudflare D1 and drops its layers on
+/// save, so the remedy differs from the other kinds.
+const CLOUDFLARE_D1_LOCAL_PORT_ERROR: &str = "Local Port is not supported for Cloudflare D1 connections, which do not use tunnel layers; open the connection and save it to remove them.";
+
+/// How the dialog names the layer at `effective_index` among the enabled
+/// layers: its own name, otherwise its 1-based position in the full list that
+/// includes disabled layers.
+fn effective_layer_label(config: &ConnectionConfig, effective_index: usize) -> String {
+ match config.transport_layers.iter().enumerate().filter(|(_, layer)| layer.enabled()).nth(effective_index) {
+ Some((position, layer)) => match layer.name().trim() {
+ "" => (position + 1).to_string(),
+ name => name.to_string(),
+ },
+ None => (effective_index + 1).to_string(),
+ }
+}
+
+/// Rejects a fixed SSH `local_port` that the connection cannot bind instead of
+/// silently using a random port. This is a property of the config, so it does
+/// not depend on the connection id or on `honor_fixed_ssh_local_ports`: Test
+/// and Connect agree, whether the config came from the dialog, an import, a
+/// cloud sync, or a hand-edited config. A layer that references a shared tunnel
+/// profile supplies its own configuration and is not checked. Kafka with a
+/// single loopback bootstrap server keeps its own rule,
+/// `kafka_loopback_local_port_error`.
+fn ssh_local_port_config_error(
+ config: &ConnectionConfig,
+ transport_layers: &[TransportLayerConfig],
+ plugin_proxy_route: Option<&str>,
+) -> Result<(), String> {
+ let Some((last, earlier)) = transport_layers.split_last() else {
+ return Ok(());
+ };
+ if let Some(index) = earlier.iter().position(|layer| ssh_layer_local_port(layer).is_some()) {
+ return Err(format!(
+ "Local Port only applies to the last enabled transport layer; clear it on SSH layer {}.",
+ effective_layer_label(config, index)
+ ));
+ }
+ if ssh_layer_local_port(last).is_none() {
+ return Ok(());
+ }
+ if config.db_type == DatabaseType::CloudflareD1 {
+ return Err(CLOUDFLARE_D1_LOCAL_PORT_ERROR.to_string());
+ }
+ match static_tunnel_bypass(config, plugin_proxy_route) {
+ Some((kind, route)) => Err(format!(
+ "Local Port is not supported for {kind} connections because they connect through {route}; clear Local Port in the SSH layer."
+ )),
+ None => Ok(()),
+ }
+}
+
/// Kafka with a single `127.0.0.1` bootstrap server binds its SSH tunnel to the
/// bootstrap port so the advertised listeners stay reachable, which leaves no
/// room for a separate fixed local port.
@@ -3850,6 +3929,7 @@ impl AppState {
config: &ConnectionConfig,
) -> Result<ConnectionEndpoint, String> {
let transport_layers = self.resolved_transport_layers(config).await?;
+ self.ensure_ssh_local_port_supported(config, &transport_layers)?;
let transport_summary = transport_layers
.iter()
.map(|layer| match layer {
@@ -3984,6 +4064,25 @@ impl AppState {
Ok(ConnectionEndpoint { host: "127.0.0.1".to_string(), port: local_port, proxy: None })
}
+ /// Config check that runs ahead of the early returns in `connection_endpoint`,
+ /// which every Test and Connect path reaches first, and in
+ /// `mq_admin_config_for_connection`, which message queue admin calls reach
+ /// without going through `connection_endpoint`.
+ fn ensure_ssh_local_port_supported(
+ &self,
+ config: &ConnectionConfig,
+ transport_layers: &[TransportLayerConfig],
+ ) -> Result<(), String> {
+ let plugin_proxy_route = if config.db_type == DatabaseType::Plugin
+ && transport_layers.iter().any(|layer| ssh_layer_local_port(layer).is_some())
+ {
+ self.plugin_host.proxy_route_provider_label(config)
+ } else {
+ None
+ };
+ ssh_local_port_config_error(config, transport_layers, plugin_proxy_route.as_deref())
+ }
+
fn static_tunnel_fixed_local_port(
&self,
connection_id: &str,
@@ -4397,15 +4496,15 @@ impl AppState {
if !config.has_effective_transport_layers() {
return Ok(mqc);
}
+ let transport_layers = self.resolved_transport_layers(config).await?;
+ self.ensure_ssh_local_port_supported(config, &transport_layers)?;
if mqc.system_kind == crate::mq::types::MqSystemKind::RocketMq {
- let transport_layers = self.resolved_transport_layers(config).await?;
let proxy = self.rocketmq_socks_proxy_for_transport_layers(connection_id, &transport_layers).await?;
return Ok(mqc.with_socks_proxy(&proxy.host, proxy.port, &proxy.username, &proxy.password));
}
if mqc.system_kind == crate::mq::types::MqSystemKind::RabbitMq {
- let transport_layers = self.resolved_transport_layers(config).await?;
let (amqp_host, amqp_port) = crate::mq::adapters::rabbitmq::primary_amqp_endpoint(&mqc)?;
let management_endpoint = crate::mq::adapters::rabbitmq::management_endpoint(&mqc)?;
let amqp_local_port = db::transport_layer_tunnel::start_transport_layers_with_final_ssh_local_port(
@@ -4466,7 +4565,6 @@ impl AppState {
if mqc.system_kind == crate::mq::types::MqSystemKind::Kafka {
if let Some((bootstrap_host, bootstrap_port)) = kafka_single_loopback_bootstrap_endpoint(&mqc.extra) {
- let transport_layers = self.resolved_transport_layers(config).await?;
if matches!(transport_layers.last(), Some(TransportLayerConfig::Ssh(_))) {
if let Some(error) = kafka_loopback_local_port_error(bootstrap_port, &transport_layers) {
return Err(error);
@@ -7854,10 +7952,11 @@ mod tests {
oceanbase_mysql_setup_queries, prestosql_jdbc_config_for_endpoint, primary_tunnel_fixed_local_port,
redact_transport_url, redacted_connection_url_for_endpoint, redis_sentinel_transport_id,
redis_sentinel_transport_prefix, report_connection_liveness_lost, sqlserver_legacy_agent_config,
- sqlserver_legacy_driver_error, sqlserver_uses_legacy_driver, task_client_session_id,
- transport_layers_through_last_ssh, upsert_connection_url_param, uses_bare_mysql_pool, uses_tcp_probe,
- validate_connection_url_params, validate_h2_database_path, AppState, MysqlMode, PoolKind, TxnConnection,
- GAUSSDB_M_JDBC_DRIVER_CLASS, GAUSSDB_M_JDBC_DRIVER_PROFILE, PRESTOSQL_JDBC_DRIVER_CLASS,
+ sqlserver_legacy_driver_error, sqlserver_uses_legacy_driver, ssh_local_port_config_error,
+ task_client_session_id, transport_layers_through_last_ssh, upsert_connection_url_param, uses_bare_mysql_pool,
+ uses_tcp_probe, validate_connection_url_params, validate_h2_database_path, AppState, MysqlMode, PoolKind,
+ TxnConnection, CLOUDFLARE_D1_LOCAL_PORT_ERROR, GAUSSDB_M_JDBC_DRIVER_CLASS, GAUSSDB_M_JDBC_DRIVER_PROFILE,
+ PRESTOSQL_JDBC_DRIVER_CLASS,
};
use crate::agent_connection::{
agent_connect_params, mongo_legacy_error_with_auth_hint, mongo_uses_legacy_driver,
@@ -9334,6 +9433,301 @@ mod tests {
}
}
+ fn unsupported_local_port(kind: &str, route: &str) -> String {
+ format!(
+ "Local Port is not supported for {kind} connections because they connect through {route}; clear Local Port in the SSH layer."
+ )
+ }
+
+ fn ssh_layer_with_port(port: Option<u16>, profile_id: &str) -> TransportLayerConfig {
+ let mut layer = ssh_layer("ssh", profile_id);
+ layer.local_port = port;
+ TransportLayerConfig::Ssh(layer)
+ }
+
+ fn config_of_type(db_type: DatabaseType) -> ConnectionConfig {
+ let mut config = mysql_config(None);
+ config.db_type = db_type;
+ config
+ }
+
+ fn message_queue_config(system_kind: &str) -> ConnectionConfig {
+ let mut config = config_of_type(DatabaseType::MessageQueue);
+ config.external_config = Some(serde_json::json!({ "systemKind": system_kind }));
+ config
+ }
+
+ fn redis_config(mode: &str) -> ConnectionConfig {
+ let mut config = config_of_type(DatabaseType::Redis);
+ config.redis_connection_mode = Some(mode.to_string());
+ config
+ }
+
+ fn with_layers(mut config: ConnectionConfig, layers: Vec<TransportLayerConfig>) -> ConnectionConfig {
+ config.transport_layers = layers;
+ config
+ }
+
+ fn named_ssh_layer(name: &str, port: Option<u16>, enabled: bool) -> TransportLayerConfig {
+ let mut layer = ssh_layer("ssh", "");
+ layer.name = name.to_string();
+ layer.local_port = port;
+ layer.enabled = enabled;
+ TransportLayerConfig::Ssh(layer)
+ }
+
+ fn non_last_layer_local_port(layer: &str) -> String {
+ format!("Local Port only applies to the last enabled transport layer; clear it on SSH layer {layer}.")
+ }
+
+ #[test]
+ fn ssh_local_port_is_rejected_only_where_the_primary_path_cannot_bind_it() {
+ let ssh = |port: Option<u16>| ssh_layer_with_port(port, "");
+ let proxy = || TransportLayerConfig::Proxy(proxy_layer("proxy", ""));
+ let disabled_proxy = || {
+ let mut layer = proxy_layer("proxy", "");
+ layer.enabled = false;
+ TransportLayerConfig::Proxy(layer)
+ };
+ let single = |config: ConnectionConfig| with_layers(config, vec![ssh(Some(4059))]);
+ let unsupported = |kind: &str, route: &str| Some(unsupported_local_port(kind, route));
+ let non_last = |layer: &str| Some(non_last_layer_local_port(layer));
+ let mut rocketmq_by_profile = config_of_type(DatabaseType::MessageQueue);
+ rocketmq_by_profile.driver_profile = Some("rocketmq".to_string());
+ let mut kafka_loopback = message_queue_config("kafka");
+ kafka_loopback.external_config = Some(serde_json::json!({
+ "systemKind": "kafka",
+ "extra": { "bootstrapServers": "127.0.0.1:9093" }
+ }));
+
+ let cases = [
+ ("mysql", single(config_of_type(DatabaseType::Mysql)), None, None),
+ ("postgres", single(config_of_type(DatabaseType::Postgres)), None, None),
+ ("mongodb", single(config_of_type(DatabaseType::MongoDb)), None, None),
+ ("elasticsearch", single(config_of_type(DatabaseType::Elasticsearch)), None, None),
+ ("jdbc", single(config_of_type(DatabaseType::Jdbc)), None, None),
+ ("agent driver", single(config_of_type(DatabaseType::Oracle)), None, None),
+ ("nacos", single(config_of_type(DatabaseType::Nacos)), None, None),
+ ("redis standalone", single(redis_config("standalone")), None, None),
+ ("redis without a mode", single(config_of_type(DatabaseType::Redis)), None, None),
+ ("plugin without proxy_route", single(config_of_type(DatabaseType::Plugin)), None, None),
+ ("kafka", single(message_queue_config("kafka")), None, None),
+ ("kafka loopback bootstrap keeps its own rule", single(kafka_loopback), None, None),
+ ("rabbitmq", single(message_queue_config("rabbitmq")), None, None),
+ ("pulsar", single(message_queue_config("pulsar")), None, None),
+ (
+ "ssh after a proxy layer",
+ with_layers(config_of_type(DatabaseType::Mysql), vec![proxy(), ssh(Some(4059))]),
+ None,
+ None,
+ ),
+ (
+ "sqlite",
+ single(config_of_type(DatabaseType::Sqlite)),
+ None,
+ unsupported("SQLite", "a remote worker over SSH"),
+ ),
+ (
+ "clickhouse",
+ single(config_of_type(DatabaseType::ClickHouse)),
+ None,
+ unsupported("ClickHouse", "a SOCKS5 route"),
+ ),
+ (
+ "cloudflare d1",
+ single(config_of_type(DatabaseType::CloudflareD1)),
+ None,
+ Some(CLOUDFLARE_D1_LOCAL_PORT_ERROR.to_string()),
+ ),
+ ("turso", single(config_of_type(DatabaseType::Turso)), None, unsupported("Turso", "a SOCKS5 route")),
+ ("rocketmq", single(message_queue_config("rocketmq")), None, unsupported("RocketMQ", "a SOCKS5 route")),
+ (
+ "rocketmq named by the driver profile",
+ single(rocketmq_by_profile),
+ None,
+ unsupported("RocketMQ", "a SOCKS5 route"),
+ ),
+ ("redis cluster", single(redis_config("cluster")), None, unsupported("Redis Cluster", "per-node tunnels")),
+ (
+ "redis cluster in another case",
+ single(redis_config("Cluster")),
+ None,
+ unsupported("Redis Cluster", "per-node tunnels"),
+ ),
+ (
+ "redis sentinel",
+ single(redis_config("sentinel")),
+ None,
+ unsupported("Redis Sentinel", "per-node tunnels"),
+ ),
+ (
+ "plugin with proxy_route is named by its provider label",
+ single(config_of_type(DatabaseType::Plugin)),
+ Some("Acme Kafka"),
+ unsupported("Acme Kafka", "a SOCKS5 route"),
+ ),
+ (
+ "plugin with proxy_route and a blank label",
+ single(config_of_type(DatabaseType::Plugin)),
+ Some(" "),
+ unsupported("this plugin's", "a SOCKS5 route"),
+ ),
+ (
+ "proxy_route is ignored for other kinds",
+ single(config_of_type(DatabaseType::Mysql)),
+ Some("Acme Kafka"),
+ None,
+ ),
+ (
+ "unsupported kind without a port",
+ with_layers(config_of_type(DatabaseType::Sqlite), vec![ssh(None)]),
+ None,
+ None,
+ ),
+ (
+ "unsupported kind with port zero",
+ with_layers(config_of_type(DatabaseType::ClickHouse), vec![ssh(Some(0))]),
+ None,
+ None,
+ ),
+ (
+ "unsupported kind with a tunnel profile layer",
+ with_layers(config_of_type(DatabaseType::Sqlite), vec![ssh_layer_with_port(Some(4059), "shared")]),
+ None,
+ None,
+ ),
+ ("unsupported kind without layers", config_of_type(DatabaseType::Sqlite), None, None),
+ (
+ "unsupported kind behind a proxy layer",
+ with_layers(config_of_type(DatabaseType::ClickHouse), vec![proxy(), ssh(Some(4059))]),
+ None,
+ unsupported("ClickHouse", "a SOCKS5 route"),
+ ),
+ (
+ "unsupported kind with a disabled layer after the port",
+ with_layers(
+ config_of_type(DatabaseType::ClickHouse),
+ vec![ssh(Some(4059)), named_ssh_layer("", None, false)],
+ ),
+ None,
+ unsupported("ClickHouse", "a SOCKS5 route"),
+ ),
+ (
+ "ssh before the last layer",
+ with_layers(config_of_type(DatabaseType::Mysql), vec![ssh(Some(4059)), ssh(None)]),
+ None,
+ non_last("1"),
+ ),
+ (
+ "ssh before a proxy layer",
+ with_layers(config_of_type(DatabaseType::Mysql), vec![ssh(Some(4059)), proxy()]),
+ None,
+ non_last("1"),
+ ),
+ (
+ "the second of three layers",
+ with_layers(config_of_type(DatabaseType::Mysql), vec![ssh(None), ssh(Some(4059)), proxy()]),
+ None,
+ non_last("2"),
+ ),
+ (
+ "a disabled layer before it still counts toward its position",
+ with_layers(
+ config_of_type(DatabaseType::Mysql),
+ vec![disabled_proxy(), named_ssh_layer("", Some(4059), true), ssh(None)],
+ ),
+ None,
+ non_last("2"),
+ ),
+ (
+ "several disabled layers before it",
+ with_layers(
+ config_of_type(DatabaseType::Mysql),
+ vec![
+ disabled_proxy(),
+ named_ssh_layer("", None, false),
+ named_ssh_layer("", Some(4059), true),
+ proxy(),
+ ],
+ ),
+ None,
+ non_last("3"),
+ ),
+ (
+ "a disabled layer between the port and the last layer",
+ with_layers(
+ config_of_type(DatabaseType::Mysql),
+ vec![named_ssh_layer("", Some(4059), true), disabled_proxy(), ssh(None)],
+ ),
+ None,
+ non_last("1"),
+ ),
+ (
+ "the layer name is used when set",
+ with_layers(
+ config_of_type(DatabaseType::Mysql),
+ vec![disabled_proxy(), named_ssh_layer(" Bastion ", Some(4059), true), ssh(None)],
+ ),
+ None,
+ non_last("Bastion"),
+ ),
+ (
+ "a blank layer name falls back to the position",
+ with_layers(
+ config_of_type(DatabaseType::Mysql),
+ vec![named_ssh_layer(" ", Some(4059), true), ssh(None)],
+ ),
+ None,
+ non_last("1"),
+ ),
+ (
+ "the last layer owns the port",
+ with_layers(config_of_type(DatabaseType::Mysql), vec![ssh(None), ssh(Some(4059))]),
+ None,
+ None,
+ ),
+ (
+ "an earlier port is reported before an unsupported kind",
+ with_layers(config_of_type(DatabaseType::ClickHouse), vec![ssh(Some(4059)), proxy()]),
+ None,
+ non_last("1"),
+ ),
+ (
+ "a profile layer before the last layer is ignored",
+ with_layers(
+ config_of_type(DatabaseType::Mysql),
+ vec![ssh_layer_with_port(Some(4059), "shared"), ssh(None)],
+ ),
+ None,
+ None,
+ ),
+ (
+ "port zero before the last layer is ignored",
+ with_layers(config_of_type(DatabaseType::Mysql), vec![ssh(Some(0)), ssh(None)]),
+ None,
+ None,
+ ),
+ ];
+
+ for (label, config, plugin_proxy_route, expected) in cases {
+ let layers = config.effective_transport_layers();
+ assert_eq!(ssh_local_port_config_error(&config, &layers, plugin_proxy_route).err(), expected, "{label}");
+ }
+ assert!(kafka_loopback_local_port_error(9093, &[ssh(Some(4059))]).is_some());
+ }
+
+ #[test]
+ fn ssh_local_port_is_rejected_for_exactly_the_connection_types_without_a_static_tunnel() {
+ let layers = [ssh_layer_with_port(Some(4059), "")];
+ let rejected =
+ [DatabaseType::Sqlite, DatabaseType::ClickHouse, DatabaseType::CloudflareD1, DatabaseType::Turso];
+
+ for db_type in DatabaseType::ALL {
+ let result = ssh_local_port_config_error(&config_of_type(*db_type), &layers, None);
+ assert_eq!(result.is_err(), rejected.contains(db_type), "{db_type:?}");
+ }
+ }
+
#[tokio::test]
async fn connection_endpoint_binds_the_fixed_ssh_local_port_only_for_opted_in_primary_tunnels() {
let (state, dir) = test_app_state().await;
@@ -9364,6 +9758,184 @@ mod tests {
let _ = std::fs::remove_dir_all(dir);
}
+ #[tokio::test]
+ async fn connection_endpoint_rejects_a_fixed_ssh_local_port_its_primary_path_cannot_bind() {
+ let (state, dir) = test_app_state().await;
+ let held = std::net::TcpListener::bind(("127.0.0.1", 0)).unwrap();
+ let fixed_port = held.local_addr().unwrap().port();
+ let bind_error = format!("Failed to bind requested local port {fixed_port}");
+ let last = |config: ConnectionConfig| with_layers(config, vec![unreachable_ssh_layer(fixed_port)]);
+ let mut disabled = proxy_layer("proxy-off", "");
+ disabled.enabled = false;
+ let before_the_last_layer = with_layers(
+ config_of_type(DatabaseType::Mysql),
+ vec![
+ TransportLayerConfig::Proxy(disabled),
+ unreachable_ssh_layer(fixed_port),
+ TransportLayerConfig::Proxy(proxy_layer("proxy", "")),
+ ],
+ );
+ let rejected = [
+ (
+ "sqlite",
+ last(config_of_type(DatabaseType::Sqlite)),
+ unsupported_local_port("SQLite", "a remote worker over SSH"),
+ ),
+ (
+ "clickhouse",
+ last(config_of_type(DatabaseType::ClickHouse)),
+ unsupported_local_port("ClickHouse", "a SOCKS5 route"),
+ ),
+ ("turso", last(config_of_type(DatabaseType::Turso)), unsupported_local_port("Turso", "a SOCKS5 route")),
+ (
+ "cloudflare d1",
+ last(config_of_type(DatabaseType::CloudflareD1)),
+ CLOUDFLARE_D1_LOCAL_PORT_ERROR.to_string(),
+ ),
+ (
+ "redis cluster",
+ last(redis_config("cluster")),
+ unsupported_local_port("Redis Cluster", "per-node tunnels"),
+ ),
+ (
+ "redis sentinel",
+ last(redis_config("sentinel")),
+ unsupported_local_port("Redis Sentinel", "per-node tunnels"),
+ ),
+ ("an earlier layer, after a disabled one", before_the_last_layer, non_last_layer_local_port("2")),
+ ];
+
+ // The error describes the config, so it must not depend on the runtime opting in to fixed ports.
+ for honor in [false, true] {
+ state.set_honor_fixed_ssh_local_ports(honor);
+ for (label, config, expected) in rejected.iter().cloned() {
+ let mut draft = config.clone();
+ draft.id = "__production_database_draft_1".to_string();
+ draft.one_time = true;
+ let test_id = format!("{}:test", config.id);
+ for (id, config) in [(config.id.clone(), &config), (test_id, &config), (draft.id.clone(), &draft)] {
+ let error = state.connection_host_port(&id, config).await.unwrap_err();
+ assert_eq!(error, expected, "{label} honor={honor} id={id}");
+ }
+ }
+
+ let supported = last(config_of_type(DatabaseType::Mysql));
+ let primary = state.connection_host_port(&supported.id, &supported).await.unwrap_err();
+ assert!(!primary.contains("Local Port"), "honor={honor}: {primary}");
+ assert_eq!(primary.contains(&bind_error), honor, "honor={honor}: {primary}");
+ let probe = state.connection_host_port("conn:test", &supported).await.unwrap_err();
+ assert!(!probe.contains("Local Port") && !probe.contains(&bind_error), "{probe}");
+ }
+
+ let _ = std::fs::remove_dir_all(dir);
+ }
+
+ #[cfg(feature = "mq-admin")]
+ #[tokio::test]
+ async fn rocketmq_rejects_a_fixed_ssh_local_port_before_opening_any_tunnel() {
+ let (state, dir) = test_app_state().await;
+ let held = std::net::TcpListener::bind(("127.0.0.1", 0)).unwrap();
+ let mut config = message_queue_config("rocketmq");
+ config.id = "fixed-rocketmq".to_string();
+ config.host = "172.19.191.166".to_string();
+ config.port = 9876;
+ config.external_config = Some(serde_json::json!({
+ "systemKind": "rocketmq",
+ "adminUrl": "",
+ "auth": { "kind": "none" },
+ "extra": { "namesrvAddr": "172.19.191.166:9876" }
+ }));
+ config.transport_layers = vec![unreachable_ssh_layer(held.local_addr().unwrap().port())];
+ let expected = unsupported_local_port("RocketMQ", "a SOCKS5 route");
+
+ for honor in [false, true] {
+ state.set_honor_fixed_ssh_local_ports(honor);
+ for id in [config.id.clone(), format!("{}:test", config.id)] {
+ let endpoint = state.connection_host_port(&id, &config).await.unwrap_err();
+ assert_eq!(endpoint, expected, "endpoint honor={honor} id={id}");
+ let admin = state.mq_admin_config_for_connection(&id, &config).await.unwrap_err();
+ assert_eq!(admin, expected, "admin honor={honor} id={id}");
+ }
+ }
+
+ let _ = std::fs::remove_dir_all(dir);
+ }
+
+ #[cfg(unix)]
+ #[tokio::test]
+ async fn plugin_endpoint_rejects_a_fixed_ssh_local_port_only_for_proxy_route_providers() {
+ use std::os::unix::fs::PermissionsExt;
+
+ let dir = tempfile::tempdir().unwrap();
+ let plugins = [
+ ("sample.routed", "Routed Sample", Some("Acme Kafka"), true),
+ ("sample.unlabelled", "Unlabelled Sample", None, true),
+ ("sample.static", "Static Sample", Some("Static Label"), false),
+ ];
+ for (plugin_id, name, provider_label, proxy_route) in plugins {
+ let plugin_dir = dir.path().join("plugins").join(plugin_id);
+ std::fs::create_dir_all(&plugin_dir).unwrap();
+ let script = plugin_dir.join("plugin.sh");
+ std::fs::write(&script, "#!/bin/sh\n").unwrap();
+ std::fs::set_permissions(&script, std::fs::Permissions::from_mode(0o755)).unwrap();
+ let mut provider = serde_json::json!({
+ "type": "connection-provider",
+ "id": "sample.connection",
+ "database_type": "sample",
+ "capabilities": ["connect"],
+ "proxy_route": proxy_route
+ });
+ if let Some(label) = provider_label {
+ provider["label"] = serde_json::json!(label);
+ }
+ std::fs::write(
+ plugin_dir.join("manifest.json"),
+ serde_json::json!({
+ "manifest_version": 1,
+ "id": plugin_id,
+ "name": name,
+ "version": "1.0.0",
+ "publisher": "sample",
+ "engines": { "dbx": ">=0.1.0", "host_api": "^1.0" },
+ "entrypoints": { "backend": {
+ "protocol_versions": [1],
+ "transport": "stdio-jsonl",
+ "executable": "plugin.sh"
+ } },
+ "contributions": [provider]
+ })
+ .to_string(),
+ )
+ .unwrap();
+ }
+ let storage = crate::persistence::test_storage::open(&dir.path().join("storage.db")).await.unwrap();
+ let state = AppState::new_with_plugin_dir(storage, dir.path().join("plugins"));
+ let held = std::net::TcpListener::bind(("127.0.0.1", 0)).unwrap();
+
+ for (plugin_id, expected_label) in [
+ ("sample.routed", Some("Acme Kafka")),
+ ("sample.unlabelled", Some("Unlabelled Sample")),
+ ("sample.static", None),
+ ] {
+ let mut config = config_of_type(DatabaseType::Plugin);
+ config.plugin_id = Some(plugin_id.to_string());
+ config.plugin_connection_provider = Some("sample.connection".to_string());
+ config.plugin_connection_type = Some("sample".to_string());
+ config.transport_layers = vec![unreachable_ssh_layer(held.local_addr().unwrap().port())];
+ let expected = expected_label.map(|label| unsupported_local_port(label, "a SOCKS5 route"));
+ for honor in [false, true] {
+ state.set_honor_fixed_ssh_local_ports(honor);
+ for id in [config.id.clone(), format!("{}:test", config.id)] {
+ let error = state.plugin_connection_endpoint(&id, &config).await.unwrap_err();
+ match &expected {
+ Some(expected) => assert_eq!(&error, expected, "{plugin_id} honor={honor} id={id}"),
+ None => assert!(!error.contains("Local Port"), "{plugin_id} honor={honor} id={id}: {error}"),
+ }
+ }
+ }
+ }
+ }
+
#[test]
fn ssh_tunnel_test_rejects_chain_without_ssh() {
let layers = vec![TransportLayerConfig::Proxy(ProxyTunnelConfig {
diff --git a/crates/dbx-plugin-runtime/src/plugins/host.rs b/crates/dbx-plugin-runtime/src/plugins/host.rs
index c4d9b4ba87..0714d67080 100644
--- a/crates/dbx-plugin-runtime/src/plugins/host.rs
+++ b/crates/dbx-plugin-runtime/src/plugins/host.rs
@@ -362,6 +362,20 @@ impl PluginHost {
Err(_) => false,
}
}
+
+ /// The user-facing label of the connection's provider when it declared
+ /// `proxy_route`, falling back to the plugin name like the other
+ /// user-facing messages. `None` when the provider does not route through
+ /// SOCKS5 or the config does not resolve to a provider.
+ pub fn proxy_route_provider_label(&self, config: &ConnectionConfig) -> Option<String> {
+ let (plugin, provider) = self.resolve_connection_provider(config).ok()?;
+ if !provider.proxy_route {
+ return None;
+ }
+ let label = provider.label.as_deref().unwrap_or(&plugin.manifest.name);
+ Some(label.trim().to_string())
+ }
+
pub async fn test_connection(
&self,
config: &ConnectionConfig,
diff --git a/docs/content/docs/ssh-tunnel.cn.mdx b/docs/content/docs/ssh-tunnel.cn.mdx
index 5cc936339f..4f7215d173 100644
--- a/docs/content/docs/ssh-tunnel.cn.mdx
+++ b/docs/content/docs/ssh-tunnel.cn.mdx
@@ -90,14 +90,14 @@ DBX 会在发送凭据前验证 SSH 主机密钥。已知密钥从系统 `known_
默认情况下,DBX 会为 SSH 隧道选择一个随机的空闲本地端口。在 **本地端口**(1-65535)中填写端口,例如 `4059`,隧道就会监听这个端口。`psql`、脚本等本机其他工具可以通过 `127.0.0.1:4059` 使用同一条隧道。
- 端口只在该连接于 DBX 中保持打开期间被占用,连接关闭后释放;
-- 只有最后一个已启用的层可以使用,并且该层必须是直接配置在连接上的 SSH 层。引用 **设置 → 隧道** 中共享配置的层没有本地端口字段;
+- 只有最后一个已启用的层可以使用,并且该层必须是直接配置在连接上的 SSH 层。引用 **设置 → 隧道** 中共享配置的层没有本地端口字段。在更早的层上设置本地端口会返回错误;
- 如果端口已被占用或无法绑定,连接会失败,并提示你关闭占用端口的程序或换一个端口;
- 连接的 **测试** 按钮、**测试 SSH 隧道**、生产数据库选择器及其他一次性草稿、定时备份,以及独立运行的 stdio MCP 服务或命令行工具使用随机端口,不会和已经打开的连接冲突。只配置了一个 `127.0.0.1` bootstrap 服务器的 Kafka 例外,见下文;
- 解析到多跳 `ProxyJump` 链的 `~/.ssh/config` 主机别名暂不支持固定本地端口,连接时会返回错误。请把跳板机单独添加为第一层,并让最后一层指向目标的真实 `HostName` 或不带 `ProxyJump` 的别名,或者留空本地端口;
- RabbitMQ 的 AMQP 连接使用固定端口,管理 API 隧道仍使用随机端口;
- 只配置了一个 `127.0.0.1` bootstrap 服务器的 Kafka 始终监听该 bootstrap 端口。请留空本地端口,或将其设为该端口;设为其他端口会返回错误;
-- SQLite(经 SSH)、ClickHouse、Turso、RocketMQ、Redis Cluster 和 Redis Sentinel 不支持本地端口,因为它们通过远程 worker、SOCKS5 转发或按节点隧道连接,而不是使用单个本地隧道端口。设置了本地端口时,连接窗口会显示错误;
-- 通过 SOCKS5 转发的插件连接(`proxy_route`)会忽略本地端口;
+- SQLite(经 SSH)、ClickHouse、Turso、RocketMQ、Redis Cluster、Redis Sentinel 和通过 SOCKS5 转发的插件连接(`proxy_route`)不支持本地端口,因为它们通过远程 worker、SOCKS5 转发或按节点隧道连接,而不是使用单个本地隧道端口。设置了本地端口时,连接窗口会显示错误。如果该设置通过其他方式写入,例如导入、云同步或手动编辑的配置,**测试** 和连接会返回错误,而不是忽略它;
+- 连接窗口没有 Cloudflare D1 的隧道设置。导入的 Cloudflare D1 配置如果设置了本地端口,连接时会返回错误;在连接窗口中打开并保存该连接即可移除它的隧道设置;
- Docker/Web 版中,固定端口在服务器或容器内打开,而不是在浏览器所在的电脑上。
<Callout type="warn">启用“允许局域网访问”后,固定端口会监听 `0.0.0.0`,任何能通过该端口访问到你这台机器的设备都可以使用这条隧道。只应在可信网络并配合防火墙使用。</Callout>
diff --git a/docs/content/docs/ssh-tunnel.mdx b/docs/content/docs/ssh-tunnel.mdx
index 66a40f5f80..160aa6d754 100644
--- a/docs/content/docs/ssh-tunnel.mdx
+++ b/docs/content/docs/ssh-tunnel.mdx
@@ -90,14 +90,14 @@ On Desktop, this may make the temporary port reachable through your computer. In
By default, DBX picks a random free local port for the SSH tunnel. Set **Local Port** (1-65535) to make the tunnel listen on a port you choose instead, for example `4059`. Other local tools, such as `psql` or a script, can then connect through the same tunnel at `127.0.0.1:4059`.
- The port is held only while the connection is open in DBX. It is released when the connection is closed.
-- Only the last enabled layer can use it, and only when that layer is an SSH layer configured directly on the connection. A layer that references a shared profile from **Settings → Tunnels** has no Local Port field.
+- Only the last enabled layer can use it, and only when that layer is an SSH layer configured directly on the connection. A layer that references a shared profile from **Settings → Tunnels** has no Local Port field. Setting Local Port on an earlier layer fails with an error.
- If the port is already in use or cannot be bound, connecting fails with a message that asks you to close the other program or choose another port.
- The connection **Test** button, **Test SSH tunnel**, the production-database picker and other one-time drafts, scheduled backups, and a standalone stdio MCP server or the CLI use a random port, so they do not collide with a connection that is already open. Kafka with a single `127.0.0.1` bootstrap server is the exception described below.
- A host alias from `~/.ssh/config` that resolves to a multi-hop `ProxyJump` chain does not support a fixed local port yet, and connecting returns an error. Add the jump host as its own first layer and point the last layer at the target's real `HostName` or at an alias without `ProxyJump`, or leave Local Port empty.
- RabbitMQ uses the fixed port for the AMQP connection. The management API tunnel keeps a random port.
- Kafka with a single `127.0.0.1` bootstrap server always listens on the bootstrap port. Leave Local Port empty or set it to that port; a different port returns an error.
-- Local Port is not supported for SQLite over SSH, ClickHouse, Turso, RocketMQ, Redis Cluster, or Redis Sentinel, because they connect through a remote worker, a SOCKS5 route, or per-node tunnels instead of one local tunnel port. The connection dialog shows an error if it is set.
-- Plugin connections that route through SOCKS5 (`proxy_route`) ignore Local Port.
+- Local Port is not supported for SQLite over SSH, ClickHouse, Turso, RocketMQ, Redis Cluster, Redis Sentinel, or plugin connections that route through SOCKS5 (`proxy_route`), because they connect through a remote worker, a SOCKS5 route, or per-node tunnels instead of one local tunnel port. The connection dialog shows an error if it is set. If the setting arrives some other way, such as an import, cloud sync, or a hand-edited config, **Test** and connecting fail with an error instead of ignoring it.
+- The connection dialog has no tunnel settings for Cloudflare D1. An imported Cloudflare D1 config that has Local Port set fails when connecting; opening the connection in the dialog and saving it removes its tunnel settings.
- In Docker/Web, the fixed port is opened on the server or container, not on the computer running the browser.
<Callout type="warn">With **Expose tunnel to LAN** on, the fixed port listens on `0.0.0.0`, so any device that can reach your machine on that port can use the tunnel. Use it only on trusted networks with appropriate firewall rules.</Callout>