Luma

自托管部署控制面

luma 轻量多服务器管理控制面

把域名、端口、入口和 region 写进 YAML。Luma 负责同步 Cloudflare DNS、 Traefik HTTPS 路由和 Nomad job；每台服务器只需要在本机加入集群。

DNS Cloudflare 同步 TLS Traefik ACME Nodes region 标签 Rollback Nomad 版本回滚
查看部署流程 查看源码
步骤 1 安装 Luma 命令行工具 (在你的服务器/控制端执行)
$ curl -fsSL https://raw.githubusercontent.com/LiuTianjie/luma/main/scripts/install-luma.sh | sh
步骤 2 安装 Luma 技能
Codex Claude Code Gemini
Install the skill from https://github.com/LiuTianjie/luma/tree/main/skills/luma-deployment-yaml
或在终端手动安装 (Manual Install)
mkdir -p ~/.codex/skills && git clone --depth 1 https://github.com/LiuTianjie/luma.git /tmp/luma-repo && cp -R /tmp/luma-repo/skills/luma-deployment-yaml ~/.codex/skills/ && rm -rf /tmp/luma-repo
部署预览 status.example.com
01 Manifest status.yaml domain: status.example.com
exposure: cn-edge
port: 80
02 Control Luma Control 把一份 manifest 转成 DNS、证书、路由和服务更新
Cloudflare DNS status.example.com -> cn-edge
Traefik Edge Host 规则 + ACME 证书
Nomad Clients status:80 allocation x2 
$ luma deploy status.yaml
ok dns     status.example.com -> cn-edge
ok tls     acme certificate requested
ok route   Host(status.example.com) -> status:80
ok nomad   status allocations x2
Domainstatus.example.com Exposurecn-edge Targetstatus:80
域名写在清单里 domain 就是服务访问地址
Cloudflare 管理 DNS 按 exposure 指到对应入口
Traefik 处理 HTTPS 每个 Host 都走自己的证书
支持私有镜像 registry token 不写进 YAML
支持 Docker Compose 标准 compose.yml 配合 Luma 旁车，轻松编排多服务
声明式共享存储卷 在控制面注册存储类，Luma 在多节点间自动调度挂载
运行态回滚 在 CLI 或控制台查看版本，并回滚 Nomad job

先把这些东西备好。

01 域名

控制 API 和公开服务都要用真实域名，例如 luma.example.com 和 status.example.com。

02 Cloudflare DNS

DNS zone 放在 Cloudflare，并准备一个能读取 zone、修改 DNS 记录的 API token。

03 Linux Manager

先准备一台有 sudo 权限的 Linux 服务器。2c2g 可以试用，但业务服务要限制资源。

04 Tailscale 可选

单台公网 manager 不一定要 Tailscale。home 节点、私有 join 或 tailscale-relay 才需要。

每条命令会更新什么。

Manager 安装 CLI 01 / 06
在 manager 上安装 luma
Manager / Control CLI 已安装
Traefik Edge 未创建
CN Worker 未加入
Global Worker 未加入
Client 未登录
域名 还没有服务 deploy 时读取 manifest
DNS 等待中 deploy 时写入记录
证书 等待中 Traefik 按 Host 申请证书
路由与负载 等待中 Traefik 转发到 service:port
status.yaml 
name: status
image: traefik/whoami:latest
region: cn
domain: status.example.com
port: 80
exposure: cn-edge
replicas: 2
resources:
  limits:
    cpus: "0.50"
    memory: 512M

Luma 读取 manifest，并更新部署链路。

  • 01
    读服务入口

    读取 domain、port 和 exposure，确定访问地址和目标端口。

  • 02
    写 DNS 记录

    在 Cloudflare 写入 DNS 记录，让域名指向选中的入口节点。

  • 03
    建 HTTPS 路由

    Traefik 读取 Host 规则，申请证书并创建 HTTPS 路由。

  • 04
    按需拉取私有镜像

    私有 GHCR 或自建 registry 会使用已保存的仓库凭证，不需要把 token 写进 manifest。

  • 05
    更新服务

    更新 Nomad job，把 status.example.com 转发到 status:80。

  • 06
    保留版本历史

    Nomad 保存 job 版本，控制台和 luma rollback 都能回退运行中的 job。

  • 07
    限制资源

    业务服务和控制组件共用小型服务器时，用 Nomad resources 限制 CPU 和内存。

多服务 Compose 与持久化存储卷

  • 01
    标准的 docker-compose.yml 编排

    无侵入设计。继续使用原本的 Compose 文件描述服务依赖与容器网络，方便本地开发测试。

  • 02
    Luma 旁车文件 (luma.compose.yml)

    将 Luma 特有的部署选项（如 Region、域名入口、存储挂载）隔离在旁车中，实现平滑集成。

  • 03
    声明式共享存储类 (StorageClass)

    在控制面注册 cn-nfs 存储。Luma 自动按 Region 与网络拓扑动态解析端点并配置挂载。

  • 04
    数据防丢保护与平滑迁移

    严格的安全检查。变更存储位置时自动拦截并要求明确声明 adopted（已迁入）或 initialize: empty（空挂载）。

luma.compose.yml 
name: app-stack
compose: docker-compose.yml
region: cn

volumes:
  pg-data:
    storageClass: cn-nfs
    path: postgres/pg-data

services:
  app:
    exposure: cn-edge
    domain: app.example.com
    port: 3000
docker-compose.yml 
version: '3.8'
services:
  app:
    image: company/app:latest
    volumes:
      - pg-data:/var/lib/pg/data
  postgres:
    image: postgres:15
    volumes:
      - pg-data:/var/lib/postgresql/data

volumes:
  pg-data: {}

按服务器角色执行对应命令。

安装 CLI

先在 manager 上安装 luma。worker 和客户端后面按需安装同一个命令。

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

初始化控制面

在第一台服务器上初始化 Nomad server，并以 Nomad job 启动 Traefik、Luma Control 和 egress gateway。

luma bootstrap manager --domain luma.example.com

加入工作节点

每台服务器自己执行 join，并写入 region 标签。调度主要看 region。

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

保存私有 registry 凭证

镜像仓库是私有的，就先保存一次 registry 凭证。

luma login https://luma.example.com --token <deploy-token>
printf '%s' "$GHCR_TOKEN" | luma registry login ghcr.io --username <user> --password-stdin

从客户端部署服务

客户端登录后提交 manifest。Luma 会打印 DNS、证书、路由和 stack 更新进度。

luma login https://luma.example.com --token <deploy-token>
luma deploy status.yaml

官方文档与指南

查阅详细的规则设计、架构原理以及各角色的使用指南。

🚀

控制面引导与部署

了解如何通过 luma bootstrap 快速初始化并部署集群控制面基础设施。

阅读文档 →
💾

Compose 与共享存储

详细阐述 luma.compose.yml 旁车编写、多服务编排与 NFS 存储类绑定规则。

阅读文档 →
🤖

AI 编码助手技能

为你的 Codex、Claude Code 或 Gemini 安装 Luma 部署技能，实现 YAML 智能生成与校验。

阅读文档 →
💻

CLI 命令行手册

Luma 命令行工具所有子命令、参数选项，以及 deploy、history、rollback 等常用操作指南。

阅读文档 →