Add comprehensive documentation for CLICD features and operations

- Introduced Container Management documentation covering lifecycle operations, resource management, and console access. - Added Dashboard documentation detailing metrics and related APIs. - Created Host Report documentation summarizing host environment and resource status. - Included Image Management documentation for template handling and management actions. - Documented Networking and Routing features including NAT4 and IPv6 management. - Added Security Alerts documentation outlining alert scenarios and API usage. - Created Snapshot Management documentation for snapshot operations and scheduling. - Documented Sub-user management for granting access to specific containers. - Added Configuration guide detailing runtime settings and security recommendations. - Created Installation guide for setting up CLICD with requirements and steps. - Added Introduction and Quick Start guides for new users. - Documented Upgrade process with version checking and pre-upgrade checklist. - Created Deployment guide for service exposure and firewall recommendations. - Added FAQ section addressing common questions and concerns. - Documented Troubleshooting steps for common issues encountered.
2026-08-06 05:52:19 +08:00 · 2026-06-10 00:42:06 +08:00
parent e71adf6830
commit a45e063fc2
29 changed files with 2332 additions and 122 deletions
@@ -0,0 +1,674 @@
+# API Integration
+
+CLICD remains compatible with legacy `/api` endpoints, so existing integrations do not need to change. New integrations should use `/api/v1`; the list below is all v1, and the recommended container list endpoint is `GET /api/v1/containers`.
+
+## Authentication
+
+API keys can be created and managed from the API Integration page. Requests support either of these headers:
+
+```bash
+curl -H "X-API-Key: YOUR_API_KEY" https://panel.example.com/api/v1/containers
+```
+
+```bash
+curl -H "Authorization: Bearer YOUR_API_KEY" https://panel.example.com/api/v1/dashboard
+```
+
+## Response Shape
+
+All APIs use the same response envelope:
+
+```json
+{
+  "success": true,
+  "message": "OK",
+  "data": {}
+}
+```
+
+Integrations should read only the business fields they need. New capabilities are added as optional fields where possible, without requiring existing plugins to rename current fields.
+
+## Creation and Reinstall
+
+Container creation, batch creation, reinstall, and batch reinstall support mixed NAT, public IPv4, IPv6 networking, plus Linux SSH login configuration. Public IPv4/IPv6 pools can be viewed with `GET /api/v1/routing` and updated with `PUT /api/v1/routing`.
+
+Create container example:
+
+```json
+{
+  "name": "demo-lxc-01",
+  "virtualization": "lxc",
+  "template_id": "debian-bookworm",
+  "vcpu": 1,
+  "ram_mb": 512,
+  "disk_gb": 10,
+  "assign_nat": true,
+  "port_mapping_count": 2,
+  "assign_ipv4": false,
+  "ipv4_count": 1,
+  "public_ipv4s": [],
+  "assign_ipv6": true,
+  "ipv6_count": 1,
+  "ipv6_addresses": [],
+  "ssh_auth_mode": "auto_password",
+  "ssh_password": "",
+  "ssh_public_key": "",
+  "expires_at": ""
+}
+```
+
+Field notes:
+
+| Field | Description |
+| --- | --- |
+| `assign_nat` | Whether to allocate NAT port mappings. If omitted, default NAT behavior is preserved. |
+| `assign_ipv4` | Whether to allocate public IPv4. |
+| `ipv4_count` | Number of public IPv4 addresses to allocate automatically. |
+| `public_ipv4s` | Explicit public IPv4 address list. |
+| `assign_ipv6` | Whether to allocate IPv6. |
+| `ipv6_count` | Number of IPv6 addresses to allocate automatically. |
+| `ipv6_addresses` | Explicit IPv6 address list. |
+| `ssh_auth_mode` | Linux creation supports `auto_password`, `password`, and `key`; reinstall also supports `keep`. |
+| `ssh_password` | Custom password for `password` mode. It must be 8-64 characters, include letters and digits, and contain no whitespace. |
+| `ssh_public_key` | One-line SSH public key for `key` mode. |
+
+Reinstall example:
+
+```json
+{
+  "template_id": "debian-bookworm",
+  "ssh_auth_mode": "keep",
+  "ssh_password": "",
+  "ssh_public_key": ""
+}
+```
+
+`keep` is only for reinstall and keeps the current SSH password. Windows KVM images ignore Linux SSH public key fields.
+
+## Python Example
+
+Fetch containers:
+
+```python
+import requests
+
+BASE_URL = "https://panel.example.com"
+API_KEY = "YOUR_API_KEY"
+
+session = requests.Session()
+session.headers.update({
+    "X-API-Key": API_KEY,
+    "Content-Type": "application/json",
+})
+
+resp = session.get(f"{BASE_URL}/api/v1/containers", timeout=15)
+resp.raise_for_status()
+print(resp.json())
+```
+
+Create a port mapping:
+
+```python
+import requests
+
+BASE_URL = "https://panel.example.com"
+API_KEY = "YOUR_API_KEY"
+CONTAINER_ID = "example-vm"
+
+payload = {
+    "protocol": "tcp",
+    "host_port": 18080,
+    "container_port": 80,
+    "description": "web",
+}
+
+resp = requests.post(
+    f"{BASE_URL}/api/v1/containers/{CONTAINER_ID}/port-mappings",
+    headers={"X-API-Key": API_KEY},
+    json=payload,
+    timeout=15,
+)
+resp.raise_for_status()
+print(resp.json())
+```
+
+## Endpoint List
+
+### Overview
+
+| Method | Path | Description |
+| --- | --- | --- |
+| GET | `/api/v1/dashboard` | Dashboard statistics |
+| GET | `/api/v1/host-info` | Host resources |
+| GET | `/api/v1/routing` | NAT/IPv4/IPv6 routing |
+| PUT | `/api/v1/routing` | Update public IPv4/IPv6 pools |
+| POST | `/api/v1/routing/ipv4-scan` | Scan a public IPv4 segment |
+| GET | `/api/v1/ipv6/status` | IPv6 status |
+| GET | `/api/v1/tasks` | Task queue |
+| DELETE | `/api/v1/tasks/{task_id}` | Delete a task |
+
+### Containers
+
+| Method | Path | Description |
+| --- | --- | --- |
+| GET | `/api/v1/containers` | Container list |
+| POST | `/api/v1/containers/list` | Compatible POST form for container list |
+| POST | `/api/v1/containers` | Create container |
+| GET | `/api/v1/containers/{id|uuid|name}` | Container details |
+| POST | `/api/v1/containers/{id}/start` | Start |
+| POST | `/api/v1/containers/{id}/stop` | Stop |
+| POST | `/api/v1/containers/{id}/restart` | Restart |
+| POST | `/api/v1/containers/{id}/reinstall` | Reinstall |
+| DELETE | `/api/v1/containers/{id}/delete` | Delete |
+| GET | `/api/v1/containers/{id}/usage` | Resource usage |
+| GET | `/api/v1/containers/{id}/traffic` | Traffic statistics |
+| POST | `/api/v1/containers/{id}/traffic-reset` | Reset traffic |
+| PUT | `/api/v1/containers/{id}/traffic-limit` | Update traffic limits |
+| PUT | `/api/v1/containers/{id}/resource-limit` | Update resource limits |
+| PUT | `/api/v1/containers/{id}/expiry` | Update expiration time |
+| POST | `/api/v1/containers/{id}/reset-password` | Reset SSH password |
+| POST | `/api/v1/containers/{id}/ipv6` | Assign IPv6 |
+
+### Ports and Snapshots
+
+| Method | Path | Description |
+| --- | --- | --- |
+| GET | `/api/v1/containers/{id}/random-port` | Random available port |
+| POST | `/api/v1/containers/{id}/port-mappings` | Add port mapping |
+| PUT | `/api/v1/containers/{id}/port-mappings/{index}` | Update port mapping |
+| DELETE | `/api/v1/containers/{id}/port-mappings/{index}` | Delete port mapping |
+| GET | `/api/v1/snapshots` | Snapshot overview |
+| GET | `/api/v1/containers/{id}/snapshots` | Container snapshots |
+| POST | `/api/v1/containers/{id}/snapshots` | Create snapshot |
+| DELETE | `/api/v1/containers/{id}/snapshots/{snapshot_id}` | Delete snapshot |
+| POST | `/api/v1/containers/{id}/snapshots/{snapshot_id}/restore` | Restore snapshot |
+| POST | `/api/v1/containers/{id}/snapshots/schedule` | Schedule snapshots |
+| PUT | `/api/v1/containers/{id}/snapshots/quota` | Snapshot quota |
+
+### Platform Management
+
+| Method | Path | Description |
+| --- | --- | --- |
+| GET | `/api/v1/templates` | Template list |
+| GET | `/api/v1/images` | Image management list |
+| POST | `/api/v1/images/download` | Download image |
+| POST | `/api/v1/images/cancel` | Cancel image download |
+| DELETE | `/api/v1/images/delete` | Delete image cache |
+| PUT | `/api/v1/images/toggle` | Enable or disable image |
+| GET | `/api/v1/security/alerts` | Security alerts |
+| POST | `/api/v1/security/check` | Run security check |
+| GET | `/api/v1/security/logs?container={name}` | Security connection logs |
+| GET | `/api/v1/security/summary` | Security summary |
+| GET | `/api/v1/security/settings` | Security settings |
+| PUT | `/api/v1/security/settings` | Update security settings |
+| GET | `/api/v1/swap` | Swap information |
+| POST | `/api/v1/swap` | Adjust Swap |
+| POST | `/api/v1/batch-create` | Batch create containers |
+| POST | `/api/v1/batch-action` | Batch power action, delete, or reinstall |
+| POST | `/api/v1/ssh-ticket` | Create WebSSH ticket |
+| POST | `/api/v1/vnc-ticket` | Create WebVNC ticket |
+
+### Accounts and Logs
+
+| Method | Path | Description |
+| --- | --- | --- |
+| POST | `/api/v1/sub-user/create` | Create sub-user link |
+| GET | `/api/v1/sub-users` | Sub-user list |
+| POST | `/api/v1/sub-users/{id}/rotate-password` | Rotate sub-user password |
+| GET | `/api/v1/sub-users/{id}/audit-logs` | Sub-user audit logs |
+| GET | `/api/v1/sub-users/{id}/login-logs` | Sub-user login logs |
+| GET | `/api/v1/audit-logs` | Audit logs |
+| GET | `/api/v1/login-logs` | Login logs |
+| GET | `/api/v1/api-keys` | API key list |
+| POST | `/api/v1/api-keys` | Create API key |
+| PATCH | `/api/v1/api-keys/{id}` | Update API key |
+| DELETE | `/api/v1/api-keys/{id}` | Delete API key |
+
+## Response Samples
+
+The samples below are grouped by endpoint path. Resource numbers, task IDs, container IDs, timestamps, IP addresses, and keys will differ in real environments. Passwords, tickets, and API keys are masked.
+
+### Overview
+
+```json
+{
+  "GET /api/v1/dashboard": {
+    "success": true,
+    "data": {
+      "running": 31,
+      "stopped": 0,
+      "total_containers": 31
+    }
+  },
+  "GET /api/v1/host-info": {
+    "success": true,
+    "data": {
+      "cpu": { "cores": 8, "usage_pct": 1.16 },
+      "ram": { "total_mb": 31825, "used_mb": 1275, "free_mb": 30550 },
+      "disk": { "total_gb": 1750.49, "used_gb": 123.98, "free_gb": 1626.51 },
+      "network": {
+        "public_ipv4": "203.0.113.10",
+        "public_ipv4_interface": "eth0",
+        "public_ipv6": "2001:db8:100::2",
+        "public_ipv6_interface": "eth0"
+      },
+      "load": { "load1": 0.01, "load5": 0.03, "load15": 0.01 }
+    }
+  },
+  "GET /api/v1/routing": {
+    "success": true,
+    "data": {
+      "nat4": { "used": 62, "remaining": "45474", "total": "45536" },
+      "ipv4": { "used": 1, "remaining": "3", "total": "4" },
+      "ipv6": { "used": 31, "remaining": "large", "total": "large" },
+      "public_ipv4_addresses": [
+        { "address": "203.0.113.10", "interface": "eth0", "prefix_len": 32, "gateway": "203.0.113.1" }
+      ],
+      "ipv4_assignments": [
+        { "container_id": 5, "container_name": "example-vm", "address": "203.0.113.10", "interface": "eth0", "prefix_len": 32, "gateway": "203.0.113.1" }
+      ],
+      "nat4_mappings": [
+        { "container_id": 5, "container_name": "example-vm", "status": "running", "ip": "10.0.0.10", "host_port": 22004, "container_port": 22, "protocol": "tcp" }
+      ],
+      "ipv6_assignments": [
+        { "container_id": 5, "container_name": "example-vm", "address": "2001:db8:100::1005", "prefix_len": 64, "interface": "eth0" }
+      ]
+    }
+  },
+  "PUT /api/v1/routing": {
+    "success": true,
+    "data": {
+      "ipv4": { "used": 1, "remaining": "3", "total": "4" },
+      "public_ipv4_addresses": [
+        { "address": "203.0.113.10", "interface": "eth0", "prefix_len": 32, "gateway": "203.0.113.1" }
+      ],
+      "ipv6_prefixes": [
+        { "interface": "eth0", "address": "2001:db8:100::2", "prefix": "2001:db8:100::/64", "prefix_len": 64, "gateway": "2001:db8:100::1" }
+      ]
+    }
+  },
+  "POST /api/v1/routing/ipv4-scan": {
+    "success": true,
+    "data": [
+      { "address": "203.0.113.10", "interface": "eth0", "prefix_len": 32, "gateway": "203.0.113.1", "status": "available", "usable": true, "reason": "" }
+    ]
+  },
+  "GET /api/v1/ipv6/status": {
+    "success": true,
+    "data": {
+      "available": true,
+      "reachable": true,
+      "reason": "usable public IPv6 prefix detected",
+      "prefixes": [
+        { "interface": "eth0", "address": "2001:db8:100::2", "prefix": "2001:db8:100::/64", "prefix_len": 64, "gateway": "2001:db8:100::1" }
+      ]
+    }
+  },
+  "GET /api/v1/tasks": {
+    "success": true,
+    "data": []
+  },
+  "DELETE /api/v1/tasks/{task_id}": {
+    "success": true,
+    "message": "Task deleted"
+  }
+}
+```
+
+### Containers
+
+```json
+{
+  "GET /api/v1/containers": {
+    "success": true,
+    "data": [
+      {
+        "id": 5,
+        "uuid": "00000000-0000-4000-8000-000000000005",
+        "name": "example-vm",
+        "virtualization": "lxc",
+        "template": "debian-bullseye",
+        "vcpu": 1,
+        "ram_mb": 512,
+        "disk_gb": 10,
+        "status": "running",
+        "ip": "10.0.0.10",
+        "ipv6": "2001:db8:100::1005",
+        "ssh_port": 22004,
+        "ssh_password": "***",
+        "port_mappings": [
+          { "container_port": 22, "host_port": 22004, "protocol": "tcp", "description": "SSH" },
+          { "container_port": 20000, "host_port": 20000, "protocol": "tcp", "description": "Port-20000" }
+        ]
+      }
+    ]
+  },
+  "POST /api/v1/containers/list": {
+    "success": true,
+    "data": [
+      { "id": 5, "uuid": "00000000-0000-4000-8000-000000000005", "name": "example-vm", "status": "running", "ip": "10.0.0.10" }
+    ]
+  },
+  "POST /api/v1/containers": {
+    "success": true,
+    "message": "Container created successfully"
+  },
+  "GET /api/v1/containers/{id|uuid|name}": {
+    "success": true,
+    "data": {
+      "id": 5,
+      "uuid": "00000000-0000-4000-8000-000000000005",
+      "name": "example-vm",
+      "status": "running",
+      "ip": "10.0.0.10",
+      "ipv6": "2001:db8:100::1005",
+      "ssh_port": 22004,
+      "ssh_password": "***",
+      "policy_blocked": false
+    }
+  },
+  "POST /api/v1/containers/{id}/start": {
+    "success": true,
+    "message": "Task queued",
+    "data": { "task_id": "task-10", "container_name": "example-vm", "status": "pending", "action": "start" }
+  },
+  "POST /api/v1/containers/{id}/stop": {
+    "success": true,
+    "message": "Task queued",
+    "data": { "task_id": "task-10", "container_name": "example-vm", "status": "pending", "action": "stop" }
+  },
+  "POST /api/v1/containers/{id}/restart": {
+    "success": true,
+    "message": "Task queued",
+    "data": { "task_id": "task-10", "container_name": "example-vm", "status": "pending", "action": "restart" }
+  },
+  "POST /api/v1/containers/{id}/reinstall": {
+    "success": true,
+    "message": "Task queued",
+    "data": { "task_id": "task-10", "container_name": "example-vm", "status": "pending", "action": "reinstall" }
+  },
+  "DELETE /api/v1/containers/{id}/delete": {
+    "success": true,
+    "message": "Task queued",
+    "data": { "task_id": "task-10", "container_name": "example-vm", "status": "pending", "action": "delete" }
+  },
+  "GET /api/v1/containers/{id}/usage": {
+    "success": true,
+    "data": {
+      "cpu_usage_pct": 0,
+      "cpu_usage_usec": 3908852,
+      "memory_usage_bytes": 29331456,
+      "disk_usage_bytes": 515100672,
+      "network_rx_bytes": 131232,
+      "network_tx_bytes": 16828,
+      "load1": 0.1,
+      "load5": 0.06,
+      "load15": 0.01
+    }
+  },
+  "GET /api/v1/containers/{id}/traffic": {
+    "success": true,
+    "data": {
+      "mode": "total",
+      "limit_gb": 0,
+      "in_limit_gb": 0,
+      "out_limit_gb": 0,
+      "total_used_bytes": 142082,
+      "rx_used_bytes": 127212,
+      "tx_used_bytes": 14870,
+      "used_pct": 0,
+      "reset_date": "2026-06"
+    }
+  },
+  "POST /api/v1/containers/{id}/traffic-reset": {
+    "success": true,
+    "message": "Traffic reset"
+  },
+  "PUT /api/v1/containers/{id}/traffic-limit": {
+    "success": true,
+    "message": "Traffic limit updated"
+  },
+  "PUT /api/v1/containers/{id}/resource-limit": {
+    "success": true,
+    "message": "Resource limits updated"
+  },
+  "PUT /api/v1/containers/{id}/expiry": {
+    "success": true,
+    "message": "Expiry updated"
+  },
+  "POST /api/v1/containers/{id}/reset-password": {
+    "success": true,
+    "message": "SSH password reset successfully",
+    "data": { "password": "***" }
+  },
+  "POST /api/v1/containers/{id}/ipv6": {
+    "success": true,
+    "message": "IPv6 assigned",
+    "data": { "id": 5, "name": "example-vm", "ipv6": "2001:db8:100::1005" }
+  }
+}
+```
+
+### Ports and Snapshots
+
+```json
+{
+  "GET /api/v1/containers/{id}/random-port": {
+    "success": true,
+    "data": { "port": 61320 }
+  },
+  "POST /api/v1/containers/{id}/port-mappings": {
+    "success": true,
+    "data": [
+      { "container_port": 22, "host_port": 22004, "protocol": "tcp", "description": "SSH" },
+      { "container_port": 8080, "host_port": 61320, "protocol": "tcp", "description": "HTTP" }
+    ]
+  },
+  "PUT /api/v1/containers/{id}/port-mappings/{index}": {
+    "success": true,
+    "data": [
+      { "container_port": 8081, "host_port": 61320, "protocol": "tcp", "description": "HTTP" }
+    ]
+  },
+  "DELETE /api/v1/containers/{id}/port-mappings/{index}": {
+    "success": true,
+    "data": []
+  },
+  "GET /api/v1/snapshots": {
+    "success": true,
+    "data": null
+  },
+  "GET /api/v1/containers/{id}/snapshots": {
+    "success": true,
+    "data": {
+      "quota": 1,
+      "schedule": { "enabled": false, "interval_hours": 0, "last_run": "", "next_run": "", "time": "", "created_by": "" },
+      "snapshots": []
+    }
+  },
+  "POST /api/v1/containers/{id}/snapshots": {
+    "success": true,
+    "data": {
+      "id": "snap-20260608-001",
+      "container_id": 5,
+      "container_name": "example-vm",
+      "created_at": "2026-06-08 16:00:00",
+      "created_by": "api:Automation",
+      "scheduled": false,
+      "size_bytes": 10485760
+    }
+  },
+  "DELETE /api/v1/containers/{id}/snapshots/{snapshot_id}": {
+    "success": true,
+    "message": "Snapshot deleted"
+  },
+  "POST /api/v1/containers/{id}/snapshots/{snapshot_id}/restore": {
+    "success": true,
+    "message": "Snapshot restored"
+  },
+  "POST /api/v1/containers/{id}/snapshots/schedule": {
+    "success": true,
+    "data": {
+      "container": { "id": 5, "name": "example-vm", "snapshot_schedule_enabled": true, "snapshot_schedule_interval_hours": 24, "snapshot_schedule_time": "03:00" }
+    }
+  },
+  "PUT /api/v1/containers/{id}/snapshots/quota": {
+    "success": true,
+    "data": {
+      "quota": 2,
+      "container": { "id": 5, "name": "example-vm", "snapshot_limit": 2 }
+    }
+  }
+}
+```
+
+### Platform Management
+
+```json
+{
+  "GET /api/v1/templates": {
+    "success": true,
+    "data": [
+      { "id": "ubuntu-noble", "name": "Ubuntu 24.04", "distro": "ubuntu", "release": "noble", "arch": "amd64", "description": "Ubuntu 24.04 LTS" },
+      { "id": "debian-bookworm", "name": "Debian 12", "distro": "debian", "release": "bookworm", "arch": "amd64", "description": "Debian 12 (Bookworm)" }
+    ]
+  },
+  "GET /api/v1/images": {
+    "success": true,
+    "data": [
+      { "id": "ubuntu-noble", "name": "Ubuntu 24.04", "type": "lxc", "downloaded": true, "enabled": true, "downloading": false, "progress": 0, "size_bytes": 135005452 }
+    ]
+  },
+  "POST /api/v1/images/download": {
+    "success": true,
+    "message": "Already downloaded"
+  },
+  "POST /api/v1/images/cancel": {
+    "success": true,
+    "message": "Cancel requested"
+  },
+  "DELETE /api/v1/images/delete": {
+    "success": true,
+    "message": "Deleted"
+  },
+  "PUT /api/v1/images/toggle": {
+    "success": true,
+    "message": "OK"
+  },
+  "GET /api/v1/security/alerts": {
+    "success": true,
+    "data": []
+  },
+  "POST /api/v1/security/check": {
+    "success": true,
+    "message": "Security check completed"
+  },
+  "GET /api/v1/security/logs?container={name}": {
+    "success": true,
+    "data": []
+  },
+  "GET /api/v1/security/summary": {
+    "success": true,
+    "data": { "critical": 0, "high": 0, "medium": 0, "low": 0, "total_alerts": 0 }
+  },
+  "GET /api/v1/security/settings": {
+    "success": true,
+    "data": { "auto_shutdown": false }
+  },
+  "PUT /api/v1/security/settings": {
+    "success": true,
+    "data": { "auto_shutdown": false }
+  },
+  "GET /api/v1/swap": {
+    "success": true,
+    "data": { "total_mb": 16383, "used_mb": 0, "free_mb": 16383, "enabled": true, "swap_file": "/swapfile" }
+  },
+  "POST /api/v1/swap": {
+    "success": true,
+    "message": "SWAP 已调整为 16384 MB",
+    "data": { "total_mb": 16383, "used_mb": 0, "free_mb": 16383, "enabled": true, "swap_file": "/swapfile" }
+  },
+  "POST /api/v1/batch-create": {
+    "success": true,
+    "data": ["task-12"]
+  },
+  "POST /api/v1/batch-action": {
+    "success": true,
+    "data": ["task-13"]
+  },
+  "POST /api/v1/ssh-ticket": {
+    "success": true,
+    "data": { "ticket": "***60 seconds valid***" }
+  },
+  "POST /api/v1/vnc-ticket": {
+    "success": true,
+    "data": { "ticket": "***60 seconds valid***" }
+  }
+}
+```
+
+### Accounts and Logs
+
+```json
+{
+  "POST /api/v1/sub-user/create": {
+    "success": true,
+    "message": "Sub-user created",
+    "data": {
+      "id": "sub-xxxxxxxx",
+      "username": "user-xxxxxxxx",
+      "password": "***",
+      "container_names": ["example-vm"],
+      "access_code": "********",
+      "created_at": "2026-06-08 16:00:00"
+    }
+  },
+  "GET /api/v1/sub-users": {
+    "success": true,
+    "data": []
+  },
+  "POST /api/v1/sub-users/{id}/rotate-password": {
+    "success": true,
+    "data": { "username": "user-xxxxxxxx", "password": "***", "access_code": "********" }
+  },
+  "GET /api/v1/sub-users/{id}/audit-logs": {
+    "success": true,
+    "data": []
+  },
+  "GET /api/v1/sub-users/{id}/login-logs": {
+    "success": true,
+    "data": []
+  },
+  "GET /api/v1/audit-logs": {
+    "success": true,
+    "data": [
+      { "time": "2026-06-08 15:44:40", "action": "apikey.create", "target": "Test", "detail": "scopes=*", "user": "admin", "success": true }
+    ]
+  },
+  "GET /api/v1/login-logs": {
+    "success": true,
+    "data": [
+      { "time": "2026-06-08 08:24:00 UTC", "username": "admin", "ip": "198.51.100.23", "user_agent": "Mozilla/5.0 ...", "success": true }
+    ]
+  },
+  "GET /api/v1/api-keys": {
+    "success": true,
+    "data": [
+      { "id": "c271023f", "name": "Test", "prefix": "clicd_sk_dd9d...", "ip_whitelist": "", "created_at": "2026-06-08 15:44:40", "last_used": "2026-06-08 15:46:10", "scopes": ["*"], "last_used_ip": "198.51.100.23" }
+    ]
+  },
+  "POST /api/v1/api-keys": {
+    "success": true,
+    "message": "API key created. Save this key now - it won't be shown again.",
+    "data": { "id": "a1b2c3d4", "name": "Automation", "key": "clicd_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "prefix": "clicd_sk_xxxx...", "scopes": ["dashboard:read", "container:read"] }
+  },
+  "PATCH /api/v1/api-keys/{id}": {
+    "success": true,
+    "data": { "id": "a1b2c3d4", "name": "Automation", "prefix": "clicd_sk_xxxx...", "scopes": ["dashboard:read", "container:read"], "disabled": false }
+  },
+  "DELETE /api/v1/api-keys/{id}": {
+    "success": true,
+    "message": "API key deleted"
+  }
+}
+```
@@ -0,0 +1,83 @@
+# Container Management
+
+Container Management is the core CLICD module. It covers creation, lifecycle operations, resource limits, network mappings, traffic statistics, password resets, and console access.
+
+## Container List
+
+The list page scans container status. Administrators can view all containers. Sub-users only see containers within their authorization scope.
+
+Common fields include:
+
+- ID, UUID, and name.
+- Virtualization type.
+- Runtime status.
+- IP and IPv6.
+- CPU, memory, and disk limits.
+- Traffic usage and traffic limits.
+- Expiration time.
+
+## Create Containers
+
+Creation requires a template and resource quotas. Batch creation is available from the panel or API and is useful for issuing multiple containers at once.
+
+```http
+POST /api/v1/containers
+POST /api/v1/batch-create
+```
+
+Linux containers and Linux KVM virtual machines support SSH login configuration during creation:
+
+- `auto_password`: generate a root SSH password automatically.
+- `password`: use a custom `ssh_password`.
+- `key`: write a one-line `ssh_public_key`; a password is still kept for WebSSH.
+
+Network allocation can combine NAT, public IPv4, and IPv6 as needed. API fields such as `assign_nat`, `assign_ipv4`, `public_ipv4s`, `assign_ipv6`, and `ipv6_addresses` are optional. If they are omitted, default behavior is preserved.
+
+## Lifecycle Operations
+
+```http
+POST /api/v1/containers/{id}/start
+POST /api/v1/containers/{id}/stop
+POST /api/v1/containers/{id}/restart
+POST /api/v1/containers/{id}/reinstall
+DELETE /api/v1/containers/{id}/delete
+```
+
+Start, stop, reinstall, and delete actions enter the task queue. Call `GET /api/v1/tasks` afterwards to check execution status.
+
+When reinstalling a Linux system, you may pass `ssh_auth_mode`, `ssh_password`, and `ssh_public_key`. `ssh_auth_mode=keep` keeps the current SSH password. If these fields are omitted, the old behavior is preserved.
+
+## Resources and Traffic
+
+The container details page supports resource usage, traffic limit changes, resource limit changes, and expiration changes.
+
+```http
+GET /api/v1/containers/{id}/usage
+GET /api/v1/containers/{id}/traffic
+POST /api/v1/containers/{id}/traffic-reset
+PUT /api/v1/containers/{id}/traffic-limit
+PUT /api/v1/containers/{id}/resource-limit
+PUT /api/v1/containers/{id}/expiry
+```
+
+## NAT Port Management
+
+The NAT port management section supports adding, editing, and deleting mappings. Add and edit actions use a dialog so name, protocol, external port, and internal port can be filled in together.
+
+```http
+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}
+```
+
+In sub-user mode, administrators can limit sub-users to changing only the internal port, preventing changes to the host-facing port and protocol.
+
+## Remote Console
+
+```http
+POST /api/v1/ssh-ticket
+POST /api/v1/vnc-ticket
+```
+
+Tickets are short-lived. Use them immediately for WebSSH or WebVNC and do not persist them.
@@ -0,0 +1,27 @@
+# Dashboard
+
+The dashboard shows the overall state of the host and virtualization resources.
+
+## Metrics
+
+- Total containers, running containers, and stopped containers.
+- CPU, memory, disk, and Swap overview.
+- Entry points for host network and routing status.
+- Task queue status.
+- Security alert summary.
+
+## Related APIs
+
+```http
+GET /api/v1/dashboard
+GET /api/v1/host-info
+GET /api/v1/routing
+GET /api/v1/ipv6/status
+GET /api/v1/tasks
+```
+
+API requests must include an API key:
+
+```bash
+curl -H "X-API-Key: YOUR_API_KEY" https://panel.example.com/api/v1/dashboard
+```
@@ -0,0 +1,21 @@
+# Host Report
+
+The host report summarizes the host runtime environment, resource status, and virtualization dependencies. It is useful for post-installation checks, troubleshooting, or sharing environment information with maintainers.
+
+## Contents
+
+- System version and kernel information.
+- CPU, memory, disk, and Swap.
+- Network status.
+- LXC/KVM dependency status.
+- CLICD service status.
+
+## Related APIs
+
+```http
+GET /api/v1/host-report
+GET /api/v1/host-info
+GET /api/v1/swap
+```
+
+Before sending a report externally, check whether it contains public IPs, private networks, usernames, keys, tickets, or business domains.
@@ -0,0 +1,29 @@
+# Image Management
+
+Image Management maintains templates used to create containers or virtual machines.
+
+## Supported Template Types
+
+The project includes common Linux distribution templates such as Debian, Ubuntu, Alpine, CentOS, Fedora, Arch Linux, and Rocky Linux. KVM templates use the corresponding distribution cloud image resources.
+
+## Management Actions
+
+```http
+GET /api/v1/templates
+GET /api/v1/images
+POST /api/v1/images/download
+POST /api/v1/images/cancel
+DELETE /api/v1/images/delete
+PUT /api/v1/images/toggle
+```
+
+- `templates` returns available template definitions.
+- `images` returns local image status.
+- `download` downloads a specific template.
+- `cancel` cancels a download task.
+- `delete` removes the local image cache.
+- `toggle` controls whether a template can be used during creation.
+
+## Windows Images
+
+This project does not distribute Windows system images and does not provide features to bypass or avoid Windows activation. Windows download links should point to official Microsoft resources, and users must obtain valid licenses themselves.
@@ -0,0 +1,61 @@
+# Networking and Routing
+
+CLICD provides NAT4 port mapping, random available ports, public IPv4 assignment, IPv6 status checks, and IPv6 assignment. During container creation, you can use NAT only, public IPv4 only, IPv6 only, or a mixed network setup.
+
+## NAT4
+
+NAT4 forwards host ports to container internal ports. Common uses include:
+
+- Forwarding SSH.
+- Exposing web services.
+- Assigning fixed external ports to sub-users.
+
+Port mappings include:
+
+| Field | Description |
+| --- | --- |
+| Name | A purpose label such as `ssh` or `web`. |
+| Protocol | `tcp` or `udp`. |
+| External port | The host port exposed to the outside. |
+| Internal port | The service port inside the container. |
+
+## IPv6
+
+IPv6 assignment requires the host to have a routable IPv6 prefix, plus correct routing, neighbor discovery, or proxy configuration.
+
+```http
+GET /api/v1/ipv6/status
+POST /api/v1/containers/{id}/ipv6
+```
+
+If the host has no public IPv6 or the upstream network is not routing the prefix correctly, assigned addresses will not be reachable from the public internet.
+
+## Public IPv4
+
+Public IPv4 assignment selects from public IPv4 addresses detected on the host, or from `public_ipv4s` specified through the API. Creation fields include:
+
+| Field | Description |
+| --- | --- |
+| `assign_nat` | Whether to enable NAT port mappings. |
+| `assign_ipv4` | Whether to assign public IPv4. |
+| `ipv4_count` | Number of public IPv4 addresses to allocate automatically. |
+| `public_ipv4s` | Explicit public IPv4 address list. |
+| `assign_ipv6` | Whether to assign IPv6. |
+| `ipv6_count` | Number of IPv6 addresses to allocate automatically. |
+| `ipv6_addresses` | Explicit IPv6 address list. |
+
+Public address pool APIs:
+
+```http
+GET /api/v1/routing
+PUT /api/v1/routing
+POST /api/v1/routing/ipv4-scan
+```
+
+## Routing Status
+
+```http
+GET /api/v1/routing
+```
+
+This endpoint shows runtime status for NAT, IPv4, IPv6, and port capacity.
@@ -0,0 +1,31 @@
+# Security Alerts
+
+CLICD includes lightweight security alerts based on connection behavior. It does not keep full normal connection logs; it focuses on abnormal behavior and high-risk patterns.
+
+## Covered Scenarios
+
+- Port scanning.
+- Lateral scanning.
+- Brute-force tendencies.
+- SMTP abuse.
+- UDP reflection risk.
+- Suspicious ports related to mining, proxies, VPNs, Tor, and similar services.
+
+## APIs
+
+```http
+GET /api/v1/security/alerts
+POST /api/v1/security/check
+GET /api/v1/security/logs?container={name}
+GET /api/v1/security/summary
+GET /api/v1/security/settings
+PUT /api/v1/security/settings
+```
+
+## Automatic Shutdown
+
+Security settings can enable automatic shutdown after alerts. Before enabling it, observe for a while and make sure the rules do not affect normal services.
+
+## Logging Advice
+
+Security alerts are risk signals. They should not replace a professional firewall, intrusion detection, or centralized logging system. For public services, still combine them with security groups, firewall rules, Fail2ban, and similar tools.
@@ -0,0 +1,31 @@
+# Snapshot Management
+
+Snapshots save the current state of a container so it can be rolled back before upgrades, configuration changes, or delivery.
+
+## Global Overview
+
+```http
+GET /api/v1/snapshots
+```
+
+Use this endpoint to view snapshot summaries for all containers.
+
+## Container Snapshots
+
+```http
+GET /api/v1/containers/{id}/snapshots
+POST /api/v1/containers/{id}/snapshots
+DELETE /api/v1/containers/{id}/snapshots/{snapshot_id}
+POST /api/v1/containers/{id}/snapshots/{snapshot_id}/restore
+```
+
+Restoring a snapshot changes container state. In production, confirm that the current workload can be interrupted first.
+
+## Scheduled Snapshots and Quotas
+
+```http
+POST /api/v1/containers/{id}/snapshots/schedule
+PUT /api/v1/containers/{id}/snapshots/quota
+```
+
+Scheduled snapshots are useful for long-running containers. Quotas prevent snapshots from growing without limit and filling the host disk.
@@ -0,0 +1,28 @@
+# Sub-users
+
+Sub-users let administrators grant specific container access to other users. They are useful for temporary delivery, shared-host allocation, teaching labs, or multi-user host scenarios.
+
+## Create an Access Link
+
+After selecting a container, the administrator can create a sub-user link:
+
+```http
+POST /api/v1/sub-user/create
+```
+
+The response may include a username, initial password, access code, or access link. When sharing externally, mask sensitive values and send the real values only to the intended user.
+
+## Manage Sub-users
+
+```http
+GET /api/v1/sub-users
+POST /api/v1/sub-users/{id}/rotate-password
+GET /api/v1/sub-users/{id}/audit-logs
+GET /api/v1/sub-users/{id}/login-logs
+```
+
+Rotating the password invalidates old credentials. Audit logs and login logs help investigate mistakes or abnormal access.
+
+## Permission Scope
+
+Sub-users can only manage authorized containers. Global configuration, image management, security policy, API keys, and other administrator features are not exposed to sub-users.