---

name: uncloud description: 用于管理 Uncloud 集群——部署服务、配置 Caddy 入口、为非集群设备添加静态代理路由、发布端口、扩缩容、检查日志，或使用 uc CLI 管理机器和卷。 origin: ECC

Uncloud 集群管理

uc CLI 参考——一个使用 Docker 容器、WireGuard 网状网络和 Caddy 反向代理的去中心化自托管平台。

激活时机

在使用 Uncloud 集群时使用此技能，特别是：

• 使用 uc machine 引导或加入机器
• 使用 uc deploy 从 Compose 文件部署服务
• 通过 Uncloud 发布 HTTP、HTTPS、TCP 或 UDP 端口
• 使用 x-caddy、x-ports 或 --caddyfile 配置 Caddy 入口
• 通过集群代理路由外部 LAN 设备
• 检查日志、服务状态、卷、DNS 或机器放置

工作原理

Uncloud 在通过 WireGuard 网状网络连接的对等机器上运行 Docker 服务。每台机器都是平等的集群成员；服务在覆盖网络上通信，Caddy 全局运行以终止公共 HTTP/HTTPS 流量。Compose 文件可以使用 Uncloud 扩展进行入口、放置和生成的 Caddy 配置，而 uc CLI 处理镜像分发、调度、扩缩容、日志和集群状态。

示例

uc machine init user@host --name machine-1
uc service run --name web -p app.example.com:8080/https nginx:latest
uc deploy

核心概念

• 无中央控制平面 — 所有机器都是通过 WireGuard 连接的平等对等节点
• Caddy 作为全局服务在每台机器上运行；自动从 Let's Encrypt 获取 TLS
• 覆盖网络 — 服务默认通过 10.210.0.0/16 通信；网状网络内提供 DNS
• Caddyfile 自动生成 — 永远不要直接编辑；使用 x-caddy / --caddyfile 代替

---

CLI 快速参考

机器

| 命令 | 用途 | |------|------| | uc machine init user@host | 引导第一台机器/新集群 | | uc machine add user@host | 将机器加入现有集群 | | uc machine ls | 列出机器 | | uc machine update NAME --public-ip IP | 更新入口的公共 IP | | uc machine rm NAME | 移除机器 |

关键 init 标志：--name、--network 10.210.0.0/16、--no-caddy、--no-dns、--public-ip auto|IP|none

服务

| 命令 | 用途 | |------|------| | uc service ls / uc ls | 列出服务 | | uc service run IMAGE | 运行单容器服务 | | uc deploy | 从 compose.yaml 部署 | | uc deploy --no-build | 部署已推送的镜像而不重新构建 | | uc deploy --recreate | 强制重新创建服务 | | uc scale SERVICE N | 设置副本数 | | uc service logs SERVICE | 查看日志 | | uc service exec SERVICE | Shell 进入容器 | | uc service inspect SERVICE | 详细信息 | | uc service rm SERVICE | 移除服务（保留命名卷） | | uc ps | 集群中所有容器 |

镜像

uc image push myapp:latest                    # Push local image to all machines
uc image push myapp:latest -m machine1,machine2  # Push to specific machines
uc images                                     # List images in cluster

卷

uc volume ls                  # All volumes
uc volume ls -m machine1      # On specific machine
uc volume create NAME -m MACHINE
uc volume rm NAME

Caddy

uc caddy config    # Show current generated Caddyfile (read-only)
uc caddy deploy    # Deploy/upgrade Caddy across cluster

DNS 与上下文

uc dns show        # Show reserved *.uncld.dev domain
uc dns reserve     # Reserve a new domain
uc ctx ls          # List cluster contexts
uc ctx use prod    # Switch context

---

端口发布

HTTP/HTTPS（通过 Caddy 反向代理）

-p [hostname:]container_port[/protocol]

| 示例 | 含义 | |------|------| | -p 8080/https | HTTPS，自动使用 service-name.cluster-domain 主机名 | | -p app.example.com:8080/https | HTTPS，自定义主机名 | | -p 8080/http | 仅 HTTP，无 TLS |

TCP/UDP（主机绑定，绕过 Caddy）

-p [host_ip:]host_port:container_port[/protocol]@host

| 示例 | 含义 | |------|------| | -p 5432:5432@host | TCP 5432 在所有接口 | | -p 127.0.0.1:5432:5432@host | TCP 5432 仅回环 | | -p 53:5353/udp@host | UDP |

---

Compose 文件扩展

Uncloud 在 Docker Compose 之上添加了这些扩展：

x-ports — 使用域名发布端口

services:
  app:
    image: app:latest
    x-ports:
      - example.com:8000/https
      - www.example.com:8000/https
      - api.example.com:9000/https

x-caddy — 服务的自定义 Caddy 配置

services:
  app:
    image: app:latest
    x-caddy: |
      example.com {
        redir https://www.example.com{uri} permanent
      }
      www.example.com {
        reverse_proxy {{upstreams 8000}}
      }