uncloud

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 网状网络连接的 peer 机器上运行 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 连接的平等 peer
• 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                    # 将本地镜像推送到所有机器
uc image push myapp:latest -m machine1,machine2  # 推送到特定机器
uc images                                     # 列出集群中的镜像

卷

uc volume ls                  # 所有卷
uc volume ls -m machine1      # 特定机器上的卷
uc volume create NAME -m MACHINE
uc volume rm NAME

Caddy

uc caddy config    # 显示当前生成的 Caddyfile（只读）
uc caddy deploy    # 在集群中部署/升级 Caddy

DNS 与上下文

uc dns show        # 显示已保留的 *.uncld.dev 域名
uc dns reserve     # 保留新域名
uc ctx ls          # 列出集群上下文
uc ctx use prod    # 切换上下文

---

端口发布

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

-p [hostname:]container_port[/protocol]

示例	含义
-p 8080/https	HTTPS，使用自动生成的 服务名.集群域名 主机名
-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}} {
          import common_proxy
        }
        basic_auth /admin/* {
          admin $2a$14$...
        }
      }

可在 x-caddy 内部使用的模板函数：

• {{upstreams [service] [port]}} —— 健康容器 IP
• {{.Name}} —— 服务名
• {{.Upstreams}} —— 所有服务到 IP 的映射

x-machines —— 放置约束

services:
  db:
    image: postgres:18
    x-machines: db-machine          # 单台机器名
  app:
    image: app:latest
    x-machines:
      - machine-1
      - machine-2

完整的多服务示例

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:

---

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

要通过 Caddy 暴露外部设备（例如 BMC、NAS、路由器管理界面），无需运行实际容器：

1. 创建 Caddyfile 片段（例如 ~/device.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. 注册为命名服务，使用无操作容器：

uc service run \
  --name device-bmc \
  --caddyfile ~/device.caddyfile \
  registry.k8s.io/pause:3.9

pause 是一个极简的无操作容器——它不做任何事情，但为 Uncloud 提供了一个服务条目来挂载 Caddyfile。

3. 验证：

uc caddy config   # device.example.com 块应该出现

--caddyfile 不能与 @host 以外的已发布端口同时使用。

DNS 提示： 通配符记录（*.yourdomain.com → 集群公共 IP）意味着任何新的子域名立即可用——无需为每个服务更改 DNS。

---

服务 DNS（内部）

集群内的服务通过名称互相解析：

DNS 名称	解析到
service-name	任意健康容器
service-name.internal	同上
rr.service-name.internal	轮询
nearest.service-name.internal	优先本地机器

---

扩缩容与全局服务

uc scale web 5    # 5 个副本（分布在多台机器上）
uc scale web 1    # 缩容

services:
  caddy:
    deploy:
      mode: global   # 每台机器运行一个容器

---

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

image: myapp:{{gitdate "20060102"}}.{{gitsha 7}}
image: myapp:{{gitsha 7}}.${GITHUB_RUN_ID:-local}

函数	输出
{{gitsha N}}	提交 SHA 的前 N 个字符
{{gitdate "format"}}	Git 提交日期（Go 格式）
{{date "format"}}	当前日期

---

常见工作流

从源代码部署：

uc deploy                          # 构建 + 推送 + 部署
uc build --push && uc deploy --no-build   # 分步操作

检查服务：

uc inspect web
uc logs -f web
uc logs --since 1h web
uc exec web                        # 打开 Shell
uc exec web /bin/sh -c "env"       # 运行特定命令

零停机部署自动进行；Uncloud 会在终止旧容器前等待健康检查通过。

强制重建：

uc deploy --recreate

---

常见错误

错误	修正
直接编辑 Caddyfile	在 Compose 中使用 x-caddy 或在 uc service run 中使用 --caddyfile
代理具有自签名证书的 HTTPS 上游	添加 transport http { tls_insecure_skip_verify }
uc caddy config 显示没有用户定义的块	Caddy 管理 socket 不可达——检查 uc inspect caddy 和 uc logs caddy
服务无法从容器内访问外部 LAN IP	验证 Caddy 容器所在主机能否路由到目标网络
uc service rm 后卷丢失	命名卷会保留；只有匿名卷会被自动移除。