虚拟主机开放 API

虚拟主机接口统一在本页说明，包含交易、安全查询和站点面板管理两部分。

分区	对外前缀	功能
交易与安全	`/host/manage/v1`	实例列表、商品目录、新购、续费、升级、漏洞扫描、敏感信息
面板管理	`/cp/site/v1`	站点发现、PHP/.NET、公共配置、域名/CDN/HTTPS、证书、备份、数据库、搬家

调用面板管理前，先从站点列表获取 instanceCode；续费和升级使用 serviceCode，两种编号不能混用。公共认证方式见签名算法，各接口所需的业务参数和写请求标识分别在对应分区说明。

交易与安全

交易与安全调用约定

接口网关为 https://x-api.xinnet.com ，本节交易与安全接口的对外前缀为 /host/manage/v1。例如实例列表的完整地址为 https://x-api.xinnet.com/host/manage/v1/list/1/20。本文保留每个后端接口的 GET/POST 方法；查询参数放在 URL 中，JSON 请求体使用 Content-Type: application/json。

公共认证字段和签名算法见签名算法。 Xn-PublicKey、 Xn-Signature、 authTimestamp 按统一网关约定处理； GET 接口的签名载体以平台登记的调用方式为准，不能擅自把后端 GET 改为 POST。业务请求体示例省略公共 authTimestamp，通过统一网关调用时应按签名约定补充并对实际发送的请求体签名。 authTimestamp 的网关时效与写请求 Xn-Request-Time 的 10 分钟窗口是两项独立校验。

代理商身份由网关根据认证结果注入，调用方无需提交 agentCode ，也不能自行设置 Xn-User 切换代理商。实例、服务和扫描记录只能查询或操作当前认证账号拥有的资源。商品和地域是公共目录，不按代理商筛选。

编号与路径

名称	含义	获取方式
instanceCode	站点实例编号，与本地 hostCode 对应	交易实例列表或面板站点列表
serviceCode	交易服务编号，用于续费和升级	实例列表或购买返回结果
scanId	漏洞扫描任务编号	扫描任务列表；不要使用列表中的 id 或 taskCode 替代

所有交易接口已移除原 /hosting 层级。例如使用 /host/manage/v1/list/1/20 ，不要使用 /host/manage/v1/hosting/list/1/20。面板管理使用独立的 /cp/site/v1 前缀，不要把 serviceCode 当作 instanceCode 传入。

统一返回

{
  "status": true,
  "code": "200",
  "res": {}
}

字段	类型	说明
status	boolean	业务成功标志，必须检查
code	string	业务返回码，成功通常为 `200` ，失败通常为 `400`
msg	string	可选提示信息
res	object / array / null	具体接口结果

HTTP 200 不代表业务成功。失败可能返回 status=false ，没有 res。来源或代理商身份检查失败时返回 HTTP 403；参数缺失、HTTP 方法错误和路径不存在也可能直接返回 HTTP 400/405/404。

写请求标识

新购、单个续费、批量续费、升级均要求下列请求头，查询接口不需要：

名称	类型	必选	说明
Xn-Request-Id	string	是	16–80 位字母、数字、下划线或短横线，每个逻辑请求唯一
Xn-Request-Time	integer	是	Unix 毫秒时间戳，与服务器时间相差不超过正负 10 分钟

同一个逻辑请求重试应复用原请求标识和相同业务参数；重新发起签名请求时使用当前有效时间戳。请求结果保留 24 小时，同标识同参数可重放已保存的成功或明确拒绝结果，同标识不同参数会被拒绝。超时或返回“正在执行/结果不确定”时，先核对订单和服务状态，不要换新标识重复下单。 24 小时去重不等于永久幂等保证；跨接口或跨新旧路径也不能视为同一请求。

交易与安全接口列表

下表路径均接在 /host/manage/v1 后。

方法	路径	功能	写请求标识
POST	`/list/{next}/{size}`	实例分页列表	否
GET	`/getGoodsSpec`	商品规格目录	否
GET	`/getRegionOptions`	地域目录	否
POST	`/buyNow`	新购	是
POST	`/renew/buyNow/{serviceCode}`	单个服务续费	是
POST	`/renew/batchRenew`	批量续费	是
POST	`/upgrade/buyNowByRemainingDays/{serviceCode}`	按剩余时长升级	是
GET	`/security/riskScan/list/{page}/{size}`	扫描任务列表	否
GET	`/security/riskScan/info/{scanId}`	扫描详情	否
GET	`/security/riskScan/vulnerabilities/{scanId}/{page}/{size}`	漏洞结果分页	否
GET	`/security/sensitive/recent/{instanceCode}`	最近两天敏感信息	否

POST 获取实例列表

POST /host/manage/v1/list/{next}/{size}

名称	位置	类型	必选	说明
next	path	integer	是	请求页码，从 1 开始
size	path	integer	是	每页条数，建议 1–100
tagNameList	body	array of string	否	标签列表
instanceType	body	string	否	实例类型，沿用实例返回值
httpSwitch	body	string	否	HTTP 开关筛选，沿用实例返回值
hasBackup	body	boolean	否	是否有备份
spaceQuota	body	integer	否	空间容量，单位 MB
phpVersion	body	string	否	PHP 版本
dotnetVersion	body	string	否	.NET 版本
dbType	body	string	否	数据库类型，如 MYSQL、MYSQL8
sslFlag	body	boolean	否	是否部署 SSL
fileProtectFlag	body	boolean	否	是否开启文件保护

不传业务请求体或传 {} 表示不增加筛选条件。示例：

{
  "hasBackup": true,
  "sslFlag": true
}

成功时 res 为分页对象：

{
  "status": true,
  "code": "200",
  "res": {
    "total": 1,
    "page": 1,
    "size": 20,
    "current": 1,
    "elements": [
      {
        "instanceCode": "0123456789abcdef0123456789abcdef",
        "hostCode": "0123456789abcdef0123456789abcdef",
        "hostName": "example-site",
        "serviceCode": "EXAMPLE_SERVICE_CODE"
      }
    ]
  }
}

total 是总条数， current 是当前页码， page 是总页数， size 是每页条数， elements 是实例数组。实例还可能包含 remark、 instanceType、 instanceStatus、 ftpSwitch、 httpSwitch、 phpSwitch、 backupCount、 os、 spaceQuota、 phpVersion、 dotnetVersion、 dotnetMode、 sslFlag、 fileProtectFlag、 dbInfo、 tagNameList 等配置字段。版本字段存在不代表套餐支持该语言；能力判断应使用面板管理。

GET 获取商品规格

GET /host/manage/v1/getGoodsSpec

无业务请求体。成功时 res 是按产品型号分组的数组，只包含当前支持的新型号商品规格：

字段	类型	说明
value	string	productType，例如 economical、enterprise、foreignTrade
comment	string	型号名称
productClass	string	domestic（共享虚拟主机）或 overseas（海外免备案）
osType	string	可选系统，可能为逗号分隔的 Windows、Linux
roomName	string	机房说明
specs	array	该型号下可用的商品规格

选择 productClass、 productType、 osType 的有效组合后再下单，不要混用不同型号、系统的规格。

GET 获取地域选项

GET /host/manage/v1/getRegionOptions

无业务参数。成功时 res 是 {value, comment} 数组，分别表示地域值和展示名称。地域目录用于展示；新购时实际地域由服务端根据商品规格确定。

POST 新购虚拟主机

POST /host/manage/v1/buyNow

必须携带写请求标识。以下示例须先用商品目录确认所选组合可售：

{
  "productClass": "domestic",
  "productType": "economical",
  "osType": "Linux",
  "buyAmount": 1,
  "buyUnit": "Y",
  "buyNum": 1,
  "autoRenew": false,
  "plugin": 0,
  "autoCreate": true
}

名称	位置	类型	必选	说明
productClass	body	string	是	domestic 或 overseas，取商品目录值
productType	body	string	是	取商品目录 value
osType	body	string	是	Windows 或 Linux，注意大小写
buyAmount	body	integer	是	时长数值，网关要求不小于 0；可售时长以商品规则为准
buyUnit	body	string	是	M（月）或 Y（年）
buyNum	body	integer	是	数量，1–30
autoRenew	body	boolean	否	是否自动续费
plugin	body	integer	否	插件型商品标识，默认 0，须与规格匹配
autoCreate	body	boolean	否	是否自动创建，默认 true
mktSource	body	string	否	已配置的渠道来源标识

agentCode、 goodsCode、 spec、 region 由服务端根据认证身份及商品选择确定，调用方不应自行指定。此接口为普通新购，不应按面板促销、限购或网站转入活动的接口使用。成功时 res 是交易平台业务结果，可能为服务编号数组；以实际返回为准，不把 status=true 解释为站点已经开通完成。

POST 单个服务续费

POST /host/manage/v1/renew/buyNow/{serviceCode}

serviceCode 必须属于当前代理商，状态必须允许续费（NORMAL 或 BLOCKING）。必须携带写请求标识。

{
  "buyAmount": 1,
  "buyUnit": "Y"
}

buyAmount 为必填整数且不小于 0， buyUnit 必填，取 M 或 Y，可售时长仍由商品及交易规则校验。服务编号取路径，当前商品规格由服务端读取。成功时 res 返回实际交易业务结果。

POST 批量续费

POST /host/manage/v1/renew/batchRenew

业务请求体为非空 JSON 数组；每项必须包含 serviceCode、 buyAmount、 buyUnit ，同一批内不得重复 serviceCode：

[
  {
    "serviceCode": "EXAMPLE_SERVICE_CODE_1",
    "buyAmount": 1,
    "buyUnit": "Y"
  },
  {
    "serviceCode": "EXAMPLE_SERVICE_CODE_2",
    "buyAmount": 1,
    "buyUnit": "M"
  }
]

每个服务均校验代理商归属及续费状态，时长约束与单个续费一致。整批使用一个写请求标识。成功时 res 返回实际交易结果，不保证每个元素都会单独生成一个结果对象。此接口的数组结构与公共签名文档的对象示例不同；公共认证载体按平台登记方式处理，不得为加入公共字段而擅自把业务数组包成对象。

POST 升级虚拟主机

POST /host/manage/v1/upgrade/buyNowByRemainingDays/{serviceCode}

serviceCode 必须属于当前代理商，服务状态为 NORMAL，仅支持升配，不支持降配。必须携带写请求标识。

{
  "productClass": "domestic",
  "productType": "professional",
  "osType": "Linux",
  "plugin": 0
}

productClass、 productType、 osType 必填且为有效商品组合， plugin 为可选插件标识。接口按服务剩余时长计算升级，不通过 buyAmount/buyUnit 指定新的购买时长；旧规格和服务归属由服务端读取。成功时 res 返回实际交易业务结果。

GET 获取漏洞扫描任务列表

GET /host/manage/v1/security/riskScan/list/{page}/{size}?condition={condition}

名称	位置	类型	必选	说明
page	path	integer	是	从 1 开始
size	path	integer	是	1–100
condition	query	string	否	按任务名称或扫描内容模糊匹配，须进行 URL 编码

只返回当前代理商的扫描任务，关键词查询仍限制在当前代理商内。 res 为与实例列表相同的分页结构。 elements 的常见字段：

字段	说明
id	数据库记录编号，不作为 scanId 使用
scanId	扫描编号，用于详情和漏洞查询
taskCode	关联任务编号
scanName	扫描名称
scanContent	扫描内容
scanInfo	扫描扩展信息
scanStatus	当前扫描状态
createTime	创建时间

本接口只查询已有任务，不会创建新的扫描。

GET 获取漏洞扫描详情

GET /host/manage/v1/security/riskScan/info/{scanId}

scanId 从扫描列表获取。成功时 res 为当前账号拥有的扫描记录，字段与列表元素相同。不存在或不属于当前账号时返回业务失败。

GET 获取漏洞结果

GET /host/manage/v1/security/riskScan/vulnerabilities/{scanId}/{page}/{size}?condition={condition}

scanId 来自自有扫描列表，page 从 1 开始，size 为 1–100，condition 为可选筛选关键词。服务端从已授权扫描记录读取结果编号，调用方不能另传 lastResultId 或报告对象名。扫描尚无结果时返回“扫描结果尚未生成”，而不是自动启动扫描。

res 为分页对象。漏洞元素常见字段为 vulId、 cve、 domain、 name、 url、 vulLevel、 vulFamily、 vulOutput、 qod、 qodType。结果结构沿用虚机漏洞扫描接口，不是托管 WAF 拦截记录。

GET 查询最近两天敏感信息

GET /host/manage/v1/security/sensitive/recent/{instanceCode}

instanceCode 为当前账号拥有的站点编号。查询范围限于该站点已绑定域名的最近两天数据，不接受任意 URL 或全局检索条件。

res 字段	类型	说明
instanceCode	string	站点编号
window	string	LAST_2_DAYS
queriedAt	string	查询时间
queriedDomainCount	integer	查询域名数量
total	integer	返回记录总数
truncated	boolean	是否截断
items	array	最多 200 条脱敏记录

每条 items 仅含 domain、 category、 urlPath、 detectedAt ，不返回违规关键词和 URL 查询字符串。无记录时可返回空数组；查询成功不代表触发了新的检测。虚拟主机不提供 WAF 拦截记录接口。

交易与安全验证范围

对外路径按平台配置将 host-platform 的 /api/gateway 映射为 /host。 2026-10-21 已用预发真实资源验证后端只读接口、新路径生效、旧路径下线及身份/归属拒绝场景。本次未验证公网统一网关的签名调用，也未执行真实新购、续费和升级；对外路由和签名载体仍应在接入环境联调确认。

面板管理

面板管理调用约定

接口网关为 https://x-api.xinnet.com ，面板对外前缀为 /cp/site/v1。例如站点列表完整地址为 https://x-api.xinnet.com/cp/site/v1/list。面板管理部分保留后端 GET/POST 方法，JSON 请求使用 Content-Type: application/json ，URL 查询值应正确编码。

认证与签名见签名算法。公共认证字段按平台约定传递，业务请求体示例省略公共 authTimestamp；通过统一网关调用时须补充相应认证载体并对实际发送的内容签名。 GET 及无业务请求体接口的签名方式以平台登记方式为准，不能自行改变 HTTP 方法。 authTimestamp 与下文 Xn-Request-Time 是两项独立的时效校验。代理商身份由网关注入，调用方无需传 agentCode，也不能通过自设 Xn-User 指定其他代理商。

所有站点操作都校验认证账号拥有 instanceCode。数据库、域名、任务和备份还会检查它们属于该站点。

先获取站点编号

先调用站点列表取得 instanceCode 。它对应站点 hostCode，与交易用 serviceCode 不同。下文 {instanceCode}、 {dbCode}、 {taskCode} 等均为路径占位符，请替换成列表返回的实际编号。

统一返回和异步结果

{
  "status": true,
  "code": "200",
  "res": {}
}

status 为业务结果， code 为字符串业务码，失败提示在可选 msg 中， res 随接口变化。 HTTP 200 时也必须检查 status；业务失败可能没有 res。身份或来源不合法返回 HTTP 403；缺少必填查询参数可能返回 HTTP 400，未注册的路径返回 HTTP 404。

搬家、恢复、CDN 等接口返回 accepted=true 仅表示请求已接受，不代表任务已完成。域名和证书操作还需检查操作记录的 status ，必要时通过 operation 查询接口复查。不能只检查 HTTP 状态或外层 status 就认定异步操作完成。

写请求标识与重试

除 domain/plan、 ssl/plan 这两个计划查询外，面板管理部分 POST 操作均要求下列请求头，包括获取备份下载地址：

名称	类型	必选	说明
Xn-Request-Id	string	是	通常 16–80 位字母、数字、下划线或短横线
Xn-Request-Time	integer	是	Unix 毫秒时间戳，与服务端时间相差不超过正负 10 分钟

站点列表虽然使用 POST，但属于查询，不要求这两个写请求头。 domain/execute 和 ssl/execute 的请求标识限制为 16–64 位，同时作为 operationId，建议使用全局唯一 UUID。 plan 不执行实际变更，无需写请求标识；execute 必须使用 plan 返回的 stateHash。

同一逻辑操作重试时复用原请求标识和业务参数，使用当前有效的时间戳重新签名。同标识不同参数会被拒绝；已保存的结果可在 24 小时内重放。不要把去重视为永久幂等。遇到超时、“处理中”或“结果不确定”时先查询配置、任务或操作记录，不能换新标识重复执行。同资源并发提交可能被明确拒绝；确认原请求没有执行后，再决定是否使用新标识发起新操作。

面板管理接口列表

以下路径以 /cp/site/v1 为前缀， {instanceCode} 是站点实例编号。

方法	路径	用途
POST	`/list`	站点发现
GET	`/{instanceCode}/environment`	系统及语言能力
GET	`/{instanceCode}/php/config`	PHP 配置
GET	`/{instanceCode}/php/options`	PHP 配置字典
POST	`/{instanceCode}/php/version`	切换 PHP 版本
POST	`/{instanceCode}/php/language`	指定 PHP 版本启停
POST	`/{instanceCode}/php/switch`	PHP 开关
POST	`/{instanceCode}/php/parameter`	PHP ini 参数
POST	`/{instanceCode}/php/disabledFunctions`	禁用函数
POST	`/{instanceCode}/php/maxUploadSize`	上传大小
GET	`/{instanceCode}/dotnet/config`	.NET 配置
POST	`/{instanceCode}/dotnet/version`	.NET 版本及管道模式
POST	`/{instanceCode}/dotnet/trustedLevel`	.NET 信任级别
POST	`/{instanceCode}/dotnet/scriptError`	.NET 错误展示
GET	`/{instanceCode}/config`	公共网站配置
POST	`/{instanceCode}/config/homepage`	默认首页
GET	`/{instanceCode}/config/rewrite/list`	伪静态模板
POST	`/{instanceCode}/config/rewrite/save`	保存伪静态模板
POST	`/{instanceCode}/config/rewrite/activate`	启用模板
POST	`/{instanceCode}/config/rewrite/reset`	重置模板
POST	`/{instanceCode}/config/rewrite/delete`	删除模板
POST	`/{instanceCode}/config/redirect`	301 重定向
POST	`/{instanceCode}/config/errorPage`	404 页面
POST	`/{instanceCode}/config/mime`	MIME 映射
GET	`/{instanceCode}/domain/list`	域名列表
GET	`/{instanceCode}/domain/status`	解析和备案状态
GET	`/{instanceCode}/domain/dns`	DNS 记录
GET	`/{instanceCode}/domain/website`	域名访问检查
POST	`/{instanceCode}/domain/plan`	绑定/解绑计划
POST	`/{instanceCode}/domain/execute`	绑定/解绑执行
GET	`/{instanceCode}/domain/operation/{operationId}`	域名操作记录
GET	`/{instanceCode}/domain/cdn/status`	CDN 能力及状态
POST	`/{instanceCode}/domain/cdn/execute`	CDN 开启/关闭/刷新
POST	`/{instanceCode}/domain/https`	HTTPS 跳转
GET	`/{instanceCode}/ssl/info`	已绑定证书元数据
GET	`/{instanceCode}/ssl/available`	可用新网证书
POST	`/{instanceCode}/ssl/plan`	证书变更计划
POST	`/{instanceCode}/ssl/execute`	申请/导入/解绑证书
GET	`/{instanceCode}/ssl/operation/{operationId}`	证书操作记录
GET	`/{instanceCode}/backup/list`	备份列表
POST	`/{instanceCode}/backup/download`	获取短期下载地址
POST	`/{instanceCode}/backup/restore`	恢复备份
GET	`/{instanceCode}/database/list`	数据库元数据
POST	`/{instanceCode}/database/{dbCode}/password`	重置数据库密码
POST	`/{instanceCode}/siteMove/create`	创建搬家任务
GET	`/{instanceCode}/siteMove/list/{page}/{size}`	搬家任务列表
GET	`/{instanceCode}/siteMove/info/{taskCode}`	搬家进度
GET	`/{instanceCode}/tasks/recent`	最近任务状态

POST 获取可管理站点列表

POST /cp/site/v1/list

名称	位置	类型	必选	说明
page	body	integer	否	从 1 开始，默认 1
size	body	integer	否	1–100，默认 20
hostName	body	string	否	站点名称筛选
domain	body	string	否	域名筛选
instanceCode	body	string	否	实例编号筛选

业务请求体可省略或传 {} 。此接口仅列出当前代理商正常服务的站点，不是所有状态服务的交易列表。

{
  "page": 1,
  "size": 20
}

成功示例：

{
  "status": true,
  "code": "200",
  "res": {
    "page": 1,
    "size": 20,
    "total": 1,
    "elements": [
      {
        "instanceCode": "0123456789abcdef0123456789abcdef",
        "serviceCode": "EXAMPLE_SERVICE_CODE",
        "hostName": "example-site",
        "serviceStatus": {"value": "NORMAL", "comment": "使用中"},
        "startTime": "2026-10-01 00:00:00",
        "endTime": "2027-10-01 00:00:00"
      }
    ]
  }
}

面板管理部分列表的 page 表示当前页码；与平台列表的分页对象不同，平台列表使用 current 表示当前页码、page 表示总页数。

GET 查询站点环境和语言能力

GET /cp/site/v1/{instanceCode}/environment

res 字段	类型	说明
os	string	实际操作系统，例如 WINDOWS、LINUX
language	string	实际主语言，例如 DoNet、PHP
supportedLanguages	string	套餐支持的语言说明
phpSupported	boolean	是否允许 PHP 配置
dotnetSupported	boolean	是否允许 .NET 配置
dotnetVersion	string / null	.NET 可用时返回的版本字段
dotnetMode	string / null	.NET 可用时返回的管道模式

PHP/.NET 能力依据套餐语言及实际环境判断，不依赖 PHP 版本字段是否非空。纯 .NET 套餐不能调用 PHP 配置，混合套餐可同时支持两者；PHP 开关关闭不代表不支持 PHP。 .NET 配置还要求 Windows 环境。缺少版本字段并不自动表示 .NET 不可用，应以 dotnetSupported 为准。

PHP 环境配置

GET 查询 PHP 配置

GET /cp/site/v1/{instanceCode}/php/config

要求 phpSupported=true。 res 返回 instanceCode、 phpSwitch、 phpVersion、 languageVersion、 errorLogSwitch、 outputBufferingSwitch、 uploadSwitch、 maxUploadSizeMb、 disabledFunctions、 shortOpenTag、 maxInputTime、 maxFileUploads、 errorReporting、 displayErrors、 dateTimezone、 supportedParameterNames。不返回 FTP 或其他连接密码。字段值可能因系统、PHP 版本而不同。

GET 查询 PHP 配置字典

GET /cp/site/v1/{instanceCode}/php/options

要求 phpSupported=true。 res 包含 parameters、 errorLevels、 timezones 三组配置字典。此接口不是可安装 PHP 版本列表，能否切换到指定版本由实际服务器能力决定。

POST 切换 PHP 版本

POST /cp/site/v1/{instanceCode}/php/version

{"version":"8.2"}

version 必填，1–32 位字母、数字、点、下划线或短横线。示例不表示所有站点都支持 8.2。本节所有 POST 均需写请求标识，成功结果采用对应配置能力的返回值；可再次查询 PHP 配置确认。

POST 开启或关闭指定 PHP 版本

POST /cp/site/v1/{instanceCode}/php/language

{"version":"8.2","enabled":true}

version 规则同上，enabled 为必填布尔值。这是指定语言版本的启停，不是安装新版本。

POST 设置 PHP 开关

POST /cp/site/v1/{instanceCode}/php/switch

{"setting":"UPLOAD","enabled":true}

setting 必填，取 ERROR_LOG、 OUTPUT_BUFFERING、 UPLOAD ；enabled 必填，使用 JSON 布尔值。

POST 修改 PHP ini 参数

POST /cp/site/v1/{instanceCode}/php/parameter

{"name":"max_input_time","value":"60"}

name、value 均必填，value 为字符串，支持范围如下：

name	value
short_open_tag	ON 或 OFF
max_input_time	0–300 的整数字符串
max_file_uploads	0–100 的整数字符串
error_reporting	从 php/options 的 errorLevels 选择
display_errors	ON 或 OFF
date.timezone	从 php/options 的 timezones 选择

POST 设置禁用函数

POST /cp/site/v1/{instanceCode}/php/disabledFunctions

{"functions":"chown,fsockopen"}

functions 必填，使用逗号分隔的函数名。 none 只清空可配置部分，system、exec 仍强制禁用。

POST 设置上传文件大小

POST /cp/site/v1/{instanceCode}/php/maxUploadSize

{"sizeMb":20}

sizeMb 为必填正整数，单位 MB，是否接受该大小由实际服务器校验。

.NET 环境配置

以下接口要求 dotnetSupported=true，使用原面板支持的 ASP.NET/.NET Framework 配置。这些接口不表示站点支持 .NET Core 或现代 .NET 托管。

GET 查询 .NET 配置

GET /cp/site/v1/{instanceCode}/dotnet/config

res 包含 instanceCode、 version、 mode、 trustedLevel、 scriptError ；部分字段可能为空。

POST 设置 .NET 版本和管道模式

POST /cp/site/v1/{instanceCode}/dotnet/version

{"version":"4.0","mode":"Integrated"}

version 必填，1–32 位字母、数字、点、下划线或短横线，实际可用版本由服务器校验。 mode 必填，取 Classic 或 Integrated 。必须携带写请求标识，提交后可查询 dotnet/config 确认。

POST 设置 .NET 信任级别

POST /cp/site/v1/{instanceCode}/dotnet/trustedLevel

{"level":"High"}

level 必填，仅支持 High、 Full 。必须携带写请求标识。

POST 设置 .NET 脚本错误展示

POST /cp/site/v1/{instanceCode}/dotnet/scriptError

{"detailed":false,"message":"站点暂时不可用"}

detailed 为必填布尔值；关闭详细错误时 message 必填，任何情况下 message 都不能超过 1000 字符。必须携带写请求标识。

公共网站配置

这组接口同时适用于 PHP 和 .NET 站点，不要求 phpSupported=true。所有 POST 均需写请求标识，成功结果采用相应配置能力的返回值；提交后可查询当前配置确认。

GET 查询公共配置

GET /cp/site/v1/{instanceCode}/config

res 包含 instanceCode、 defaultHomepage、 rewriteEnabled、 rewriteCode、 redirects、 errorPage、 mimeMappings。

POST 设置默认首页

POST /cp/site/v1/{instanceCode}/config/homepage

{"documents":"index.aspx,index.html"}

documents 为必填字符串，最多 512 字符，不能为空或包含换行；保留首页顺序和原有分隔约定。

GET 查询伪静态模板

GET /cp/site/v1/{instanceCode}/config/rewrite/list

成功时 res 为模板列表；后续修改、启用或删除使用其返回的模板 code。

POST 保存伪静态模板

POST /cp/site/v1/{instanceCode}/config/rewrite/save

{
  "code": "",
  "name": "example-rewrite",
  "tryFile": true,
  "rules": [
    {"action":"last","content":"^/post/亇 /index.php?id=亇"}
  ]
}

字段	类型	必选	说明
code	string	否	新建时可省略或为空，更新时使用模板编号
name	string	是	名称，非空且最多 64 字符
tryFile	boolean	是	沿用模板配置中的 tryFile 开关
rules	array	是	1–30 条规则
rules.action	string	是	break 或 last
rules.content	string	是	非空、最多 2048 字符，须含特殊占位符亇，不允许分号和换行

POST 启用伪静态模板

POST /cp/site/v1/{instanceCode}/config/rewrite/activate

{"code":"EXAMPLE_TEMPLATE_CODE"}

code 必填，长度 1–128，仅允许字母、数字、点、下划线、冒号和短横线。

POST 重置伪静态配置

POST /cp/site/v1/{instanceCode}/config/rewrite/reset

无业务请求体，恢复默认配置。

POST 删除伪静态模板

POST /cp/site/v1/{instanceCode}/config/rewrite/delete

{"code":"EXAMPLE_TEMPLATE_CODE"}

code 规则同启用模板。当前正在使用的模板不能删除。

POST 设置域名 301 重定向

POST /cp/site/v1/{instanceCode}/config/redirect

{"action":"ADD","source":"www.example.com","target":"target.example.com"}

action 取 ADD 或 REMOVE ，source 必须是本站绑定域名，target 必填、最多 2048 字符，不能含换行或竖线。 REMOVE 也需传入相应 source 和 target。该来源域名已开启 HTTPS 跳转时，不允许新增 301。

POST 设置 404 错误页面

POST /cp/site/v1/{instanceCode}/config/errorPage

{"action":"SET","path":"/www/404.html"}

action 取 SET 或 UNSET 。SET 时 path 必填，为以 / 开头的站点内路径，最多 1024 字符，不能含 .. 、反斜杠或换行。取消示例： {"action":"UNSET"}。

POST 修改 MIME 映射

POST /cp/site/v1/{instanceCode}/config/mime

{"action":"ADD","mimeType":"application/json","extension":".json"}

action 取 ADD 或 REMOVE ；两种操作均需 mimeType、extension。扩展名可带前导点，后续沿用系统自身规则处理。仅接受有效的 MIME 类型和扩展名，不接受任意服务器配置指令。

域名、CDN 和 HTTPS

GET 获取绑定域名列表

GET /cp/site/v1/{instanceCode}/domain/list

成功时 res 为域名元数据列表，无记录时结果可能为空或 null。常见字段为 code、 bindDomain、 hostDomain、 resolveAddress、 cdnEnabled、 httpsRedirectEnabled、 certificateServiceCode、 certificateStatus、 createTime、 modifyTime。不返回证书正文、私钥或 CDN 分发内部编号。

GET 查询域名解析和备案状态

GET /cp/site/v1/{instanceCode}/domain/status

查询本站域名的解析/备案状态，成功时 res 沿用站点所属地域的检查结果。

GET 查询 DNS 记录

GET /cp/site/v1/{instanceCode}/domain/dns?domain=www.example.com

domain 是必填查询参数，必须是本站已绑定域名。res 包含 aRecords、 cnameRecords 等解析结果。

GET 检查域名访问状态

GET /cp/site/v1/{instanceCode}/domain/website?domain=www.example.com

domain 必填且属于本站，不接受任意 URL。res 包含 ifPass、 time、 domain。必须检查 ifPass 判断访问检查结果，外层 status=true 仅表示本次检查调用成功。

POST 生成绑定或解绑计划

POST /cp/site/v1/{instanceCode}/domain/plan

{"action":"BIND","domain":"www.example.com"}

action 必填，取 BIND 或 UNBIND ；domain 必填。无需写请求标识，不会实际绑定或解绑。 res 返回计划，包括 stateHash、是否允许执行及校验结果。执行前检查计划约束，保留 stateHash。

POST 执行绑定或解绑

POST /cp/site/v1/{instanceCode}/domain/execute

{
  "action": "BIND",
  "domain": "www.example.com",
  "stateHash": "STATE_HASH_FROM_PLAN",
  "confirm": false
}

action、domain、stateHash 必填，且必须与计划一致。需要 16–64 位 Xn-Request-Id 和 Xn-Request-Time。状态已变化导致 stateHash 失效时，应重新获取并检查计划后再处理。 UNBIND 必须显式传 confirm=true ，确认关联 CDN、HTTPS、证书和插件配置的联动清理。接口保留实名、域名配额、解析/备案等约束；旧 Linux 实例不支持的域名功能不会被绕过。

GET 查询域名操作状态

GET /cp/site/v1/{instanceCode}/domain/operation/{operationId}

operationId 使用执行时的 Xn-Request-Id，只能查询本站的操作。res 为操作记录，应检查其 status，不能把存在记录理解为操作成功。

GET 查询 CDN 能力和状态

GET /cp/site/v1/{instanceCode}/domain/cdn/status?domain=www.example.com

domain 可省略；提供时必须为本站绑定域名。res 包含 instanceCode、 productType、 productSpecAvailable、 instanceType、 cdnSupported、 requestedDomain、 matchedCount、 domains 等能力和域名状态信息。商品不支持 CDN 与查询失败是不同结果，应检查 cdnSupported 和具体域名状态。

POST 开启、关闭 CDN 或刷新缓存

POST /cp/site/v1/{instanceCode}/domain/cdn/execute

{"domain":"www.example.com","action":"OPEN"}

domain 必填且已绑定本站；action 必填，取 OPEN、 CLOSE、 REFRESH ，分别表示开启、关闭、刷新。需写请求标识。仅支持具备 CDN 能力的套餐；开启须满足有效绑定证书等原有条件。 REFRESH 沿用站点 CDN 的缓存刷新能力，不是托管 CDN 文档中的 URL/目录预热接口。 res 中 accepted=true 表示请求被接受，应再次查询 CDN 状态确认云端生效。

POST 开启或关闭 HTTPS 跳转

POST /cp/site/v1/{instanceCode}/domain/https

{"domain":"www.example.com","enabled":true}

domain、enabled 必填，需写请求标识。开启须已有有效绑定证书，并且同一域名没有冲突的 301 重定向。此接口只控制跳转，不负责上传或申请证书。成功提交后可查询域名列表确认 httpsRedirectEnabled。

SSL 证书

GET 查询已绑定证书

GET /cp/site/v1/{instanceCode}/ssl/info?domain=www.example.com

domain 必填，且已绑定本站。res 为脱敏证书元数据，没有已绑定证书时可能为 null；不返回正文和私钥。旧 Linux 实例不支持证书时返回业务失败。

GET 查询可用新网证书

GET /cp/site/v1/{instanceCode}/ssl/available?domain=www.example.com

domain 必填。res 为当前站点可用的新网证书元数据列表，applyCode 用于后续导入计划。

POST 生成证书操作计划

POST /cp/site/v1/{instanceCode}/ssl/plan

{"action":"XINNET_IMPORT","domain":"www.example.com","applyCode":"EXAMPLE_APPLY_CODE"}

action 取 FREE_APPLY、 XINNET_IMPORT、 UNBIND ，分别为申请免费证书、导入新网证书、解绑。 domain 必填，导入时 applyCode 必填。无需写请求标识，不执行实际证书变更；res 返回校验结果和 stateHash。

POST 执行证书变更

POST /cp/site/v1/{instanceCode}/ssl/execute

{
  "action": "XINNET_IMPORT",
  "domain": "www.example.com",
  "applyCode": "EXAMPLE_APPLY_CODE",
  "stateHash": "STATE_HASH_FROM_PLAN",
  "confirm": true
}

必须携带 16–64 位 Xn-Request-Id 和 Xn-Request-Time，并提交与计划一致的 action、domain、applyCode、stateHash。替换和解绑必须确认，导入及解绑传 confirm=true；免费申请若涉及替换，也应先确认计划中的影响。免费申请可能进入证书订单流程。提交成功后检查操作记录 status，不代表证书已经签发或部署完成。

GET 查询证书操作记录

GET /cp/site/v1/{instanceCode}/ssl/operation/{operationId}

operationId 为执行时的 Xn-Request-Id，只能查询本站操作。对于未确认完成的申请、导入或解绑，先查记录再决定后续动作。

备份

GET 查询站点或数据库备份

GET /cp/site/v1/{instanceCode}/backup/list?dbCode={dbCode}

dbCode 可省略，不传时查询站点备份；传入时查询该数据库备份，数据库必须属于本站。 res 为备份数组，常用字段为 backupId、 objectName、 size、 backupTime、 backupType。后续下载和恢复必须使用返回的完整 objectName，不使用 backupId，也不能自行拼接对象名。

POST 获取备份下载地址

POST /cp/site/v1/{instanceCode}/backup/download

{"objectName":"FULL_OBJECT_NAME_FROM_LIST"}

字段	类型	必选	说明
objectName	string	是	当前资源备份列表返回的完整对象名
dbCode	string	否	数据库备份必填；站点备份省略

必须携带写请求标识，保留下载次数限制。res 为 {"url":"https://example.com/temporary-signed-url"}。返回地址是短期敏感链接，不是 HTTP 跳转；应及时使用并防止泄漏。原请求结果重放可能包含已过期 URL，确认原请求状态后可用新的逻辑请求获取新地址。

POST 恢复站点或数据库备份

POST /cp/site/v1/{instanceCode}/backup/restore

{
  "objectName": "FULL_OBJECT_NAME_FROM_LIST",
  "confirmRestore": true
}

objectName 必填，confirmRestore 必须为 true，数据库恢复还需 dbCode。必须携带写请求标识。恢复会覆盖目标数据；站点恢复保留原有站点关闭、恢复和回调流程。资源位置由服务端推导，不能传入机器、地域或任意存储路由。 res 返回 {instanceCode, accepted:true} ；数据库恢复时 instanceCode 可能为数据库编号。从站点的 tasks/recent 查询恢复进度，不要通过重复恢复确认是否完成。

数据库

GET 获取数据库列表

GET /cp/site/v1/{instanceCode}/database/list

res 为数据库元数据数组，仅包含 dbCode、 dbUserName、 dbType、 serviceStatus、 createTime ，不返回密码。

POST 重置数据库密码

POST /cp/site/v1/{instanceCode}/database/{dbCode}/password

{"password":"AES_BASE64_CIPHERTEXT"}

password 必填，沿用面板既有 AES 加密后 Base64 编码的协议，不能直接传明文，也不能将占位示例当作有效密文。加密算法为 AES/CBC/PKCS5Padding，密钥和 IV 沿用面板接入约定，结果使用 Base64 编码；不因使用密文而省略 HTTPS。解密后的密码须为 8–20 位，仅允许英文字母、数字及 @$!%*?&#. ，并至少包含字母、数字、符号中的两类。需写请求标识，站点和数据库归属均检查。成功时 res 为 {dbCode, accepted:true} ，不回显密码。

网站搬家

POST 创建搬家任务

POST /cp/site/v1/{instanceCode}/siteMove/create

{
  "ftpServer": "ftp.example.com",
  "port": 21,
  "ftpUser": "example-user",
  "ftpPass": "SOURCE_FTP_PASSWORD",
  "srcPath": "/www",
  "targetPath": "/www",
  "ignoreName": []
}

名称	类型	必选	说明
ftpServer	string	是	源 FTP 服务器
ftpUser	string	是	源 FTP 用户名
ftpPass	string	是	源 FTP 密码，通过 HTTPS 提交，不写入调用日志
port	integer	否	源 FTP 端口，按实际服务填写
srcPath	string	否	源目录，按原搬家服务约定填写
targetPath	string	否	目标目录，按原搬家服务约定填写
ignoreName	array of string	否	忽略项

需写请求标识。同一站点存在未完成任务时会拒绝创建；taskCode、callback 由服务端产生，调用方不应指定。 res 为 {instanceCode, accepted:true} ，不保证立即返回 taskCode。先查询搬家任务列表，再根据返回 taskCode 查询进度。

GET 查询搬家任务列表

GET /cp/site/v1/{instanceCode}/siteMove/list/{page}/{size}

page 从 1 开始，size 为 1–100。仅返回本站创建的任务，res 包含 page、 size、 total、 elements。每项仅包含 taskCode、status、createTime、modifyTime，不返回源 FTP 凭据和原始任务内容。

GET 查询搬家进度

GET /cp/site/v1/{instanceCode}/siteMove/info/{taskCode}

taskCode 从本站搬家列表获取。res 包含任务元数据，若进度可用还返回 copiedBytes、copiedFiles、copiedFolders。此查询会刷新搬家任务状态；任务不存在或不属于本站时拒绝。

GET 查询最近任务

GET /cp/site/v1/{instanceCode}/tasks/recent

返回本站最近五条任务的元数据，字段为 taskCode、taskType、taskStatus、postStatus、createTime、endTime。不返回原始 taskParam、taskInfo 或凭据。可用于确认备份恢复等任务的实际结果。

面板管理验证范围

对外路径按平台配置将 host-panel 的 /api/gateway 映射为 /cp。 2026-10-21 已使用预发真实站点验证 Windows/.NET 与 Linux/PHP 查询、公共配置、域名/DNS/CDN 状态、证书、备份、数据库和任务列表，以及身份缺失、资源归属、未绑定域名和参数错误的拒绝行为。尚未执行真实配置修改、域名变更、恢复、密码重置或证书申请；预发后端读取成功不代表公网签名链路或写操作已完成验收。

Last modified: 23 October 2026