LinkPort/docs/connection-editor.md

连接配置页签与 URL

目标的新建、编辑子页面提供“连接信息、TLS/SSL、连接方式、高级、账号”页签。新建入口已经固定资源类别：从“目标服务”进入只会新建目标，从“网关服务”进入只会新建网关，表单不再显示“资源类别”下拉。两类新建页均把“服务类型”作为第一个配置字段，便于先确定协议再填写后续参数；编辑已有服务时协议保持锁定。SSH/SFTP 使用自身的加密传输，不显示 TLS/SSL 页。页签切换保留未保存字段及尚未解析的 URL；保存和测试连接使用所有页签中的当前配置。网关仍使用“网关与访问、账号”分组。

• 连接信息：服务类型（首项）、完整 URL 导入、独立 URL 参数、名称、颜色/备注、主机、端口、数据库和集群配置。
• TLS/SSL：上游 TLS 与 CA 证书资产，开启时验证证书与主机名。
• 连接方式：直接连接，或按类型引用 Kubeconfig/SSH/SOCKS5/sing-box 网络代理。代理凭据与固定 Kubernetes 资源在「代理管理」维护，文件在使用处上传或选择。
• 高级：有实际运行支持的超时/保活、项目、环境、目标分组、MySQL/MongoDB 压缩，以及 SSH 主机指纹校验设置。
• 账号：目标账号通过下拉框切换，一次编辑一个账号；“添加账号”自动选中新账号，切换保留草稿，删除后选择剩余账号。保存时会自动切换到存在校验错误的账号。认证方式和凭据资产配置继续保留，网关只读权限仍在网关配置中维护。

连接与网关的标识各自保存。目标连接选项由引用它的网关继承，包括账号独立目标映射；网关不能直接覆盖目标的 connectionOptions。

目标连接方式的独立页签

当前入口为「代理管理」：Kubeconfig、SSH、SOCKS5、sing-box 独立保存后供目标和 TCP 网关引用。「SSH 隧道/代理」页签更名为「连接方式」。旧内联 K8s 配置继续兼容，具体见 网络代理管理。

选择 Kubernetes 固定资源（包括 StatefulSet，兼容旧 K8s 引用）后，未启用 TLS 的目标不再显示主机/IP 输入，用户维护资源与服务端口即可。保存和草稿测试均允许地址为空，后端以资源名称补全协议内部地址；实际 Pod 由 Kubernetes 查询确定，不使用这个名称解析 Pod IP。已有地址保留，切回直连后可继续编辑。启用 TLS（或 HTTPS）时显示「证书校验域名」并要求填写匹配证书的域名，不取消证书校验。

新建或编辑目标服务时，在独立的「连接方式」页签直接选择类型，再选择已保存的代理；直连有独立选项。「连接信息」页不重复展示连接方式。页签切换保留草稿，测试与保存使用相同配置。新引用只提交 outboundId，不复制代理凭据。旧内联 Kubernetes 配置仅在编辑原记录时保留 outbound 和 kubeConfigAssetId。

代理选择器按选中类型列出全部范围的配置，不受目标或工作区项目、环境筛选影响。切换页签或修改目标归属不会清空已有引用；切换代理类型则清空旧引用，必须重新选择才能保存。已有引用不在列表时明确显示不可用，不静默退回直连。Kubeconfig 与其他类型一样可新建和复用。

MongoDB 使用 Kubernetes 固定资源时，部署模式须选择「单节点」，不启用副本集自动发现，也不会自动识别主节点；这不要求真实 MongoDB 是独立实例。本次不批量迁移既有资产或引用，兼容与本轮验证边界见 统一资产与目标连接。

sing-box 编辑器使用密码型输入保存一个单 outbound JSON；不解析 URI，也不允许填写 binary 路径。原始输入应用后立即清空，已保存正文不回填，只显示协议摘要。64 KiB、宿主能力限制、LINKPORT_SING_BOX/PATH 查找和“检查配置”与目标真实连接的边界见 sing-box 连接资产。

独立 URL 参数与提交一致性

完整 URL 下方提供独立“URL 参数”输入区，示例为 MySQL charset=utf8mb4&tls=true、PostgreSQL application_name=linkport&sslmode=verify-full。参数区使用与完整 URL 一致的协议白名单，把值规范化到已有字段及 connectionOptions，不保存任意驱动参数字符串，也不透传未支持选项。

• 点击“应用参数”后同步表单；测试和保存也会先应用待处理输入。显式参数覆盖对应字段，缺省的数据库、TLS、认证来源、压缩或集群参数保持表单当前值；删除 charset / application_name 则恢复协议默认值。参数应用后可继续在其他页签修改字段，回读文本由当前结构化字段生成。
• 重复参数（包含大小写变体）、冲突同义参数、非法编码和未支持项统一报错；解析失败不部分修改配置，不发送测试或保存请求。百分号编码用于特殊字符；允许的空值遵循协议语义，例如 MySQL database= 清除默认库、MongoDB compressors= 关闭压缩，charset= 无效。
• 独立参数区拒绝 user / username / password；凭据只从完整 URL 导入或在账号页编辑。完整 URL 和参数区同时有待应用修改时，要求先手动应用其中一项并核对，避免两个输入源静默覆盖。
• 完整 URL 显示“待解析 / 已填入 / 解析错误”；测试/保存前自动解析仍未应用的 URL，不再使用旧主机或旧凭据。成功解析后清空原始 URL，关闭或切换工作区前仍有未保存确认。
• 切换协议清空协议相关参数及待处理输入，保留名称、范围、出口和颜色/备注。所有原始 URL、未处理参数和草稿只放内存，不写入浏览器偏好。

URL 支持范围

填写 URL 后可点击“解析并填入配置”，也可直接测试或保存，由统一提交准备流程解析。输入默认隐藏；只保存解析后的配置和按现有方式加密的凭据。部署模式手动选择，不提供自动识别模式；MongoDB 完整 URL 未包含 replicaSet 或 directConnection=true 时，需手动选择模式后再保存或测试。独立参数未修改集群项时保留原部署模式。

服务	URL 示例	支持的查询参数
MySQL	mysql://user:password@host:3306/app?charset=utf8mb4	database、tls、ssl、charset（utf8mb4 / utf8 / latin1 / ascii）
Redis	redis://:password@host:6379/3 或 rediss://user:password@host/0	database、db、tls、ssl
PostgreSQL	postgresql://user:password@host/app?sslmode=verify-full	database、tls、ssl、sslmode、application_name（1–63 个 UTF-8 字节）
SQL Server	sqlserver://user:password@host?database=master&encrypt=true	database、tls、ssl、encrypt
RabbitMQ	amqps://user:password@host/%2F	vhost、tls、ssl
SSH/SFTP	ssh://user:password@host:22、sftp://user:password@host:22	无协议专用参数
HTTP/HTTPS	https://user:password@host:443	无协议专用参数；只支持上游主机，不支持请求路径
MongoDB	mongodb://user:password@host-a,host-b/app?replicaSet=rs0&authSource=admin	见 数据库集群

除 MongoDB 沿用其专用解析器外，各协议还支持 user/username、password 查询参数。PostgreSQL 同时接受 postgres，SQL Server 同时接受 mssql。协议必须匹配当前服务类型；IPv6 使用方括号，特殊字符使用百分号编码。布尔值必须为 true 或 false。PostgreSQL sslmode 仅支持 disable 和 verify-full，其他模式无法准确映射到当前 TLS 校验行为。安全协议不可再指定关闭 TLS。

没有凭据时保留已有账号；包含凭据时更新选中的账号，多账号可明确选择写入对象。编辑已保存账号时，空密码沿用现有的“保留已存密码”规则；要更换密码请提供新密码。Redis 仅密码认证使用 default 用户名。导入 SSH 密码凭据会把选中账号切换为密码认证。非 MongoDB URL 按单节点配置导入；集群及其他节点可随后在表单中配置。

MySQL 的默认数据库用于测试连接和客户端未指定数据库的新连接；客户端指定数据库优先。Redis 在认证成功后发送 SELECT，服务端拒绝时连接失败，空值/0 保持默认库；Redis Cluster 仅支持 0。PostgreSQL、SQL Server 继续使用现有 authSource 字段保存默认库；RabbitMQ 的 vhost 用于连接测试，网关客户端仍自行指定 vhost。

MySQL charset 映射为上游握手的 utf8mb4_general_ci / utf8_general_ci / latin1_swedish_ci / ascii_general_ci；空设置沿用原来的 utf8mb4。PostgreSQL application_name 进入上游启动参数，缺省为 linkport。客户端后续会话语句仍可能修改这些设置，它们不是权限策略。

高级选项能力矩阵

所有数值单位为秒，仅作用于当前目标；没有虚构的全局选项来源。没有实际支持的控件明确禁用，后端同样拒绝不适用于该协议的非默认值。

配置字段	支持范围	边界与实际语义
connectTimeoutSeconds	全部目标协议及出口	0–120；0 沿用默认。设置直连、SOCKS5、SSH 转发及 K8s 建链上下文期限；默认普通拨号 5 秒、K8s 30 秒。MySQL/MongoDB 上游握手及 PostgreSQL 连接配置也使用此覆盖值；其他协议认证阶段保留原有限制。不是整个会话总时限，也不延长外层测试接口或调用方更短的期限。
queryTimeoutSeconds	仅 PostgreSQL	0–86400；非零作为新上游会话 statement_timeout（转换为毫秒）。0 不覆盖服务端默认。由 PostgreSQL 执行查询超时，客户端仍可调整；没有把原始套接字读超时冒充多协议查询超时。
idleTimeoutSeconds	仅 MongoDB 网关会话	0–86400；0 关闭。在认证后等待下一条完整请求时设置下游读期限，收到请求后立即清除，不中断正在执行的查询。不是连接池回收，也不是目标测试的空闲设置。
keepAliveSeconds	全部目标协议的直连 / SOCKS5 / SSH 底层 TCP	缺省/null 使用 Go / 系统默认，0 禁用，1–3600 为覆盖值；“使用默认”会明确保存为 null，不保留之前的覆盖。Kubernetes port-forward 不支持，必须使用默认。不是数据库心跳、SSH 应用层探测或会话有效性保证。
persistent	全部目标协议；单节点 MySQL/MongoDB/PostgreSQL/Redis 使用备用会话，SSH/K8s 使用共享隧道，其余使用后台探测	布尔值；11 种类型的新建界面草稿默认 true，旧目标沿用保存值。关联运行网关时无客户端也预建或探测、心跳及重连；会话借出后不回收，停服释放。明确认证/身份拒绝暂停重试。集群不预认证，原 K8s 固定资源限制保持。详见 persistent-targets.md。

旧配置省略 connectionOptions 时不改变连接行为。高级页清空数值恢复默认语义；编辑已保存目标或网关时协议保持锁定。运行中保存的新值只影响随后建立的连接，已有连接保持接受时的快照。若运行配置已被其他操作更新，保存返回 409，刷新后再编辑。

连接标识与测试反馈

• 目标和网关各有 color（空或六位十六进制色）、remark（不含 NUL、最多 2000 个 UTF-8 字节；UI 限制为 600 个字符）及 showRemark。提供预设色、自定义选色和清除；旧配置缺省为空且不显示备注。
• 名称旁显示颜色点，目标卡片、网关桌面/手机列表、资源树和最近访问按开关展示备注。搜索只显示名称及颜色，不检索备注；连接色不替代运行状态色。文件资产备注继续使用原有字段，不与目标/网关混用。备注不应填写凭据。
• 编辑器底部保留草稿测试账号选择和加载状态，完成后内联显示成功/失败、协议、TLS 和耗时；仍可打开完整结果。修改配置、账号或待处理 URL/参数后标记“需重新测试”。关闭编辑器后的迟到结果不会回填到其他编辑器。
• “复制脱敏诊断”仅包含协议、成功标志、耗时、TLS、是否过期及草稿范围；不复制名称、目标地址、账号、原始错误、服务器自由文本、URL、密码、私钥或资产正文。完整结果在连接测试子页面展示，不写入偏好。

兼容和验证

沿用 MySQL/Redis 的 database，新增目标的可选 connectionOptions 及目标/网关的标识字段。通过已有加密配置、配置历史、备份/恢复和多端同步保存，无 SQLite 表结构迁移。网关运行快照继承关联目标选项，但网关记录只保存自身标识与目标引用，不复制上游配置；目标标识不会覆盖网关标识。

结构化 PATCH 仍拒绝未知字段与普通字段的 null；新增可空指针选项允许 keepAliveSeconds:null 恢复默认，其他字段的空值规则没有放开。使用新字段前应升级参与同步的所有客户端，旧版本不能保证保留其不认识的配置字段。

2026-09-20 实测：Go 1.25.0 全部后端测试及 vet 通过，前端全量类型检查通过，7 项前端纯逻辑测试函数在单进程执行通过。新增 fixture 验证 MySQL 握手字符集字节、PostgreSQL 启动参数、MongoDB 空闲关闭但不中断执行中请求；API 与 store 测试验证草稿、保存回读、清除保活、元数据隔离、加密备份恢复和同步快照替换。上述协议验证均为本地 fixture，不是实际数据库服务器验收。

已补充浏览器用例，但当前 Vite/esbuild 与 Playwright worker 均遇到 spawn EPERM，生产构建、全套浏览器执行和截图尚未完成，也没有使用旧二进制替代。完整结果见 变更原因 与 工作区交互。