一、前提条件
访问 Sandbox 端口前，请确认以下信息：
注意：说明：
注意：平台按 Sandbox ID、Port 和 Access Domain 解析目标端口。如需展示或分发可访问链接，请按这篇规则组装 URL。
| 项 | 说明 |
| Sandbox ID | 目标 Instance 的唯一标识。 |
| Port | 目标业务端口，范围 1-65535。 |
| Access Domain | 当前环境分配的接入域名，格式为 {region}.tencentags.com，{region} 为你的地域标识（如 ap-guangzhou）。 |
| 访问凭证 | 根据 Instance 认证模式准备 X-Access-Token、access_token 或签名参数。 |
二、路由优先级
同一请求同时满足多种路由规则时，平台只使用第一种命中的规则，优先级固定为：
Host > Header > Cookie > Path
·如果 Host 已经符合 {port}-{sandbox-id}.<access-domain> 形式，平台不再读取 Header、Cookie 或 Path 中的路由信息。
·如果 Host 使用固定前缀域名（如 miniprogram.<access-domain>），平台继续读取该模式要求的 Header、Cookie 或 URL Path。
三、Host 访问
Host 访问把目标端口和 Sandbox ID 写入主机名：
{port}-{sandbox-id}.<access-domain>
示例：
https://8080-<sandbox-id>.ap-guangzhou.tencentags.com/wss://9000-<sandbox-id>.ap-guangzhou.tencentags.com/cdp/devtools/page/<page-id>
适用场景：浏览器直接访问、WebSocket/WSS 连接、可自定义 Host 的 HTTP 客户端。
规则说明：
·主机名前缀中第一段端口号即为目标端口。
·Host 解析成功后，不再回退到其他路由方式。
·URL Path 原样转发给目标端口上的服务。
四、Header 访问
Header 访问使用固定前缀域名，通过请求头指定目标 Instance 和端口：
https://miniprogram.<access-domain>/
请求头：
X-Sandbox-ID: <sandbox-id>X-Sandbox-Port: <port>
兼容字段：
X-CS-Sandbox-ID: <sandbox-id>X-CS-Sandbox-Port: <port>
规则说明：
·新接入建议统一使用 X-Sandbox-ID 和 X-Sandbox-Port。
·兼容字段仅用于存量迁移。
·同时传入新旧两套字段时，平台优先读取 X-Sandbox-ID 和 X-Sandbox-Port。
·miniprogram 是默认前缀；环境如有额外前缀，同样遵循 Header 规则。
五、Cookie 访问
Cookie 访问使用固定前缀域名 webview.<access-domain>。首次访问通过 URL Query 引导写入 Cookie，后续请求由 Cookie 完成路由。
首次访问示例：
https://webview.<access-domain>/?x-sandbox-id=<sandbox-id>&x-sandbox-port=<port>
兼容 Query：
https://webview.<access-domain>/?x-cs-sandbox-id=<sandbox-id>&x-cs-sandbox-port=<port>
引导完成后，平台执行以下操作：
1. 校验 Query 中的 Sandbox ID 和端口。
2. 写入新版 Cookie：x-sandbox-id、x-sandbox-port。
3. 删除引导参数，返回 302 重定向。
重定向后，后续请求直接访问：
https://webview.<access-domain>/<your-path>
规则说明：
·即使首次使用兼容 Query Key，平台写回的仍然是新版 Cookie Key。
·302 跳转后的 URL 会剥离引导参数，但保留业务 Query。
·Cookie 模式只在 webview 前缀域名下生效。
六、Path 访问
Path 访问使用固定前缀域名 miniprogrampath.<access-domain>，把 Sandbox ID 和端口写入 URL Path：
https://miniprogrampath.<access-domain>/<sandbox-id>/<port>/<path>
示例：
https://miniprogrampath.<access-domain>/<sandbox-id>/8080/api/files
规则说明：
·第 1 段 Path 是 Sandbox ID。
·第 2 段 Path 是目标端口。
·第 3 段起为实际业务路径。
·转发时平台自动剥离前两段，只把剩余路径发给目标服务。
示例：
原始请求: /<sandbox-id>/8080/api/files实际转发: /api/files
七、Access Token
优先使用请求头传递：
X-Access-Token: <access-token>
部分客户端也支持通过 Query 传递访问令牌，常见参数名：
tokenaccess_tokenauthauthorization
八、签名访问
文件上传、下载等场景可使用签名参数，必填字段：
| 参数 | 必填 | 说明 |
| signature | 是 | 签名值。 |
| username | 是 | 签名对应的用户标识。 |
| path | 是 | 签名覆盖的资源路径。 |
| signature_expiration | 否 | 签名过期时间。 |
九、HTTPS 和 WSS
平台支持 http、https、ws、wss 四种 scheme。URL 组合规则在不同 scheme 下保持一致，只是协议前缀不同：
http://8080-<sandbox-id>.<access-domain>/https://8080-<sandbox-id>.<access-domain>/ws://9000-<sandbox-id>.<access-domain>/cdp/devtools/page/<page-id>wss://9000-<sandbox-id>.<access-domain>/cdp/devtools/page/<page-id>
注意事项：
·路由规则本身支持 HTTPS 和 WSS。
·实际是否提供 HTTPS 或 WSS 入口，取决于当前环境的证书和 TLS 配置。
·如果环境只开通了 HTTP 或 WS，Host 和路径规则不变，切换为实际可用的 scheme 即可。
十、验证访问
按以下顺序排查访问是否生效：
1. 确认目标端口在 Instance 内已经监听。
2. 确认使用的路由方式与域名前缀匹配。
3. 确认端口值在 1-65535 范围内。
4. 如果使用 Header 或 Cookie 模式，确认字段名使用新版 Key。
5. 如果使用 Cookie 引导，确认首次请求收到 302 和两个新版 Cookie。
6. 如果使用 HTTPS 或 WSS，确认当前环境已配置有效证书。
十一、使用限制
·目标端口范围为 1-65535。
·Header、Cookie、Path 三种前缀路由依赖固定域名前缀，默认分别为 miniprogram、webview、miniprogrampath。
·新旧字段并存时，标准字段优先，兼容字段仅用于存量迁移。
·同一请求只取第一种命中的路由方式，不会并行生效。
·展示或分发访问地址时，请结合 Sandbox ID、Port 和 Access Domain 按这篇规则组装完整 URL。