CLICD/Mofang/README.md

# CLICD 魔方财务对接模块

这是用于智简魔方 / IDCSMART 的 CLICD 服务器模块。模块通过 CLICD API 完成实例开通、删除、开关机、重启、重装、改密、资源变更、流量重置、NAT 端口映射管理、实例信息展示和 WebSSH 入口。

## 文件结构

```text
clicd.php
README.md
handlers/
  webssh.php
templates/
  firewall.html
  info.html
  nat.html
```

安装时请保持目录结构不变，将整个 `clicd` 目录放入魔方服务器模块目录：

```text
public/plugins/servers/clicd/
```

## 服务器配置

在魔方后台添加服务器时，模块名称选择 `clicd`。

CLICD 面板地址建议使用 HTTPS：

```text
主机名 = https://0.0.0.0:8999
```

也可以拆分填写：

```text
IP地址 = 0.0.0.0
端口      = 8999
secure    = 开启
```

API Key 可以填写在以下任意一个字段中：

```text
Hash
密码
```

模块请求 CLICD 时会同时携带：

```text
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` |

如果接口返回的密码是 `***` 这类脱敏值，模块不会覆盖魔方里已有密码。

## 客户区页面

模块提供三个客户区选项卡：

```text
实例信息
NAT转发
防火墙
```

客户区按钮提供：

```text
WebSSH
```

## 实例信息

实例信息页展示：

- 实例名称、运行状态、SSH 地址、IPv6
- CPU、内存、负载、磁盘圆环状态
- 月流量进度
- CPU 使用率、内存使用、网络流量、磁盘 IO 图表
- IPv4、SSH 端口、SSH 密码、资源配置、到期时间

图表数据通过客户区懒加载接口获取，不会强制刷新整个魔方页面。页面首次打开会加载一次数据，之后由用户选择是否自动刷新：

```text
不刷新
10 秒
1 分钟
5 分钟
10 分钟
```

也可以点击“立即刷新”手动刷新一次。当前 CLICD 用量接口返回的是实时值，不是历史数组；图表曲线由客户区前端持续采样生成。若需要打开页面立即显示历史曲线，需要 CLICD 额外提供历史指标接口。

流量显示支持智能单位，小流量会显示 B / KB / MB，大流量显示 GB，例如：

```text
370.5 KB / 100 GB
```

模块会优先调用：

```text
GET /api/v1/containers/{name}/usage
GET /api/v1/containers/{name}/traffic
```

如果 `/api/v1/containers/{name}/usage` 不可用，模块会在容器详情存在 `uuid` 时尝试兼容：

```text
GET /api/containers/{uuid}/usage
```

已兼容的常见用量字段包括：

```text
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：

```text
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 请求体，例如：

```json
{
  "container_port": 8080,
  "host_port": 61320,
  "protocol": "tcp",
  "description": "HTTP"
}
```

## 防火墙

防火墙是独立客户区页面，支持：

- 查看防火墙启用状态、默认动作和规则列表
- 启用 / 停用防火墙
- 设置默认动作：未匹配拒绝或未匹配放行
- 添加规则
- 编辑规则
- 删除规则
- 单独启用 / 停用某条规则

页面会先在前端修改规则列表和开关状态，点击“保存设置”后才统一同步到 CLICD。这样可以避免每次切换开关、修改默认动作或编辑规则时都立即请求后端，减少客户区卡顿。

注意：防火墙关闭时也可以保存规则；关闭只表示暂时不接管该容器流量，不代表规则必须清空。

使用的 CLICD API：

```text
GET /api/v1/containers/{id}/firewall
PUT /api/v1/containers/{id}/firewall
```

更新防火墙时必须使用 JSON 请求体，例如：

```json
{
  "enabled": true,
  "default_action": "ACCEPT",
  "rules": [
    {
      "id": "",
      "network": "ipv4",
      "direction": "in",
      "protocol": "tcp",
      "port": "22",
      "source_ip": "",
      "action": "ACCEPT",
      "description": "Allow SSH",
      "enabled": true
    }
  ]
}
```

规则字段说明：

| 字段 | 说明 |
| --- | --- |
| `network` | 网络范围，常用 `ipv4`，也支持 `ipv6` / `all` |
| `direction` | 方向，`in` 入站，`out` 出站 |
| `protocol` | 协议，`tcp` 或 `udp` |
| `port` | 端口，可填写单端口、逗号分隔端口或端口段，例如 `22`、`80,443`、`8000-9000` |
| `source_ip` | 来源 IP / CIDR，留空表示任意来源 |
| `action` | 动作，`ACCEPT` 放行，`DROP` 拒绝 |
| `description` | 规则描述 |
| `enabled` | 是否启用该规则 |

IPv4 NAT 入站规则的端口按容器内部端口匹配，不是宿主机公网端口。例如公网 `22023 -> 容器 22`，防火墙规则端口应填写 `22`。
## WebSSH

WebSSH 按钮会调用：

```text
POST /api/v1/ssh-ticket
```

请求体：

```json
{
  "container_name": "example-vm"
}
```

接口返回 60 秒有效票据后，模块会打开本地 handler：

```text
/plugins/servers/clicd/handlers/webssh.php
```

浏览器会从该页面直连 CLICD：

```text
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 白名单，例如：

```text
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` |
| 查询防火墙 | `GET /api/v1/containers/{id}/firewall` |
| 更新防火墙 | `PUT /api/v1/containers/{id}/firewall` |
| WebSSH | `POST /api/v1/ssh-ticket` |

## 建议 API 权限

API Key 至少需要以下权限，具体名称以 CLICD 后端实际权限系统为准：

```text
dashboard:read
container:read
container:create
container:power
container:delete
container:reinstall
container:password
container:traffic
container:resize
container:port
container:firewall
task:read
ssh-ticket:create
```

如果 API Key 使用 `*` 或 `admin:*`，通常可以覆盖上述权限。

## 建议先测试的 curl

连接测试：

```bash
curl -H "X-API-Key: clicd_sk_xxxx" \
  https://0.0.0.0:8999/api/v1/dashboard
```

容器详情：

```bash
curl -H "X-API-Key: clicd_sk_xxxx" \
  https://0.0.0.0:8999/api/v1/containers/example-vm
```

资源用量：

```bash
curl -H "X-API-Key: clicd_sk_xxxx" \
  https://0.0.0.0:8999/api/v1/containers/example-vm/usage
```

流量统计：

```bash
curl -H "X-API-Key: clicd_sk_xxxx" \
  https://0.0.0.0:8999/api/v1/containers/example-vm/traffic
```

修改 NAT：

```bash
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"}'
```

查询防火墙：

```bash
curl -H "X-API-Key: clicd_sk_xxxx" \
  https://0.0.0.0:8999/api/v1/containers/10/firewall
```

更新防火墙：

```bash
curl --location --request PUT \
  "https://0.0.0.0:8999/api/v1/containers/10/firewall" \
  --header "X-API-Key: clicd_sk_xxxx" \
  --header "Content-Type: application/json" \
  --data-raw '{"enabled":true,"default_action":"ACCEPT","rules":[{"id":"","network":"ipv4","direction":"in","protocol":"tcp","port":"22","source_ip":"","action":"ACCEPT","description":"Allow SSH","enabled":true}]}'
```
创建 WebSSH 票据：

```bash
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`。正确请求头：

```text
Content-Type: application/json
```

### 防火墙获取提示“不支持的方法”

请确认模块版本已经包含防火墙页签修复。客户区防火墙列表应通过模块公开的 `firewallList` 调用，再由模块向 CLICD 发起：

```text
GET /api/v1/containers/{id}/firewall
```

如果页面或二开代码直接把读取请求改成 `POST /api/v1/containers/{id}/firewall`，CLICD 会返回“不支持的方法”。

### 防火墙保存后规则为空

请确认更新接口最终发往 CLICD 的请求体是 JSON，并且包含 `rules` 数组。防火墙关闭时也可以保存规则，`enabled: false` 不应自动清空 `rules`。

正确请求体示例：

```json
{
  "enabled": false,
  "default_action": "ACCEPT",
  "rules": [
    {
      "id": "",
      "network": "ipv4",
      "direction": "in",
      "protocol": "tcp",
      "port": "22",
      "source_ip": "",
      "action": "ACCEPT",
      "description": "Allow SSH",
      "enabled": true
    }
  ]
}
```
### 图表刚打开只有一条横线

CLICD 当前用量接口返回的是实时值，不是历史序列。页面刚打开时只有一个采样点，所以会显示当前值横线。选择 `10 秒` 自动刷新或点击“立即刷新”多采样几次后，会逐步形成折线。

### 流量显示为 0

旧版本只显示 GB，小流量换算后会被四舍五入成 `0 GB`。当前版本已改为智能单位，会显示 B / KB / MB / GB。

### 防火墙

防火墙是独立客户区页面，支持：

- 查看防火墙启用状态、默认动作和规则列表
- 启用 / 停用防火墙
- 设置默认动作：未匹配拒绝或未匹配放行
- 添加规则
- 编辑规则
- 删除规则
- 单独启用 / 停用某条规则

页面会先在前端修改规则列表和开关状态，点击“保存设置”后才统一同步到 CLICD。这样可以避免每次切换开关、修改默认动作或编辑规则时都立即请求后端，减少客户区卡顿。

注意：防火墙关闭时也可以保存规则；关闭只表示暂时不接管该容器流量，不代表规则必须清空。

使用的 CLICD API：

```text
GET /api/v1/containers/{id}/firewall
PUT /api/v1/containers/{id}/firewall
```

更新防火墙时必须使用 JSON 请求体，例如：

```json
{
  "enabled": true,
  "default_action": "ACCEPT",
  "rules": [
    {
      "id": "",
      "network": "ipv4",
      "direction": "in",
      "protocol": "tcp",
      "port": "22",
      "source_ip": "",
      "action": "ACCEPT",
      "description": "Allow SSH",
      "enabled": true
    }
  ]
}
```

规则字段说明：

| 字段 | 说明 |
| --- | --- |
| `network` | 网络范围，常用 `ipv4`，也支持 `ipv6` / `all` |
| `direction` | 方向，`in` 入站，`out` 出站 |
| `protocol` | 协议，`tcp` 或 `udp` |
| `port` | 端口，可填写单端口、逗号分隔端口或端口段，例如 `22`、`80,443`、`8000-9000` |
| `source_ip` | 来源 IP / CIDR，留空表示任意来源 |
| `action` | 动作，`ACCEPT` 放行，`DROP` 拒绝 |
| `description` | 规则描述 |
| `enabled` | 是否启用该规则 |

IPv4 NAT 入站规则的端口按容器内部端口匹配，不是宿主机公网端口。例如公网 `22023 -> 容器 22`，防火墙规则端口应填写 `22`。
## WebSSH 打不开或提示不安全 WebSocket

请确认 CLICD 面板已经启用 HTTPS/WSS，并且魔方服务器配置使用 HTTPS：

```text
server_host = https://0.0.0.0:8999
```

如果仍然使用 `http://`，模块会生成 `ws://` 地址，HTTPS 客户区页面会被浏览器拦截。

如果 WSS 证书正常但仍返回 `Forbidden` 或浏览器显示 `code=1006`，请检查 CLICD 的 WebSSH Origin 白名单。新版 CLICD 已支持放行魔方财务域名，需要把魔方客户区访问域名完整加入白名单，例如：

```text
https://www.example.com
```

注意需要填写浏览器实际访问魔方客户区时的协议和域名，`http` / `https`、带不带 `www` 都要与实际访问地址一致。

### 开通后魔方里的 IP、端口、密码不对

执行“同步状态”或重装 / 改密后，模块会重新拉取容器详情。请确认 CLICD 容器详情接口能返回：

```text
ssh_port
ssh_password
status
```

公网 IP 优先使用 `nat_public_ip/public_ip/host_ip/external_ip/node_ip/nat_host` 等字段；如果接口没有返回，则使用魔方服务器配置的 IP。