WEWhaleEngineAgent API 文档
正式接口契约

云鲸引擎 Hyper-V Agent API

面向业务系统、IDC 财务系统和自动化平台的完整中文对接文档。本文档以 Agent 1.9.9.28 当前代码为准,共收录 73 条公开路由。已安装节点版本以其 /health 为准。

API 基线 /api/v1JSON UTF-8HMAC-SHA256异步任务Idempotency-Key更新:2026-10-09
安全提醒:ApiSecret、管理员密码和完整请求正文不得写入日志、URL或数据库明文字段。文档示例全部使用占位符。

调用约定

Agent 地址https://agent.example.com:8787

生产环境推荐 HTTPS;地址不包含末尾斜杠。

VM 引用{vmRef}

可使用 Agent 返回的 vmId/订单别名,写操作仍需 confirmVmId 防误操作。

时间与重放UTC + nonce

请求时间必须位于 Agent 允许偏差内,nonce 不可重复。

HMAC-SHA256 鉴权

除匿名健康页、控制台静态 viewer 和带短时 token 的信令外,业务 API 均使用节点 ApiKeyId/ApiSecret 签名。

HTTPS 节点的 Agent.AllowedRemoteCidrs 可留空,表示不限来源 IP,不表示免认证;HMAC、时间戳、nonce 防重放和授权校验仍必需。旧节点升级保留原白名单和凭据,不自动清空。公网 HTTP 仍要求来源白名单。每个被控独立域名和 API 凭据,直接打开节点返回的 HTML 控制台链接无需填写财务站域名;不要把 API Secret 放入 HTML、URL或日志。

Agent.ApiProtection 默认每实际连接来源 100 请求/秒、全节点 500 请求/秒、64 个并发 HTTP 请求。超限返回 429 API_RATE_LIMITED 和 Retry-After: 1;退避后生成新时间戳、nonce 和签名,保留原业务幂等键。普通 API 请求体最多 1 MiB,超限返回 413;精确的迁移文件 PUT 路由继续使用原流式传输限制。已升级的 WebSocket 不继续占用普通 HTTP 并发名额,也不限制媒体和键盘输入帧。

请求头必填说明
X-Api-Key是Manager 生成的 ApiKeyId
X-Timestamp是UTC Unix 秒
X-Nonce是每次请求唯一随机值,长度 16–128
X-Signature是HMAC-SHA256 结果的小写十六进制字符串,共 64 个字符
Idempotency-Key写操作必填一次业务动作固定复用;不要在轮询时生成新值
X-Request-ID建议用于跨系统日志关联,不得包含敏感信息
canonicalString = METHOD + "\n"
+ PATH(不含查询字符串) + "\n"
+ TIMESTAMP + "\n"
+ NONCE + "\n"
+ SHA256_HEX(原始请求体字节)

signature = LOWER_HEX(HMACSHA256(ApiSecret, UTF8(canonicalString)))
最常见的 401 原因:签名路径和实际路径不一致、JSON 签名后又被重新序列化、时间不是 UTC、ApiKeyId/ApiSecret 不成对、body 为空时没有使用空字节 SHA-256。

异步任务与幂等

创建、重装、删除、电源、密码、远程访问、安全组、到期网络开关、带宽、快照、备份和迁移等写操作通常返回 taskId,业务系统随后轮询 GET /api/v1/tasks/{taskId}。

status处理方式
queued / running继续轮询;建议 3–5 秒起步并逐步退避。重试等待表现为 status=queued、stage=retry_wait。
succeeded读取 result,核对 vmId、IP、远程端口、安全策略/指纹等最终数据
failed停止自动重复创建;依据 errorCode、errorMessage 和业务上下文决定人工复核
{
  "taskId": "00000000-0000-0000-0000-000000000000",
  "status": "running",
  "stage": "waiting_guest",
  "progress": 90,
  "result": null,
  "error": null
}

幂等规则:同一业务动作的网络重试必须复用同一 Idempotency-Key;任务已经明确失败且契约允许重试时,使用新 key。revision 型安全组更新必须按当前策略版本递增。

Agent.MaxConcurrentTasks 支持 1 或 2,默认 1,升级不改变已有设置。选择 2 可让不同 VM 的首启等待重叠;模板复制、离线挂载、VM 创建及管理脚本仍跨进程串行。同 VM 任务互斥、容量/IP 预留和幂等规则保持不变。排队等待宿主重操作时为 waiting_host_operation,客户机未完整就绪时仍是 running / waiting_guest,不提前完成。服务中断后的磁盘/IP 操作仍必须核对实际状态。

首启立即探测,随后按 2/5/10 秒逐步降低频率,以单调计时核对等待超时;探测本身耗时另计。Windows 主机名、初始化、IP、ready 标志、RDP/防火墙和敏感文件清理,以及 Linux cloud-init、网络、SSH/密码仍全部验证。主机外部 RDP 路径仅作最长等待 1.5 秒的诊断,不代替客户机验证。模板仍为独立完整 VHDX,不启用差分盘或修改原模板;NTFS 未承诺块克隆或复制吞吐提升。

GET /api/v1/host/metrics 共享一次宿主机采集并复用 3 秒内完成的样本,sampledAt 是真实采样时间;不缓存任务、电源、容量/IP 预留或授权判断。

全部接口(73 条)

下面列表按 Agent 1.9.9.28 当前路由逐项核对。输入方法、路径或中文功能可过滤。

基础 1 项

GET/healthAgent 健康检查200 健康状态

控制台 7 项

GET/console-viewerHTML5 控制台页面200 HTML
GET/fastmos-console/console-viewer反向代理兼容入口200 HTML
GET/api/v1/console/capabilitiesHTML5 控制台能力200 JSON
POST/api/v1/vms/{vmRef}/console-sessions创建短时控制台会话201 JSON
GET/api/v1/console-sessions/{sessionId:guid}查询控制台会话200 JSON
DELETE/api/v1/console-sessions/{sessionId:guid}主动关闭控制台会话200 JSON
GET/api/v1/console-sessions/{sessionId:guid}/signal短时令牌保护的 WebSocket 信令101 Switching Protocols

宿主机 2 项

GET/api/v1/host宿主机、网络和版本信息200 JSON
GET/api/v1/host/metricsCPU、内存、磁盘和 VM 数量200 JSON

监控 4 项

GET/api/v1/metrics/capabilities查询历史指标采集能力和保留策略200 JSON
GET/api/v1/vms/{vmRef}/traffic查询累计流量200 JSON
GET/api/v1/vms/{vmRef}/metrics查询 VM 实时指标200 JSON
GET/api/v1/vms/{vmRef}/metrics/history查询 CPU、内存和网络历史指标200 JSON

存储 2 项

GET/api/v1/storage/profiles存储方案容量与配额200 JSON
GET/api/v1/vms/{vmRef}/storage查询 VM 磁盘分配和使用200 JSON

授权 2 项

GET/api/v1/license/status本机授权状态200 JSON
POST/api/v1/license/deactivate注销本机授权绑定200 JSON

模板 3 项

GET/api/v1/templates可用系统模板200 JSON
GET/api/v1/templates/diagnostics模板扫描诊断200 JSON
POST/api/v1/templates/refresh立即刷新模板缓存200 JSON

带宽 3 项

GET/api/v1/bandwidth/capabilities限速驱动能力200 JSON
GET/api/v1/vms/{vmRef}/bandwidth查询 VM 限速200 JSON
POST/api/v1/vms/{vmRef}/bandwidth修改上下行限速202 taskId

安全组 3 项

GET/api/v1/security-groups/capabilitiesHyper-V ACL 能力200 JSON
GET/api/v1/vms/{vmRef}/security-policy查询安全策略与漂移200 JSON
PUT/api/v1/vms/{vmRef}/security-policy应用安全组202 taskId

到期网络 3 项

GET/api/v1/network-lock/capabilities到期网络封禁能力200 JSON
GET/api/v1/vms/{vmRef}/network-lock查询到期网络封禁状态200 JSON
PUT/api/v1/vms/{vmRef}/network-lock开启或解除到期网络封禁202 taskId

迁移 3 项

GET/api/v1/migration/capabilities实时/离线迁移能力200 JSON
POST/api/v1/vms/{vmRef}/migration/precheck迁移预检200 JSON
POST/api/v1/vms/{vmRef}/migration执行实时或离线迁移202 taskId

迁移内部 8 项

POST/api/v1/migration-receive-sessions创建离线迁移接收会话201 JSON
GET/api/v1/migration-receive-sessions/{sessionId}查询接收会话200 JSON
PUT/api/v1/migration-receive-sessions/{sessionId}/manifest提交迁移文件清单200 JSON
GET/api/v1/migration-receive-sessions/{sessionId}/files/{fileId}查询文件传输进度200 JSON
PUT/api/v1/migration-receive-sessions/{sessionId}/files/{fileId}分块上传迁移文件200 JSON
POST/api/v1/migration-receive-sessions/{sessionId}/commit提交并校验迁移文件200 JSON
POST/api/v1/migration-receive-sessions/{sessionId}/activate导入并激活目标 VM200 JSON
DELETE/api/v1/migration-receive-sessions/{sessionId}取消并清理接收会话200 JSON

任务 2 项

GET/api/v1/tasks/{taskId:guid}查询异步任务200 JSON
POST/api/v1/tasks/{taskId:guid}/cleanup安全清理失败任务占用200 JSON

云主机 6 项

GET/api/v1/vms/{vmRef}查询 VM 详情200 JSON
POST/api/v1/vms创建 VM202 taskId
POST/api/v1/vms/{vmRef}/power开机、关机、重启202 taskId
POST/api/v1/vms/{vmRef}/delete删除 VM202 taskId
POST/api/v1/vms/{vmRef}/password修改管理员密码202 taskId
POST/api/v1/vms/{vmRef}/reinstall重装操作系统202 taskId

硬件升级 3 项

GET/api/v1/vms/{vmRef}/hardware查询 CPU、内存和磁盘硬件基线200 JSON
POST/api/v1/vms/{vmRef}/hardware/resize/previewCPU/内存升级只读预检200 JSON
POST/api/v1/vms/{vmRef}/hardware/resize执行 CPU/静态内存增配202 taskId

磁盘扩容 6 项

POST/api/v1/vms/{vmRef}/disks/add/preview新增数据盘只读预检200 canProceed/checks
POST/api/v1/vms/{vmRef}/disks/add新增数据盘202 taskId
POST/api/v1/vms/{vmRef}/disks/resize/preview扩大系统盘或数据盘只读预检200 canProceed/checks
POST/api/v1/vms/{vmRef}/disks/resize扩大已有 VHDX 容量202 taskId
GET/api/v1/vms/{vmRef}/disks/expansion-status查询待核对的磁盘容量预留200 JSON
POST/api/v1/vms/{vmRef}/disks/reconcile只读核对失败任务并结算容量预留200 JSON / 202 重放

IP 扩容 3 项

GET/api/v1/vms/{vmRef}/network/ips查询主 IP、附加 IP 和预留地址200 JSON
POST/api/v1/vms/{vmRef}/network/ips/preview追加 IPv4 地址只读预检200 canProceed/checks
POST/api/v1/vms/{vmRef}/network/ips为已有 VM 追加 IPv4 地址202 taskId

快照备份 10 项

GET/api/v1/vms/{vmRef}/snapshots查询检查点200 JSON
GET/api/v1/vms/{vmRef}/backups查询完整备份200 JSON/空数组
GET/api/v1/vms/{vmRef}/backups/{name}查询单个备份详情200 JSON
POST/api/v1/vms/{vmRef}/backups/{name}/restore/preview备份恢复只读预检200 JSON
POST/api/v1/vms/{vmRef}/snapshots创建检查点202 taskId
POST/api/v1/vms/{vmRef}/snapshots/{name}/restore恢复检查点202 taskId
DELETE/api/v1/vms/{vmRef}/snapshots/{name}删除检查点202 taskId
POST/api/v1/vms/{vmRef}/backups创建完整备份202 taskId
DELETE/api/v1/vms/{vmRef}/backups/{name}删除完整备份202 taskId
POST/api/v1/vms/{vmRef}/backups/{name}/restore/dry-run备份恢复安全演练200 JSON

远程访问 2 项

PUT/api/v1/vms/{vmRef}/remote-access修改 SSH/RDP 端口和来源202 taskId
POST/api/v1/vms/{vmRef}/linux/access-repairLinux 受控登录修复202 taskId

模板接口

GET /api/v1/templates 返回稳定的 imageCode。imageCode 是业务 SKU,不能跟随 VHDX 文件名随意变化。diagnostics 用于查看只读属性、Manifest 和扫描异常;refresh 立即刷新缓存。

正式模板下载地址统一为 https://license.taoidc.com/templates/。需要从 ISO 制作新模板时,请按 Windows 与 Linux 模板制作教程 完成系统安装、Sysprep/cloud-init 封装、Manifest、SHA-256、只读属性和入库验收。

关键字段说明
imageCode业务系统持久化的稳定模板代码
osFamily / osDistributionwindows/linux 与发行版
defaultLoginUser / Protocol / Port默认登录信息
supportsCustomRemotePort是否允许随机 RDP/SSH 端口
minimumDiskGb下单系统盘不得低于此值
supportsReinstall / SecurityGroup / Console模板能力开关

创建云主机

POST /api/v1/vms,必须提供 Idempotency-Key。系统盘支持模板最小容量至 500GB 范围内的任意整数容量;最终上限还受宿主机和配置限制。

{
  "orderId": "CS00100",
  "customerId": 10001,
  "hostname": "CS00100",
  "planCode": "plan-2c4g",
  "imageCode": "ubuntu-24.04-x86_64",
  "storageProfileId": "default",
  "cpu": 2,
  "memoryMb": 4096,
  "diskGb": 95,
  "adminPassword": "<由业务系统临时生成,不记录明文>",
  "nics": [{
    "networkId": "extranet",
    "adapterName": "External",
    "ipAddress": "203.0.113.10",
    "prefixLength": 24,
    "gateway": "203.0.113.1",
    "dnsServers": ["1.1.1.1", "8.8.8.8"],
    "additionalIpAddresses": []
  }],
  "dataDisks": [{"sizeGb": 37, "label": "data01"}],
  "remoteAccess": {
    "protocol": "ssh",
    "port": 24550,
    "allowedSourceCidrs": ["198.51.100.10/32"]
  },
  "bandwidth": {"uploadMbps": 20, "downloadMbps": 50},
  "securityPolicy": {
    "securityGroupId": "sg-default-open",
    "revision": 1,
    "defaultInboundAction": "allow",
    "defaultOutboundAction": "allow",
    "preserveRemoteAccess": true,
    "rules": []
  }
}
{
  "vmId": "CS00100",
  "taskId": "00000000-0000-0000-0000-000000000000",
  "status": "queued",
  "replayed": false,
  "internalVmId": "00000000-0000-0000-0000-000000000000",
  "name": "CS00100",
  "orderId": "CS00100"
}

数据盘:不得假定 Linux 永远是 /dev/sdb。Agent/模板应按唯一标识、容量与未格式化状态识别。创建受理时预留系统盘和数据盘容量;失败清理或删除成功后释放。

VM 查询与管理

动作请求要点
power{"action":"start|stop|restart","force":false}
delete必须传 confirmVmId,成功后再释放业务系统 IP
password传 currentAdminPassword 与 newAdminPassword;密码只进入 DPAPI 保护任务载荷
reinstall传 imageCode、adminPassword、preserveDataDisks、可选 remoteAccess
metrics / traffic实时指标与累计流量用途不同,不要混算

首次开通状态

创建任务处于 queued 或 running 时,GET /api/v1/vms/{vmRef} 固定返回根级 state=Provisioning、status=provisioning、powerStatus=Provisioning 和 operationStatus=provisioning。operationExecutionStatus 在排队时为 waiting,开始执行后为 executing;同时返回真实任务进度和阶段。

{
  "state": "Provisioning",
  "status": "provisioning",
  "powerStatus": "Provisioning",
  "actualPowerStatus": "Off",
  "powerStatusSource": "hyperv",
  "operationStatus": "provisioning",
  "operationProgress": 45,
  "operationStage": "waiting_guest",
  "operationExecutionStatus": "executing"
}

actualPowerStatus 仅用于诊断 Hyper-V 在开通过程中的瞬时状态,业务页面不得据此把新 VM 显示为“已关机”。创建任务成功后,Agent 才解除开通中状态;通过客户机就绪验证且 Hyper-V 实际状态为 Running 时,页面显示“已开机”。创建失败则按任务错误显示失败,不应自动重开。

CPU 与内存升级

Agent 1.9.9.14 第一阶段支持查询 VM 实际硬件,以及 CPU、静态内存增配。只允许增加,不允许降配;动态内存 VM 暂不支持修改内存。CPU 或内存发生变化时需要正常关闭 VM,成功后可恢复升级前的运行状态。

1. 查询当前硬件

GET /api/v1/vms/CS00100/hardware

响应中的 actual 来自 Hyper-V 实时查询,是升级计算的权威基线;recorded 是 Agent 数据库记录;drift 表示两者是否存在差异;storage 返回磁盘清单;capabilities 明确当前阶段支持的操作。

2. 提交只读预检

POST /api/v1/vms/CS00100/hardware/resize/preview
Content-Type: application/json

{
  "confirmVmId": "CS00100",
  "cpu": 4,
  "memoryMb": 8192,
  "shutdownTimeoutSeconds": 180,
  "restorePreviousPowerState": true
}

cpu 和 memoryMb 至少提供一个;省略的字段保持当前实际值。只有 canProceed=true 才能执行。预检会检查 VM 状态、是否降配、动态内存、宿主机可用内存、CPU 超售警告和数据库漂移。

3. 执行增配

POST /api/v1/vms/CS00100/hardware/resize
Idempotency-Key: hardware-CS00100-order-20260906-001
Content-Type: application/json

{
  "confirmVmId": "CS00100",
  "cpu": 4,
  "memoryMb": 8192,
  "shutdownTimeoutSeconds": 180,
  "restorePreviousPowerState": true
}

执行接口返回 202 + taskId,业务系统必须轮询任务到终态。任务会在执行前再次核对硬件基线,使用正常关机,修改后读取 Hyper-V 实际值验证;失败时尝试恢复旧 CPU、旧内存和原电源状态。任务固定只执行一次,不自动重试;成功后才更新 Agent 数据库。

任务阶段说明
queued_hardware_resize任务已排队
prechecking_hardware再次核对 VM 与硬件基线
stopping_vm_for_hardware_resize等待客户机正常关机
applying_cpu_memory应用 CPU 和内存配置
verifying_hardware验证 Hyper-V 实际值
starting_vm_after_hardware_resize恢复原运行状态
verifying_final_hardware_state最终核对
completed成功完成并更新数据库
CPU/内存预检返回 canProceed=false 时,请展示 checks 中 level=fail 且 passed=false 的具体原因。执行接口返回 409 HARDWARE_PRECHECK_FAILED,原因位于 error.details;其中的 warn 项本身不会阻断。检查包含电源状态、降配、没有增配、动态内存及宿主机 1 GiB 内存余量。硬件升级期间,同一 VM 的其他管理任务返回 VM_OPERATION_CONFLICT。VM 的 operationStatus=hardware_resizing 与电源状态相互独立。磁盘增配请使用下方独立接口。

磁盘升级:新增数据盘与扩大 VHDX

Agent 1.9.9.19 支持对 Running 或 Off 的受管 VM 新增数据盘,或扩大已有系统盘、数据盘。系统自动正常关机 → 扩容并核实磁盘 → 自动开机,原本 Off 的 VM 成功后也会开机。关机限时 180 秒、开机限时 120 秒;不强制断电,失败明确报错、不自动重试。单次处理一盘;不缩容、不格式化、不修改客户机分区。磁盘预检与执行都需要有效 provision 授权及 HMAC;查询接口可用于基础诊断。

POST /api/v1/vms/CS00100/disks/resize/preview
Content-Type: application/json

{
  "confirmVmId": "CS00100",
  "role": "system",
  "diskIndex": 0,
  "sizeGb": 100
}

sizeGb 为目标总容量(GiB),不是增加量;范围为 1–65536,且必须大于当前容量。系统盘使用 role=system,diskIndex=0;数据盘使用 role=data,索引从 0 开始。新增数据盘使用 /disks/add/preview,role=data,索引为已有数据盘数量;例如第一块数据盘为 0。先通过 GET /hardware 或 GET /storage 核对磁盘基线。

预检返回 canProceed、checks、currentSizeBytes、targetSizeBytes、additionalBytes 、guestPartitionAction、powerAction=graceful_shutdown_expand_start、shutdownTimeoutSeconds=180 和 startTimeoutSeconds=120。要求标准 SCSI 0 布局、受控订单目录、系统盘 os.vhdx、盘清单一致、无检查点/差分盘/共享盘/重解析路径,并检查数据盘上限(min(16, Agent.MaxDataDisks))、存储逻辑配额和物理余量。任意检查不通过时应展示具体 checks。

POST /api/v1/vms/CS00100/disks/resize
Idempotency-Key: disk-CS00100-order-20260919-001
Content-Type: application/json

{
  "confirmVmId": "CS00100",
  "role": "system",
  "diskIndex": 0,
  "sizeGb": 100
}

新增数据盘的执行地址为 /disks/add,使用对应预检的请求体。执行返回 202 + taskId;轮询 GET /api/v1/tasks/{taskId},仅在 completed 后更新业务套餐。任务先原子预留容量,再次检查 VM 身份、磁盘路径和容量基线,正常关机后再次核对基线,执行后核实容量/挂载结果,再自动开机并确认 Hyper-V 为 Running,最后在同一事务内更新分配记录和任务成功状态。并发管理操作返回 VM_OPERATION_CONFLICT;同幂等键/同请求可查询原任务,换请求体返回幂等冲突。

失败与恢复:磁盘扩大不可自动缩回。任务失败或 Agent 中断后保留容量预留,避免已扩大磁盘被当作空闲配额再次出售。使用 GET /api/v1/vms/{vmRef}/disks/expansion-status 查看待核对项,并核对 Hyper-V 实际结果;不要通过换幂等键反复提交或手工删除数据库预留。VHDX 容量扩大后,客户机内仍需按其分区/文件系统流程扩展;新增盘需由客户机管理员初始化,Agent 不自动格式化数据。

核对失败任务使用 POST /api/v1/vms/{vmRef}/disks/reconcile,携带独立幂等键,请求体为 {"confirmVmId":"CS00100","taskId":"原失败任务 UUID"}。该接口只读检查实际磁盘、不写盘、不改变电源;仍要求 VM 关机和安全布局。完全符合目标状态时返回 outcome=applied_capacity_committed 并结算容量。对新版自动开机任务,这不代表开机验证成功:原任务保持 failed,stage=disk_reconciled_start_unconfirmed,error=DISK_POWER_RECOVERY_REQUIRED;管理员核实后再单独开机。仅旧版不含自动开机的任务可补记成功;完全未改变且无遗留新增盘时返回 unchanged_reservation_released 并释放预留。部分完成、漂移或无法确认时返回 409 DISK_RECONCILIATION_REQUIRED 并继续保留预留,交管理员处理。重复请求可返回原核对任务的 202 响应。

磁盘任务排队时任务 status=queued;开始执行后至开机核实完成前保持 status=running、operationExecutionStatus=executing。VM 查询在该任务活动期间统一返回 state=Executing、status=executing、powerStatus=Executing,操作类型为 disk_adding 或 disk_resizing。actualPowerStatus 仅供诊断,前台不要用它显示中途关机。阶段依次包含 prechecking_disk_power_workflow、stopping_vm_for_disk_expansion(原为 Running)、磁盘变更、verifying_disk_expansion、starting_vm_after_disk_expansion、verifying_disk_power_state、completed。失败显示 failed,不得伪装为完成或无限执行中;Running 验证不等于客户机业务应用已就绪。

IP 扩容:为已有虚机追加 IPv4

在 Running 状态为唯一外网 NIC 追加地址,保留主 IP、网关、DNS、现有附加 IP、安全组及网络封禁配置。每个外网 NIC 的已确认与已预留附加地址总数最多 16;单节点内地址唯一,已有地址不能更改前缀。请求中的地址应已由业务 IP 池合法分配,并由上游网络配置对应路由。

GET /api/v1/vms/CS00100/network/ips

POST /api/v1/vms/CS00100/network/ips/preview
Content-Type: application/json

{
  "confirmVmId": "CS00100",
  "additionalIpAddresses": [
    { "ipAddress": "192.0.2.21", "prefixLength": 24 },
    { "ipAddress": "192.0.2.22", "prefixLength": 24 }
  ]
}

查询区分 additionalIpAddresses(已验证)与 reservedAdditionalIpAddresses(待核对),mutationBlocked 和 recovery 提示是否需要恢复未确认操作。预检返回 canProceed、checks、guestMethod、guestCredentialValidated=false;预检不使用客户机密码,执行时才验证登录和持久化后端。Windows 使用 PowerShell Direct;Linux 要求已有 root SSH 与已记录的 SSH 主机指纹,支持的持久化方式由执行器检测,不支持时明确失败。目标 NIC 必须使用静态 IPv4;DHCP 模式明确拒绝,不会为了加 IP 而关闭原 DHCP。

POST /api/v1/vms/CS00100/network/ips
Idempotency-Key: ips-CS00100-order-20260919-001
Content-Type: application/json

{
  "confirmVmId": "CS00100",
  "currentAdminPassword": "<从凭据库读取的当前客户机管理员密码>",
  "additionalIpAddresses": [
    { "ipAddress": "192.0.2.21", "prefixLength": 24 },
    { "ipAddress": "192.0.2.22", "prefixLength": 24 }
  ]
}

执行接口需要 provision 授权及 HMAC,返回 202 + taskId。密码仅进入受保护任务载荷,不应记录在业务日志、URL 或公开安装包。Agent 在同一事务中创建任务并预留地址,确认客户机运行地址和持久配置后才写入已确认附加地址并标记任务完成。同 VM 操作互斥、跨 VM IP 冲突和幂等键复用冲突均会拒绝。

Linux 通过主 IP 的 SSH 执行,主机指纹必须匹配;网络封禁或客户机不可达时不能扩容。失败时仅尝试撤销本次新增内容;连接丢失时结果可能不确定,地址预留会保留,避免分配给其他 VM。通过 IP 查询和任务错误核对实际状态后再恢复;不得把预留地址视为可用池。Agent 不修改上游路由,也不把客户机地址配置成功等同于公网可达性验证。

存在失败未核对的 IP 任务或未确认地址时,其他 VM 修改操作返回 IP_EXPANSION_REVIEW_REQUIRED,基础查询仍可用。核对客户机后,可对同一 VM、同一组地址/前缀使用新幂等键安全续做;执行器在客户机内防并发并核对原有配置,所有预留地址验证成功后才解除保护。旧幂等键只重放旧结果,不会重新执行。

Linux 客户机还需 Python 3(可使用发行版 platform-python)和 systemd。每张 NIC 使用独立的扩容地址清单与恢复服务,在网络和 cloud-init 首启配置之后仅恢复本功能管理的附加 IP,避免模板开机初始化覆盖扩容结果;NetworkManager 可用时同步追加其持久地址列表。不会重写主 IP、默认路由或 DNS。

CPU、内存与网络历史监控

Agent 默认每 1 分钟批量采集一次 VM 指标并写入本机 SQLite,默认保留 30 天;可配置采集间隔 1–5 分钟、保留 7–30 天。历史接口只读取已持久化数据,不会在查询时临时启动性能采集。

GET /api/v1/vms/CS00100/metrics/history?from=2026-08-30T00:00:00Z&to=2026-08-31T00:00:00Z&intervalMinutes=5
{
  "vmId": "CS00100",
  "vmName": "CS00100",
  "from": "2026-08-30T00:00:00+00:00",
  "to": "2026-08-31T00:00:00+00:00",
  "intervalMinutes": 5,
  "collectionIntervalMinutes": 1,
  "retentionDays": 30,
  "rawSampleCount": 1440,
  "points": [{
    "sampledAt": "2026-08-30T00:00:00+00:00",
    "lastSampledAt": "2026-08-30T00:04:00+00:00",
    "sampleCount": 5,
    "vmState": "Running",
    "metricsAvailable": true,
    "cpuPercent": 21.37,
    "memoryUsedBytes": 3221225472,
    "memoryTotalBytes": 4294967296,
    "networkInBytesPerSecond": 1250000,
    "networkOutBytesPerSecond": 320000,
    "networkInTotalBytes": 9876543210,
    "networkOutTotalBytes": 3456789012,
    "networkInDeltaBytes": 375000000,
    "networkOutDeltaBytes": 96000000,
    "unavailableMetrics": []
  }]
}

network*BytesPerSecond 是区间平均速率;network*TotalBytes 是该桶最后一次 Hyper-V 累计计数;network*DeltaBytes 是该时间桶内增量并兼容计数器重置。省略时间范围默认查询最近 24 小时,省略 intervalMinutes 默认 5 分钟。请求超过保留期时 from 会自动收敛到最早可保留时间;结果点数超过上限时返回 400,业务系统应增大 intervalMinutes。

远程访问

PUT /api/v1/vms/CS00100/remote-access
{
  "confirmVmId": "CS00100",
  "currentAdminPassword": "<当前密码>",
  "protocol": "ssh",
  "port": 24551,
  "allowedSourceCidrs": ["198.51.100.10/32"]
}

allowedSourceCidrs 表示远程登录来源限制;空数组按当前 Agent 策略处理。preserveRemoteAccess=true 表示安全组更新时保留 Agent 生成的远程访问系统 ACL,不是额外对所有来源全放行。Ubuntu 的 ssh.socket 与 ssh.service 由 Agent 兼容处理,验证失败会回滚旧端口。

安全组

PUT /api/v1/vms/CS00100/security-policy
{
  "confirmVmId": "CS00100",
  "securityGroupId": "sg-web",
  "revision": 2,
  "defaultInboundAction": "deny",
  "defaultOutboundAction": "allow",
  "preserveRemoteAccess": true,
  "rules": [{
    "ruleId": "allow-https",
    "direction": "inbound",
    "protocol": "tcp",
    "remoteCidr": "0.0.0.0/0",
    "portFrom": 443,
    "portTo": 443,
    "action": "allow",
    "priority": 100,
    "enabled": true,
    "description": "HTTPS"
  }]
}

每个策略最多 64 条客户规则;priority 范围 1–10000。ICMP/ALL 省略端口。Agent 返回的系统规则使用 owner/source/visibleToUser/editable/reason 标记,业务系统必须按 visibleToUser=false 隐藏,不能靠 IP 猜测。

查询状态含义
not_configured尚未配置策略
applied策略与 ACL 已验证一致
drifted检测到漂移,需重新应用或人工核对
rollback_failed回滚失败,必须人工复核
temporary_deny_remains临时保护规则残留,禁止继续自动操作

到期网络开关

订单到期时,业务系统调用独立的 network-lock 接口。Agent 只在 VM 的公网网卡上添加两条系统级 Deny ACL(入方向全部拒绝、出方向全部拒绝),不会删除网卡,也不会改写客户安全组、带宽、远程端口或来源配置。续费后关闭开关,只移除这两条系统规则,原网络策略立即恢复。

PUT /api/v1/vms/CS00100/network-lock
Idempotency-Key: expire-CS00100-20260901

{
  "confirmVmId": "CS00100",
  "enabled": true,
  "reason": "expired"
}
// 续费恢复网络:使用新的业务动作幂等键
PUT /api/v1/vms/CS00100/network-lock
{
  "confirmVmId": "CS00100",
  "enabled": false,
  "reason": "renewed"
}

解除封禁推荐使用 reason=renewed;旧业务系统继续使用 expired 也兼容。写操作返回 202 + taskId,必须轮询任务到 succeeded 后再更新订单展示。GET /api/v1/vms/{vmRef}/network-lock 返回 desiredEnabled、appliedEnabled、networkPaused、status、最近任务和系统规则;locked 表示封禁已验证,unlocked 表示未封禁,drifted 表示数据库期望与 Hyper-V 实际 ACL 不一致。

VM 详情 GET /api/v1/vms/{vmRef} 会实时核对 Hyper-V:actualPowerStatus 是当前实际电源状态,powerStatusSource=hyperv 表示实时读取成功,database_fallback 表示本次查询临时使用数据库缓存。没有电源任务时,powerStatus=Running/Off;任务执行中则依次显示 Starting/Stopping/Restarting。封禁时返回根级 status=network_paused、networkStatus=paused、networkPaused=true。原 state 和 status 继续保留,避免破坏旧版业务系统。

电源、断网或恢复联网任务执行期间,VM 详情另外返回 operationStatus、operationTaskId、operationProgress、operationStage、operationExecutionStatus。电源状态分别为 power_starting、power_stopping、power_restarting;网络状态分别为 network_locking、network_unlocking。排队、校验、重试及 Agent 重启恢复阶段均保持正确方向,任务结束后操作字段返回 null。业务系统不得用处理中状态覆盖 VM 原始 state。

网络开关幂等:每次用户点击仍推荐生成新的 Idempotency-Key,同一次网络重试复用原 key。Agent 1.9.9.12 会按当前网络状态代际隔离 key,因此旧业务系统即使在“断网→联网”后复用了第一次断网 key,也会创建新的断网任务,不会静默重放历史成功任务。

电源操作重复执行:Agent 1.9.9.13 兼容按“VM+动作+请求体”固定生成 key 的旧业务系统。开机、关机、重启任务尚在排队或执行时,同一请求返回活动 taskId;任务进入终态后再次点击,即使复用原 key,也会创建新的 taskId 并重新执行。不同电源动作并发时返回 POWER_OPERATION_IN_PROGRESS。

{
  "state": "Running",
  "powerStatus": "Running",
  "actualPowerStatus": "Running",
  "powerStatusSource": "hyperv",
  "status": "Running",
  "networkStatus": "online",
  "networkPaused": false,
  "operationStatus": "network_locking",
  "operationTaskId": "00000000-0000-0000-0000-000000000000",
  "operationProgress": 90,
  "operationStage": "verifying_network_lock",
  "operationExecutionStatus": "executing"
}
保护项Agent 行为
客户安全组上限两条到期系统规则不计入客户 64 条上限
前台可见性owner=system、source=agent、visibleToUser=false、editable=false、reason=expired-network-lock
重启恢复状态持久化到 Agent SQLite;启动时立即校准,此后每 5 分钟检查一次
作用网卡只允许且只作用于唯一的 external 公网网卡
授权异常network-lock 不依赖授权 feature 开关,避免授权异常导致无法恢复客户网络;仍必须通过 HMAC 和来源限制
状态字段必须分开:VM 电源状态读取 powerStatus;任务接口的兼容字段 status=running 仍保留,但页面展示应读取 executionStatus=executing。任务查询同时返回 taskStatus,不得把任务 running 当作 VM 已开机。

HTML5 控制台

先查询 capabilities,再创建短时会话。viewer 页面允许匿名加载,但 WebSocket 信令继续使用短时 token 和 Origin 校验。会话过期后不得复用旧 URL,应由业务系统重新创建。

POST /api/v1/vms/CS00100/console-sessions
{
  "ttlSeconds": 300,
  "allowedSourceCidrs": ["198.51.100.10/32"]
}

当前 Agent 返回 viewerUrl:业务后端通过鉴权接口创建会话后,将此完整 HTML 链接交给已授权用户直接打开,无需拼接 URL。原有 signalUrl 和 accessToken 继续兼容,两个页面路径 /console-viewer、/fastmos-console/console-viewer 均有效。已关闭、过期或失败会话的重放响应不提供 viewerUrl。令牌位于 URL fragment,不应写入日志、数据库或第三方统计。多节点各自返回自己的域名和端口,不能固定转发到同一节点。

独立域名直连时,Agent:Console:PublicBaseUrl 配置为 HTTPS 源地址(域名及实际端口,不带路径前缀、查询参数或 fragment),证书必须覆盖该域名。AllowedOrigins 留空自动采用本节点 PublicBaseUrl 的 Origin;非空高级配置必须包含该协议、域名及端口。PublicBaseUrl 只生成链接,不自动设置 DNS、证书或监听端口。页面加载不等于取得 VM 控制权,信令继续校验短时 token、Origin 和来源限制。此 WSS 是 WebRTC 信令,不是供外部 noVNC 使用的 RFB WebSocket。

signalUrl 是 WebRTC 的 WSS 信令,不是 noVNC 所需的 RFB-over-WebSocket 地址,不能直接交给外部 noVNC。HTTPS/WSS 与 WebRTC UDP 媒体均需按节点实际配置放行;当前 viewer 未配置 TURN,不应将反向代理 HTTPS 成功视为媒体连接已验证。

存储容量与带宽

GET /api/v1/storage/profiles 返回每个存储方案的系统盘/数据盘根目录、总量、已用、预留、剩余、配额和 overcommitRatio。GET /api/v1/vms/{vmRef}/storage 返回单 VM 逻辑分配、VHDX 文件占用和客户机可见用量(支持时)。

{
  "storageProfileId": "default",
  "system": {"totalBytes": 1099511627776, "usedBytes": 500000000000, "reservedBytes": 102005473280, "availableBytes": 497506154496},
  "data": {"totalBytes": 2199023255552, "usedBytes": 800000000000, "reservedBytes": 53687091200, "availableBytes": 1345336164352},
  "quota": {"enabled": true, "systemLimitBytes": 1649267441664, "dataLimitBytes": 3298534883328, "overcommitRatio": 1.5}
}

超额销售只改变允许分配的逻辑上限,不创造物理空间。Agent 同时保留物理安全余量,超过配额或安全余量时创建返回 409。业务系统可提前展示容量,但最终以 Agent 原子校验为准。

POST /api/v1/vms/CS00100/bandwidth
{"uploadMbps":20,"downloadMbps":50}

// 0 表示不限制;字段单位为 Mbps,不是 MB/s。

快照与完整备份

快照是 Hyper-V 检查点,不等于异机备份。没有备份或备份目录不存在时,列表接口返回 200 + [],不是 502。备份恢复采用 preview/dry-run 安全预检;真实恢复能力应以当前 capabilities 和接口返回为准。

动作保护要求
恢复快照confirmVmId 必须匹配
备份恢复 preview只读检查备份完整性、VM 状态、路径与冲突
restore/dry-run要求 confirmVmId、confirmBackupName,并明确断电/安全备份/网络身份策略
删除备份使用幂等键;终态成功后才更新业务系统记录

实时与离线迁移

先查询 capabilities,再对指定 VM 执行 precheck。canProceed=false 时必须展示阻断项,不能绕过。实时迁移依赖 Hyper-V、域/Kerberos 或正确委派;离线迁移使用目标 Agent 的短时接收会话,可自动创建目标目录。

POST /api/v1/vms/CS00100/migration
{
  "confirmVmId": "CS00100",
  "destinationHost": "node02.example.com",
  "destinationStoragePath": "D:\\VHD\\System\\CS00100",
  "includeStorage": true,
  "mode": "offline",
  "shutdownTimeoutSeconds": 180,
  "startAfterMigration": true,
  "createDestinationDirectory": true,
  "switchMappings": {"fastmos_extranet_vmswitch":"fastmos_extranet_vmswitch"},
  "destinationAgentBaseUrl": "https://node02.example.com:8787",
  "destinationSessionId": "<短时会话ID>",
  "destinationTransferToken": "<一次性令牌>"
}

内部 receive-session 文件传输接口只允许节点间编排使用,不应直接暴露给会员端。迁移成功并核对目标 VM 后,业务系统才能修改节点归属;失败时保持原节点记录并按 result 判断回滚状态。

授权接口

GET /api/v1/license/status 返回 enabled、mode、status、valid、inGracePeriod、expiresAt、features、maxNodes、maxVms 和最近错误。IP 仅作审计,主要绑定机器指纹和节点 ID。

POST /api/v1/license/deactivate 用于受控换机/卸载前注销。强制模式下,Agent 服务端对开通、控制台、带宽、安全组、模板、远程访问、备份和迁移能力分别校验 feature,不能只靠 Manager 隐藏按钮。

统一错误结构与重试

{
  "error": {
    "code": "SECURITY_POLICY_HYPERV_FAILED",
    "message": "Hyper-V security policy application failed.",
    "retryable": false,
    "details": {
      "failureStage": "applying_security_policy",
      "operation": "Add-VMNetworkAdapterExtendedAcl",
      "sanitizedMessage": "<脱敏信息>",
      "rollbackAttempted": true,
      "rollbackSucceeded": true,
      "temporaryDenyRemoved": true
    }
  }
}
HTTP典型含义处理
400REQUEST_INVALID / 字段校验失败修正请求,不自动重试
401AUTH_HEADERS_INVALID核对 key、secret、时间、nonce、原始 body
403SOURCE_IP_FORBIDDEN / LICENSE_FEATURE_DISABLED人工核对来源与授权
404VM/TASK/BACKUP_NOT_FOUND核对节点和引用
409幂等冲突、revision 过期、存储配额不足、资源占用读取现状后决定新 revision/key
422模板或当前 VM 状态不兼容修改业务条件
502Hyper-V/Console/来宾执行失败读取脱敏 details,通常人工复核
503能力暂不可用、授权服务器不可用且无缓存按 retryable 退避重试
HTTP新增防护错误处理
413REQUEST_TOO_LARGE普通 API 请求体超过配置上限,默认 1 MiB;缩减请求正文,不原样重试。迁移文件 PUT 使用独立流式传输限制,不通过调大普通 JSON 上限解决。
429API_RATE_LIMITED按 Retry-After 退避(默认 1 秒),重新生成时间戳、nonce 和签名;重试同一业务动作保留原 Idempotency-Key,避免重复提交。

安全组专项错误包括 SECURITY_POLICY_INVALID、UNAVAILABLE、REVISION_STALE、REVISION_CONFLICT、EXTERNAL_NIC_CONFIGURATION_INVALID、SECURITY_POLICY_HYPERV_FAILED、VERIFY_FAILED、ROLLBACK_FAILED、TEMPORARY_DENY_REMAINS。Linux 创建/远程访问常见错误包括 LINUX_SSH_UNAVAILABLE、GUEST_READY_TIMEOUT;控制台常见错误包括 CONSOLE_ENCODER_START_FAILED、会话过期与 Origin 403。

日志允许保存:requestId、taskId、vmId、HTTP 状态、error.code、脱敏 message/details、请求体 SHA-256。
禁止保存:ApiSecret、License Key 全文、密码、控制台 token、完整请求正文、宿主机敏感路径、完整 PowerShell 命令。

业务系统必须实现清单

  1. 保存节点 ApiKeyId/ApiSecret,签名原始 JSON 字节;Secret 仅加密保存。
  2. 同步 templates、capabilities、host 和 storage profiles,imageCode 稳定持久化。
  3. 所有写操作生成 Idempotency-Key,保存 taskId 并轮询到终态。
  4. 创建时提交 nics、remoteAccess、bandwidth、securityPolicy;系统盘不得低于模板最小值。
  5. 只有 Agent succeeded 后才标记正式开通;Linux 必须通过 cloud-init/SSH 真实验证。
  6. 安全组只显示 visibleToUser=true 的客户规则。
  7. Console 过期后重新创建会话,不复用旧 token。
  8. 失败创建先查询 Agent 是否已有 VM,再决定 cleanup 或同步,禁止直接重复创建。
  9. 删除/迁移/恢复等危险操作必须使用 confirm 字段并保留审计。
  10. 展示存储与带宽时明确 GB/GiB、Mbps/MB/s 的单位差异。

版本与兼容说明

1.9.9.26 / R34:新建及重装后的新 VM 使用 StartIfRunning,只恢复宿主关闭前运行的机器;Agent.VmAutomaticStartDelaySeconds 基础延迟默认 30 秒,范围 0~300,非零时按名称增加稳定 0~30 秒错峰,总延迟不超过 300 秒;0 为无延迟。升级不调整任何已有 VM,不自动开机或删除旧测试机。域名证书使用 classic(有效期以 CA 实际签发为准,目前约 90 天),续签窗口 30 天;IP 保留 shortlived,续签窗口 3 天。保留证书两阶段、候选端点预检和失败回滚。Console 3.6.0.2 与最新 Viewer 完整封包,含票据解码、财务端重连入口和持续观看修复;旧 R33 下载包不含这些最新 VNC 修复。

版本主要变化
1.9.9.28新增 Windows 10 客户端模板自动首启:初始化管理员、网络及磁盘,清理临时初始化内容;新建 Windows 客户机关闭显示休眠并优化远程桌面。完整 R35 保留 VNC、限速和扩容组件,升级不重跑已有 VM 首启。
1.9.9.27控制台启动和管道通信增加有界等待、隔离健康/停止通道;改进会话回收、首帧自动显示与自动播放失败提示。Console 3.6.0.3 保留工具栏和多会话能力,不把 VM 的 Stopping 状态强行改成运行。
1.9.9.26新建/重装 VM 宿主重启自动恢复、稳定错峰启动;域名 classic/IP shortlived 证书分流;完整 R34 包纳入 Console 3.6.0.2 与最新 Viewer,保留已有 VM 设置和现网配置。
1.9.9.25受控任务并发(默认 1,可选 2),首启等待重叠、宿主重操作互斥;任务原子领取、单调计时与自适应就绪探测,独立完整磁盘暂存核对及拒绝覆盖。
1.9.9.24HTTPS 来源 IP 可选,保留 HMAC、时间戳、防重放及授权;节点自身 Origin 自动派生、请求限流/请求体限制及共享宿主监控采集。
1.9.9.23新开通 Linux 的控制台防黑屏设置和持久化验证;不重跑已有虚拟机首启脚本。
1.9.9.22验证 Hyper-V 网卡标识与 VM 归属,修复限速策略集成;独立域名 HTML 控制台兼容原接口。宿主以 Windows Server 2025 为主要目标。
1.9.9.21集成完整原生控制台与 viewerUrl,保留键盘/鼠标/工具栏功能,修复会话退出竞争与有界关闭。
1.9.9.20补齐正式 HTML5 控制台页面和发布内容;安装、打包及部署检查要求页面与 Console 组件齐全,避免缺页造成控制台 404。
1.9.9.19磁盘扩容自动正常关机、扩容验证和开机,执行过程持续显示“执行中”,开机确认后才完成;关机/开机失败保留可核对记录。
1.9.9.18修复 Windows 首启分区兼容性。
1.9.9.17新增受控磁盘增配、失败容量核对和 Windows/Linux 附加 IPv4 扩容;任务、配额及地址预留保持事务一致,安装包补齐执行脚本并移除生产参数。
1.9.9.16未填写 License Key 时仍可启动服务及完成基础设置,授权业务操作继续按授权策略校验。
1.9.9.15首次开通期间 VM 详情统一返回 provisioning/执行中状态,不再把 Hyper-V 瞬时 Off 写入 VM 生命周期;实际电源状态仅通过 actualPowerStatus 供诊断,任务完成后才展示最终 Running。
1.9.9.14新增 VM 硬件查询、CPU/静态内存升级预检与异步执行接口;仅支持增配,正常关机后变更,成功后恢复原电源状态,失败自动尝试回滚;同 VM 管理操作互斥。
1.9.9.13电源操作幂等键按已完成任务代际隔离:活动请求安全重放,任务终结后的第二次开机、关机或重启即使复用旧业务键也创建新任务。
1.9.9.12VM 详情实时核对 Hyper-V 电源状态;开机、关机、重启显示独立执行中状态并等待终态确认;网络开关幂等键按状态代际隔离,修复首次有效、第二次断网静默复用旧任务。
1.9.9.11分离 VM 电源状态与任务执行状态:VM 新增 powerStatus,任务新增 taskStatus、executionStatus;执行中展示值为 executing,不再与 VM Running 混淆。
1.9.9.10网络操作方向在排队、校验、重试和 Agent 重启恢复阶段显式保留,重复提交同状态操作时也不会反向显示。
1.9.9.9VM 详情新增断网/恢复联网执行中字段:operationStatus、operationTaskId、operationProgress、operationStage;保留原 state/status 兼容旧业务系统。
1.9.9.8恢复联网接受 reason=renewed,开启封禁仍严格拒绝该值。
1.9.9.7VM 详情新增根级断网状态:status=network_paused、networkStatus=paused、networkPaused=true;保留原 state 字段兼容旧业务系统。
1.9.9.6新增独立到期网络开关:公网网卡双向系统 Deny ACL、任务化启用/解除、SQLite 持久化、启动与周期自动恢复;系统规则不计入客户安全组上限,安全组和远程访问更新不会覆盖封禁;查询与变更错误码分别返回。
1.9.9.4新增 VM CPU、内存、网络速率和累计流量历史采集、SQLite 保留策略及按时间范围/采样间隔查询接口;修复本地化 Hyper-V WMI Caption 与 PowerShell 5.1 JSON 数组枚举导致批量采集不完整的问题。
1.9.9.1新增存储方案容量、单 VM 磁盘统计、系统盘/数据盘逻辑配额与超额销售安全校验;带宽接口纳入同一正式契约。
1.9.8.x离线迁移接收会话、授权节点生命周期、模板手动刷新与安装运营稳定化。
1.9.7.x备份查询、恢复 preview/dry-run、Linux 随机 SSH 端口、ssh.socket 兼容与详细回滚诊断。
1.8.x安全组、HTML5 控制台、带宽控制等能力形成正式异步接口。

1.9.9.28 / R35:Windows 10 Pro 22H2 简体中文模板使用 windows-10-pro-22h2-zh-cn,Generation 2,Microsoft Windows 安全启动,系统盘至少 80 GiB。先升级节点到 R35,再下载 VHDX、同名 Manifest 和 SHA-256 文件到节点模板目录并刷新模板。新建客户机自动完成管理员、网络和磁盘初始化;取消显示休眠、桌面背景及多余特效,关闭密码错误次数锁定;保留 NLA、Defender 和防火墙。模板不包含测试账号或固定部署密码。升级不会重新初始化已有 VM。

当前正式节点安装包:WE-Node-R35

组件版本说明
Agent1.9.9.28本页 API 基线;实际节点版本以 /health 为准。
Manager1.3.50节点基础设置、域名/证书配置与管理工具。
NodeInstaller0.1.15完整组件与配置权限检查;升级保留既有配置。
Console3.6.0.3完整 WebRTC HTML5 控制台、原生组件及运行依赖;signalUrl 不是 noVNC 的 RFB WebSocket。
TrafficGuard19.28.32.702签名驱动、控制工具及安装/升级/回滚脚本;安装包包含组件,不表示驱动已自动安装或已信任发布者。

授权站与在线文档独立发布,当前 License Server 0.2.40,不属于 R35 节点安装包。下载 R35 完整安装包,并用包内 RELEASE-MANIFEST.json 与 PACKAGE-SHA256SUMS.txt 核对版本和文件;不能只复制单个 EXE 后认定组件齐全。

宿主机与客户机兼容边界

宿主机:本次正式目标为 Windows Server 2025 + Hyper-V,完整组件在该宿主环境验收。Windows Server 2019 不在本次宿主兼容保证范围,尤其不保证 TrafficGuard 驱动可加载;不得通过关闭驱动签名校验或降低系统安全设置规避。

客户虚拟机:宿主机兼容范围不等于客户机系统限制。客户机可用系统与能力以模板的 imageCode、Manifest、最小磁盘容量及 capabilities 为准;Windows Server 2019 客户机与 Server 2019 宿主机是不同概念。新建 Linux 采用首启控制台防黑屏设置,升级 Agent 不会重跑已有 VM 首启脚本,也不会自动修改已有客户机的休眠配置。

配置权限与升级保留

当前安装器和 Manager 在标准配置写入流程中限制敏感配置、临时文件及备份的 ACL;管理员/SYSTEM 可访问,普通用户不能读取 API Secret 等凭据。配置文件权限过宽表示非必要账户可读,不表示接口可以免签名访问。不要将含凭据的配置放入下载站、源码或公开日志,也不要为排障给 Everyone/Users 开放读取权限。

升级保留既有 API 凭据、来源白名单和配置值,必要时收紧配置访问权限,不自动放开旧节点来源限制;Agent.MaxConcurrentTasks 默认为 1,可选 2,不因升级自动启用双任务。改用独立域名时分别配置 DNS、匹配域名的 HTTPS 证书和节点 URL,不能把多个节点固定跳转到同一被控。

兼容原则:不传新增可选字段保持旧行为;业务系统应忽略未知响应字段;不得根据展示名称替代稳定 imageCode;升级不要求迁移旧 VM,数据库变化由 Agent 自身兼容处理。