mcpField
Z
zeabur-domain-url

zeabur-domain-url

github.com/zeabur云与 DevOps39189 次安装7 周前更新
代码仓库

关于 zeabur-domain-url

为使用 Zeabur CLI 的开发者提供域名配置指导，涵盖 URL 变量、生成域名与自定义域名，并说明 Wonder Mesh 服务的域名限制。

主要功能

  1. 01区分 URL 与域名变量
  2. 02创建生成域名和自定义域名
  3. 03列出与删除域名
  4. 04说明 Wonder Mesh 域名限制

适用场景

  1. 01避免 URL 尾部斜杠导致路径问题
  2. 02为 Zeabur 服务配置公开域名

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/zeabur/agent-skills --skill zeabur-domain-url

安装后在 Claude Code 中输入/zeabur-domain-url确认已加载。

详细介绍

Zeabur 域名 URL 配置

始终使用 npx zeabur@latest 调用 Zeabur CLI。 切勿直接使用 zeabur 或通过其他方式安装。如果无法使用 npx，请先安装 Node.js。

症状

  • 重定向到错误的 URL（缺少域名后缀或末尾带有斜杠）
  • URL 不匹配导致 CORS 错误
  • ${ZEABUR_WEB_URL} 末尾带有斜杠，导致路径问题

系统变量

变量示例说明
ZEABUR_WEB_URLhttps://app.zeabur.app/末尾带有斜杠
ZEABUR_WEB_DOMAINapp.zeabur.app仅包含域名，不包含协议

解决方案

将入口服务中的 URL 暴露给其他服务：

- name: entry-service
  domainKey: PUBLIC_DOMAIN
  spec:
    env:
      APP_URL:
        default: https://${ZEABUR_WEB_DOMAIN}
        expose: true

- name: backend
  spec:
    env:
      WEB_URL:
        default: ${APP_URL}

使用 https://${ZEABUR_WEB_DOMAIN}，而不是 ${ZEABUR_WEB_URL}，以避免末尾的斜杠。

CLI 域名管理

列出域名
npx zeabur@latest domain list --id <service-id> -i=false
创建生成的域名（*.zeabur.app）

使用 -g 创建由 Zeabur 管理的子域名。使用 -g 时，--domain 只接受前缀（而非完整域名）：

npx zeabur@latest domain create --id <service-id> -g --domain myapp -y -i=false
# Suffix is auto-appended by backend based on region:
#   Default:           myapp.zeabur.app
#   Aliyun (China):    myapp.preview.aliyun-zeabur.cn
#   Tencent (China):   myapp.preview.tencent-zeabur.cn
#   Huawei (China):    myapp.preview.huawei-zeabur.cn
# China suffixes require completed identity verification on Zeabur.

生成的域名前缀验证规则：

  • 至少 3 个字符
  • 不允许包含点号——只能使用字母、数字和连字符
  • 少于 3 个字符时出错：DOMAIN_NAME_TOO_SHORT
  • 前缀包含点号时出错：UNSUPPORTED_DOMAIN_NAME
创建自定义域名

不使用 -g 时，--domain 接受完整域名：

npx zeabur@latest domain create --id <service-id> --domain example.com -y -i=false

创建自定义域名后，使用 zeabur-domain-dns 技能配置所需的 DNS 记录。对于专用服务器，使用以下命令查找 IP：

npx zeabur@latest server list -i=false
# Note the IP address of the server running your service

然后在 DNS 提供商处配置：

Type: A
Name: <your subdomain or @>
Value: <server IP from above>

切勿猜测 DNS 值。 配置 DNS 前，始终从 server list 输出中获取实际的服务器 IP。

删除域名
npx zeabur@latest domain delete --id <service-id> --domain <domain> -y -i=false
Wonder Mesh 服务器：WONDER_MESH_SERVER_REQUIRES_GATEWAY

无法将域名直接绑定到运行在 Wonder Mesh 提供商服务器上的服务。任何创建域名的流程——domain create、部署期间的自动域名绑定、模板部署或 PR 预览——都可能被拒绝，并返回：

Error: WONDER_MESH_SERVER_REQUIRES_GATEWAY

这不是服务上的端口或网络配置错误，CLI 重试也不会成功。后端会拒绝请求，因为直接绑定到应用服务的域名会永远停留在 PROVISIONING 状态。这些服务的域名必须通过 Wonder Mesh 网关绑定，而该流程只能在 Zeabur Dashboard 中完成。

收到此错误时：

  1. 停止操作。 不要重试 domain create——无论使用相同参数、不同标志、修改端口配置还是更换服务 ID 都不行。
  2. 引导用户前往 Dashboard。 告知用户在 Zeabur Dashboard 中打开该服务，并在其 Domains 标签页中设置域名。
  3. 说明 Dashboard 会执行的操作。 Domains 标签页会运行 Wonder Mesh 网关绑定流程：代表用户将域名绑定到 wonder-mesh-gateway-{wonderNetID} 项目中的 app-gateway 服务。这是唯一受支持的方式。

请勿：

  • 通过 CLI 或 API 将域名直接绑定到 Wonder Mesh 应用服务
  • 自行使用 domain create 将域名绑定到网关服务
  • 使用任何 CLI / MCP“网关绑定”命令——此类命令不存在

其他所有服务器上的服务均不受影响：上述生成的域名和自定义域名流程仍照常适用。

注意事项
  • 在非交互模式下，始终必须提供 --domain。若未提供，CLI 会返回 INVALID_DOMAIN_NAME。
  • 使用 -g 时，只提供前缀（例如 myapp），而非完整的 myapp.zeabur.app。
  • 不使用 -g 时，提供完整域名（例如 example.com）。

评论

支持 Markdown