5109227欢迎您-《BM093项目接入指南》-海界

5109227欢迎您-《BM093项目接入指南》

1. 目的本文档用于说明 BM093 项目如何接入公司网关，并给出从权限申请、凭证获取、kubeconfig 配置到连接验证的完整操作流程。适用于新成员首次接入项目环境、已有成员更换设备后重新配置环...

1. 目的

本文档用于说明 BM093 项目如何接入公司网关，并给出从权限申请、凭证获取、kubeconfig 配置到连接验证的完整操作流程。适用于新成员首次接入项目环境、已有成员更换设备后重新配置环境，以及部署脚本执行前的自检。

BM093 项目依赖公司统一网关访问内部集群和认证服务。为了避免因网络、DNS、凭证或 kubeconfig 配置不一致导致部署失败，接入前应先完成本文档中的前置检查。

2. 接入流程

整体流程如下：

申请网关接入权限；
获取接入凭证（AK/SK）；
配置本地 kubeconfig；
验证 VPN、DNS 与网关连通性；
执行部署脚本并确认认证结果。

2.1 申请网关接入权限

新成员入职后，需要先在权限平台申请 BM093 项目的公司网关接入权限。申请时建议填写项目名称、使用场景、目标环境和有效期，避免只写“开发需要”导致审批信息不完整。

项目名称：BM093；
接入类型：公司网关 / Kubernetes 集群访问；
使用场景：本地开发、联调、部署验证；
目标环境：按实际需要选择 dev、test、prod；
审批人：项目负责人或对应环境 owner。

权限审批通过后，再继续获取 AK/SK 或其他接入凭证。如果权限未审批完成，即使 kubeconfig 文件格式正确，也可能在认证阶段返回 401 Unauthorized。

2.2 获取接入凭证（AK/SK）

权限通过后，在凭证平台生成或领取 BM093 对应环境的 AK/SK。请注意区分不同环境的凭证，不要把测试环境凭证配置到生产网关，也不要把生产凭证放到公共目录。

建议将凭证写入本机受保护的配置文件或系统凭证管理器，不要提交到 Git 仓库，不要贴到群聊，也不要写进截图。

BM093_ACCESS_KEY=***
BM093_SECRET_KEY=******

2.3 配置 kubeconfig

下载项目提供的 kubeconfig 模板后，重点确认以下字段：

clusters[].cluster.server：应指向 BM093 当前环境的公司网关地址；
certificate-authority-data 或 CA 文件路径：应与公司网关证书链匹配；
users[].user：应使用已审批通过的认证方式；
contexts[].context.cluster 与 contexts[].context.user：应引用同一套环境配置。

配置完成后，可以先查看当前上下文：

kubectl config current-context
kubectl config view --minify

3. 终端报错示例

以下为图片中终端日志识别后的文本内容。排查时请优先关注 UnknownHostException，它说明当前环境无法解析内部网关或认证服务域名。

[w5109227@dev-cn-bja-0385 ~]$ ./deploy.sh
[INFO] Start to deploy ...
[ERROR] Failed to connect to gateway service.
java.net.UnknownHostException: xxx-gateway.internal.xxcorp.net
        at java.base/sun.nio.ch.NioSocketImpl.connect(NioSocketImpl.java:572)
        at java.base/java.net.SocksSocketImpl.connect(SocksSocketImpl.java:327)
        at java.base/java.net.Socket.connect(Socket.java:633)
        at java.base/sun.security.ssl.SSLSocketImpl.connect(SSLSocketImpl.java:304)
        at java.base/sun.security.ssl.BaseSSLSocketImpl.connect(BaseSSLSocketImpl.java:173)
        at java.base/sun.net.NetworkClient.doConnect(NetworkClient.java:183)
        at java.base/sun.net.www.http.HttpClient.openServer(HttpClient.java:531)
        at java.base/sun.net.www.http.HttpClient.openServer(HttpClient.java:636)
        at java.base/sun.net.www.protocol.https.HttpsClient.<init>(HttpsClient.java:264)
        at java.base/sun.net.www.protocol.https.HttpsClient.New(HttpsClient.java:377)
        at java.base/sun.net.www.protocol.https.AbstractDelegateHttpsURLConnection.getNewHttpClient(AbstractDelegateHttpsURLConnection.java:193)
        at java.base/sun.net.www.protocol.http.HttpURLConnection.plainConnect0(HttpURLConnection.java:1237)
        at java.base/sun.net.www.protocol.http.HttpURLConnection.plainConnect(HttpURLConnection.java:1123)
        at java.base/sun.net.www.protocol.https.AbstractDelegateHttpsURLConnection.connect(AbstractDelegateHttpsURLConnection.java:179)
        at java.base/sun.net.www.protocol.http.HttpURLConnection.getInputStream0(HttpURLConnection.java:1665)
        at java.base/sun.net.www.protocol.http.HttpURLConnection.getInputStream(HttpURLConnection.java:1589)
        at java.base/sun.net.www.protocol.https.HttpsURLConnectionImpl.getInputStream(HttpsURLConnectionImpl.java:223)
        ... 23 more
[INFO] Try to authenticate ...
[ERROR] Authentication failed.
com.xxcorp.auth.client.AuthException: 401 Unauthorized
        at com.xxcorp.auth.client.AuthClient.login(AuthClient.java:88)
        at com.xxcorp.deploy.DeployService.init(DeployService.java:132)
        at com.xxcorp.deploy.DeployService.main(DeployService.java:48)
Caused by: java.net.UnknownHostException: auth-svc.prod.xxcorp.net
        at java.base/sun.nio.ch.NioSocketImpl.connect(NioSocketImpl.java:572)
        ... 28 more

[w5109227@dev-cn-bja-0385 ~]$

4. 部署前网络自检

如果本地执行 ./deploy.sh 出现连接失败，首先不要急着重装证书。应先确认 VPN、DNS 和网关端口是否正常。

4.1 确认 VPN 状态

办公 VPN 需要处于已连接状态，并且账号应为当前申请权限的公司账号。VPN 显示已连接，只代表隧道建立成功，不代表内部域名一定能被终端或 Java 进程解析。

4.2 验证内部域名解析

在 Windows PowerShell 或 Git Bash 中执行：

nslookup xxx-gateway.internal.xxcorp.net
nslookup auth-svc.prod.xxcorp.net

如果返回 Non-existent domain、超时，或直接无法解析，说明问题优先在 DNS/VPN/网络策略，而不是 kubeconfig 文件本身。

4.3 验证端口连通性

域名能解析后，再检查 443 端口：

Test-NetConnection xxx-gateway.internal.xxcorp.net -Port 443
Test-NetConnection auth-svc.prod.xxcorp.net -Port 443

如果 DNS 正常但端口不通，需要确认 VPN 路由、网络权限、防火墙策略或当前账号是否具备访问对应环境的网络权限。

5. 常见问题处理

5.1 java.net.UnknownHostException

示例报错：

[ERROR] Failed to connect to gateway service.
java.net.UnknownHostException: xxx-gateway.internal.xxcorp.net

该错误表示当前 Java 进程无法解析内部网关域名。此时请求还没有真正到达网关，也没有进入证书校验或权限判断阶段。优先处理 DNS、VPN 和网络路由。

5.2 401 Unauthorized

示例报错：

[ERROR] Authentication failed.
com.xxcorp.auth.client.AuthException: 401 Unauthorized

如果同时伴随 UnknownHostException，应先解决域名解析问题。只有在网关和认证服务都能解析、端口也能连通的情况下，401 才更可能是 AK/SK 错误、权限未审批、token 过期或账号未加入项目权限组。

5.3 VPN 已连接但仍然访问失败

常见原因包括：

VPN 虚拟网卡未正确下发公司 DNS；
浏览器可以通过代理访问 wiki，但终端没有走同一套代理；
Git Bash、IDE 终端、Java 进程继承的网络环境不一致；
split DNS 或 split tunnel 未覆盖 BM093 网关域名；
本机安全客户端策略未完成设备合规检查。

6. 执行部署脚本

完成权限、凭证、kubeconfig 和网络自检后，再执行部署脚本：

./deploy.sh

正常情况下，脚本应完成网关连接、认证初始化和部署动作。如果失败，请优先保留完整终端日志，并按以下顺序定位：

是否能解析网关域名；
是否能访问认证服务域名；
443 端口是否连通；
kubeconfig server 是否与当前环境一致；
AK/SK 是否正确、未过期；
账号是否已具备 BM093 项目权限。

7. 注意事项

不要将 AK/SK、token、kubeconfig 明文提交到代码仓库；
不要在公开截图中暴露真实域名、账号、项目凭证；
生产环境凭证应单独申请、单独管理，不要与测试环境混用；
更换电脑、重装系统、切换 VPN 客户端后，需要重新做 DNS 与端口自检；
遇到 UnknownHostException，优先查 DNS；遇到 SSLHandshakeException，再重点查证书链。

8. 结论

BM093 项目接入公司网关的关键，不只是拿到 kubeconfig 文件，而是要保证权限、凭证、DNS、VPN、网关地址和本地执行环境全部一致。部署失败时，应按照“网络解析 → 端口连通 → kubeconfig → 凭证权限”的顺序排查。

如果出现“VPN 已连接但 kubeconfig 仍然连不上”的情况，先用 nslookup 和 Test-NetConnection 验证基础链路。基础链路不通，继续修改 kubeconfig 或重装证书通常都解决不了问题。

显示评论 (0)

文章评论

取消回复

要发表评论，您必须先登录。