Web Hosting

Web Hosting 是将构建好的静态网站上传到 Space，并以 {subdomain}.weegloo.app 地址提供服务的资源。以服装商城为例，将构建好的商城站点发布到 dailywear-shop.weegloo.app，就是一个 Web Hosting。

上传顺序如下。首先将构建结果打包为 ZIP 或 tar.gz，通过 Upload API 上传以获得一个 Upload。然后引用该 Upload，使用 POST /web-hostings 创建 Web Hosting。当系统处理完上传的文件、sys.state 变为 COMPLETED 后，即可通过 url 访问站点。在 CMA 中，Web Hosting 是 Space 的子资源，路径以 /spaces/{spaceId}/web-hostings 为基准。

资源结构

下面是处理完成的 Web Hosting「DailyWear 商城网站」的单条查询响应。它包含 sys（系统属性）以及主体属性（name、description、isSpa、subdomain、url、pageMetas）。

{
  "sys": {
    "id": "3trmXRM3RqbgSnifyg7PWeb01Examp",
    "type": "WebHosting",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-18T11:40:00.000Z",
    "updatedAt": "2026-06-18T11:40:05.000Z",
    "state": "COMPLETED",
    "totalFileSize": 245786,
    "originMetas": [
      {
        "file": "index.html",
        "meta": {
          "title": "Daily Wear Store",
          "description": "Everyday clothing store"
        }
      }
    ],
    "version": 3
  },
  "name": "DailyWear 商城网站",
  "description": "服装、杂货商城静态站点",
  "isSpa": true,
  "subdomain": "dailywear-shop",
  "url": "https://dailywear-shop.weegloo.app",
  "pageMetas": [
    {
      "file": "index.html",
      "meta": {
        "title": "DailyWear - clothes for every day",
        "description": "Everyday pieces you can wear to work and on weekends.",
        "image": "https://dailywear-shop.weegloo.app/og-cover.png"
      }
    }
  ]
}

主要键：

  • subdomain：站点提供服务所用的子域名。上例为 dailywear-shop，最终地址为 dailywear-shop.weegloo.app。
  • url：处理完成后可访问的站点地址。
  • isSpa：是否为单页应用（SPA）。为 true 时，所有路径请求都会被发送到 index.html。
  • state：上传文件的部署处理状态。在下方系统属性 (sys)中说明。
  • pageMetas：按文档覆盖的元标签值。sys.originMetas 保存覆盖前的值。两者都在下方按文档的元数据中说明。

系统属性 (sys)

每个 Web Hosting 都将通用的系统属性存放在 sys 对象中。space、createdBy、updatedBy 采用 Refer 形式（{ "sys": { "id", "type": "Refer", "targetType" } }）。

属性类型说明
idstring资源唯一标识符。用于单条查询、修改、删除路径中的 {webHostingId}。
typestring资源种类。Web Hosting 始终为 "WebHosting"。
spaceRefer<Space>该 Web Hosting 所属的 Space。
createdByRefer<User>创建该资源的用户。
createdAtstring (date-time)创建时间。
updatedByRefer<User>最后修改的用户。
updatedAtstring (date-time)最后修改时间。
statestring (enum)部署处理状态。为下列 4 种之一。
errorstring处理失败时的原因。未失败时为空。
totalFileSizeinteger上传文件的总大小（字节）。
originMetasPageMeta[]文档原本携带的元标签值。仅在通过安装 MarketApp 创建的 Web Hosting 中填充。在下方按文档的元数据中说明。
versioninteger (≥1)资源版本。每次创建、修改都会加 1。修改、部分修改请求需要通过 x-weegloo-version 携带该值。

state 表示部署上传文件的处理阶段。它不是 Content 的发布状态，Web Hosting 也没有发布或归档的概念。文件处理完成、变为 COMPLETED 后，即可通过 url 访问站点。

state含义
PENDING等待处理。
PROCESSING处理中。
COMPLETED处理完成。可通过 url 访问。
FAILED处理失败。原因存放在 sys.error 中。

主体属性

Web Hosting 的主体属性如下。

属性类型说明
namestring (1~64)Web Hosting 名称。创建时必填。
descriptionstring (≤128)说明。可选。
isSpaboolean是否为单页应用。为 true 时所有路径请求都会被发送到 index.html（用于 SPA 路由）。创建时必填。
subdomainstring (3~32)服务子域名。模式为 ^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$（小写字母、数字、连字符，首尾不可为连字符）。创建时必填。
uploadRefer<Upload>指向待上传文件的引用。为 ZIP 或 tar.gz，根目录需有 index.html，资源需以相对路径引用。
urlstring处理完成后的访问 URL。由系统填充。
pageMetasPageMeta[]按文档覆盖的元标签值。可选。在下方按文档的元数据中说明。
customDomainstring已连接的自定义域名。可选。在下方自定义域名中说明。

子域名检查

在创建 Web Hosting 之前，可以检查想要使用的子域名是否空闲。向 GET /web-hostings/availability?subdomain=... 通过 subdomain 查询参数传入要检查的子域名即可。

响应为以下形式，available 为 true 时即可使用该子域名。

{ "subdomain": "dailywear-shop", "available": true }

自定义域名

可以将自己拥有的域名连接到 Web Hosting，代替默认地址 {subdomain}.weegloo.app。已连接域名的状态以 customDomain 对象表示，形式为 { id, domain, dns, cert }。dns 和 cert 分别为域名所有权验证（DNS）和证书签发（cert）状态，二者均为 { status, txtName, txtContent } 形式。txtName、txtContent 是需要在域名端注册的 DNS TXT 记录的名称和值。

{
  "id": 1024,
  "domain": "shop.dailywear.example",
  "dns": {
    "status": "pending",
    "txtName": "_weegloo.shop.dailywear.example",
    "txtContent": "weegloo-verify=3trmXRM3RqbgSnifyg7PWebVerifyEx"
  },
  "cert": {
    "status": "pending",
    "txtName": "_acme-challenge.shop.dailywear.example",
    "txtContent": "acme-verify=3trmXRM3RqbgSnifyg7PWebCertEx"
  }
}

在域名端注册 TXT 记录后，使用 PUT /web-hostings/{webHostingId}/custom-domain/status/verify 触发验证，并通过 GET /web-hostings/{webHostingId}/custom-domain/status 查询当前状态。验证完成后，dns.status 会变为 active，cert.status 会变为 ok。对未连接自定义域名的 Web Hosting 调用状态查询时，将以错误响应（参见错误）。

按文档的元数据

可以覆盖已上传站点中每个文档 <head> 里的元标签。搜索结果和聊天工具链接预览中显示的标题、说明和图片会变成这些值。目的是用一次请求完成更改，而不必重新构建并再次上传文件。

只有通过安装 MarketApp 创建的 Web Hosting 才能编辑。一旦通过 upload 替换文件，就无法再编辑，sys.originMetas 也会一并清空。违反该条件的请求会被拒绝（参见错误）。

值放在 pageMetas 数组中，一个条目对应一个文档。

属性类型说明
filestring (1-1024)目标文档的相对路径。例如 index.html、about/index.html。
metaWebHostingMeta应用到该文档的槽位值。

sys.originMetas 形式相同，保存覆盖前文档原本携带的值。要还原时重新发送这些值即可。

槽位

meta 的键称为槽位。一个槽位会同时更改多个标签。

槽位最大长度更改的标签
title200<title>、og:title、twitter:title
description500description、og:description、twitter:description
canonical2048link[rel=canonical]、og:url
image2048og:image、twitter:image
siteName200og:site_name
favicon2048link[rel=icon]、link[rel="shortcut icon"]、link[rel=apple-touch-icon]
themeColor32theme-color

如果文档中没有某个标签，会创建并插入。五个例外：twitter:title、twitter:description、twitter:image、link[rel="shortcut icon"] 和 link[rel=apple-touch-icon] 只在文档中已有时才会改变，没有时不会新建。

不同取值的结果

结果取决于发送值的形式。

请求中放入的内容结果
没有该槽位键当前设置保持不变。
槽位键为 null当前设置保持不变。
槽位键为空字符串从文档中删除该标签。
槽位键带有值用该值覆盖。
从 pageMetas 中略去某个文档条目该文档的设置保持不变。
没有 pageMetas所有文档的设置保持不变。

请特别注意最后两行。服务器会按文档和按槽位合并发送的内容。因此从数组中略去条目并不会清除设置；要清除必须在该槽位上明确给出空字符串。

空字符串是删除标签，而不是还原为原样。文档原本携带的标签也会一并消失。要还原为原值，请重新发送 sys.originMetas 中仍保留的值。

以下请求体只更改 index.html 的标题，并删除其说明标签。

{
  "pageMetas": [
    {
      "file": "index.html",
      "meta": {
        "title": "DailyWear - 每天都穿的衣服",
        "description": ""
      }
    }
  ]
}

更改 pageMetas 会重新运行把这些值应用到实际文档的处理。sys.state 会回到 PENDING 然后再回到 COMPLETED，在此期间修改和删除都会被拒绝。

错误

以下是处理 Web Hosting 时会遇到的错误码。所有资源共通的错误码，请参见通用错误。

错误码条件
WGL422031试图修改或删除正在处理部署文件的 Web Hosting。请在处理结束之后重试。
WGL422113向无法编辑按文档元数据的 Web Hosting 发送了 pageMetas。它要么不是通过安装 MarketApp 创建的，要么其文件此后已被上传替换。
WGL500039未能从分发网络读取所连接的自定义域名的信息。
WGL429001为原本没有自定义域名的 Web Hosting 新绑定域名时，该 Organization 的自定义域名数量已达到套餐上限。变更已有的域名不会增加数量，因此不受这项检查。

API

下列所有端点的基准 URL 均为 https://cma.weegloo.com/v1，Authorization 头需携带用于 CMA 认证的 Bearer 令牌。修改、部分修改为实现乐观并发控制，需同时发送 X-Weegloo-Version 头（当前资源的 sys.version）。创建、删除请求不带该头。

  • Upload API：上传静态文件 ZIP 以获得用于创建 Web Hosting 的 Upload 的请求。
  • Space：Web Hosting 所属的 Space。