mirror of
https://github.com/MengMengCode/CLICD.git
synced 2026-08-04 21:31:23 +08:00
docs
This commit is contained in:
MengMengCode
@@ -0,0 +1,4 @@
|
||||
node_modules/
|
||||
.vitepress/cache/
|
||||
.vitepress/dist/
|
||||
.vitepress/.temp/
|
||||
@@ -0,0 +1,74 @@
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
title: 'CLICD',
|
||||
description: '面向 LXC/KVM 的轻量虚拟化管理面板文档',
|
||||
lang: 'zh-CN',
|
||||
base: process.env.VITEPRESS_BASE || '/',
|
||||
cleanUrls: true,
|
||||
ignoreDeadLinks: true,
|
||||
head: [
|
||||
['link', { rel: 'icon', href: '/favicon.svg' }],
|
||||
],
|
||||
themeConfig: {
|
||||
logo: '/favicon.svg',
|
||||
search: {
|
||||
provider: 'local',
|
||||
},
|
||||
nav: [
|
||||
{ text: '指南', link: '/guide/introduction' },
|
||||
{ text: '功能', link: '/features/dashboard' },
|
||||
{ text: '运维', link: '/operations/deployment' },
|
||||
{ text: '开发', link: '/developer/architecture' },
|
||||
],
|
||||
sidebar: [
|
||||
{
|
||||
text: '开始',
|
||||
items: [
|
||||
{ text: '项目介绍', link: '/guide/introduction' },
|
||||
{ text: '安装', link: '/guide/installation' },
|
||||
{ text: '升级', link: '/guide/upgrade' },
|
||||
{ text: '快速上手', link: '/guide/quick-start' },
|
||||
{ text: '配置说明', link: '/guide/configuration' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: '功能',
|
||||
items: [
|
||||
{ text: '控制面板', link: '/features/dashboard' },
|
||||
{ text: '容器管理', link: '/features/containers' },
|
||||
{ text: '镜像管理', link: '/features/images' },
|
||||
{ text: '网络与路由', link: '/features/networking' },
|
||||
{ text: '快照管理', link: '/features/snapshots' },
|
||||
{ text: '安全告警', link: '/features/security' },
|
||||
{ text: '子用户', link: '/features/sub-users' },
|
||||
{ text: 'API 集成', link: '/features/api' },
|
||||
{ text: '主机报告', link: '/features/host-report' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: '运维',
|
||||
items: [
|
||||
{ text: '部署建议', link: '/operations/deployment' },
|
||||
{ text: '故障排查', link: '/operations/troubleshooting' },
|
||||
{ text: '常见问题', link: '/operations/faq' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: '开发',
|
||||
items: [
|
||||
{ text: '系统架构', link: '/developer/architecture' },
|
||||
{ text: '本地构建', link: '/developer/build' },
|
||||
{ text: '发布流程', link: '/developer/release' },
|
||||
],
|
||||
},
|
||||
],
|
||||
socialLinks: [
|
||||
{ icon: 'github', link: 'https://github.com/MengMengCode/CLICD' },
|
||||
],
|
||||
footer: {
|
||||
message: 'CLICD 文档面向部署、使用、运维和二次开发场景。',
|
||||
copyright: 'Copyright © CLICD contributors',
|
||||
},
|
||||
},
|
||||
})
|
||||
@@ -0,0 +1,26 @@
|
||||
:root {
|
||||
--vp-c-brand-1: #0284c7;
|
||||
--vp-c-brand-2: #0ea5e9;
|
||||
--vp-c-brand-3: #7dd3fc;
|
||||
--vp-c-brand-soft: rgba(14, 165, 233, 0.14);
|
||||
--vp-home-hero-name-color: #0369a1;
|
||||
--vp-home-hero-image-background-image: linear-gradient(135deg, #7dd3fc 0%, #38bdf8 46%, #86efac 100%);
|
||||
--vp-home-hero-image-filter: blur(46px);
|
||||
}
|
||||
|
||||
.dark {
|
||||
--vp-c-brand-1: #7dd3fc;
|
||||
--vp-c-brand-2: #38bdf8;
|
||||
--vp-c-brand-3: #0ea5e9;
|
||||
--vp-c-brand-soft: rgba(125, 211, 252, 0.16);
|
||||
--vp-home-hero-name-color: #bae6fd;
|
||||
}
|
||||
|
||||
.VPHomeHero .text {
|
||||
max-width: 680px;
|
||||
}
|
||||
|
||||
.vp-doc table {
|
||||
display: table;
|
||||
width: 100%;
|
||||
}
|
||||
@@ -0,0 +1,4 @@
|
||||
import DefaultTheme from 'vitepress/theme'
|
||||
import './custom.css'
|
||||
|
||||
export default DefaultTheme
|
||||
@@ -0,0 +1,42 @@
|
||||
# 系统架构
|
||||
|
||||
CLICD 由 Go 后端、React 前端和宿主机虚拟化能力组成。
|
||||
|
||||
## 后端
|
||||
|
||||
后端入口在 `backend/main.go`，HTTP 服务路由集中在 `backend/internal/server/server.go`。主要模块：
|
||||
|
||||
- `internal/api`：Web 面板和 `/api/v1` 的 HTTP 接口。
|
||||
- `internal/config`：配置和 SQLite 存储。
|
||||
- `internal/lxc`：LXC 容器管理。
|
||||
- `internal/kvm`：KVM/libvirt 虚拟机管理。
|
||||
- `internal/cli`：命令行管理入口。
|
||||
- `internal/server`：静态前端嵌入和 HTTP 服务。
|
||||
- `internal/version`：版本号。
|
||||
|
||||
## 前端
|
||||
|
||||
前端入口在 `frontend/src/main.tsx`，页面位于 `frontend/src/pages`，通用组件位于 `frontend/src/components`。
|
||||
|
||||
主要页面：
|
||||
|
||||
- 控制面板：`Dashboard.tsx`
|
||||
- 容器列表：`Containers.tsx`
|
||||
- 容器详情：`ContainerDetail.tsx`
|
||||
- 镜像管理：`ImageManagement.tsx`
|
||||
- 安全告警：`Security.tsx`
|
||||
- 快照管理：`Snapshots.tsx`
|
||||
- 路由管理：`Routing.tsx`
|
||||
- API 集成：`ApiIntegration.tsx`
|
||||
- 主机报告：`HostReport.tsx`
|
||||
- 子用户管理：`SubUserManagement.tsx`
|
||||
|
||||
## 前端嵌入
|
||||
|
||||
生产构建时，前端产物会放入 `backend/internal/server/web`，后端通过 Go embed 提供静态文件，并对非 API 路由返回 SPA 入口。
|
||||
|
||||
## 接口分层
|
||||
|
||||
- `/api/*`：Web 面板和兼容接口。
|
||||
- `/api/v1/*`：推荐给外部自动化系统使用的版本化接口。
|
||||
- WebSSH 和 WebVNC 使用短期票据后建立 WebSocket 连接。
|
||||
@@ -0,0 +1,42 @@
|
||||
# 本地构建
|
||||
|
||||
## 前端构建
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
npm run build
|
||||
```
|
||||
|
||||
构建输出位于 `frontend/dist`。
|
||||
|
||||
## 后端构建
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
go test ./...
|
||||
go build -o ../build/clicd .
|
||||
```
|
||||
|
||||
如果要打包嵌入式 Web 面板，需要先把前端构建产物同步到后端嵌入目录。
|
||||
|
||||
## 一键构建
|
||||
|
||||
项目根目录提供了构建脚本：
|
||||
|
||||
```bash
|
||||
bash build.sh
|
||||
```
|
||||
|
||||
该脚本用于串联前端构建、静态资源同步和 Go 二进制构建。
|
||||
|
||||
## 文档站构建
|
||||
|
||||
```bash
|
||||
cd docs
|
||||
npm install
|
||||
npm run dev
|
||||
npm run build
|
||||
```
|
||||
|
||||
`npm run dev` 用于本地预览，`npm run build` 用于生成静态文档。
|
||||
@@ -0,0 +1,44 @@
|
||||
# 发布流程
|
||||
|
||||
CLICD 的安装和升级依赖 GitHub Release 产物。发布时建议使用语义化版本标签，例如 `v1.1.6`。
|
||||
|
||||
## 版本号
|
||||
|
||||
版本号需要同步检查：
|
||||
|
||||
- `backend/internal/version/version.go`
|
||||
- `frontend/package.json`
|
||||
- Release 标签。
|
||||
|
||||
## Release 产物
|
||||
|
||||
安装脚本会优先下载 Linux AMD64 产物：
|
||||
|
||||
```text
|
||||
clicd-linux-amd64.tar.gz
|
||||
```
|
||||
|
||||
在部分场景中也会尝试下载单独二进制：
|
||||
|
||||
```text
|
||||
clicd-linux-amd64
|
||||
```
|
||||
|
||||
## 安装脚本行为
|
||||
|
||||
- `CLICD_VERSION=latest`：使用 GitHub `releases/latest`。
|
||||
- `CLICD_VERSION=vX.Y.Z`：下载指定标签的 Release 产物。
|
||||
|
||||
示例：
|
||||
|
||||
```bash
|
||||
CLICD_VERSION=v1.1.6 sh install.sh
|
||||
```
|
||||
|
||||
## 发布后验证
|
||||
|
||||
- 安装脚本可以下载新版本。
|
||||
- `systemctl status clicd` 正常。
|
||||
- `/api/version` 返回新版本。
|
||||
- Web 面板可以加载前端资源。
|
||||
- 容器列表、任务队列、API Key 页面可以正常打开。
|
||||
@@ -0,0 +1,136 @@
|
||||
# API 集成
|
||||
|
||||
CLICD 对外推荐使用 `/api/v1` 接口。旧版未带版本号的接口主要用于 Web 面板和兼容场景，新接入请优先使用 `/api/v1`。
|
||||
|
||||
## 认证
|
||||
|
||||
API Key 可在“API 集成”页面创建和管理。请求时支持两种写法：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
## Python 示例
|
||||
|
||||
```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()
|
||||
containers = resp.json()
|
||||
|
||||
print(containers)
|
||||
```
|
||||
|
||||
创建端口映射：
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
BASE_URL = "https://panel.example.com"
|
||||
API_KEY = "YOUR_API_KEY"
|
||||
CONTAINER_ID = "example-vm"
|
||||
|
||||
payload = {
|
||||
"name": "web",
|
||||
"protocol": "tcp",
|
||||
"host_port": 18080,
|
||||
"container_port": 80,
|
||||
}
|
||||
|
||||
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())
|
||||
```
|
||||
|
||||
## 返回结构示例
|
||||
|
||||
容器列表：
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"id": 5,
|
||||
"uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
|
||||
"name": "example-vm",
|
||||
"status": "running",
|
||||
"ip": "10.0.3.25",
|
||||
"ipv6": "2001:db8:100::1005",
|
||||
"cpu_limit": 2,
|
||||
"memory_limit": 2048,
|
||||
"disk_limit": 20480,
|
||||
"traffic_limit": 107374182400,
|
||||
"expires_at": "2026-12-31 23:59:59"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
任务队列：
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"id": "task-13",
|
||||
"type": "restart",
|
||||
"status": "running",
|
||||
"created_at": "2026-06-09T10:00:00+08:00"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
WebSSH 票据：
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"ticket": "***60秒有效票据***"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 常用接口
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| GET | `/api/v1/dashboard` | 控制面板统计 |
|
||||
| GET | `/api/v1/host-info` | 主机资源 |
|
||||
| GET | `/api/v1/containers` | 容器列表 |
|
||||
| POST | `/api/v1/containers` | 创建容器 |
|
||||
| POST | `/api/v1/containers/{id}/start` | 开机 |
|
||||
| POST | `/api/v1/containers/{id}/stop` | 关机 |
|
||||
| POST | `/api/v1/containers/{id}/restart` | 重启 |
|
||||
| DELETE | `/api/v1/containers/{id}/delete` | 删除 |
|
||||
| GET | `/api/v1/tasks` | 任务队列 |
|
||||
| GET | `/api/v1/templates` | 模板列表 |
|
||||
| GET | `/api/v1/images` | 镜像管理列表 |
|
||||
| GET | `/api/v1/snapshots` | 快照总览 |
|
||||
| GET | `/api/v1/security/alerts` | 安全告警 |
|
||||
| GET | `/api/v1/audit-logs` | 操作日志 |
|
||||
| GET | `/api/v1/api-keys` | API Key 列表 |
|
||||
|
||||
完整接口清单请以面板内“API 集成”页面为准。
|
||||
@@ -0,0 +1,73 @@
|
||||
# 容器管理
|
||||
|
||||
容器管理是 CLICD 的核心模块，覆盖创建、生命周期控制、资源限制、网络映射、流量统计、密码重置和控制台访问。
|
||||
|
||||
## 容器列表
|
||||
|
||||
列表页用于扫描所有容器状态。管理员可以查看全部容器，子用户只能看到授权范围内的容器。
|
||||
|
||||
常见字段包括：
|
||||
|
||||
- ID、UUID、名称。
|
||||
- 虚拟化类型。
|
||||
- 运行状态。
|
||||
- IP、IPv6。
|
||||
- CPU、内存、磁盘限制。
|
||||
- 流量使用量和流量上限。
|
||||
- 到期时间。
|
||||
|
||||
## 创建容器
|
||||
|
||||
创建时需要选择模板，并设置资源配额。批量创建可以通过面板或 API 完成，适合一次性发放多个容器。
|
||||
|
||||
```http
|
||||
POST /api/v1/containers
|
||||
POST /api/v1/batch-create
|
||||
```
|
||||
|
||||
## 生命周期操作
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
开关机、重装、删除等操作会进入任务队列。调用后可通过 `GET /api/v1/tasks` 查看执行状态。
|
||||
|
||||
## 资源与流量
|
||||
|
||||
容器详情页支持查看资源用量，调整流量限制、资源限制和到期时间。
|
||||
|
||||
```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 端口管理
|
||||
|
||||
容器详情页的 NAT 端口管理支持新增、编辑和删除映射。新增和编辑会在弹窗里完成，便于集中填写名称、协议、外部端口和内部端口。
|
||||
|
||||
```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}
|
||||
```
|
||||
|
||||
子用户模式下，管理员可限制子用户只能调整内部端口，避免修改宿主机对外端口和协议。
|
||||
|
||||
## 远程控制台
|
||||
|
||||
```http
|
||||
POST /api/v1/ssh-ticket
|
||||
POST /api/v1/vnc-ticket
|
||||
```
|
||||
|
||||
票据只适合短时间使用，返回后应立即用于 WebSSH 或 WebVNC 连接，不要持久化保存。
|
||||
@@ -0,0 +1,27 @@
|
||||
# 控制面板
|
||||
|
||||
控制面板用于查看宿主机和虚拟化资源的整体状态。
|
||||
|
||||
## 统计项
|
||||
|
||||
- 容器总数、运行中数量和停止数量。
|
||||
- CPU、内存、磁盘、Swap 等资源概览。
|
||||
- 主机网络和路由状态入口。
|
||||
- 任务队列状态。
|
||||
- 安全告警摘要。
|
||||
|
||||
## 相关接口
|
||||
|
||||
```http
|
||||
GET /api/v1/dashboard
|
||||
GET /api/v1/host-info
|
||||
GET /api/v1/routing
|
||||
GET /api/v1/ipv6/status
|
||||
GET /api/v1/tasks
|
||||
```
|
||||
|
||||
API 需要携带 API Key：
|
||||
|
||||
```bash
|
||||
curl -H "X-API-Key: YOUR_API_KEY" https://panel.example.com/api/v1/dashboard
|
||||
```
|
||||
@@ -0,0 +1,21 @@
|
||||
# 主机报告
|
||||
|
||||
主机报告用于汇总宿主机运行环境、资源状态和虚拟化依赖，适合安装后自检、故障排查或给维护人员交付环境信息。
|
||||
|
||||
## 查看内容
|
||||
|
||||
- 系统版本和内核信息。
|
||||
- CPU、内存、磁盘、Swap。
|
||||
- 网络状态。
|
||||
- LXC/KVM 依赖状态。
|
||||
- CLICD 服务状态。
|
||||
|
||||
## 相关接口
|
||||
|
||||
```http
|
||||
GET /api/v1/host-report
|
||||
GET /api/v1/host-info
|
||||
GET /api/v1/swap
|
||||
```
|
||||
|
||||
对外发送报告前，请先检查是否包含公网 IP、内网网段、用户名、密钥、票据或业务域名。
|
||||
@@ -0,0 +1,29 @@
|
||||
# 镜像管理
|
||||
|
||||
镜像管理用于维护可创建容器或虚拟机的模板。
|
||||
|
||||
## 支持的模板类型
|
||||
|
||||
项目内置了常见 Linux 发行版模板，例如 Debian、Ubuntu、Alpine、CentOS、Fedora、Arch Linux、Rocky Linux 等。KVM 模板会使用对应发行版的云镜像资源。
|
||||
|
||||
## 管理动作
|
||||
|
||||
```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` 返回可用模板定义。
|
||||
- `images` 返回本地镜像状态。
|
||||
- `download` 下载指定模板。
|
||||
- `cancel` 取消下载任务。
|
||||
- `delete` 删除本地镜像缓存。
|
||||
- `toggle` 控制模板是否对创建流程可用。
|
||||
|
||||
## Windows 镜像说明
|
||||
|
||||
本项目不分发 Windows 系统镜像，也不提供绕过或规避 Windows 激活机制的功能。涉及 Windows 的下载链接应指向微软官方资源，使用者需要自行获得合法授权。
|
||||
@@ -0,0 +1,39 @@
|
||||
# 网络与路由
|
||||
|
||||
CLICD 提供 NAT4 端口映射、随机可用端口、IPv6 状态检查和 IPv6 分配能力。
|
||||
|
||||
## NAT4
|
||||
|
||||
NAT4 用于把宿主机端口转发到容器内部端口。典型用途：
|
||||
|
||||
- 转发 SSH。
|
||||
- 暴露 Web 服务。
|
||||
- 给子用户分配固定外部端口。
|
||||
|
||||
端口映射包含：
|
||||
|
||||
| 字段 | 说明 |
|
||||
| --- | --- |
|
||||
| 名称 | 用于识别用途，例如 `ssh`、`web`。 |
|
||||
| 协议 | `tcp` 或 `udp`。 |
|
||||
| 外部端口 | 宿主机对外监听端口。 |
|
||||
| 内部端口 | 容器内部服务端口。 |
|
||||
|
||||
## IPv6
|
||||
|
||||
IPv6 分配要求宿主机本身拥有可路由 IPv6 地址段，并且系统路由、邻居发现或代理策略配置正确。
|
||||
|
||||
```http
|
||||
GET /api/v1/ipv6/status
|
||||
POST /api/v1/containers/{id}/ipv6
|
||||
```
|
||||
|
||||
如果宿主机没有公网 IPv6 或上游没有正确路由，面板中分配出的地址也无法从公网访问。
|
||||
|
||||
## 路由状态
|
||||
|
||||
```http
|
||||
GET /api/v1/routing
|
||||
```
|
||||
|
||||
该接口用于查看 NAT、IPv6、端口容量等运行时状态。
|
||||
@@ -0,0 +1,31 @@
|
||||
# 安全告警
|
||||
|
||||
CLICD 内置基于连接行为的轻量安全告警能力。它不保存完整正常连接日志，而是关注异常行为和高风险模式。
|
||||
|
||||
## 覆盖场景
|
||||
|
||||
- 端口扫描。
|
||||
- 横向扫描。
|
||||
- 爆破倾向。
|
||||
- SMTP 滥用。
|
||||
- UDP 反射风险。
|
||||
- 挖矿、代理、VPN、Tor 等可疑端口。
|
||||
|
||||
## 接口
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
## 自动关机
|
||||
|
||||
安全设置中可配置告警后的自动关机策略。开启前建议先观察一段时间，确认规则不会影响正常业务。
|
||||
|
||||
## 日志建议
|
||||
|
||||
安全告警适合做风险提示，不应替代专业防火墙、入侵检测或集中日志系统。对公网暴露服务时，仍建议结合安全组、防火墙、Fail2ban 等工具。
|
||||
@@ -0,0 +1,31 @@
|
||||
# 快照管理
|
||||
|
||||
快照用于保存容器当前状态，方便在升级、变更配置或交付前回滚。
|
||||
|
||||
## 全局总览
|
||||
|
||||
```http
|
||||
GET /api/v1/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
|
||||
```
|
||||
|
||||
恢复快照会改变容器状态，生产环境建议先确认当前业务是否可以中断。
|
||||
|
||||
## 计划快照与配额
|
||||
|
||||
```http
|
||||
POST /api/v1/containers/{id}/snapshots/schedule
|
||||
PUT /api/v1/containers/{id}/snapshots/quota
|
||||
```
|
||||
|
||||
计划快照适合长期运行的容器。配额用于避免快照无限增长占满宿主机磁盘。
|
||||
@@ -0,0 +1,28 @@
|
||||
# 子用户
|
||||
|
||||
子用户用于把指定容器授权给其他用户管理。它适合临时交付、拼车分配、教学实验或多人共用宿主机的场景。
|
||||
|
||||
## 创建访问链接
|
||||
|
||||
管理员选择容器后创建子用户链接：
|
||||
|
||||
```http
|
||||
POST /api/v1/sub-user/create
|
||||
```
|
||||
|
||||
返回内容中可能包含用户名、初始密码、访问码或访问链接。对外展示时必须脱敏，真实值只应发送给对应用户。
|
||||
|
||||
## 管理子用户
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
轮换密码会让旧凭证失效。审计日志和登录日志可用于排查误操作或异常访问。
|
||||
|
||||
## 权限范围
|
||||
|
||||
子用户只能管理被授权的容器。涉及全局配置、镜像管理、安全策略、API Key 等管理员功能不会开放给子用户。
|
||||
@@ -0,0 +1,30 @@
|
||||
# 配置说明
|
||||
|
||||
CLICD 安装后会以 systemd 服务运行，运行时配置和数据库保存在宿主机本地。实际路径可能随安装脚本参数变化，默认安装建议以 `/root/.clicd/` 为主要检查位置。
|
||||
|
||||
## 常见配置项
|
||||
|
||||
| 配置 | 说明 |
|
||||
| --- | --- |
|
||||
| Web 端口 | 默认 `8999`，服务启动时监听 `0.0.0.0:8999`。 |
|
||||
| 管理员账号 | 用于登录 Web 面板和管理 API Key。 |
|
||||
| 数据库 | SQLite，用于保存容器元数据、子用户、审计日志、API Key 等。 |
|
||||
| NAT 端口范围 | 用于随机端口和端口映射分配。 |
|
||||
| IPv6 地址段 | 宿主机有可路由 IPv6 时可配置分配策略。 |
|
||||
| 安全告警 | 可配置自动关机等策略。 |
|
||||
|
||||
## 服务命令
|
||||
|
||||
```bash
|
||||
systemctl status clicd
|
||||
systemctl restart clicd
|
||||
journalctl -u clicd -n 100 --no-pager
|
||||
```
|
||||
|
||||
## 安全建议
|
||||
|
||||
- 不要把 Web 面板直接暴露给不可信来源。
|
||||
- 使用复杂管理员密码，并定期轮换。
|
||||
- API Key 按用途拆分权限，避免长期使用全权限密钥。
|
||||
- WebSSH、WebVNC 票据是短期凭证，不应写入日志或外发。
|
||||
- 对外文档、截图和工单里不要粘贴真实 IP、密码、API Key 或票据。
|
||||
@@ -0,0 +1,46 @@
|
||||
# 安装
|
||||
|
||||
CLICD 提供一键安装脚本。脚本默认安装 GitHub Releases 的最新版本，也可以通过环境变量指定固定版本。
|
||||
|
||||
## 环境要求
|
||||
|
||||
- Linux x86_64 宿主机。
|
||||
- root 权限。
|
||||
- systemd。
|
||||
- 网络可访问 GitHub Release 下载地址。
|
||||
- 如果要使用 LXC，需要宿主机支持 LXC 运行环境。
|
||||
- 如果要使用 KVM，需要宿主机开启虚拟化并安装 libvirt/QEMU。
|
||||
|
||||
## 安装最新版本
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/MengMengCode/CLICD/main/install.sh | sudo sh
|
||||
```
|
||||
|
||||
脚本当前默认使用 `CLICD_VERSION=latest`，也就是下载 `releases/latest` 对应的 `clicd-linux-amd64.tar.gz`。
|
||||
|
||||
## 安装指定版本
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/MengMengCode/CLICD/main/install.sh | sudo CLICD_VERSION=v1.1.6 sh
|
||||
```
|
||||
|
||||
把 `v1.1.6` 替换成需要安装的 Release 标签即可。
|
||||
|
||||
## 访问面板
|
||||
|
||||
安装完成后，浏览器访问：
|
||||
|
||||
```text
|
||||
http://YOUR_SERVER_IP:8999
|
||||
```
|
||||
|
||||
首次登录请使用安装脚本输出的管理员账号信息。生产环境建议在防火墙或反向代理层限制访问来源，并尽快修改默认账号和密码。
|
||||
|
||||
## 卸载
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/MengMengCode/CLICD/main/install.sh | sudo sh -s -- uninstall
|
||||
```
|
||||
|
||||
卸载前请确认是否需要保留容器、镜像缓存、数据库和配置文件。
|
||||
@@ -0,0 +1,29 @@
|
||||
# 项目介绍
|
||||
|
||||
CLICD 是一个面向 LXC/KVM 的轻量虚拟化管理面板。它把常见宿主机运维动作收敛到 Web 控制台和命令行里，适合用来管理小型 VPS、独立服务器或需要批量分发容器访问权限的场景。
|
||||
|
||||
## 核心能力
|
||||
|
||||
- 管理 LXC 容器和 KVM 虚拟机。
|
||||
- 创建、开机、关机、重启、重装、删除容器。
|
||||
- 配置 CPU、内存、磁盘、流量限制和到期时间。
|
||||
- 管理 NAT4 端口映射，并在宿主机具备 IPv6 路由时分配公网 IPv6。
|
||||
- 在浏览器中打开 WebSSH 或 WebVNC。
|
||||
- 管理镜像下载、启用状态和本地缓存。
|
||||
- 创建、恢复、删除快照，配置计划快照和快照配额。
|
||||
- 基于连接行为生成安全告警，并保留审计日志。
|
||||
- 为指定容器创建子用户访问链接。
|
||||
- 通过 API Key 接入 `/api/v1` 自动化接口。
|
||||
|
||||
## 适用场景
|
||||
|
||||
- 一台宿主机上需要快速分配多个 Linux 容器。
|
||||
- 需要给用户临时发放容器控制台、SSH、VNC 或 NAT 端口管理权限。
|
||||
- 希望用 API 自动化创建容器、调整资源、重置密码或回收资源。
|
||||
- 需要一个比纯 CLI 更直观，但又不重型的平台面板。
|
||||
|
||||
## 技术栈
|
||||
|
||||
- 后端：Go、`net/http`、SQLite、systemd、LXC、KVM/libvirt、cgroup v2、iptables、conntrack。
|
||||
- 前端：React、TypeScript、Vite、Tailwind CSS、lucide-react、xterm.js、noVNC。
|
||||
- 发布：GitHub Actions 构建 Linux AMD64 release 产物，安装脚本默认拉取最新 Release。
|
||||
@@ -0,0 +1,36 @@
|
||||
# 快速上手
|
||||
|
||||
下面是一条从安装后到创建第一台容器的常用路径。
|
||||
|
||||
## 1. 登录控制台
|
||||
|
||||
访问 `http://YOUR_SERVER_IP:8999`，使用管理员账号登录。
|
||||
|
||||
进入面板后先检查：
|
||||
|
||||
- 控制面板是否显示主机资源。
|
||||
- 镜像管理是否能列出模板。
|
||||
- 路由管理中 NAT 和 IPv6 状态是否符合宿主机预期。
|
||||
|
||||
## 2. 下载镜像
|
||||
|
||||
进入“镜像管理”，选择需要的模板并下载。宿主机资源较小时，可以优先选择 Alpine、Debian 这类轻量镜像。
|
||||
|
||||
镜像下载是异步任务，可以在任务队列中观察进度。
|
||||
|
||||
## 3. 创建容器
|
||||
|
||||
进入“容器管理”，点击创建：
|
||||
|
||||
- 选择虚拟化类型和模板。
|
||||
- 设置 CPU、内存、磁盘。
|
||||
- 设置流量限制和到期时间。
|
||||
- 如果需要外部访问，创建后到容器详情里添加 NAT 端口映射或分配 IPv6。
|
||||
|
||||
## 4. 打开终端
|
||||
|
||||
容器创建完成后，可以在详情页打开 WebSSH。KVM 虚拟机可使用 WebVNC 查看控制台。
|
||||
|
||||
## 5. 分发给子用户
|
||||
|
||||
如果需要把某个容器交给其他用户管理，进入“子用户管理”创建访问链接。子用户只会看到被授权的容器，并受到管理员配置的操作范围限制。
|
||||
@@ -0,0 +1,43 @@
|
||||
# 升级
|
||||
|
||||
CLICD 的安装脚本和 CLI 都围绕 GitHub Release 产物工作。升级前建议先确认当前版本、备份配置和数据库。
|
||||
|
||||
## 查看版本
|
||||
|
||||
Web 面板侧边栏底部会显示当前版本，也可以访问：
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:8999/api/version
|
||||
```
|
||||
|
||||
返回示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"version": "1.1.6"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 使用安装脚本升级
|
||||
|
||||
安装脚本默认使用最新 Release：
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/MengMengCode/CLICD/main/install.sh | sudo sh
|
||||
```
|
||||
|
||||
指定版本：
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/MengMengCode/CLICD/main/install.sh | sudo CLICD_VERSION=v1.1.6 sh
|
||||
```
|
||||
|
||||
## 升级前检查
|
||||
|
||||
- 确认 `/root/.clicd/` 或实际配置目录已备份。
|
||||
- 确认系统服务没有正在执行关键任务。
|
||||
- 如果正在下载镜像或恢复快照，建议等待任务完成后再升级。
|
||||
- 升级后检查 `systemctl status clicd` 和 Web 面板版本号。
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
layout: home
|
||||
|
||||
hero:
|
||||
name: CLICD
|
||||
text: 轻量 LXC/KVM 虚拟化管理面板
|
||||
tagline: 提供 Web 控制台、CLI、容器编排、NAT/IPv6、快照、安全告警、子用户和 API 自动化能力。
|
||||
actions:
|
||||
- theme: brand
|
||||
text: 开始安装
|
||||
link: /guide/installation
|
||||
- theme: alt
|
||||
text: 查看 API
|
||||
link: /features/api
|
||||
|
||||
features:
|
||||
- title: 面向小型宿主机
|
||||
details: 适合在单台 VPS 或独立服务器上管理 LXC 容器与 KVM 虚拟机。
|
||||
- title: Web 与 CLI 并行
|
||||
details: 管理员可使用 Web 面板，也可以进入 clicd CLI 完成维护操作。
|
||||
- title: 自动化友好
|
||||
details: /api/v1 提供容器、镜像、快照、安全、日志、子用户和 API Key 管理接口。
|
||||
---
|
||||
@@ -0,0 +1,46 @@
|
||||
# 部署建议
|
||||
|
||||
CLICD 可以直接运行在宿主机上，也可以放在反向代理之后。生产环境建议先做好访问控制，再开放给管理员使用。
|
||||
|
||||
## 服务暴露
|
||||
|
||||
默认 Web 端口为 `8999`：
|
||||
|
||||
```text
|
||||
http://YOUR_SERVER_IP:8999
|
||||
```
|
||||
|
||||
建议：
|
||||
|
||||
- 仅允许固定管理员 IP 访问。
|
||||
- 使用反向代理配置 HTTPS。
|
||||
- 不要在公开文档或截图里暴露真实登录地址。
|
||||
|
||||
## systemd
|
||||
|
||||
常用命令：
|
||||
|
||||
```bash
|
||||
systemctl status clicd
|
||||
systemctl restart clicd
|
||||
systemctl enable clicd
|
||||
journalctl -u clicd -f
|
||||
```
|
||||
|
||||
## 防火墙
|
||||
|
||||
至少确认：
|
||||
|
||||
- 面板端口只对可信来源开放。
|
||||
- NAT 映射端口按需开放。
|
||||
- SSH 管理端口不与容器映射冲突。
|
||||
- IPv6 防火墙规则与 IPv4 同步规划。
|
||||
|
||||
## 备份
|
||||
|
||||
建议定期备份：
|
||||
|
||||
- CLICD 配置目录。
|
||||
- SQLite 数据库。
|
||||
- 容器配置。
|
||||
- 关键容器的快照或外部数据备份。
|
||||
@@ -0,0 +1,29 @@
|
||||
# 常见问题
|
||||
|
||||
## 安装脚本默认安装哪个版本？
|
||||
|
||||
默认安装 GitHub Releases 的最新版本。脚本中默认值是 `CLICD_VERSION=latest`，会下载 `releases/latest` 下的 Linux AMD64 产物。
|
||||
|
||||
## 可以固定安装某个版本吗？
|
||||
|
||||
可以：
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/MengMengCode/CLICD/main/install.sh | sudo CLICD_VERSION=v1.1.6 sh
|
||||
```
|
||||
|
||||
## 子用户能看到全部容器吗？
|
||||
|
||||
不能。子用户只会看到管理员授权给他的容器。
|
||||
|
||||
## API Key 和登录密码一样吗？
|
||||
|
||||
不一样。API Key 在“API 集成”页面创建，用于程序化调用接口。登录密码用于 Web 面板登录。
|
||||
|
||||
## 到达流量限制后会怎样？
|
||||
|
||||
容器达到流量限制后会被自动关机，避免继续产生超额流量。管理员可以调整限制或重置流量。
|
||||
|
||||
## IPv6 分配后为什么公网不通？
|
||||
|
||||
IPv6 是否可达取决于宿主机和上游网络。需要确认宿主机拥有可路由 IPv6 地址段，并且路由、防火墙、邻居发现或代理配置正确。
|
||||
@@ -0,0 +1,46 @@
|
||||
# 故障排查
|
||||
|
||||
## 服务无法访问
|
||||
|
||||
检查服务状态：
|
||||
|
||||
```bash
|
||||
systemctl status clicd
|
||||
journalctl -u clicd -n 100 --no-pager
|
||||
```
|
||||
|
||||
检查端口监听：
|
||||
|
||||
```bash
|
||||
ss -lntp | grep 8999
|
||||
```
|
||||
|
||||
如果使用反向代理，请同时检查代理日志和上游地址。
|
||||
|
||||
## 镜像下载失败
|
||||
|
||||
- 确认宿主机可以访问镜像源和 GitHub Release。
|
||||
- 检查磁盘空间。
|
||||
- 在任务队列里查看失败原因。
|
||||
- 如下载卡住，可尝试取消任务后重新下载。
|
||||
|
||||
## 容器无法联网
|
||||
|
||||
- 检查宿主机 NAT 和转发规则。
|
||||
- 检查容器 IP 是否分配成功。
|
||||
- 检查防火墙是否拦截转发流量。
|
||||
- IPv6 场景下确认上游已经把地址段路由到宿主机。
|
||||
|
||||
## WebSSH 或 WebVNC 连接失败
|
||||
|
||||
- 确认容器或虚拟机正在运行。
|
||||
- WebSSH 需要容器内 SSH 服务可用。
|
||||
- WebVNC 需要 KVM 控制台可访问。
|
||||
- 票据有效期很短，过期后重新创建即可。
|
||||
|
||||
## API 返回未授权
|
||||
|
||||
- 确认 API Key 没有被禁用。
|
||||
- 确认请求头使用 `X-API-Key` 或 `Authorization: Bearer`。
|
||||
- 确认密钥权限范围覆盖目标接口。
|
||||
- 不要把面板登录密码当作 API Key 使用。
|
||||
Generated
+2511
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"name": "clicd-docs",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
"dev": "vitepress dev . --host 127.0.0.1",
|
||||
"build": "vitepress build .",
|
||||
"preview": "vitepress preview . --host 127.0.0.1"
|
||||
},
|
||||
"devDependencies": {
|
||||
"vitepress": "^1.6.4"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1 @@
|
||||
<svg t="1780499553554" class="icon" viewBox="0 0 1024 1024" version="1.1" xmlns="http://www.w3.org/2000/svg" p-id="4260" width="200" height="200"><path d="M852.9 147.8c4.9 0 9.1 4.2 9.1 9.1v167.8c0 4.9-4.2 9.1-9.1 9.1H171.1c-4.9 0-9.1-4.2-9.1-9.1V156.9c0-4.9 4.2-9.1 9.1-9.1h681.8m0-50H171.1c-32.5 0-59.1 26.6-59.1 59.1v167.8c0 32.5 26.6 59.1 59.1 59.1h681.8c32.5 0 59.1-26.6 59.1-59.1V156.9c0-32.5-26.6-59.1-59.1-59.1z" p-id="4261" fill="#707070"></path><path d="M290.5 214h-60v60h60v-60zM393.5 214h-60v60h60v-60zM806 214H591v60h215v-60zM852.9 417.8c4.9 0 9.1 4.2 9.1 9.1v167.8c0 4.9-4.2 9.1-9.1 9.1H171.1c-4.9 0-9.1-4.2-9.1-9.1V426.9c0-4.9 4.2-9.1 9.1-9.1h681.8m0-50H171.1c-32.5 0-59.1 26.6-59.1 59.1v167.8c0 32.5 26.6 59.1 59.1 59.1h681.8c32.5 0 59.1-26.6 59.1-59.1V426.9c0-32.5-26.6-59.1-59.1-59.1z" p-id="4262" fill="#707070"></path><path d="M290.5 484h-60v60h60v-60zM393.5 484h-60v60h60v-60zM806 484H591v60h215v-60zM852.9 687.8c4.9 0 9.1 4.2 9.1 9.1v167.8c0 4.9-4.2 9.1-9.1 9.1H171.1c-4.9 0-9.1-4.2-9.1-9.1V696.9c0-4.9 4.2-9.1 9.1-9.1h681.8m0-50H171.1c-32.5 0-59.1 26.6-59.1 59.1v167.8c0 32.5 26.6 59.1 59.1 59.1h681.8c32.5 0 59.1-26.6 59.1-59.1V696.9c0-32.5-26.6-59.1-59.1-59.1z" p-id="4263" fill="#707070"></path><path d="M290.5 754h-60v60h60v-60zM393.5 754h-60v60h60v-60zM806 754H591v60h215v-60z" p-id="4264" fill="#707070"></path></svg>
|
||||
|
After Width: | Height: | Size: 1.3 KiB |
Reference in New Issue
Block a user