欢
10 KiB
CLICD 魔方财务对接模块
这是用于智简魔方 / IDCSMART 的 CLICD 服务器模块。模块通过 CLICD API 完成实例开通、删除、开关机、重启、重装、改密、资源变更、流量重置、NAT 端口映射管理、实例信息展示和 WebSSH 入口。
文件结构
clicd.php
README.md
handlers/
webssh.php
templates/
info.html
nat.html
安装时请保持目录结构不变，将整个 clicd 目录放入魔方服务器模块目录：
public/plugins/servers/clicd/
服务器配置
在魔方后台添加服务器时，模块名称选择 clicd。
CLICD 面板地址建议使用 HTTPS：
主机名 = https://0.0.0.0:8999
也可以拆分填写：
IP地址 = 0.0.0.0
端口 = 8999
secure = 开启
API Key 可以填写在以下任意一个字段中：
Hash
密码
模块请求 CLICD 时会同时携带：
X-API-Key: clicd_sk_xxxx
Authorization: Bearer clicd_sk_xxxx
Content-Type: application/json
产品配置项
| 字段 | 说明 |
|---|---|
virtualization |
虚拟化类型，lxc 或 kvm |
template_id |
CLICD 模板 / 镜像 ID |
vcpu |
CPU 核心数 |
cpu_percent |
CPU 使用率限制，0 表示不额外限制 |
ram_mb |
内存，单位 MB |
disk_gb |
系统盘，单位 GB |
network_bw_mbps |
带宽，单位 Mbps |
traffic_mode |
total 总流量，或 in_out 入 / 出分开 |
monthly_traffic_gb |
月流量 GB |
traffic_in_gb |
入站流量 GB，in_out 模式使用 |
traffic_out_gb |
出站流量 GB，in_out 模式使用 |
io_speed_mbps |
磁盘 IO 限制，0 表示不限制 |
port_mapping_count |
开通时分配的 NAT 端口数量，最小 2 |
snapshot_limit |
快照配额 |
extra_ports |
额外映射的容器端口，逗号分隔，例如 80,443 |
assign_ipv6 |
开通时是否自动分配 IPv6 |
sync_expiry |
是否同步魔方到期时间到 CLICD |
客户产品的 domain 会作为 CLICD 容器名称。模块会自动把不适合作为容器名的字符替换为 -。
开通后字段同步
开通、同步、重装、改密后，模块会从 CLICD 容器详情拉取最新信息并写回魔方主机表：
| 魔方字段 | 写入内容 |
|---|---|
dedicatedip |
NAT 外网 IP，优先使用 API 返回的公网字段，否则使用服务器 IP |
username |
固定写入 root |
password |
CLICD 返回的 SSH 密码，兼容魔方 cmf_encrypt() |
port |
CLICD 返回的 ssh_port |
domainstatus |
CLICD 状态为 running 时写 Active，否则写 Suspended |
如果接口返回的密码是 *** 这类脱敏值，模块不会覆盖魔方里已有密码。
客户区页面
模块提供两个客户区选项卡：
实例信息
NAT转发
客户区按钮提供：
WebSSH
实例信息
实例信息页展示：
- 实例名称、运行状态、SSH 地址、IPv6
- CPU、内存、负载、磁盘圆环状态
- 月流量进度
- CPU 使用率、内存使用、网络流量、磁盘 IO 图表
- IPv4、SSH 端口、SSH 密码、资源配置、到期时间
图表数据通过客户区懒加载接口获取，不会强制刷新整个魔方页面。页面首次打开会加载一次数据，之后由用户选择是否自动刷新：
不刷新
10 秒
1 分钟
5 分钟
10 分钟
也可以点击“立即刷新”手动刷新一次。当前 CLICD 用量接口返回的是实时值，不是历史数组；图表曲线由客户区前端持续采样生成。若需要打开页面立即显示历史曲线，需要 CLICD 额外提供历史指标接口。
流量显示支持智能单位，小流量会显示 B / KB / MB，大流量显示 GB，例如：
370.5 KB / 100 GB
模块会优先调用：
GET /api/v1/containers/{name}/usage
GET /api/v1/containers/{name}/traffic
如果 /api/v1/containers/{name}/usage 不可用，模块会在容器详情存在 uuid 时尝试兼容：
GET /api/containers/{uuid}/usage
已兼容的常见用量字段包括：
cpu_usage_pct
memory_usage_bytes
disk_usage_bytes
network_rx_bps
network_tx_bps
disk_read_bps
disk_write_bps
rx_used_bytes
tx_used_bytes
total_used_bytes
limit_gb
used_pct
NAT 转发
NAT 转发是独立页面，支持：
- 查看端口映射
- 获取随机可用端口
- 添加端口映射
- 修改端口映射
- 删除端口映射
删除端口映射时使用页面内确认弹窗，不使用浏览器自带确认框。
使用的 CLICD API：
GET /api/v1/containers/{id|uuid|name}
GET /api/v1/containers/{id}/random-port
POST /api/v1/containers/{id}/port-mappings
PUT /api/v1/containers/{id}/port-mappings/{index}
DELETE /api/v1/containers/{id}/port-mappings/{index}
添加 / 修改 NAT 映射时必须使用 JSON 请求体，例如：
{
"container_port": 8080,
"host_port": 61320,
"protocol": "tcp",
"description": "HTTP"
}
WebSSH
WebSSH 按钮会调用：
POST /api/v1/ssh-ticket
请求体：
{
"container_name": "example-vm"
}
接口返回 60 秒有效票据后，模块会打开本地 handler：
/plugins/servers/clicd/handlers/webssh.php
浏览器会从该页面直连 CLICD：
wss://0.0.0.0:8999/api/ssh?container=example-vm
Sec-WebSocket-Protocol: clicd-ticket.xxxxx
注意：WebSSH 受浏览器安全策略和 CLICD 后端 Origin 校验影响。魔方客户区通常是 HTTPS，因此 CLICD 面板也必须启用 HTTPS/WSS。请把魔方服务器配置里的 主机名 改为 https://0.0.0.0:8999，或把 secure 设为 开启。
新版 CLICD 已支持 WebSSH Origin 放行。部署时需要在 CLICD 后端把魔方财务客户区域名加入 WebSSH Origin 白名单，例如：
https://www.example.com
如果 WebSSH 页面显示 WebSocket error、Disconnected code=1006，但直接以 CLICD 自身 Origin 测试能返回 101 Switching Protocols，通常说明 CLICD 后端未放行魔方客户区域名的 WebSocket Origin。此时请检查 CLICD 的 WebSSH Origin 白名单配置；前端页面无法伪造浏览器 Origin。
支持的魔方操作
| 魔方操作 | CLICD API |
|---|---|
| 连接测试 | GET /api/v1/dashboard |
| 开通 | POST /api/v1/containers |
| 删除 | DELETE /api/v1/containers/{name}/delete |
| 开机 | POST /api/v1/containers/{name}/start |
| 关机 | POST /api/v1/containers/{name}/stop |
| 重启 | POST /api/v1/containers/{name}/restart |
| 重装 | POST /api/v1/containers/{name}/reinstall |
| 改密 | POST /api/v1/containers/{name}/reset-password |
| 重置流量 | POST /api/v1/containers/{name}/traffic-reset |
| 变更资源 | PUT /api/v1/containers/{name}/resource-limit |
| 变更流量 | PUT /api/v1/containers/{name}/traffic-limit |
| 同步到期 | PUT /api/v1/containers/{name}/expiry |
| WebSSH | POST /api/v1/ssh-ticket |
建议 API 权限
API Key 至少需要以下权限，具体名称以 CLICD 后端实际权限系统为准：
dashboard:read
container:read
container:create
container:power
container:delete
container:reinstall
container:password
container:traffic
container:resize
container:port
task:read
ssh-ticket:create
如果 API Key 使用 * 或 admin:*，通常可以覆盖上述权限。
建议先测试的 curl
连接测试：
curl -H "X-API-Key: clicd_sk_xxxx" \
https://0.0.0.0:8999/api/v1/dashboard
容器详情：
curl -H "X-API-Key: clicd_sk_xxxx" \
https://0.0.0.0:8999/api/v1/containers/example-vm
资源用量：
curl -H "X-API-Key: clicd_sk_xxxx" \
https://0.0.0.0:8999/api/v1/containers/example-vm/usage
流量统计：
curl -H "X-API-Key: clicd_sk_xxxx" \
https://0.0.0.0:8999/api/v1/containers/example-vm/traffic
修改 NAT：
curl --location --request PUT \
"https://0.0.0.0:8999/api/v1/containers/10/port-mappings/1" \
--header "X-API-Key: clicd_sk_xxxx" \
--header "Authorization: Bearer clicd_sk_xxxx" \
--header "Content-Type: application/json" \
--data-raw '{"container_port":8081,"host_port":61320,"protocol":"tcp","description":"HTTP"}'
创建 WebSSH 票据：
curl --location --request POST \
"https://0.0.0.0:8999/api/v1/ssh-ticket" \
--header "X-API-Key: clicd_sk_xxxx" \
--header "Content-Type: application/json" \
--data-raw '{"container_name":"example-vm"}'
常见问题
NAT 修改不生效
确认请求体必须是 JSON，不要使用 multipart/form-data。正确请求头：
Content-Type: application/json
图表刚打开只有一条横线
CLICD 当前用量接口返回的是实时值，不是历史序列。页面刚打开时只有一个采样点，所以会显示当前值横线。选择 10 秒 自动刷新或点击“立即刷新”多采样几次后，会逐步形成折线。
流量显示为 0
旧版本只显示 GB，小流量换算后会被四舍五入成 0 GB。当前版本已改为智能单位，会显示 B / KB / MB / GB。
WebSSH 打不开或提示不安全 WebSocket
请确认 CLICD 面板已经启用 HTTPS/WSS，并且魔方服务器配置使用 HTTPS：
server_host = https://0.0.0.0:8999
如果仍然使用 http://，模块会生成 ws:// 地址，HTTPS 客户区页面会被浏览器拦截。
如果 WSS 证书正常但仍返回 Forbidden 或浏览器显示 code=1006，请检查 CLICD 的 WebSSH Origin 白名单。新版 CLICD 已支持放行魔方财务域名，需要把魔方客户区访问域名完整加入白名单，例如：
https://www.example.com
注意需要填写浏览器实际访问魔方客户区时的协议和域名，http / https、带不带 www 都要与实际访问地址一致。
开通后魔方里的 IP、端口、密码不对
执行“同步状态”或重装 / 改密后，模块会重新拉取容器详情。请确认 CLICD 容器详情接口能返回：
ssh_port
ssh_password
status
公网 IP 优先使用 nat_public_ip/public_ip/host_ip/external_ip/node_ip/nat_host 等字段；如果接口没有返回，则使用魔方服务器配置的 IP。