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）：

curl -sf https://uncloud.run/install.sh | sh

或者参考官方安装指南：https://uncloud.run/docs/getting-started/install-cli

3. 验证安装

uc --version

三、核心概念

1. 基本术语

  • uc：Uncloud 命令行客户端工具
  • uncloudd：Uncloud 守护进程，运行在集群节点上
  • Corrosion：状态同步和服务发现组件
  • WireGuard：用于创建安全的网状网络
  • Context：集群上下文，允许管理多个集群

2. 工作原理

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

mermaid

Uncloud 工作原理

3. 架构说明

Uncloud 采用控制节点和工作节点的架构：

  • 控制节点：运行 uc CLI，用于远程管理集群
  • 工作节点：运行 uncloudd 守护进程和 Docker，承载容器负载
  • 网状网络：通过 WireGuard 自动创建，节点间安全通信
  • 服务发现：由 Corrosion 组件提供
  • 入口路由：Caddy 作为全局服务运行

四、快速上手

1. 初始化第一个集群节点

在控制机上执行以下命令，将 server-1 初始化为集群的第一个节点：

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. 查看集群状态

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. 添加第二个节点

uc machine add laborant@server-2

再次查看集群状态：

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. 重命名集群节点

默认节点名称带有随机后缀，可以重命名为更有意义的名称：

uc machine rename machine-incv server-1
uc machine rename machine-m4wy server-2

五、服务部署

1. 查看现有服务

uc ls

输出示例：

NAME    MODE    REPLICAS  IMAGE          ENDPOINTS
caddy   global  2         caddy:2.10.2

Caddy 自动以 global 模式部署，在每个节点上运行一个实例，用于路由请求。

2. 部署新服务

部署 Excalidraw 服务：

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. 查看服务详情

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. 访问服务

从集群内的任何机器访问服务：

curl --header 'Host: excalidraw.internal' server-1

六、集群管理

1. 上下文管理

Uncloud 支持管理多个集群，通过上下文进行切换。

查看所有上下文：

uc ctx ls

输出示例：

NAME     CURRENT  CONNECTIONS
default  ✓        2

配置文件位置：~/.config/uncloud/config.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. 切换上下文

uc ctx use <context-name>

3. 更新节点属性

uc machine update <machine-name> <options>

七、进阶操作

1. 扩展服务副本

将服务扩展到 2 个副本：

uc scale excalidraw 2

2. 使用 Compose 配置部署

使用类似 Docker Compose 的配置文件部署服务：

uc deploy <compose-file>

3. 发布服务到互联网

配置服务的公网访问，需要：

  1. 使用 --public-ip auto 初始化节点
  2. 配置自定义域名
  3. 设置 HTTPS 入口

详细文档：https://uncloud.run/docs/concepts/ingress/publishing-services

八、集群架构

1. 网络架构

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

Uncloud 网络架构

2. 服务路由流程

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 响应

mermaid

服务路由流程

九、常见问题

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
  2. Uncloud Official Documentation
  3. Uncloud CLI Reference
  4. WireGuard Official Site
最后修改：2026 年 01 月 18 日
© 允许规范转载
如果觉得我的文章对你有用，请随意赞赏