QoderWake内网穿透实战：让公司外的数字员工也能访问局域网数据

先说几个核心判断：公司外的数字员工想要直接访问内网数据库、Confluence知识库，或者调用本地部署的ERP接口，基本是不可能的——因为这些服务监听在127.0.0.1:3306、192.168.10.5:8090这类地址上，公网根本够不着。这时候，内网穿透就是绕不过去的基础设施。它能建立起一条稳定、可鉴权、低延迟的双向通信链路，让外部的数字员工像在内网一样发起请求。

接下来，我们从几个关键环节入手，把QoderWake的内网穿透能力彻底跑通。

确认QoderWake是否启用内网穿透模式

从v26.4.0开始，QoderWake原生支持内网穿透通道，但默认是不开的。这个功能与Harness-First架构深度绑定，只有当Session账本存储指向内网PostgreSQL，并且Critic-Refiner机制启用时，穿透能力才会被激活。

可以直接跑一下qodercli system status --verbose，注意看输出里有没有tunnel_mode: enabled和tunnel_endpoint: wss://tunnel.qoder.ai/v26这两行。如果显示的是disabled，那就得先编辑/opt/qoder/core/config/harness.yaml，把tunnel_enabled改成true，然后执行./restart-harness.sh重载框架。

这一步不能跳过。没开启穿透模式的QoderWake，会直接拒绝所有来自tunnel.qoder.ai域名的WebSocket握手请求，返回403错误。

配置穿透隧道客户端（Tunnel Agent）

内网穿透依赖一个独立运行的Tunnel Agent进程。它会驻留在内网服务器上，主动连接QoderWake的云中控节点，反向建立加密信道。Agent本身不暴露任何端口，因此能轻松绕过防火墙的限制。

方法一：使用最新CLI一键部署

在内网服务器直接执行：qodercli tunnel install --region cn-shanghai --license-file /opt/qoder/license.lic。这条命令会自动下载qoder-tunnel-agent-v26.4.0-linux-amd64二进制文件，放到/usr/local/bin/，并注册为systemd服务qoder-tunnel.service。整个过程基本是傻瓜式的。

方法二：手动部署（适用于无root权限环境）

从https://tunnel.qoder.ai/download/qoder-tunnel-agent-v26.4.0-linux-amd64下载二进制，赋予执行权限chmod +x qoder-tunnel-agent，然后运行：./qoder-tunnel-agent --license /home/user/qoder/license.lic --endpoint wss://tunnel.qoder.ai/v26 --bind 127.0.0.1:3306,192.168.10.5:8090。这里有一个重要细节：--bind参数必须显式列出所有需要穿透的IP:PORT对，不能偷懒写成0.0.0.0:*。

在QoderWake中声明穿透资源别名

数字员工没法直接拿原始内网地址来用，必须通过逻辑别名来调用。这是权限沙盒的强制要求：所有穿透资源都得经过QoderWake路由层做统一鉴权和审计。

第一步：登录QoderWake企业控制台，进入【集成中心】→【内网穿透管理】。

第二步：点击【新增穿透资源】，填写以下字段：

• 别名：erp-db-primary（只能用英文小写、数字和短横线，长度不超过32）
• 协议：mysql（支持mysql、postgres、http、https）
• 目标地址：127.0.0.1:3306（必须和Tunnel Agent中--bind的值严格一致）

第三步：勾选「启用连接池」，把最大连接数设成50，点击【保存】。

保存之后，系统会生成一个唯一的tunnel_id，看起来像tun-7a2f9c1e。这个ID在后面数字员工的技能配置里会用到。

数字员工调用穿透资源的正确写法

在数字员工的技能脚本（比如Python技能）里，一定不能硬编码127.0.0.1:3306或192.168.10.5:8090，必须使用QoderWake注入的环境变量或SDK封装调用。

方法一：通过环境变量注入（推荐用于SQL类连接）

在技能配置的env区块里加上：DB_URL: "mysql://user:pass@${TUNNEL_erp_db_primary}/app"。运行时，QoderWake会自动把${TUNNEL_erp_db_primary}替换成实际的穿透地址，格式是tun-7a2f9c1e.tunnel.qoder.ai:443。

方法二：调用Qoder SDK（推荐用于HTTP请求）

在Python技能里导入from qoder.tunnel import TunnelClient，然后执行：client = TunnelClient("confluence-kb") → resp = client.get("/rest/api/space")。SDK会自动处理TLS握手、JWT令牌续期和断线重连，省去不少麻烦。

这一步操作起来很简单，把环境变量名写对就行。但有一点需要特别注意：如果写成了${TUNNEL_ERP_DB_PRIMARY}（下划线误作大写），QoderWake是解析不了的，连接时会抛出Connection refused——不是DNS错误，排查起来相当麻烦。

验证穿透链路是否生效

① 在QoderWake控制台的【内网穿透管理】页面，找到刚才创建的erp-db-primary资源，状态栏应该显示Connected (2m17s)，括号里表示持续在线时长。

② 在数字员工技能里插入一条调试语句：qodercli tunnel ping --alias erp-db-primary。如果终端输出✅ Latency: 42ms | TLS: active | Auth: valid，就说明端到端通路是正常的。

③ 最后执行一次真实查询：qodercli tunnel exec --alias erp-db-primary --query "SELECT VERSION()"。如果能返回MySQL版本字符串，那就彻底验证成功了。