8.1 KiB
Kubernetes port-forward
linkport 内置 Kubernetes 客户端，不需要安装 kubectl。在「代理管理 → 新建代理」选择 Kubeconfig，选择或上传配置，确定 Context、命名空间和 StatefulSet/Pod/Service/Deployment。保存后，目标或 TCP 纯端口转发网关可像选择 SSH、SOCKS5 一样引用该代理。代理拥有固定资源，服务拥有目的端口；非 TLS 目标无需维护 IP，TLS 目标仍需证书域名。旧内联配置与旧代理 ID 继续兼容，详见 网络代理管理。
下拉中找不到 Kubeconfig
- 只有资产类型为
Kubeconfig的文件可以选择；把 YAML 上传为“其他配置文件”不会自动变成 Kubeconfig。没有此类型资产时，界面显示明确提示，可点击「上传 Kubeconfig」就地上传。 - 资产是全局资源，不按项目分类；Kubeconfig 选择器直接列出全部 Kubeconfig，不受目标的项目或环境影响，无需展开其他范围。SSH/SOCKS5 与 Kubeconfig 在代理管理中独立创建，项目编辑入口仍不展示。
- 在别的页面上传资产后，可点击「刷新 Kubeconfig 列表」重新获取选项。刷新失败显示错误并允许重试，不清空已有选择；非 Kubeconfig 文件仍不会混入。
- SSH 私钥和 CA 等其他资产选择器同样按类型全局列出，不会因为切换项目丢失已选引用。
配置
| 字段 | 含义 |
|---|---|
| Kubeconfig 配置 | 在代理中选择或上传的凭据文件，用于查询和选择资源。旧版保存的默认配置或路径仍可用于连接，界面重新查询时需要选择资产 |
| Context | kubeconfig 中的 context 名称；留空使用当前 context |
| 命名空间 | 选择资产或切换 Context 后自动查询，从下拉框选择；初始使用 context 的命名空间或 default，查询失败可重试 |
| Kubernetes 资源 | pod/mysql-0、service/mysql、deployment/mysql 或 statefulset/mongo |
| 本机监听端口 | 自动模式在 49152–65535 分配；固定模式填写 1024–65535，仅监听 linkport 所在机器的 127.0.0.1，不是数据库目标端口或网关对外端口 |
| 目标端口 | Pod/Deployment/StatefulSet 使用容器 TCP 端口；Service 使用 Service 的 port，自动解析数字或命名 targetPort |
| 目标主机 | 保留数据库 TLS 的证书主机名；实际连接通过 Kubernetes API 转发，不在本机解析该主机 |
例如 MySQL Service 在 database 命名空间暴露 3306：从命名空间下拉框选择 database，查询并选择 service/mysql，目标端口填 3306；TLS 开启时目标主机须匹配数据库证书，例如 mysql.database.svc。数据库账号密码仍填目标服务自己的凭据，客户端使用网关账号。
MongoDB 同样引用已保存的 K8s 代理：例如代理选择 pod/mongo-0，Mongo 目标主机填写用于 TLS 校验的服务域名，端口填写 27017，新建目标时在「连接方式」中选择 Kubeconfig 类型后选择该代理。代理属于其他项目/环境时也默认可选，无需展开范围。部署模式选择「单节点」，表示固定连接 port-forward 选中的节点，不要求 MongoDB 实际是独立部署；固定资源出口不支持副本集自动发现或多节点故障切换。需要写入时应选择已确认可写的成员或合适的 Service；仅按 StatefulSet 选择 Pod 不会识别 Mongo 主节点。
资产支持最大 512 KiB 的 UTF-8 YAML/JSON 文件，内容加密保存在 SQLite。资产列表与日常配置查询接口不返回文件内容；模板和历史差异隐藏内容。「导出配置」以口令加密保存全部资产的原始文件、文件名及引用，导入后可一并恢复，详见 配置备份。上传/内联 Kubeconfig 必须使用内嵌证书、私钥和 Token，不接受外部文件引用、exec 或 auth-provider 登录插件；需要云厂商登录插件时只能使用管理员显式配置的本地 Kubeconfig 路径，并确保命令与文件由可信部署方维护。
凭据或证书失效后，在「资产管理」编辑同一资产、重新上传并保存即可。未上传新文件时保留原文件，取消本次上传不会替换已存内容。更新前须停止使用该资产的网关；更新后引用它的代理在后续连接中使用新内容，无需逐个上传。仍被代理引用的资产不能删除，须先解除引用。更新资产可能改变 SSH 目标身份，原已确认主机指纹会清除，需要重新探测确认。
权限与连接
集群 API 必须可从 linkport 所在机器访问。凭据需要所选资源的读取权限、Service/Deployment/StatefulSet 对应 Pod 的列表权限，以及 pods/portforward 的创建权限。Service 必须有 Pod selector，选出的 Pod 必须处于 Running 状态且未被删除，优先选择 Ready Pod。
例如 MongoDB StatefulSet：从下拉框选择实际部署的命名空间，查询后选择 statefulset/mongo，目标端口填 27017。需要 apps API 组下 statefulsets 的 get 和 list 权限。按 StatefulSet 选择 Pod 不会识别 MongoDB 主节点；如需固定成员，可在查询结果中选择 pod/mongo-0。切换资产、Context 或命名空间后需重新查询和选择；编辑已有配置时可以看到已保存的资源，未查询验证时会明确标注。
默认本机监听端口为自动高位端口，绑定冲突时最多尝试 32 个端口；只有绑定失败重试，不重试认证或 API 错误。页面「代理管理 → Kubeconfig → 本机监听端口」可切换固定端口，固定端口占用或绑定被拒绝时明确报错，不自动换端口。API 字段为 outbound.localPort，省略或 0 为自动模式，无存储迁移。
普通上游连接拥有独立 port-forward 通道；开启持久连接后，同一运行时隧道可复用本机监听端口。固定端口不能同时用于多个独立隧道，多个目标、网关或并发非持久连接共享相同配置时可能冲突，应使用自动模式或不同端口。连接关闭、网关停止或建连失败时清理通道和监听端口，不回退直连。建立成功的数据库会话不受建连超时影响。Pod 重启或网络中断后，原会话断开；客户端重连时重新选择 Pod，不自动重放 SQL 或消息。
error creating error stream ... Timeout occurred 属于 Kubernetes SPDY 流建立超时；使用高位或固定端口不保证修复此问题，还需检查 API 流式升级、集群网络和长连接状态。
当前使用 Kubernetes SPDY port-forward 协议，仅支持 TCP，要求 linkport 直接访问集群 API；暂不支持 kubeconfig 的 proxy-url 或匹配 API 地址的 HTTP(S) 代理环境变量，配置这些代理时明确返回失败。集群 API 自身的反向代理需要允许流式连接升级。普通 kubeconfig 证书、Token 认证无需 kubectl；特定云平台认证和真实集群兼容性需在实际环境验证。
本轮验证
2026-10-02：Go 1.27.1 model/outbound 专项和 vet 通过，SPDY fixture 验证自动高位范围、固定端口通信、占用拒绝与关闭释放；前端类型检查、生产构建和新嵌入程序构建通过。隔离 Playwright 端口专项通过，保存/编辑回读 55032 并检查 390px 布局与截图；同文件资产重传用例在搜索框处超时。全量后端仍存在此前 API、cluster、desktop、syncjob 失败，详见 变更记录。未连接真实 Kubernetes 集群，未部署到真实服务。
2026-09-21：前端类型检查、生产构建与 7 项隔离浏览器回归通过，覆盖跨范围 Kubeconfig 选择、普通文件排除、代理保存、Mongo 目标引用与回读、刷新失败重试、390px 小屏，以及原有资产更新、项目筛选和就地上传。Go 1.25.0 全量测试和 vet 串行复跑通过；全量浏览器检查为 79 通过、3 项已记录失败、8 未运行，详情见 测试记录。Kubernetes 命名空间/资源查询使用模拟响应，资产及配置保存使用真实隔离 API；没有连接真实 MongoDB 或 Kubernetes 集群，不作为真实 port-forward 连通性验收。