应用通过集群详情页显示的访问地址连接 TSDB 专享版数据接口。REST API 与 Flight SQL 复用同一个用户访问入口；客户端需要同时配置连接地址、目标 Database 和访问令牌。

选择访问地址

• 内网地址：集群默认提供，适合与集群位于同一 VPC 或网络已打通的客户端。生产环境推荐优先使用内网地址，以获得更稳定的高带宽网络。
• 公网地址：绑定 EIP 后提供，适合无法使用内网的客户端。只有公网访问状态为“已绑定”时才使用；同时在弹性公网 IP（EIP）产品侧配置来源 IP 白名单。

进入集群详情页，在“网络信息”区块复制“内网 IP”（启用公网访问后也可以使用“公网 IP”）和“服务端口”，并使用明文 HTTP 组成完整 URL。TSDB 专享版当前不支持 HTTPS / TLS，也不提供公网白名单配置。来源 IP 白名单只限制访问来源，不会加密传输内容。不要使用页面未显示的其他端口。使用公网地址时，访问令牌和数据都以明文传输，存在被截获风险；请严格控制访问来源，并只使用最小权限业务访问令牌。

如果客户端与集群位于不同 VPC，请先通过云网络产品打通网络，或按安全要求配置公网访问。

选择访问令牌

管理员访问令牌由控制台或集群生命周期 OpenAPI 获取或重置；业务访问令牌通过数据库资源管理 API 或 tsdb-cli 创建。

配置客户端环境变量

本文档中的命令行示例使用环境变量，便于连续执行多条命令：

1export TSDB_HOST_URL='http://<访问地址>:<端口>'
2export TSDB_AUTH_TOKEN='<业务访问令牌>'
3export TSDB_DATABASE_NAME='mydb'

单次调用 tsdb-cli 时，也可以通过 --host、--token 和 --database 参数传入相同信息。显式传入的命令行参数优先于环境变量。不要把真实令牌写入脚本、代码仓库、镜像或日志。

HTTP 认证

REST API 推荐使用 Bearer Token：

1Authorization: Bearer <token>

例如，列出当前令牌可见的 Database：

1curl "$TSDB_HOST_URL/api/v3/configure/database?format=json" \
2  -H "Authorization: Bearer $TSDB_AUTH_TOKEN"

Flight SQL 使用同名 gRPC metadata：

1authorization: Bearer <token>

不要把令牌放在 URL query 参数中。

验证连接

1. 确认集群状态为“运行中”。
2. 从运行客户端的网络环境连接页面显示的地址和端口。
3. 使用业务访问令牌列出 Database 或执行一条只读查询。
4. 记录 HTTP status 或 gRPC status，以及服务端返回的错误信息。

常见认证与资源错误

Flight SQL 对应返回 Unauthenticated 或 PermissionDenied 时，按相同方向检查令牌和权限。

安全建议

• 优先使用内网地址。
• 为每个应用和环境创建独立的业务访问令牌。
• 在凭证管理系统中保存和注入令牌，并建立轮换流程。
• 不在源码、镜像、日志、URL、工单或聊天记录中保存令牌。
• 公网接入时同时控制网络来源和令牌权限。