Loading... # Uncloud 多机集群搭建指南 # 一、概述 ## 1. 简介 ### A. 是什么 Uncloud 是一个轻量级的集群化和容器编排工具，能够在云虚拟机和裸金属服务器上部署和管理 Web 应用。它自动在 Docker 主机之间创建安全的 WireGuard 网状网络，并提供自动服务发现、负载均衡和 HTTPS 入口功能，且没有 Kubernetes 的复杂性。 ### B. 为什么学 - 比 Kubernetes 更简单易用，适合中小规模容器编排 - 自动创建安全的网状网络，无需手动配置 - 内置服务发现、负载均衡和 HTTPS 支持 - 支持多机容器部署和管理 ### C. 学完能做什么 - 从零开始搭建 Uncloud 多机集群 - 在集群中部署和管理容器化应用 - 配置服务发现和负载均衡 - 管理 Uncloud 集群上下文 ## 2. 前置知识 ### A. 必备技能 - 基本 Linux 命令行操作 - SSH 远程连接知识 - Docker 基础概念 ### B. 推荐知识 - 容器技术基础 - 网络基础知识 - WireGuard VPN 概念 # 二、环境准备 ## 1. 系统要求 - 操作系统：Ubuntu 20.04+ 或其他 Linux 发行版 - 控制机：用于远程管理集群的开发机器 - 集群节点：至少两台"干净"的 Ubuntu 机器 ## 2. 安装 Uncloud CLI 在控制机上安装 Uncloud CLI 工具（uc）： ```bash curl -sf https://uncloud.run/install.sh | sh ``` 或者参考官方安装指南：https://uncloud.run/docs/getting-started/install-cli ## 3. 验证安装 ```bash uc --version ``` # 三、核心概念 ## 1. 基本术语 - uc：Uncloud 命令行客户端工具 - uncloudd：Uncloud 守护进程，运行在集群节点上 - Corrosion：状态同步和服务发现组件 - WireGuard：用于创建安全的网状网络 - Context：集群上下文，允许管理多个集群 ## 2. 工作原理 ```mermaid graph TB A[控制机 dev-machine] -->|SSH 管理| B[server-1] A -->|SSH 管理| C[server-2] B -->|WireGuard 网状网络| C B -->|Docker| D[容器服务] C -->|Docker| D E[Corrosion] -->|服务发现| B E -->|服务发现| C F[Caddy global] -->|路由| B F -->|路由| C ```   ## 3. 架构说明 Uncloud 采用控制节点和工作节点的架构： - 控制节点：运行 uc CLI，用于远程管理集群 - 工作节点：运行 uncloudd 守护进程和 Docker，承载容器负载 - 网状网络：通过 WireGuard 自动创建，节点间安全通信 - 服务发现：由 Corrosion 组件提供 - 入口路由：Caddy 作为全局服务运行 # 四、快速上手 ## 1. 初始化第一个集群节点 在控制机上执行以下命令，将 server-1 初始化为集群的第一个节点： ```bash uc machine init laborant@server-1 --public-ip none --no-dns ``` **命令说明**： - `laborant@server-1`：SSH 连接信息 - `--public-ip none`：不配置公网 IP 入口（适用于实验环境） - `--no-dns`：跳过 DNS 子域名预留 该命令会自动在远程机器上安装： - Docker - uncloudd 守护进程 - Corrosion 服务 - 所有必要的依赖 ## 2. 查看集群状态 ```bash uc machine ls ``` 输出示例： ``` NAME STATE ADDRESS PUBLIC IP WIREGUARD ENDPOINTS MACHINE ID machine-incv Up 10.210.0.1/24 - 172.16.0.3:51820, ... 6cec579e... ``` **字段说明**： - NAME：机器在集群中的唯一名称 - STATE：机器状态（Up 表示运行中） - ADDRESS：WireGuard 网状网络中的私有 IP 地址和子网 - PUBLIC IP：用于入口的公网 IP（如配置） - WIREGUARD ENDPOINTS：其他机器可通过此端点连接 - MACHINE ID：机器的唯一标识符 ## 3. 添加第二个节点 ```bash uc machine add laborant@server-2 ``` 再次查看集群状态： ```bash uc machine ls ``` 输出示例： ``` NAME STATE ADDRESS PUBLIC IP WIREGUARD ENDPOINTS MACHINE ID machine-incv Up 10.210.0.1/24 - 172.16.0.3:51820, ... 6cec579e... machine-m4wy Up 10.210.1.1/24 - 172.16.0.4:51820, ... e84e115e... ``` 每个节点自动获得独立的 /24 子网（10.210.0.0/24、10.210.1.0/24 等），用于分配容器 IP 地址。 ## 4. 重命名集群节点 默认节点名称带有随机后缀，可以重命名为更有意义的名称： ```bash uc machine rename machine-incv server-1 uc machine rename machine-m4wy server-2 ``` # 五、服务部署 ## 1. 查看现有服务 ```bash uc ls ``` 输出示例： ``` NAME MODE REPLICAS IMAGE ENDPOINTS caddy global 2 caddy:2.10.2 ``` Caddy 自动以 global 模式部署，在每个节点上运行一个实例，用于路由请求。 ## 2. 部署新服务 部署 Excalidraw 服务： ```bash uc run --name excalidraw --publish excalidraw.internal:80/http excalidraw/excalidraw ``` **命令说明**： - `--name excalidraw`：服务名称 - `--publish excalidraw.internal:80/http`：发布为 HTTP 服务 - `excalidraw/excalidraw`：Docker 镜像 **执行过程**： 1. 随机选择一个集群节点 2. 拉取 Docker 镜像 3. 创建服务并启动容器 4. 通过 Caddy 在所有集群节点上暴露服务 ## 3. 查看服务详情 ```bash uc inspect excalidraw ``` 输出示例： ``` Service ID: 0af10efcb5a0d9155268bbbcbfc1419f Name: excalidraw Mode: replicated CONTAINER ID IMAGE CREATED STATUS IP ADDRESS MACHINE 38410444eaf3 excalidraw/excalidraw 2 minutes ago Up 2 minutes (healthy) 10.210.0.3 server-1 ``` ## 4. 访问服务 从集群内的任何机器访问服务： ```bash curl --header 'Host: excalidraw.internal' server-1 ``` # 六、集群管理 ## 1. 上下文管理 Uncloud 支持管理多个集群，通过上下文进行切换。 查看所有上下文： ```bash uc ctx ls ``` 输出示例： ``` NAME CURRENT CONNECTIONS default ✓ 2 ``` 配置文件位置：`~/.config/uncloud/config.yaml` ```yaml current_context: default contexts: default: connections: - ssh: laborant@server-1 ssh_key_file: ~/.ssh/id_ed25519 - ssh: laborant@server-2 ssh_key_file: ~/.ssh/id_ed25519 ``` ## 2. 切换上下文 ```bash uc ctx use <context-name> ``` ## 3. 更新节点属性 ```bash uc machine update <machine-name> <options> ``` # 七、进阶操作 ## 1. 扩展服务副本 将服务扩展到 2 个副本： ```bash uc scale excalidraw 2 ``` ## 2. 使用 Compose 配置部署 使用类似 Docker Compose 的配置文件部署服务： ```bash uc deploy <compose-file> ``` ## 3. 发布服务到互联网 配置服务的公网访问，需要： 1. 使用 `--public-ip auto` 初始化节点 2. 配置自定义域名 3. 设置 HTTPS 入口 详细文档：https://uncloud.run/docs/concepts/ingress/publishing-services # 八、集群架构 ## 1. 网络架构 ```mermaid graph LR A[控制机] -->|SSH| B[server-1] A -->|SSH| C[server-2] B -->|WireGuard| D[10.210.0.0/24] C -->|WireGuard| E[10.210.1.0/24] D <-->|网状网络| E F[Corrosion] -.同步.-> B F -.同步.-> C ```  ## 2. 服务路由流程 ```mermaid sequenceDiagram participant C as 客户端 participant G as Caddy global participant N1 as server-1 participant N2 as server-2 participant S as Excalidraw C->>G: HTTP 请求 G->>N1: 转发请求 N1->>S: 服务发现 S-->>N1: 返回响应 N1-->>G: 返回结果 G-->>C: HTTP 响应 ```   # 九、常见问题 ## 1. 为什么使用 --public-ip none 在实验环境或多租户环境中，可能无法完全控制机器的公网 IP。使用 `--public-ip none` 跳过入口配置。生产环境通常使用 `--public-ip auto` 自动检测。 ## 2. 为什么使用 --no-dns 跳过通过 Uncloud 托管 DNS 服务预留 `*.uncld.dev` 子域名。实验环境中此功能不可用，生产环境可以启用。 ## 3. 节点无法连接 检查： - SSH 连接是否正常 - 防火墙规则是否允许 WireGuard 端口（默认 51820） - 节点上 uncloudd 是否运行 ## 4. 服务无法访问 检查： - 服务是否正常运行：`uc ls` - Caddy 是否运行：`uc inspect caddy` - 网络连接是否正常：`ping <节点 IP>` # 十、参考资料 *** ## 参考资料 1. [Uncloud: How to Set Up a New Cluster](https://labs.iximiuz.com/tutorials/uncloud-create-cluster-ebebf72b) 2. [Uncloud Official Documentation](https://uncloud.run/docs/) 3. [Uncloud CLI Reference](https://uncloud.run/docs/cli-reference/) 4. [WireGuard Official Site](https://www.wireguard.com/) 最后修改：2026 年 01 月 18 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏