{"openapi":"3.1.0","info":{"title":"Asset Workspace API","version":"1.0.0","description":"缓存优先的域名 / IP 工作台。使用 Bearer API 密钥或登录 Session；云配置与登录密码不能读回。"},"servers":[{"url":"/"}],"paths":{"/api/setup/status":{"get":{"operationId":"getSetupStatus","summary":"首次配置状态","security":[],"description":"请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}}}},"/api/setup":{"post":{"operationId":"initializeWorkspace","summary":"首次使用时设置管理员账号和密码，自动登录","security":[],"description":"请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"parameters":[{"name":"X-CSRF-Token","in":"header","required":true,"schema":{"type":"string"},"description":"先 GET /api/setup/status 获取，同时保留 Cookie"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"string"},"password":{"type":"string","format":"password","writeOnly":true}},"required":["user","password"]}}}}}},"/api/login":{"post":{"operationId":"login","summary":"账号密码登录，返回 Session 和 CSRF Token","security":[],"description":"请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"user":{"type":"string"},"csrf_token":{"type":"string"}}}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"string"},"pass":{"type":"string","format":"password","writeOnly":true}},"required":["user","pass"]}}}}}},"/api/me":{"get":{"operationId":"getIdentity","summary":"读取当前登录身份","security":[{"bearerAuth":[]},{"sessionCookie":[]}],"description":"请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}}}},"/api/logout":{"post":{"operationId":"logout","summary":"退出管理员会话","security":[{"sessionCookie":[]}],"description":"仅管理员登录会话可调用。使用 Cookie 会话时必须传 X-CSRF-Token；有效 Bearer Token 不需要 CSRF。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"parameters":[{"name":"X-CSRF-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Cookie 会话写入时必填；Bearer 调用不需要"}]}},"/api/health":{"get":{"operationId":"getHealthSnapshot","summary":"读取缓存健康看板、子域名和 IP 关系","security":[{"bearerAuth":[]},{"sessionCookie":[]}],"description":"Bearer 权限：assets:read。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object","properties":{"assets":{"type":"array","items":{"$ref":"#/components/schemas/Asset"}},"summary":{"type":"object"},"cache":{"type":"object"}}}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"x-required-scopes":["assets:read"]}},"/api/health/check":{"post":{"operationId":"checkHealth","summary":"检查 1–5 项资产并保存结果","security":[{"bearerAuth":[]},{"sessionCookie":[]}],"description":"Bearer 权限：checks:run。使用 Cookie 会话时必须传 X-CSRF-Token；有效 Bearer Token 不需要 CSRF。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"x-required-scopes":["checks:run"],"parameters":[{"name":"X-CSRF-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Cookie 会话写入时必填；Bearer 调用不需要"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"asset_ids":{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string"}}},"required":["asset_ids"]}}}}}},"/api/health/ips":{"post":{"operationId":"createIpAsset","summary":"登记公网 IP 检查目标","security":[{"bearerAuth":[]},{"sessionCookie":[]}],"description":"Bearer 权限：assets:write。使用 Cookie 会话时必须传 X-CSRF-Token；有效 Bearer Token 不需要 CSRF。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"x-required-scopes":["assets:write"],"parameters":[{"name":"X-CSRF-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Cookie 会话写入时必填；Bearer 调用不需要"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ip":{"type":"string","description":"公网 IPv4 或 IPv6 字面量"},"port":{"type":"integer","minimum":1,"maximum":65535,"default":443},"name":{"type":"string"}},"required":["ip"]}}}}}},"/api/health/ips/{id}":{"put":{"operationId":"updateIpAsset","summary":"编辑 IP 资产资料","security":[{"bearerAuth":[]},{"sessionCookie":[]}],"description":"Bearer 权限：assets:write。使用 Cookie 会话时必须传 X-CSRF-Token；有效 Bearer Token 不需要 CSRF。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"x-required-scopes":["assets:write"],"parameters":[{"name":"id","in":"path","required":true,"description":"从列表响应取得的标识","schema":{"type":"string"}},{"name":"X-CSRF-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Cookie 会话写入时必填；Bearer 调用不需要"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"note":{"type":"string"},"server_provider":{"type":"string"},"expires_at":{"type":"string"}}}}}}},"delete":{"operationId":"deleteIpAsset","summary":"移除手工登记的 IP 目标","security":[{"bearerAuth":[]},{"sessionCookie":[]}],"description":"Bearer 权限：assets:write。使用 Cookie 会话时必须传 X-CSRF-Token；有效 Bearer Token 不需要 CSRF。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"x-required-scopes":["assets:write"],"parameters":[{"name":"id","in":"path","required":true,"description":"从列表响应取得的标识","schema":{"type":"string"}},{"name":"X-CSRF-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Cookie 会话写入时必填；Bearer 调用不需要"}]}},"/api/health/domains/{id}/bindings":{"put":{"operationId":"saveDomainBindings","summary":"保存域名与服务器的人工确认绑定","security":[{"bearerAuth":[]},{"sessionCookie":[]}],"description":"Bearer 权限：assets:write。使用 Cookie 会话时必须传 X-CSRF-Token；有效 Bearer Token 不需要 CSRF。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"x-required-scopes":["assets:write"],"parameters":[{"name":"id","in":"path","required":true,"description":"从列表响应取得的标识","schema":{"type":"string"}},{"name":"X-CSRF-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Cookie 会话写入时必填；Bearer 调用不需要"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ip_ids":{"type":"array","items":{"type":"string"}}},"required":["ip_ids"]}}}}}},"/api/domains":{"get":{"operationId":"listDomains","summary":"查询本地缓存域名台账","security":[{"bearerAuth":[]},{"sessionCookie":[]}],"description":"Bearer 权限：assets:read。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"x-required-scopes":["assets:read"],"parameters":[{"name":"provider","in":"query","required":false,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"schema":{"type":"string"}},{"name":"valid","in":"query","required":false,"schema":{"type":"string","enum":["0","1"]}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["expire","expire_desc","domain","synced"]}},{"name":"expiring","in":"query","required":false,"schema":{"type":"string"}},{"name":"access","in":"query","required":false,"schema":{"type":"string"}},{"name":"all","in":"query","required":false,"schema":{"type":"string","enum":["1"]}}]},"post":{"operationId":"createDomain","summary":"添加本地域名台账，不购买域名","security":[{"bearerAuth":[]},{"sessionCookie":[]}],"description":"Bearer 权限：assets:write。使用 Cookie 会话时必须传 X-CSRF-Token；有效 Bearer Token 不需要 CSRF。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"x-required-scopes":["assets:write"],"parameters":[{"name":"X-CSRF-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Cookie 会话写入时必填；Bearer 调用不需要"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","description":"云账号 ID 或 manual"},"domain":{"type":"string"},"status":{"type":"string"},"expire_at":{"type":"string","description":"YYYY-MM-DD 或空字符串"},"registration_date":{"type":"string"},"registrar":{"type":"string"},"note":{"type":"string"},"valid":{"type":"boolean"}},"required":["provider","domain"]}}}}},"put":{"operationId":"updateDomain","summary":"编辑本地域名台账，不修改云端 DNS","security":[{"bearerAuth":[]},{"sessionCookie":[]}],"description":"Bearer 权限：assets:write。使用 Cookie 会话时必须传 X-CSRF-Token；有效 Bearer Token 不需要 CSRF。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"x-required-scopes":["assets:write"],"parameters":[{"name":"X-CSRF-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Cookie 会话写入时必填；Bearer 调用不需要"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","description":"云账号 ID 或 manual"},"domain":{"type":"string"},"status":{"type":"string"},"expire_at":{"type":"string","description":"YYYY-MM-DD 或空字符串"},"registration_date":{"type":"string"},"registrar":{"type":"string"},"note":{"type":"string"},"valid":{"type":"boolean"}},"required":["provider","domain"]}}}}},"delete":{"operationId":"deleteDomain","summary":"删除本地域名台账，不删除云端域名","security":[{"bearerAuth":[]},{"sessionCookie":[]}],"description":"Bearer 权限：assets:write。使用 Cookie 会话时必须传 X-CSRF-Token；有效 Bearer Token 不需要 CSRF。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"x-required-scopes":["assets:write"],"parameters":[{"name":"X-CSRF-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Cookie 会话写入时必填；Bearer 调用不需要"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string"},"domain":{"type":"string"}},"required":["provider","domain"]}}}}}},"/api/domains/stats":{"get":{"operationId":"getDomainStats","summary":"读取域名统计","security":[{"bearerAuth":[]},{"sessionCookie":[]}],"description":"Bearer 权限：assets:read。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"x-required-scopes":["assets:read"]}},"/api/domains/{provider}/{domain}/records":{"get":{"operationId":"listDnsRecords","summary":"读取并缓存解析记录；refresh=1 显式刷新云端","security":[{"bearerAuth":[]},{"sessionCookie":[]}],"description":"Bearer 权限：dns:read。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"x-required-scopes":["dns:read"],"parameters":[{"name":"provider","in":"path","required":true,"description":"云账号 ID，例如 aliyun_1；从域名列表读取，不能填 aliyun","schema":{"type":"string"}},{"name":"domain","in":"path","required":true,"description":"从列表响应取得的标识","schema":{"type":"string"}},{"name":"refresh","in":"query","required":false,"schema":{"type":"string","enum":["1"]}}]},"post":{"operationId":"createDnsRecord","summary":"新增云端 DNS 解析记录","security":[{"bearerAuth":[]},{"sessionCookie":[]}],"description":"Bearer 权限：dns:write。使用 Cookie 会话时必须传 X-CSRF-Token；有效 Bearer Token 不需要 CSRF。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"x-required-scopes":["dns:write"],"parameters":[{"name":"provider","in":"path","required":true,"description":"云账号 ID，例如 aliyun_1；从域名列表读取，不能填 aliyun","schema":{"type":"string"}},{"name":"domain","in":"path","required":true,"description":"从列表响应取得的标识","schema":{"type":"string"}},{"name":"X-CSRF-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Cookie 会话写入时必填；Bearer 调用不需要"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","NS","SRV","CAA"]},"name":{"type":"string","description":"相对主机记录，例如 @、www、api"},"value":{"type":"string"},"ttl":{"type":"integer","default":600},"priority":{"type":"integer","default":0},"line":{"type":"string","default":"默认"}},"required":["type","name","value"]}}}}}},"/api/domains/{provider}/{domain}/records/{recordId}":{"put":{"operationId":"updateDnsRecord","summary":"修改云端解析，保留未请求修改的字段","security":[{"bearerAuth":[]},{"sessionCookie":[]}],"description":"Bearer 权限：dns:write。使用 Cookie 会话时必须传 X-CSRF-Token；有效 Bearer Token 不需要 CSRF。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"x-required-scopes":["dns:write"],"parameters":[{"name":"provider","in":"path","required":true,"description":"云账号 ID，例如 aliyun_1；从域名列表读取，不能填 aliyun","schema":{"type":"string"}},{"name":"domain","in":"path","required":true,"description":"从列表响应取得的标识","schema":{"type":"string"}},{"name":"recordId","in":"path","required":true,"description":"从列表响应取得的标识","schema":{"type":"string"}},{"name":"X-CSRF-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Cookie 会话写入时必填；Bearer 调用不需要"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","NS","SRV","CAA"]},"name":{"type":"string","description":"相对主机记录，例如 @、www、api"},"value":{"type":"string"},"ttl":{"type":"integer","default":600},"priority":{"type":"integer","default":0},"line":{"type":"string","default":"默认"}},"required":["type","name","value"]}}}}},"delete":{"operationId":"deleteDnsRecord","summary":"删除云端 DNS 记录","security":[{"bearerAuth":[]},{"sessionCookie":[]}],"description":"Bearer 权限：dns:write。使用 Cookie 会话时必须传 X-CSRF-Token；有效 Bearer Token 不需要 CSRF。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"x-required-scopes":["dns:write"],"parameters":[{"name":"provider","in":"path","required":true,"description":"云账号 ID，例如 aliyun_1；从域名列表读取，不能填 aliyun","schema":{"type":"string"}},{"name":"domain","in":"path","required":true,"description":"从列表响应取得的标识","schema":{"type":"string"}},{"name":"recordId","in":"path","required":true,"description":"从列表响应取得的标识","schema":{"type":"string"}},{"name":"X-CSRF-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Cookie 会话写入时必填；Bearer 调用不需要"}]}},"/api/domains/{provider}/{domain}/records/access-check":{"post":{"operationId":"checkDnsHosts","summary":"检查解析记录对应的主机访问状态","security":[{"bearerAuth":[]},{"sessionCookie":[]}],"description":"Bearer 权限：checks:run。使用 Cookie 会话时必须传 X-CSRF-Token；有效 Bearer Token 不需要 CSRF。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"x-required-scopes":["checks:run"],"parameters":[{"name":"provider","in":"path","required":true,"description":"云账号 ID，例如 aliyun_1；从域名列表读取，不能填 aliyun","schema":{"type":"string"}},{"name":"domain","in":"path","required":true,"description":"从列表响应取得的标识","schema":{"type":"string"}},{"name":"X-CSRF-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Cookie 会话写入时必填；Bearer 调用不需要"}]}},"/api/accounts":{"get":{"operationId":"listCloudAccounts","summary":"列出云账号标识和脱敏信息","security":[{"bearerAuth":[]},{"sessionCookie":[]}],"description":"Bearer 权限：assets:read。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"array","items":{"type":"object"}}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"x-required-scopes":["assets:read"]},"post":{"operationId":"createCloudAccount","summary":"添加云账号配置","security":[{"sessionCookie":[]}],"description":"仅管理员登录会话可调用。使用 Cookie 会话时必须传 X-CSRF-Token；有效 Bearer Token 不需要 CSRF。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"},"201":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}}},"parameters":[{"name":"X-CSRF-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Cookie 会话写入时必填；Bearer 调用不需要"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["aliyun","tencent","godaddy"]},"name":{"type":"string"},"enabled":{"type":"boolean"},"access_key_id":{"type":"string","format":"password","writeOnly":true},"access_key_secret":{"type":"string","format":"password","writeOnly":true},"secret_id":{"type":"string","format":"password","writeOnly":true},"secret_key":{"type":"string","format":"password","writeOnly":true},"api_key":{"type":"string","format":"password","writeOnly":true},"api_secret":{"type":"string","format":"password","writeOnly":true}},"required":["name","provider"],"oneOf":[{"properties":{"provider":{"const":"aliyun"}},"required":["access_key_id","access_key_secret"]},{"properties":{"provider":{"const":"tencent"}},"required":["secret_id","secret_key"]},{"properties":{"provider":{"const":"godaddy"}},"required":["api_key","api_secret"]}]}}}}}},"/api/accounts/{id}":{"put":{"operationId":"updateCloudAccount","summary":"编辑云账号；密钥留空保留，enabled=false 停用","security":[{"sessionCookie":[]}],"description":"仅管理员登录会话可调用。使用 Cookie 会话时必须传 X-CSRF-Token；有效 Bearer Token 不需要 CSRF。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"parameters":[{"name":"id","in":"path","required":true,"description":"从列表响应取得的标识","schema":{"type":"string"}},{"name":"X-CSRF-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Cookie 会话写入时必填；Bearer 调用不需要"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["aliyun","tencent","godaddy"]},"name":{"type":"string"},"enabled":{"type":"boolean"},"access_key_id":{"type":"string","format":"password","writeOnly":true},"access_key_secret":{"type":"string","format":"password","writeOnly":true},"secret_id":{"type":"string","format":"password","writeOnly":true},"secret_key":{"type":"string","format":"password","writeOnly":true},"api_key":{"type":"string","format":"password","writeOnly":true},"api_secret":{"type":"string","format":"password","writeOnly":true}}}}}}}},"/api/accounts/{id}/test":{"post":{"operationId":"testCloudAccount","summary":"测试云账号连接","security":[{"bearerAuth":[]},{"sessionCookie":[]}],"description":"Bearer 权限：sync:run。使用 Cookie 会话时必须传 X-CSRF-Token；有效 Bearer Token 不需要 CSRF。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"x-required-scopes":["sync:run"],"parameters":[{"name":"id","in":"path","required":true,"description":"从列表响应取得的标识","schema":{"type":"string"}},{"name":"X-CSRF-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Cookie 会话写入时必填；Bearer 调用不需要"}]}},"/api/test-all":{"post":{"operationId":"testAllCloudAccounts","summary":"测试全部云账号连接","security":[{"bearerAuth":[]},{"sessionCookie":[]}],"description":"Bearer 权限：sync:run。使用 Cookie 会话时必须传 X-CSRF-Token；有效 Bearer Token 不需要 CSRF。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"array","items":{"type":"object"}}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"x-required-scopes":["sync:run"],"parameters":[{"name":"X-CSRF-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Cookie 会话写入时必填；Bearer 调用不需要"}]}},"/api/sync":{"post":{"operationId":"syncDomains","summary":"显式同步云端域名列表","security":[{"bearerAuth":[]},{"sessionCookie":[]}],"description":"Bearer 权限：sync:run。使用 Cookie 会话时必须传 X-CSRF-Token；有效 Bearer Token 不需要 CSRF。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"x-required-scopes":["sync:run"],"parameters":[{"name":"X-CSRF-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Cookie 会话写入时必填；Bearer 调用不需要"}]}},"/api/sync/logs":{"get":{"operationId":"getSyncLogs","summary":"读取同步记录","security":[{"bearerAuth":[]},{"sessionCookie":[]}],"description":"Bearer 权限：assets:read。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"x-required-scopes":["assets:read"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}]}},"/api/access-check":{"get":{"operationId":"getLegacyAccessResults","summary":"读取历史访问检查结果","security":[{"bearerAuth":[]},{"sessionCookie":[]}],"description":"Bearer 权限：assets:read。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"x-required-scopes":["assets:read"]},"post":{"operationId":"runLegacyAccessCheck","summary":"运行域名访问检查","security":[{"bearerAuth":[]},{"sessionCookie":[]}],"description":"Bearer 权限：checks:run。使用 Cookie 会话时必须传 X-CSRF-Token；有效 Bearer Token 不需要 CSRF。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"x-required-scopes":["checks:run"],"parameters":[{"name":"X-CSRF-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Cookie 会话写入时必填；Bearer 调用不需要"}]}},"/api/settings":{"get":{"operationId":"getWorkspaceSettings","summary":"读取当前配置状态和可配置字段（不回显秘密）","security":[{"sessionCookie":[]}],"description":"仅管理员登录会话可调用。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}}}},"/api/settings/http":{"put":{"operationId":"updateHttpSettings","summary":"更新云商接口代理与超时","security":[{"sessionCookie":[]}],"description":"仅管理员登录会话可调用。使用 Cookie 会话时必须传 X-CSRF-Token；有效 Bearer Token 不需要 CSRF。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"parameters":[{"name":"X-CSRF-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Cookie 会话写入时必填；Bearer 调用不需要"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"proxy":{"type":"string","format":"password","writeOnly":true},"clear_proxy":{"type":"boolean"},"timeout":{"type":"integer","minimum":5,"maximum":120},"connect_timeout":{"type":"integer","minimum":1,"maximum":30}}}}}}}},"/api/auth/credentials":{"put":{"operationId":"updateAdminCredentials","summary":"修改管理员账号和密码；会话和旧 API 密钥失效","security":[{"sessionCookie":[]}],"description":"仅管理员登录会话可调用。使用 Cookie 会话时必须传 X-CSRF-Token；有效 Bearer Token 不需要 CSRF。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"parameters":[{"name":"X-CSRF-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Cookie 会话写入时必填；Bearer 调用不需要"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"current_password":{"type":"string","format":"password","writeOnly":true},"user":{"type":"string"},"password":{"type":"string","format":"password","writeOnly":true}},"required":["current_password","user","password"]}}}}}},"/api/tokens":{"get":{"operationId":"listApiTokens","summary":"列出密钥元数据和可授权范围","security":[{"sessionCookie":[]}],"description":"仅管理员登录会话可调用。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}}},"post":{"operationId":"createApiToken","summary":"创建 API 密钥，仅此次返回明文","security":[{"sessionCookie":[]}],"description":"仅管理员登录会话可调用。使用 Cookie 会话时必须传 X-CSRF-Token；有效 Bearer Token 不需要 CSRF。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"},"201":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}}},"parameters":[{"name":"X-CSRF-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Cookie 会话写入时必填；Bearer 调用不需要"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"current_password":{"type":"string","format":"password","writeOnly":true},"name":{"type":"string"},"scopes":{"type":"array","minItems":1,"items":{"type":"string","enum":["assets:read","assets:write","dns:read","dns:write","checks:run","sync:run"]}},"expires_in_days":{"type":"integer","minimum":1,"maximum":365,"default":90}},"required":["name","current_password"]}}}}}},"/api/tokens/{id}":{"delete":{"operationId":"revokeApiToken","summary":"撤销 API 密钥，立即停止后续调用","security":[{"sessionCookie":[]}],"description":"仅管理员登录会话可调用。使用 Cookie 会话时必须传 X-CSRF-Token；有效 Bearer Token 不需要 CSRF。请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}},"parameters":[{"name":"id","in":"path","required":true,"description":"从列表响应取得的标识","schema":{"type":"string"}},{"name":"X-CSRF-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Cookie 会话写入时必填；Bearer 调用不需要"}]}},"/api/openapi.json":{"get":{"operationId":"getOpenApi","summary":"读取完整接口契约","security":[],"description":"请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}}}},"/api/capabilities":{"get":{"operationId":"getCapabilities","summary":"读取 AI 能力与认证说明","security":[],"description":"请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}}}},"/api/env-check":{"get":{"operationId":"checkRuntimeEnvironment","summary":"读取安装环境诊断","security":[],"description":"请求失败时检查 HTTP 状态以及响应 ok:false。","responses":{"200":{"description":"成功（业务失败需检查 ok:false）","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未登录或密钥无效"},"403":{"description":"权限不足或 CSRF 无效"},"409":{"description":"状态冲突"},"422":{"description":"参数验证失败"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"aw_<64 hex>","description":"在产品设置创建，按 scopes 授权"},"sessionCookie":{"type":"apiKey","in":"cookie","name":"AW_aa3aee1912f1","description":"先 POST /api/login；写请求另传 X-CSRF-Token"}},"schemas":{"Asset":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["domain","ip"]},"name":{"type":"string"},"provider":{"type":"string"},"ip":{"type":"string"},"ip_version":{"type":"string","enum":["IPv4","IPv6"]},"port":{"type":"integer"},"linked_ips":{"type":"array","items":{"type":"string"}},"bound_ips":{"type":"array","items":{"type":"string"}},"subdomain_count":{"type":["integer","null"]},"subdomains":{"type":"array","items":{"type":"object"}},"health":{"type":"object","properties":{"status":{"type":"string","enum":["healthy","unhealthy","stale","unchecked"]},"message":{"type":"string"},"checked_at":{"type":["string","null"]}}}},"required":["id","kind","name","health"]}}}}