快速上手#

本文带你从一台空的 Linux 服务器走到一个运行中的应用：安装 CLI、初始化一台 Manager、部署第一个工作负载，再加入更多节点。不需要任何 Luma 前置配置。

准备条件#

第一个工作负载不需要 Tailscale、构建节点或私有镜像仓库。需要家庭节点、中继或源码构建时再添加。

1. 安装 CLI#

在 Manager 以及所有要用来部署的机器上执行：

curl -fsSL https://raw.githubusercontent.com/LiuTianjie/luma/main/scripts/install-luma.sh | sh
~/.local/bin/luma doctor --local

安装脚本需要 Python 3.9+ 以及 curl 或 wget。它把最新发布版安装到 ~/.local/share/luma，并把 luma 放到 ~/.local/bin；如果该目录还不在 PATH 中，请打开一个新的 shell。安装过程不会改动 Docker、Nomad 或防火墙。

其他安装方式：

# A specific release, a branch or a commit
curl -fsSL https://raw.githubusercontent.com/LiuTianjie/luma/main/scripts/install-luma.sh | LUMA_INSTALL_REF=v0.2.14 sh

# CI runners and virtual environments
python -m pip install "luma-infra==0.2.14"

卸载 CLI 使用 scripts/uninstall-luma.sh（不会动 /opt/luma 下的服务器状态）；加 --purge 会同时删除本地保存的配置和登录信息。

2. 初始化 Manager#

在 Manager 服务器上执行：

luma bootstrap --domain luma.example.com

luma bootstrap 会询问缺少的配置并解释每一项：

• CLOUDFLARE_API_TOKEN 和 TRAEFIK_ACME_EMAIL 必填。
• 无法自动推断时，会询问 LUMA_DNS_EDGE_TARGET（DNS 记录指向的公网 IP）。
• TAILSCALE_AUTHKEY 和 EGRESS_SUBSCRIPTION_URL 可选，直接回车跳过。

回答会保存到 ~/.luma.config.json（权限 0600），重跑时不再询问。也可以用环境变量提供，或写在当前目录的 .env 中；Luma 只会从 ./.env 读取它自己的配置项。

如果 Manager 需要代理才能访问 GHCR（中国大陆服务器通常如此），请在初始化前设置 EGRESS_SUBSCRIPTION_URL；否则加 --skip-egress。

初始化会安装 Docker 和 Nomad server、写入节点元数据、配置防火墙、以 Nomad job 方式部署 Traefik 和 Luma Control，并在 /opt/luma/control/control.sqlite3 创建 Control 数据库。每一步都会打印 [start]、[ok] 或 [fail]，失败时附带 Fix: 提示。修复后可以直接重跑；也可以单独修复某一层：luma manager egress、luma node tailscale、luma doctor。

完成后会输出：

Control URL: https://luma.example.com
Management token: ...
Node join token: ...
Dashboard: https://luma.example.com/dashboard/

两个令牌都要保密：

• 管理令牌用于 CLI、CI 和控制台登录，拥有全部权限。对应的环境变量是 LUMA_DEPLOY_TOKEN。
• 节点加入令牌只用于服务器加入集群。

节点 agent 的凭据由系统自动管理，你不需要接触。

如需使用自己的 Control 镜像，请先发布镜像，并在初始化前设置 LUMA_CONTROL_IMAGE。初始化和升级过程中，Luma 不会构建或复用陈旧的本地镜像。

3. 部署第一个工作负载#

最快的验证方式是控制台：打开 Dashboard 地址，粘贴管理令牌，选择 应用 → 创建应用 → hello-world 首装验证。它会部署一个不需要 DNS 和镜像仓库的内部服务，用来证明调度正常。

在你的电脑上登录并部署一个公网服务：

luma login https://luma.example.com --token-stdin < token.txt
luma init --name status --image traefik/whoami:v1.10.3 --region cn --domain status.example.com --port 80
luma validate status.yaml
luma deploy status.yaml --dry-run
luma deploy status.yaml
luma app list

luma init 会生成一份带注释的 manifest，包含内存上限和健康检查，按需修改即可。--dry-run 会打印 Control 将要提交的 Nomad job。请把 status.example.com 换成你 Cloudflare 域名下的主机名。本地构建、仓库导入和 Compose 应用见部署应用。

4. 加入更多节点#

使用节点加入令牌，在每台新服务器上执行：

luma node join https://luma.example.com --token <node-join-token> --region global --name sg-1

• --region 决定哪些服务可以运行在这里：cn、global、home，或通过 luma region create 创建的区域。
• --name 是节点名，manifest 用 node: 固定服务时填写它。

家庭节点和其他私网节点需要 Tailscale：先设置 TAILSCALE_AUTHKEY 或执行 luma node tailscale。macOS 节点还需要运行中的 Docker（Docker Desktop 或 OrbStack）。

luma node list 显示已注册节点及其 agent 状态。luma node exit 会停止本机的 Nomad 并删除本机的 Luma 状态；加上 --endpoint 和 --token 会同时从集群注销。

所需端口#

Luma 会在 Linux 节点上配置 UFW。云安全组和 Tailscale ACL 请保持一致：

Manager 有 Tailscale 地址时，Luma 只在 tailscale0 上开放 Nomad 端口。出站代理端口 7890 永远不会对公网开放。

5. 保持更新#

luma update            # on the manager: CLI and Control; on a node: CLI and agent; elsewhere: CLI
luma update fleet      # from any client: every node with a ready agent (the manager is skipped)

未指定 --install-ref 时都会安装最新发布版。控制台的 节点 → 升级中心 提供带进度和路由检查的同等操作，是升级 Manager 的首选方式。luma update 不会重启 Docker 或 Nomad，也不会重新部署应用。

6. 检查健康状态#

luma status
luma doctor
luma doctor --deep

doctor 会检查登录、Control、DNS 配置、节点 agent 和 Nomad；--deep 还会评估每个节点上报的 Docker 和 Nomad 诊断信息。

下一步#

• 核心概念：区域、暴露方式和出站代理。
• 部署应用：镜像、本地构建、仓库导入、Compose 与 CI。
• 日常运维：日志、回滚、重启、删除和节点维护。
• 故障排查：某一步失败时怎么办。