一、常见现象
·Instance 可以启动，但访问公网 API、私网数据库或内网域名超时或被拒绝。
·通过接入域名访问业务端口时返回 404、502，或连接始终无法建立。
·创建或更新 Tool 时直接返回 InvalidParameterValue.NetworkMode、MissingParameter.VPCParameters、InvalidParameterValue.SandboxTool 或 UnsupportedOperation.SandboxTool。
·排查内网域名时，如果解析结果落在 169.254.x.x 网段，请先结合完整域名和使用环境确认，不要仅凭 IP 网段判断为解析异常。AGS 的部分平台服务使用 169.254.x.x 地址提供内部访问，因此这类解析结果并不一定表示故障。
二、排查前准备
先确认当前 CLI 是否已配置云 API 凭证：
agr status -o json –non-interactive
重点关注 Data.Auth.SecretId.Present 和 Data.Auth.SecretKey.Present 是否都为 true。
如果需要先定位对象，再执行诊断查询：
agr tool list -o json –non-interactive –jq '.Data.Items[] | {ToolId, ToolName, NetworkConfiguration, Status}'
agr instance list -o json –non-interactive –jq '.Data.Items[] | {InstanceId, ToolId, ToolName, NetworkMode, Status}'
这些命令都是只读查询，不会创建、停止或修改 Tool 和 Instance。
三、诊断命令
查看 Tool 的默认网络配置、端口声明和 Tool 级 NetworkPolicy：
agr tool get <tool-id> -o json –non-interactive –jq '.Data | {ToolId, NetworkConfiguration, Ports: .CustomConfiguration.Ports, DNSConfig: .CustomConfiguration.DNSConfig, NetworkPolicy, LogConfiguration}'
查看运行中 Instance 的实际网络模式、端口和实例级 NetworkPolicy：
agr instance get <instance-id> -o json –non-interactive –jq '.Data | {InstanceId, ToolId, NetworkMode, Status, Ports: .CustomConfiguration.Ports, NetworkPolicy}'
排查前建议记录以下信息，便于后续定位和联系支持：
·ToolId
·InstanceId
·RequestId
·Status
·NetworkMode
·NetworkPolicy
·CustomConfiguration.Ports
四、Tool 或 Instance 的 NetworkMode 与目标场景不匹配
访问公网通常需要 PUBLIC，访问私网资源通常需要 VPC。如果 agr tool get 和 agr instance get 查到的网络模式与目标场景不一致，先更新 Tool，再重新启动 Instance。
切换到公网模式：
agr tool update <tool-id> –network-configuration '{"NetworkMode":"PUBLIC"}' -o json –non-interactive
切换到 VPC 模式并补齐子网与安全组：
agr tool update <tool-id> –network-configuration '{"NetworkMode":"VPC","VpcConfig":{"SubnetIds":["subnet-xxxxxxxx"],"SecurityGroupIds":["sg-xxxxxxxx"]}}' -o json –non-interactive
注意：agr instance update 当前只公开 –timeout 和 –metadata，不提供网络相关参数。需要让新网络配置生效时，请更新 Tool 后重新启动 Instance。
五、VPC 模式缺少必要网络参数
如果 NetworkMode 已经是 VPC，但 SubnetIds 或 SecurityGroupIds 缺失、填错，或者与目标私网资源不在同一可达范围，Instance 仍然无法访问私网地址。
排查时重点查看 NetworkConfiguration.VpcConfig 中的 SubnetIds 和 SecurityGroupIds。修复时请一次性提交完整的 NetworkConfiguration，不要只改 NetworkMode 而遗漏 VpcConfig。
六、显式 DNSConfig 覆盖了默认 DNS
当 Tool 显式配置了 CustomConfiguration.DNSConfig 时，Instance 会优先使用该配置，而不是按当前网络环境注入默认 DNS。私网域名解析异常时，先检查 DNSConfig 是否与预期一致。
如果需要修正 DNS 设置，请使用 agr tool update –custom-configuration 提交新的 CustomConfiguration，再重新启动 Instance 验证解析结果。
七、NetworkPolicy 拦截了出站请求
如果目标域名、端口、路径或方法不在策略允许范围内，请求会被 Tool 级或 Instance 级 NetworkPolicy 拦截。
如果需要修改 Tool 级或 Instance 级 NetworkPolicy，请改用 Cloud API 的 UpdateSandboxTool 或 UpdateSandboxInstance，并在请求体中传入 NetworkPolicy。例如：
{ "ToolId": "sdt-xxxxxxxx", "NetworkPolicy": {}}
{ "InstanceId": "ins-xxxxxxxx", "NetworkPolicy": { "DefaultDecision": "deny", "Rules": [ { "Name": "allow-api", "Decision": "allow", "Resources": [ { "Hosts": [ "api.example.com" ], "Ports": [ "443" ] } ] } ] }}
如果目标是恢复到“无策略”状态，不建议依赖 null 清空。当前更稳妥的做法是新建一个未配置 NetworkPolicy 的 Tool，再从该 Tool 启动新的 Instance。
八、业务端口不可达或误用了保留端口
如果业务端口没有写入 CustomConfiguration.Ports，或者监听端口与声明不一致，外部请求无法正确转发到容器进程。
此外，以下端口是平台保留端口，不能用于业务流量：
·32000：平台保留用于日志采集，请勿占用。
·57890：平台保留用于实例运行管理，请勿占用。
修复时请改用其他业务端口，并确认容器进程在同一端口监听；随后重新查询 Tool 或 Instance，确认 CustomConfiguration.Ports 与实际监听一致。
九、SANDBOX 模式与 CLSConfig 同时开启
SANDBOX 模式不提供日志投递到 CLS 所需的网络访问能力。如果 Tool 同时配置了 NetworkMode=SANDBOX 和 LogConfiguration.CLSConfig，更新请求会被拒绝，或日志无法按预期投递。
处理方式：
·如果必须把日志投递到 CLS，请改用 PUBLIC、INTERNAL_SERVICE 或符合要求的 VPC 模式。
·如果必须保持 SANDBOX 模式，请移除 LogConfiguration.CLSConfig。
十、联系支持时提供的信息
如果完成上述调整后问题仍然存在，提交工单 时建议一并提供：
·ToolId
·InstanceId
·RequestId
·Response.Error.Code
·Response.Error.Message
·当前 NetworkMode
·当前 NetworkPolicy
·VpcConfig 中的 SubnetIds 和 SecurityGroupIds
·目标地址、目标端口，以及失败方向是出站还是入站
十一、相关文档
·网络模式
·查询沙箱工具