Back to Details

uncloud

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Uncloud Cluster Management

Uncloud集群管理

Reference for the 
uc
CLI — a decentralised self-hosting platform using Docker containers, WireGuard mesh networking, and Caddy reverse proxy.
uc
CLI参考文档——一个基于Docker容器、WireGuard网格网络和Caddy反向代理的去中心化自托管平台。

When to Activate

适用场景

Use this skill when working with Uncloud clusters, especially when:
  • Bootstrapping or joining machines with 
    uc machine
  • Deploying services from Compose files with 
    uc deploy
  • Publishing HTTP, HTTPS, TCP, or UDP ports through Uncloud
  • Configuring Caddy ingress with 
    x-caddy
    , 
    x-ports
    , or 
    --caddyfile
  • Routing external LAN devices through the cluster proxy
  • Inspecting logs, service state, volumes, DNS, or machine placement
在处理Uncloud集群时使用此技能，尤其是在以下场景：
  • 使用
    uc machine
    引导或加入机器
  • 使用
    uc deploy
    从Compose文件部署服务
  • 通过Uncloud发布HTTP、HTTPS、TCP或UDP端口
  • 使用
    x-caddy
    、
    x-ports
    或
    --caddyfile
    配置Caddy入口
  • 通过集群代理路由外部LAN设备
  • 查看日志、服务状态、卷、DNS或机器部署位置

How It Works

工作原理

Uncloud runs Docker services across peer machines connected by a WireGuard mesh. Each machine is an equal cluster member; services communicate on the overlay network and Caddy runs globally to terminate public HTTP/HTTPS traffic. Compose files can use Uncloud extensions for ingress, placement, and generated Caddy configuration, while the 
uc
CLI handles image distribution, scheduling, scaling, logs, and cluster state.
Uncloud在通过WireGuard网格连接的对等机器上运行Docker服务。每台机器都是平等的集群成员；服务通过覆盖网络通信，Caddy全局运行以终止公共HTTP/HTTPS流量。Compose文件可使用Uncloud扩展进行入口配置、部署位置设置和生成Caddy配置，而
uc
CLI负责镜像分发、调度、扩容、日志和集群状态管理。

Examples

示例

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

Core Concepts

核心概念

  • No central control plane — all machines are equal peers connected by WireGuard
  • Caddy runs as a global service on every machine; auto-obtains TLS from Let's Encrypt
  • Overlay network — services communicate via 
    10.210.0.0/16
    by default; DNS provided inside the mesh
  • Caddyfile is autogenerated — never edit it directly; use 
    x-caddy
    / 
    --caddyfile
    instead
  • 无中央控制平面 —— 所有机器都是通过WireGuard连接的平等节点
  • Caddy作为全局服务在每台机器上运行；自动从Let's Encrypt获取TLS证书
  • 覆盖网络 —— 服务默认通过
    10.210.0.0/16
    通信；网格内提供DNS服务
  • Caddyfile自动生成 —— 切勿直接编辑；请使用
    x-caddy
    / 
    --caddyfile
    替代

CLI Quick Reference

CLI快速参考

Machines

机器管理

CommandPurpose
uc machine init user@host
Bootstrap first machine / new cluster
uc machine add user@host
Join machine to existing cluster
uc machine ls
List machines
uc machine update NAME --public-ip IP
Update public IP for ingress
uc machine rm NAME
Remove machine
Key 
init
flags: 
--name
, 
--network 10.210.0.0/16
, 
--no-caddy
, 
--no-dns
, 
--public-ip auto\|IP\|none
命令用途
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

Services

服务管理

CommandPurpose
uc service ls
/ 
uc ls
List services
uc service run IMAGE
Run a single container service
uc deploy
Deploy from 
compose.yaml
uc deploy --no-build
Deploy already-pushed images without rebuilding
uc deploy --recreate
Force service recreation
uc scale SERVICE N
Set replica count
uc service logs SERVICE
View logs
uc service exec SERVICE
Shell into container
uc service inspect SERVICE
Detailed info
uc service rm SERVICE
Remove service (keeps named volumes)
uc ps
All containers across cluster
命令用途
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
查看集群中所有容器

Images

镜像管理

bash
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
bash
uc image push myapp:latest                    # 将本地镜像推送到所有机器
uc image push myapp:latest -m machine1,machine2  # 将镜像推送到指定机器
uc images                                     # 列出集群中的镜像

Volumes

卷管理

bash
uc volume ls                  # All volumes
uc volume ls -m machine1      # On specific machine
uc volume create NAME -m MACHINE
uc volume rm NAME
bash
uc volume ls                  # 查看所有卷
uc volume ls -m machine1      # 查看指定机器上的卷
uc volume create NAME -m MACHINE
uc volume rm NAME

Caddy

Caddy管理

bash
uc caddy config    # Show current generated Caddyfile (read-only)
uc caddy deploy    # Deploy/upgrade Caddy across cluster
bash
uc caddy config    # 查看当前生成的Caddyfile（只读）
uc caddy deploy    # 在集群中部署/升级Caddy

DNS & Context

DNS与上下文

bash
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
bash
uc dns show        # 查看保留的*.uncld.dev域名
uc dns reserve     # 保留新域名
uc ctx ls          # 列出集群上下文
uc ctx use prod    # 切换上下文

Port Publishing

端口发布

HTTP/HTTPS (via Caddy reverse proxy)

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

-p [hostname:]container_port[/protocol]
ExampleMeaning
-p 8080/https
HTTPS with auto 
service-name.cluster-domain
hostname
-p app.example.com:8080/https
HTTPS with custom hostname
-p 8080/http
HTTP only, no TLS
-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 (host-bound, bypasses Caddy)

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

-p [host_ip:]host_port:container_port[/protocol]@host
ExampleMeaning
-p 5432:5432@host
TCP 5432 on all interfaces
-p 127.0.0.1:5432:5432@host
TCP 5432 loopback only
-p 53:5353/udp@host
UDP
-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 File Extensions

Compose文件扩展

Uncloud adds these extensions on top of Docker Compose:
Uncloud在Docker Compose基础上添加了以下扩展：

x-ports
— publish ports with domains

x-ports
—— 带域名的端口发布

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

x-caddy
— custom Caddy config for service

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

yaml
services:
  app:
    image: app:latest
    x-caddy: |
      example.com {
        redir https://www.example.com{uri} permanent
      }
      www.example.com {
        reverse_proxy {{upstreams 8000}} {
          import common_proxy
        }
        basic_auth /admin/* {
          admin $2a$14$...
        }
      }
Template functions available inside 
x-caddy
:
  • {{upstreams [service] [port]}}
    — healthy container IPs
  • {{.Name}}
    — service name
  • {{.Upstreams}}
    — map of all services → IPs
yaml
services:
  app:
    image: app:latest
    x-caddy: |
      example.com {
        redir https://www.example.com{uri} permanent
      }
      www.example.com {
        reverse_proxy {{upstreams 8000}} {
          import common_proxy
        }
        basic_auth /admin/* {
          admin $2a$14$...
        }
      }
x-caddy
中可用的模板函数：
  • {{upstreams [service] [port]}}
    —— 健康容器的IP地址
  • {{.Name}}
    —— 服务名称
  • {{.Upstreams}}
    —— 所有服务→IP的映射

x-machines
— placement constraints

x-machines
—— 部署位置约束

yaml
services:
  db:
    image: postgres:18
    x-machines: db-machine          # Single machine name
  app:
    image: app:latest
    x-machines:
      - machine-1
      - machine-2
yaml
services:
  db:
    image: postgres:18
    x-machines: db-machine          # 指定单个机器名称
  app:
    image: app:latest
    x-machines:
      - machine-1
      - machine-2

Full multi-service example

完整多服务示例

yaml
services:
  api:
    build: ./api
    x-ports:
      - api.example.com:3000/https
    environment:
      DATABASE_URL: postgres://db:5432/mydb

  web:
    build: ./web
    x-ports:
      - example.com:8000/https
      - www.example.com:8000/https
    environment:
      API_URL: http://api:3000

  db:
    image: postgres:18
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - db-data:/var/lib/postgresql/data
    x-machines: db-machine

volumes:
  db-data:
yaml
services:
  api:
    build: ./api
    x-ports:
      - api.example.com:3000/https
    environment:
      DATABASE_URL: postgres://db:5432/mydb

  web:
    build: ./web
    x-ports:
      - example.com:8000/https
      - www.example.com:8000/https
    environment:
      API_URL: http://api:3000

  db:
    image: postgres:18
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - db-data:/var/lib/postgresql/data
    x-machines: db-machine

volumes:
  db-data:

Routing to External (Non-Cluster) Devices

路由到外部（非集群）设备

To expose an external device (e.g. BMC, NAS, router UI) via Caddy without running a real container:
1. Create a Caddyfile snippet (e.g. 
~/device.caddyfile
):
caddyfile
https://device.example.com {
    reverse_proxy https://192.168.1.x {
        transport http {
            tls_insecure_skip_verify   # needed for self-signed BMC certs
        }
    }
    log
}
For plaintext upstream: 
reverse_proxy http://192.168.1.x:port
2. Register as a named service with no-op container:
bash
uc service run \
  --name device-bmc \
  --caddyfile ~/device.caddyfile \
  registry.k8s.io/pause:3.9
pause
is a minimal no-op container — it does nothing, but gives Uncloud a service entry to attach the Caddyfile to.
3. Verify:
bash
uc caddy config   # device.example.com block should appear
--caddyfile
cannot be combined with non-
@host
published ports.
DNS tip: A wildcard record (
*.yourdomain.com → cluster-public-ip
) means any new subdomain works immediately — no DNS change needed per service.
要通过Caddy暴露外部设备（如BMC、NAS、路由器UI）而无需运行真实容器：
1. 创建Caddyfile片段（例如
~/device.caddyfile
）：
caddyfile
https://device.example.com {
    reverse_proxy https://192.168.1.x {
        transport http {
            tls_insecure_skip_verify   # 自签名BMC证书需要此配置
        }
    }
    log
}
对于明文上游服务：
reverse_proxy http://192.168.1.x:port
2. 注册为带无操作容器的命名服务：
bash
uc service run \
  --name device-bmc \
  --caddyfile ~/device.caddyfile \
  registry.k8s.io/pause:3.9
pause
是一个最小化的无操作容器——它不执行任何操作，但为Uncloud提供一个服务条目来关联Caddyfile。
3. 验证：
bash
uc caddy config   # 应显示device.example.com配置块
--caddyfile
不能与非
@host
类型的发布端口结合使用。
DNS提示： 通配符记录（
*.yourdomain.com → cluster-public-ip
）意味着任何新子域名可立即生效——无需为每个服务修改DNS。

Service DNS (Internal)

服务DNS（内部）

Services inside the cluster resolve each other by name:
DNS nameResolves to
service-name
Any healthy container
service-name.internal
Same
rr.service-name.internal
Round-robin
nearest.service-name.internal
Machine-local first
集群内的服务可通过名称相互解析：
DNS名称解析目标
service-name
任意健康容器
service-name.internal
同上
rr.service-name.internal
轮询解析
nearest.service-name.internal
优先解析本地机器上的容器

Scaling & Global Services

扩容与全局服务

bash
uc scale web 5    # 5 replicas (spread across machines)
uc scale web 1    # Scale down
yaml
services:
  caddy:
    deploy:
      mode: global   # One container on every machine
bash
uc scale web 5    # 5个副本（分布在多台机器上）
uc scale web 1    # 缩容
yaml
services:
  caddy:
    deploy:
      mode: global   # 在每台机器上运行一个容器

Image Tag Templates (in compose.yaml)

镜像标签模板（在compose.yaml中）

yaml
image: myapp:{{gitdate "20060102"}}.{{gitsha 7}}
image: myapp:{{gitsha 7}}.${GITHUB_RUN_ID:-local}
FunctionOutput
{{gitsha N}}
First N chars of commit SHA
{{gitdate "format"}}
Git commit date in Go format
{{date "format"}}
Current date
yaml
image: myapp:{{gitdate "20060102"}}.{{gitsha 7}}
image: myapp:{{gitsha 7}}.${GITHUB_RUN_ID:-local}
函数输出
{{gitsha N}}
提交SHA的前N个字符
{{gitdate "format"}}
Go格式的Git提交日期
{{date "format"}}
当前日期

Common Workflows

常见工作流

Deploy from source:
bash
uc deploy                          # Build + push + deploy
uc build --push && uc deploy --no-build   # Separate steps
Inspect a service:
bash
uc inspect web
uc logs -f web
uc logs --since 1h web
uc exec web                        # Opens shell
uc exec web /bin/sh -c "env"       # Run specific command
Zero-downtime deploys happen automatically; Uncloud waits for health checks before terminating old containers.
Force recreate:
bash
uc deploy --recreate
从源码部署：
bash
uc deploy                          # 构建 + 推送 + 部署
uc build --push && uc deploy --no-build   # 分步执行
检查服务：
bash
uc inspect web
uc logs -f web
uc logs --since 1h web
uc exec web                        # 打开Shell
uc exec web /bin/sh -c "env"       # 运行指定命令
零停机部署自动完成；Uncloud在终止旧容器前会等待健康检查通过。
强制重新创建：
bash
uc deploy --recreate

Common Mistakes

常见错误

MistakeFix
Editing the Caddyfile directlyUse 
x-caddy
in compose or 
--caddyfile
on 
uc service run
Proxying an HTTPS upstream with self-signed certAdd 
transport http { tls_insecure_skip_verify }
uc caddy config
shows no user-defined blocks		Caddy admin socket unreachable — check 
uc inspect caddy
and 
uc logs caddy
Service can't reach external LAN IP from containerVerify Caddy container's host can route to target network
Volumes lost after 
uc service rm
Named volumes persist; only anonymous volumes are auto-removed
错误修复方案
直接编辑Caddyfile在compose中使用
x-caddy
或在
uc service run
中使用
--caddyfile
代理带自签名证书的HTTPS上游服务添加
transport http { tls_insecure_skip_verify }
配置
uc caddy config
未显示用户定义的配置块		Caddy管理套接字不可达——检查
uc inspect caddy
和
uc logs caddy
容器内的服务无法访问外部LAN IP验证Caddy容器所在主机可路由到目标网络
uc service rm
后卷丢失		命名卷会保留；仅匿名卷会被自动删除