elestio

Elestio 技能

版本： 2.4 用途： 在 Elestio DevOps 平台上部署和管理服务 状态： 可使用 最后更新： 2026-09-22

Elestio 是一个全托管的 DevOps 平台。使用专用 VM（而非共享 Kubernetes）。提供 400 多个开源模板、10 家云服务提供商和 100 多个区域。负责处理部署、安全、更新、备份、监控和支持。

此技能使用 官方 Elestio CLI（elestio 命令，通过 npm install -g elestio 安装）。 如果改用 Elestio MCP 连接器（提供 deploy_template、 deploy_catalog_pipeline、list_clusters 等工具），请使用它的工具：下方规则同样适用。有关与各命令对应的工具，请参阅 “使用 Elestio MCP 连接器”。

---

何时使用此技能

在以下情况下使用此技能：

• 用户想部署 PostgreSQL、MySQL、Redis、MongoDB、Elasticsearch 等
• 用户说“部署”“启动”“创建服务器”“我需要一个数据库”
• 用户提到任何开源软件（WordPress、Grafana、n8n、Metabase 等）
• 用户想通过 CI/CD 部署自定义代码
• 用户需要管理备份、防火墙、SSL、SSH 访问
• 用户询问服务状态、费用或凭据

触发短语：

• “部署 PostgreSQL” -> elestio deploy postgresql
• “我需要 Redis 缓存” -> elestio deploy redis
• “为自动化设置 n8n” -> elestio deploy n8n
• “从 GitHub 部署我的应用” -> CI/CD 工作流（阶段 4）
• “当前有哪些服务在运行？” -> elestio services
• “费用是多少？” -> elestio billing

何时不使用此技能

• 初始账户设置 —— 注册、付款和审批必须由人工手动完成
• 交互式 SSH 会话 —— 请改用直接 SSH
• 复杂的 Docker Compose 编辑 —— 直接通过 SSH 登录服务器

---

决策树：应该部署什么？

部署方式有三种，而不是两种。选错是部署失败最常见的原因。

Is the software in the Elestio catalog?  (elestio templates search <name>)
|
+-- YES
|   |
|   +-- Does the user want a managed, isolated VM?  (production databases,
|   |   anything needing backups / monitoring / support)
|   |       -> MANAGED SERVICE
|   |          elestio deploy <template> --project <id>
|   |
|   +-- Does the user want replication / high availability?
|   |       -> CLUSTER   (19 templates only: elestio clusters templates)
|   |          elestio deploy <template> --cluster --nodes <n> --project <id>
|   |
|   +-- Does the user want it cheap, or several apps on one VM?
|           -> PIPELINE FROM CATALOG TEMPLATE
|              elestio cicd deploy-template <software> --target <vmID>
|
+-- NO, it is the user's own code
    |
    +-- In a Git repo?
    |       -> elestio cicd create --auto --target <vmID> --name X --repo owner/repo
    |
    +-- Just a docker-compose file?
            -> elestio cicd create <pipeline.json>

重要：在流水线中部署目录软件

要在 CI/CD 目标上运行目录软件（Vaultwarden、Redis、Metabase 等）， 必须使用 elestio cicd deploy-template（MCP：deploy_catalog_pipeline）。不得使用 elestio cicd create（MCP：create_pipeline_docker / create_pipeline_auto）。

cicd create 会创建一个空流水线。它不了解软件的端口、 环境变量或安装脚本，因此流水线虽然部署了，却不会运行任何内容。这是收到报告最多的失败问题。

deploy-template 会读取模板的 elestio.yml（位于 github.com/elestio-examples/<software>），并据此配置流水线。

# RIGHT
elestio cicd deploy-template vaultwarden --target <vmID>

# WRONG -- produces an empty pipeline
elestio cicd create --auto --target <vmID> --name vaultwarden --repo elestio-examples/vaultwarden

从 CLI 1.3.0 起，这适用于整个目录，包括需要从其仓库挂载文件或需要运行安装脚本的软件（Chromadb、Kafka、 ClickHouse、WordPress、n8n 等）。流水线指向 elestio-examples 仓库，Elestio 会在 VM 本机克隆该仓库，因此这些文件可用，脚本也能运行。无需 Git 账户，也无需将任何内容复制到其他位置。

在 CLI 1.2.x 及更早版本中，唯一的方式是内嵌 Compose 文件，而目录中约有一半的软件无法以这种方式运行。如果使用的是较旧的 CLI，请升级 （npm install -g elestio@latest），不要退回到控制面板操作。

检查目录： elestio templates search # 所有软件 elestio cicd templates # 可作为流水线部署 elestio clusters templates # 支持集群

---

使用 Elestio MCP 连接器

当 Elestio MCP 工具可用时（claude.ai 连接器、Claude Code MCP 服务……），请使用这些工具，而不是 CLI。它们涵盖相同的操作，本技能中的所有规则也都适用于这些工具。破坏性工具需要设置 "confirm": true：请先征求用户同意，和使用 --force 前一样。

任务	CLI	MCP 工具
查找软件	elestio templates search <name>	search_templates
部署托管服务	elestio deploy <template>	deploy_template
部署集群	elestio deploy <template> --cluster --nodes N	使用 cluster_nodes（以及 cluster_mode）调用 deploy_template
查看可组成集群的内容	elestio clusters templates	list_cluster_templates
等待部署完成	elestio wait <vmID>	wait_for_deployment（对于集群，按原样传入以逗号分隔的 providerServerID）
CI/CD 目标	elestio deploy CI-CD-Target	deploy_cicd_target
在管道中部署目录软件	elestio cicd deploy-template <software> --target <vmID>	deploy_catalog_pipeline（支持 dry_run）
在管道中部署自己的仓库	elestio cicd create --auto ...	create_pipeline_auto
在管道中部署自己的 compose	elestio cicd create <pipeline.json>	create_pipeline_docker
查看目标上的管道	elestio cicd pipelines <vmID>	list_pipelines
查看项目中的集群	elestio clusters	list_clusters
查看集群及其节点	elestio clusters info <clusterID>	get_cluster
提升副本	elestio clusters promote <clusterID> <vmID> --force	promote_cluster_node
开启/关闭自动故障转移	elestio clusters failover <clusterID> on|off	set_cluster_auto_failover
重新同步副本	elestio clusters resync <clusterID> --force	resync_cluster
锁定/解锁集群	elestio clusters lock|unlock <clusterID>	lock_cluster / unlock_cluster
添加节点	elestio clusters add-node <clusterID> [--dry-run]	add_cluster_node（支持 dry_run）
移除节点	elestio clusters remove-node <clusterID> <vmID> --force	remove_cluster_node
集群防火墙	elestio clusters firewall|firewall-restrict|firewall-open <clusterID>	get_cluster_firewall / set_cluster_port_access
删除集群	elestio clusters delete <clusterID> --force	delete_cluster
管道的构建历史记录	elestio cicd pipeline-history <vmID> <pipelineID>	get_pipeline_history
删除管道	elestio cicd pipeline-delete <vmID> <pipelineID> --force	delete_pipeline
服务的实时日志	elestio logs <vmID>	get_service_logs
服务的审计记录	elestio audits <vmID>	get_service_audits

MCP 的 deploy_template 不支持试运行：部署集群前，请自行说明 VM 数量和月度费用（使用带有 provider 和 region 的 list_providers_and_sizes 可获取每台 VM 的价格），并征得用户同意。不带筛选条件调用时，list_providers_and_sizes 只会返回各提供商的区域。

MCP 的 provider 值：netcup、hetzner、ovh、aws、lightsail、azure、scaleway、linode、digitalocean、vultr、tcloud。除 netcup 和 OVH 外，deploy_template 需要明确指定 region。attach_volume 接受 storage_type（NVME 或 HDD）。

---

设置（一次性——需要人工操作）

前提条件

1. 创建账户： https://dash.elest.io/signup
2. 验证电子邮件： 检查收件箱并点击验证链接
3. 添加信用卡： https://dash.elest.io/account/payment
4. 等待批准： 通常会即时完成，有时需要 24-48h
5. 创建 API 令牌： https://dash.elest.io/account/security -> Manage API Tokens -> Create Token
6. 配置技能： 向 Agent 提供电子邮件地址和 API 令牌

配置凭据

elestio login --email "[email protected]" --token "xxx_..."
elestio auth test

验证设置

# Should show: [SUCCESS] Authenticated as [email protected]
elestio auth test

# List projects (should show at least one)
elestio projects

---

快速入门示例

部署 PostgreSQL（2 条命令）

# 1. Find template ID
elestio templates search postgresql
# -> ID: 11, PostgreSQL

# 2. Deploy (uses defaults: netcup/nbg/MEDIUM-2C-4G)
elestio deploy postgresql --project 112 --name my-db
# -> Waits for deployment, shows credentials when ready

部署 Redis 缓存

elestio deploy redis --project 112

部署 WordPress

elestio deploy wordpress --project 112

部署集群（复制 / 高可用）

# 1. Check the software supports clustering and see its minimum node count
elestio clusters templates

# 2. ALWAYS dry-run first: billing is per VM, --nodes 3 bills 3 VMs
elestio deploy postgresql --cluster --nodes 3 --project 112 --dry-run

# 3. Deploy
elestio deploy postgresql --cluster --nodes 3 --project 112

# 4. Follow it
elestio clusters list --project 112
elestio clusters info <clusterID>

规则：

• --nodes 表示节点总数，包含主节点。--nodes 3 = 1 个主节点 + 2 个副本。
• ClickHouse、Vault、OpenSearch、RabbitMQ、rke2 和 Nats 至少需要 3 个节点。
• 其他所有服务从 2 个节点起步。最多 15 个。
• --cluster-mode multi-master 仅适用于 MySQL；其他服务均使用 primary-replica（默认值）。

将目录软件部署为流水线（Vaultwarden、Redis、Metabase……）

当用户希望将目录软件部署到 CI/CD 目标，而不是专用 VM 时，应使用此方式。

# 1. Create a CI/CD target if none exists (this is a VM; pipelines share it)
elestio deploy CI-CD-Target --project 112 --name my-target
# -> note the vmID

# 2. Confirm the software is available as a pipeline template
elestio cicd templates vaultwarden

# 3. ALWAYS dry-run first: it prints the ports, env vars and lifecycle hooks
#    that will be applied, and creates nothing
elestio cicd deploy-template vaultwarden --target <vmID> --dry-run

# 4. Deploy (default route: Elestio clones the template repo on the VM)
elestio cicd deploy-template vaultwarden --target <vmID>

成功后，CLI 会输出该软件的 URL、登录名和生成的密码。

有三种方式。请使用默认方式。

	repo（默认）	inline（--inline-compose）	git（--owner <git-user>）
流水线运行的内容	Elestio 在 VM 上克隆的 elestio-examples 仓库	仅内联的 docker-compose.yml	用户 Git 账户中的仓库副本
需要 Git 账户	否	否	是
安装脚本（pre/postInstall）	运行	跳过	运行
compose 挂载或读取的文件（env_file）	存在	缺失	存在
适用范围	整个目录	不需要仓库文件的模板	所有模板

默认方式会发送 imageData.dockerExample（模板仓库 URL）、branch 和 repoName。后端会将它们存储为流水线的 gitConfig.repoURL，部署 Agent 会使用 Elestio 自己的 Git 令牌克隆该仓库。这与仪表板的操作完全一致。

--inline-compose 适用于你自己的 compose 文件。使用此方式时，如果模板的 compose 会挂载或读取仓库文件，CLI 会拒绝该模板并指出文件名：文件可能随仓库提供（n8n 的 ./n8n-task-runners.json）、由安装脚本生成（Kafka 的 ./jaas/*.conf），也可能是 env_file。不要传入 --force 绕过限制；请改用默认方式。

git 方式不可用：它需要 POST /api/cicd/createRepoByTemplate，但 Elestio API 会对此返回 404 （控制器虽已存在，但未注册在后端路由白名单中）。 既然默认方式已可用，该方式也没有必要。

始终验证部署是否成功，不要想当然地认为它已成功：

elestio cicd pipelines <vmID>                          # Build column must say "success"
elestio cicd pipeline-history <vmID> <pipelineID>      # Status, duration, log file

从 GitHub 部署自定义应用（用户自己的代码）

# 1. Deploy CI/CD target
elestio deploy CI-CD-Target --project 112 --name my-cicd

# 2. Auto-create pipeline
elestio cicd create --auto --target <vmID> --name my-app --repo owner/repo --mode github --auth-id <authID>
# -> Site is live at https://<name>-u<userID>.vm.elestio.app/

仅当部署用户自己的仓库时使用此方式。对于目录软件，请改用 cicd deploy-template，详见上文。

部署自定义应用（手动 — Docker 模式）

# 1. Deploy CI/CD target
elestio deploy CI-CD-Target --project 112 --name my-cicd

# 2. Add SSH key for agent access
elestio ssh-keys add <vmID> --name "agent-key" --key "ssh-ed25519 AAAA..."

# 3. Generate pipeline config
elestio cicd template docker > pipeline.json
# Edit pipeline.json with correct CI/CD target info (see JSON reference below)

# 4. Create pipeline
elestio cicd create pipeline.json

# 5. SSH and configure
ssh root@<ipv4>
cd /opt/app/<pipeline-name>
# Edit docker-compose.yml, add code, docker-compose up -d

Pipeline JSON 参考（Docker 模式——createCiCdExistServer 负载）

请勿手动编写。 使用 elestio cicd template docker 生成，并 替换 REPLACE 值。端点接收仪表板的完整表单状态，任何不一致都会导致 500 错误或流水线始终无法构建。当前格式（CLI 1.1.0， 已在线验证）：

{
  "cluster": {
    "isCluster": false,
    "createNew": false,
    "target": {
      "displayName": "REPLACE",
      "id": "REPLACE",
      "serverName": "REPLACE",
      "vmID": "REPLACE",
      "vmProvider": "REPLACE",
      "vmRegion": "REPLACE",
      "levelName": "Elestio-services",
      "projectID": "REPLACE"
    }
  },
  "gitData": {},
  "imageData": {
    "isPrivate": false,
    "compose": "services:\n  nginx:\n    image: nginx:alpine\n    ports:\n      - \"172.17.0.1:3000:80\"\n    volumes:\n      - ./html:/usr/share/nginx/html:ro",
    "dockerExample": "",
    "repoName": "CustomDocker"
  },
  "configData": {
    "buildDir": "/",
    "rootDir": "/",
    "runTime": "NodeJs",
    "buildCmd": "",
    "runCmd": "",
    "installCmd": "",
    "framework": "NoFramework",
    "version": "20"
  },
  "ports": [
    {
      "protocol": "HTTPS",
      "targetProtocol": "HTTP",
      "listeningPort": "443",
      "targetPort": 3001,
      "public": true,
      "targetIP": "172.17.0.1",
      "path": "/",
      "isAuth": false,
      "login": "",
      "password": "",
      "loginTitle": ""
    }
  ],
  "variables": "",
  "isPublicGitRepo": false,
  "exposedPorts": [
    {
      "protocol": "HTTP",
      "hostPort": "3000",
      "containerPort": "3000",
      "interface": "172.17.0.1"
    }
  ],
  "gitVolumeConfig": [
    {}
  ],
  "isNeedToCreateRepo": false,
  "gitUserFormData": {
    "selectedUser": "",
    "searchGitUser": "",
    "gitOrgsFilteredList": {
      "GITHUB": [],
      "GITLAB": []
    },
    "gitOrgsList": [],
    "selectedRepo": {},
    "thirdPartyRepoInput": "",
    "gitScopesUsers": [],
    "thirdPartyRepoScopeName": "",
    "getGitScopeUser": {
      "GITHUB": [],
      "GITLAB": []
    },
    "thirdPartyRepoName": "",
    "thirdPartyRepoPrivate": false,
    "loadSearch": false
  },
  "lifeCycleCommand": {
    "preInstallCommand": "",
    "postInstallCommand": "",
    "preBackupCommand": "",
    "postBackupCommand": "",
    "preRestoreCommand": "",
    "postRestoreCommand": "",
    "preUpdateCommand": "",
    "postUpdateCommand": "",
    "preDeployCommand": "",
    "postDeployCommand": ""
  },
  "monoRepoWorkSpaces": [
    ""
  ],
  "copyCommandConfig": [],
  "CICDMode": "DockerCompose",
  "projectID": "REPLACE",
  "pipelineName": "REPLACE",
  "isMovePipeline": false,
  "authID": null
}

cluster.target 的值来自 elestio cicd targets：id 是目标的 serverID（后端会读取它），vmID 是其 vmID。

需要避免的常见负载错误：

字段	错误	正确
CICDMode	"DOCKER"	"DockerCompose"
configData.runTime	runtime（小写 t）	runTime（大写 T）
configData.framework	""	"NoFramework"
imageData	{ imageName, imageTag, registryUrl }	{ isPrivate, compose, dockerExample, repoName }
gitData（Docker 模式）	{ projectName, branch, ... }	{}（空对象）
authID（Docker 模式）	"0"	null
isPublicGitRepo	"false"（字符串）	false（布尔值）
gitVolumeConfig	[]	[{}]
ports[]	{ targetPort, publishedPort, isDefault }	{ protocol, targetProtocol, listeningPort, targetPort, targetIP, public, path, isAuth, login, password, loginTitle }
exposedPorts	省略	[{ protocol, hostPort, containerPort, interface }]
cluster.target	只有 vmID	id（serverID）、vmID、vmProvider、vmRegion、levelName、projectID、displayName、serverName
nonRepoWorkSpaces	存在	移除——改用 monoRepoWorkSpaces
variables	省略或 []（数组）	"" 或 "KEY=value\nKEY2=value2"（字符串；后端会运行 variables.trim()）
lifeCycleCommand（compose，无仓库）	类似 ./scripts/preInstall.sh 的钩子路径	全部设为 ""：Agent 会在运行 docker compose 之前对这些路径执行 chmod，导致构建失败

---

命令参考

身份验证与配置

elestio login --email X --token Y  # Set credentials
elestio auth test                  # Verify authentication
elestio whoami                     # Show current user
elestio config                     # Show current config
elestio config --set-default-project X  # Set default project

目录（无需身份验证）

elestio templates                  # List all 400+ templates
elestio templates search <query>   # Search by name
elestio templates info <name>      # Template details
elestio categories                 # List categories
elestio sizes                      # All provider/region/size combos
elestio sizes --provider netcup    # Filter by provider
elestio sizes --provider ovh       # OVHcloud: prices already include the launch offer

项目

elestio projects                   # List all projects
elestio projects create <name>     # Create project
elestio projects delete <id> --force  # Delete project
elestio projects members <id>      # List members
elestio projects add-member <id> <email>
elestio projects remove-member <id> <memberId>

服务

elestio services                   # List all services
elestio services --project 123     # Filter by project
elestio service <vmID>             # Service details
elestio deploy <template> --project X --name Y
elestio deploy <template> --cluster --nodes 3   # Cluster (see Clusters below)
elestio deploy CI-CD-Target --project X         # Deploy a CI/CD target VM
elestio delete-service <vmID> --force
elestio move-service <vmID> <targetProjectId>
elestio wait <vmID>                # Wait for deployment

电源管理

elestio reboot <vmID>              # Graceful reboot
elestio reset <vmID>               # Hard reset
elestio shutdown <vmID>            # Graceful shutdown
elestio poweroff <vmID>            # Force power off
elestio poweron <vmID>             # Power on
elestio restart-stack <vmID>       # Restart Docker only (fastest)
elestio lock <vmID>                # Enable termination protection
elestio unlock <vmID>              # Disable termination protection
elestio resize <vmID> --size LARGE-4C-8G  # Upgrade/downgrade VM size (OVH: never to a smaller disk)

防火墙

elestio firewall get <vmID>        # List rules
elestio firewall enable <vmID> --rules '[{"type":"INPUT","port":"22","protocol":"tcp","targets":["0.0.0.0/0"]}]'
elestio firewall update <vmID> --rules '[...]'
elestio firewall disable <vmID>

SSL / 自定义域名

elestio ssl list <vmID>            # List domains
elestio ssl add <vmID> <domain>    # Add with auto-SSL
elestio ssl remove <vmID> <domain>

SSH 密钥

elestio ssh-keys list <vmID>       # List keys
elestio ssh-keys add <vmID> --name "name" --key "ssh-ed25519 AAAA..."
elestio ssh-keys remove <vmID> --name "name"

注意： 添加 SSH 密钥时，只需提供密钥类型和密钥数据（例如 ssh-ed25519 AAAA...）。请勿包含密钥末尾的注释／电子邮件地址。

自动更新

elestio updates system-enable <vmID> --day 0 --hour 5 --security-only
elestio updates system-disable <vmID>
elestio updates system-now <vmID>  # Run OS update now
elestio updates app-enable <vmID> --day 0 --hour 3
elestio updates app-disable <vmID>
elestio updates app-now <vmID>     # Run app update now
elestio change-version <vmID> <version>  # e.g., PostgreSQL 15

警报

elestio alerts get <vmID>          # Get current rules
elestio alerts enable <vmID> --rules '{...}' --cycle 60
elestio alerts disable <vmID>

备份

# Local backups (application-level)
elestio backups local-list <vmID>
elestio backups local-take <vmID>
elestio backups local-restore <vmID> /opt/app-backups/backup.zst
elestio backups local-delete <vmID> /opt/app-backups/backup.zst

# Remote backups (Elestio managed)
elestio backups remote-list <vmID>
elestio backups remote-take <vmID>
elestio backups remote-restore <vmID> <backup-name>
elestio backups auto-enable <vmID>
elestio backups auto-disable <vmID>

# S3 external backups
elestio s3-backup verify <vmID> --key X --secret Y --bucket Z --endpoint S
elestio s3-backup enable <vmID> --key X --secret Y --bucket Z --endpoint S
elestio s3-backup disable <vmID>
elestio s3-backup take <vmID>
elestio s3-backup list <vmID>
elestio s3-backup restore <vmID> <backup-key>
elestio s3-backup delete <vmID> <backup-key>

快照

Elestio 不再为任何服务提供 VM 快照（自 2026-08-06 起取消）： CLI 中没有快照命令，MCP 中也没有对应工具。如果用户提出此需求， 请改用备份（elestio backups remote-take，并通过 backups auto-enable 设置计划）。

访问与凭据

elestio credentials <vmID>         # App URL + login
elestio ssh <vmID>                 # SSH terminal URL
elestio ssh <vmID> --direct        # Direct SSH command
elestio vscode <vmID>              # VSCode web URL
elestio files <vmID>               # File explorer URL
elestio logs <vmID>                # Live app logs (temporary URL); --mode install for the install log
elestio audits <vmID> [--days 7]   # Who did what on the service

卷

注意： 卷支持情况取决于云服务提供商。Hetzner 和 OVHcloud 支持完整的卷操作。netcup 等一些提供商的卷支持有限或不支持卷。

--type NVME（默认，高速）或 --type HDD（经典型，更便宜）。在 OVH：首发优惠期间（截至 2027 年 1 月 1 日），NVME 为 $0.125/GB/月，HDD 为 $0.075/GB/月；之后分别为 $0.25 和 $0.15。HDD 仅适用于 Vultr 和 OVHcloud，且 OVH 的 EU-WEST-PAR（巴黎）和 EU-SOUTH-MIL（米兰）不支持 HDD：CLI 会在这些区域拒绝该选项。

elestio volumes                    # List all volumes in project
elestio volumes create --name X --size 10 [--type NVME|HDD]
elestio volumes service-list <vmID>    # List attached to service
elestio volumes service-create <vmID> --name X --size 10 [--type NVME|HDD]
elestio volumes resize <vmID> <volumeID> --size 20
elestio volumes detach <vmID> <volumeID>
elestio volumes delete <vmID> <volumeID>
elestio volumes protect <vmID> <volumeID>

集群

elestio clusters templates                  # Software that supports clustering
elestio clusters                            # List clusters in the project
elestio clusters info <clusterID>           # Details + nodes
elestio clusters nodes <clusterID>          # Active nodes only

# Creation goes through deploy, not through clusters
elestio deploy <template> --cluster --nodes <n> [--cluster-mode multi-master]

# Operations -- all destructive ones require --force
elestio clusters promote <clusterID> <vmID> --force   # Promote a replica
elestio clusters failover <clusterID> on|off          # AUTOMATIC failover switch, does not switch now
elestio clusters resync <clusterID> --force           # ERASES replica data
elestio clusters lock <clusterID>                     # Termination protection
elestio clusters unlock <clusterID>
elestio clusters delete <clusterID> --force           # Deletes ALL nodes (not delete-service)

# Nodes -- dry-run add-node first: billed as one more VM
elestio clusters add-node <clusterID> --dry-run       # Copies the primary: provider, region, size, version
elestio clusters add-node <clusterID> [--size X] [--region Y]
elestio clusters remove-node <clusterID> <vmID> --force   # Replicas only

# Firewall -- applies to every node; the cluster's own nodes stay allowed
elestio clusters firewall <clusterID>
elestio clusters firewall-restrict <clusterID> --port 25432 --ips 203.0.113.7,198.51.100.0/24
elestio clusters firewall-open <clusterID> --port 25432

限制（CLI 会在调用 API 前强制执行）：

规则	值
--nodes 计数	节点总数，包含主节点
大多数软件的最小值	2
ClickHouse、Vault、OpenSearch、RabbitMQ、rke2、Nats 的最小值	3（仲裁）
最大值	15
--cluster-mode multi-master	仅限 MySQL
计费	按 VM 计费。--nodes 5 表示 5 个 VM。
手动切换主节点	使用 promote，而非 failover（它只会切换自动故障转移）
副本	只读，且不支持 SSL：在副本上使用 sslmode=require 会失败
add-node 的前提条件	在主节点上启用远程备份（elestio backups auto-enable <vmID>），并处于主副本模式
执行 add-node 后	VM 部署完成后，Elestio 会花几分钟将其设为副本。此期间集群状态显示为 running；在进行其他节点或防火墙更改前请等待（CLI 会拒绝这些操作）
移除主节点	不可行：先对某个副本执行 promote，或删除集群
限制访问	使用 clusters firewall-restrict，切勿对单个节点运行 elestio firewall：这会导致它与其他节点配置不一致

部署集群前，务必先运行 --dry-run，并告知用户 VM 数量和费用。

CI/CD 流水线

# CATALOG SOFTWARE -> always use deploy-template (reads the template elestio.yml)
elestio cicd templates [query]     # Catalog software deployable as a pipeline
elestio cicd deploy-template <software> --target <vmID>
elestio cicd deploy-template <software> --target <vmID> --dry-run
elestio cicd deploy-template <software> --target <vmID> --inline-compose   # your own compose only
elestio cicd deploy-template <software> --target <vmID> --owner <git-user>  # git route (currently 404)
# Options: --name, --branch, --private, --non-org, --auth-id, --git-type,
#          --repo-name, --build-cmd, --run-cmd, --install-cmd, --build-dir

elestio cicd targets               # List CI/CD targets
elestio cicd pipelines <vmID>      # List pipelines
elestio cicd pipeline-info <vmID> <pipelineID>

# USER'S OWN REPO -> create --auto. Never use this for catalog software.
elestio cicd create --auto --target <vmID> --name my-app --repo owner/repo --mode github
elestio cicd create --auto --target <vmID> --name my-app --repo owner/repo --mode github --auth-id <id>
# Modes: github, github-fullstack, gitlab, gitlab-fullstack, docker
# Optional: --branch, --build-cmd, --run-cmd, --install-cmd, --build-dir, --framework, --node-version

# Manual pipeline creation (from JSON template)
elestio cicd template docker       # Docker Compose (custom, no Git)
elestio cicd template github       # GitHub Static SPA (Vite/React)
elestio cicd template github-fullstack  # GitHub Full Stack (Node.js)
elestio cicd template gitlab       # GitLab Static SPA (Vite/React)
elestio cicd template gitlab-fullstack  # GitLab Full Stack (Node.js)
elestio cicd create <config.json>

# Pipeline actions
elestio cicd pipeline-restart <vmID> <pipelineID>
elestio cicd pipeline-stop <vmID> <pipelineID>
elestio cicd pipeline-logs <vmID> <pipelineID>          # Running app logs
elestio cicd pipeline-log <vmID> --pipeline <id>       # Latest build log (URL)
elestio cicd pipeline-log <vmID> --pipeline <id> --file <logID>   # One build, logID from pipeline-history
elestio cicd pipeline-history <vmID> <pipelineID>
elestio cicd pipeline-delete <vmID> <pipelineID> --force

# Pipeline domains
elestio cicd domains <vmID> <pipelineID>
elestio cicd domain-add <vmID> --pipeline <id> --domain myapp.example.com
elestio cicd domain-remove <vmID> --pipeline <id> --domain myapp.example.com

# Docker registries
elestio cicd registries
elestio cicd registry-add --name X --username U --password P --url URL

**自动创建流水线的流程：**CLI 会查找已连接的 Git 账户（或使用 --auth-id），解析仓库和 CI/CD 目标，并通过 API 创建流水线。随后 Elestio 会克隆、构建并启动流水线；请使用 elestio cicd pipelines <vmID> 和 elestio cicd pipeline-history <vmID> <pipelineID> 跟踪构建。

计费

elestio billing                    # Total costs
elestio billing project <id>       # Per-service breakdown

---

强制要求：交互式部署流程

**重要：**部署任何服务时，必须使用 AskUserQuestion 逐一询问用户每个必需参数。未经用户明确确认，切勿使用默认值进行部署。

必填参数（按以下顺序询问）：

1. 提供商——使用 AskUserQuestion 询问：

• Netcup（推荐）——性价比最高，位于欧盟，可靠
• Hetzner——功能最全面：全面支持卷和电源管理
• OVHcloud——欧洲提供商，在全球拥有 35 个区域，带宽不限，所有资源在 2027 年 1 月 1 日前享受 5 折优惠
• AWS——Amazon Web Services，覆盖全球
• Azure——Microsoft 云

2. 区域——根据所选提供商，使用 AskUserQuestion 询问：

• Netcup：nbg（欧洲 - 德国纽伦堡）| mns（北美 - 美国马纳萨斯）
• Hetzner：fsn1（德国法尔肯施泰因）、nbg1（德国纽伦堡）、hel1（芬兰赫尔辛基）、ash（美国阿什本）
• OVHcloud：DE1（德国法兰克福）、GRA11（法国格拉沃利讷）、UK1（英国伦敦）、BHS5（加拿大博阿努瓦）、SGP1（新加坡）。区域代码均为大写；Local Zones（*-LZ-*）可选规格较少
• AWS：us-east-1、eu-west-1、ap-southeast-1 等
• Azure：germanywestcentral、eastus、westeurope 等

如需查询确切的可用区域，请使用 elestio sizes --provider <provider>。

3. 服务套餐（规格）——使用 AskUserQuestion 询问，并提供可选规格及价格：

• SMALL-1C-1G——1 核、1GB RAM（约 $11/月，Linode）
• MEDIUM-2C-4G——2 核、4GB RAM（约 $16/月，Netcup DE）
• LARGE-4C-8G——4 核、8GB RAM（约 $30/月，Netcup DE）
• XL-8C-16G——8 核、16GB RAM（约 $55/月，Netcup DE）

使用 elestio sizes --provider <provider> 查询所选提供商的确切规格和价格。

**OVHcloud 定价：**所有 OVH 资源在 2027 年 1 月 1 日前享受 5 折优惠（上线优惠），包括服务、CI/CD 目标、负载均衡器和卷。支持套餐不参与折扣。卷：NVME（高速）$0.25/GB/月，优惠期间为 $0.125；HDD（经典）$0.15/GB/月，优惠期间为 $0.075。elestio sizes、deploy --dry-run 和 MCP 的 list_providers_and_sizes 已显示折后价格（listPricePerHour 保留原价），因此请报折后价格，并说明这是上线优惠。OVH 最便宜的套餐：SMALL-1C-2G-D2，优惠期间约 $10/月（原价 $21/月）。

4. 服务名称——不要使用 AskUserQuestion。只需用普通文本询问用户提供名称，并根据服务类型建议一个默认名称（例如 “prod-postgres”、“staging-redis”）。等待用户输入文本。

5. 管理员邮箱——使用 AskUserQuestion 询问，并建议将雇主的邮箱设为默认值。让用户确认或修改。

示例流程：

User: "Deploy PostgreSQL"
Agent: [AskUserQuestion] Which cloud provider? (Netcup recommended, Hetzner, OVHcloud, AWS, Azure)
User: "Netcup"
Agent: [AskUserQuestion] Which region? (nbg Europe-Germany, mns North America-US)
User: "nbg"
Agent: [AskUserQuestion] Which service plan? (SMALL ~$11/mo, MEDIUM ~$16/mo, LARGE ~$30/mo, XL ~$55/mo)
User: "MEDIUM"
Agent: "What name do you want for this service? Suggestion: prod-postgresql"
User: "demo-postgres"
Agent: [AskUserQuestion] Admin email? (Suggested: [email protected])
User: confirms
Agent: Deploys with all confirmed parameters

---

黄金规则

1. 始终先进行身份验证 -- 每个会话都必须从有效的 JWT 开始
2. vmID != serverID -- 大多数端点使用 vmID，备份/备注使用 serverID（两者均来自 elestio services）
3. 检查部署状态 -- 部署后，等待 deploymentStatus = "Deployed" 再进行访问
4. 未经确认绝不删除 -- 始终要求提供 --force 标志
5. 尽可能使用目录 -- 第 3 阶段（目录）比第 4 阶段（CI/CD）更简单 5b. 在流水线中部署目录软件 -> cicd deploy-template（MCP：deploy_catalog_pipeline），绝不使用 cicd create（MCP：create_pipeline_docker / create_pipeline_auto） -- 这些方式无法获知软件的端口、环境变量或安装脚本，因此生成的流水线不会部署或运行任何内容
6. 验证组合 -- Provider、数据中心和 serverType 必须与 elestio sizes 匹配
7. 账户必须经过批准 -- 新账户需要添加信用卡并获得批准后才能部署
8. 始终遵循上方的交互式部署流程 -- 绝不跳过参数问题
9. 设置默认项目 -- 使用 elestio config --set-default-project <id>，避免每次都传入 --project
10. 服务属于某个项目 -- 使用 elestio service <vmID> 时，请确保 vmID 属于当前默认项目，或指定 --project
11. 对会增加 VM 数量的操作先进行试运行 -- 集群部署前始终运行 --dry-run，并告知用户 VM 数量和每月费用；集群按 VM 计费
12. --nodes 表示总数 -- --nodes 3 表示 1 个主节点 + 2 个副本，按 3 个 VM 计费，而不是 4 个

---

默认值

设置	默认值	覆盖方式
Provider	netcup	--provider hetzner / --provider ovh
数据中心	netcup 使用 nbg（德国），OVH 使用 DE1（法兰克福）	--region fsn1 -- 其他 Provider 均为必需
服务器规格	MEDIUM-2C-4G	--size LARGE-4C-8G
支持级别	level1	--support level2

为什么选 netcup？ 性价比最高。位于欧盟。可靠。

---

Provider 限制

并非所有云 Provider 都支持所有功能。使用 --provider 进行切换。

功能	netcup	Hetzner	OVHcloud	AWS	Azure	Scaleway
目录部署	是	是	是	是	是	是
CI/CD 部署	是	是	是	是	是	是
卷	否	是	是（NVME、HDD；巴黎/米兰不支持 HDD）	是	是	是
电源操作	有限	是	是	是	是	是
防火墙	是	是	是	是	是	是
SSL/域名	是	是	是	是	是	是
降低规格	是	否	是，仅限磁盘容量相等或更大	是	是	是
带宽			无限

Elestio 不提供 GCP Provider。

OVHcloud IP 为静态 IP： 服务在整个生命周期内（包括调整规格后）都保持相同的公共 IPv4 和 IPv6，因此指向该 IP 的 DNS 记录和防火墙允许列表无需更新。

降低规格支持： 只有 Netcup、AWS、Azure、Scaleway 和 OVHcloud 支持降低实例规格。其他 Provider（如 Hetzner）只支持升级。在不支持的 Provider 上尝试降级可能会导致服务受阻，并需要 Elestio 支持团队介入。CLI 会自动阻止在不支持的 Provider 上尝试降级。

OVHcloud 不会缩小磁盘，无论升降级方向如何：即使 CPU 和 RAM 不变，也会拒绝磁盘容量更小的套餐（LARGE-4C-8G 100 GB -> LARGE-4C-8G-D2 50 GB）。请选择 storageGB（见 elestio sizes --provider ovh --json）不小于当前值的目标规格。

建议： 需要卷或完整电源管理时，使用 Hetzner。基本功能即可满足需求且追求最佳性价比时，使用 netcup。需要欧洲 Provider、多个区域、无限带宽和首发优惠时，使用 OVHcloud。需要灵活降低实例规格时，使用 netcup、AWS、Azure、Scaleway 或 OVHcloud。

---

速率限制（执行任何循环前请阅读）

API 会限制突发请求，随后几分钟内所有端点（包括身份验证）都会返回 Access temporarily restricted——这看起来像是凭据问题，但并非如此。

• 切勿并行发起请求。 遍历服务、项目或包含 420 个模板的目录时，必须按顺序进行，并在每次调用之间间隔约一秒。一次并行遍历导致一个账户被限制了半小时以上。
• 遇到此错误时立即停止，切勿循环重试：重试会向一个已经受到限流的账户发送更多请求。
• 切勿将其视为空结果。 如果脚本将其视为“此模板没有配置”，就会报告成功，但实际上什么也没获取到。
• 告知用户等待几分钟，然后从停止的位置继续。

CLI（>= 1.2.3）和 MCP 连接器都会明确报告此错误。

---

错误处理

错误	原因	解决方案
"Not configured"	缺少凭据	elestio login --email X --token Y
"Authentication failed"	凭据错误或令牌已过期	在控制面板中重新创建 API 令牌
"Account not approved"	新账户尚未获批	等待审批，或联系 [email protected]
"Template not found"	名称或 ID 错误	使用 elestio templates search <name>
"Invalid serverType"	服务提供商/区域/规格组合不存在	检查 elestio sizes --provider X
--region is required for <provider>	除 netcup 和 OVH 外，没有默认区域	指定 --region，可从 elestio sizes --provider X 获取
OVH cannot shrink the disk (X GB -> Y GB)	OVH 调整为磁盘容量更小的规格	选择磁盘容量相同或更大的规格
HDD (classic) volumes are not available in ...	在 OVH 的巴黎或米兰区域使用 HDD 卷	使用 --type NVME
"Service not found"	vmID 或项目错误	检查 elestio services --project X
"Deployment timeout"	耗时过长	检查控制面板；如果超过 10 min，请联系支持团队
"Project not found"	projectId 错误	检查 elestio projects

---

组合使用：后续操作...

部署服务后

1. 获取凭据： elestio credentials <vmID>
2. 验证运行状态： 打开 URL，确认服务正常运行
3. 启用备份： elestio backups auto-enable <vmID>
4. 添加自定义域名： elestio ssl add <vmID> myapp.example.com
5. 配置防火墙： elestio firewall enable <vmID> --rules [...]
6. 启用自动更新： elestio updates system-enable <vmID> --security-only

创建 CI/CD 目标后

目录中的软件（Vaultwarden、Redis、Metabase 等）——使用以下流程：

1. 检查是否可用： elestio cicd templates <software>
2. 预览： elestio cicd deploy-template <software> --target <vmID> --no-git --dry-run
3. 部署： elestio cicd deploy-template <software> --target <vmID>
4. 将输出的 URL、登录名和密码告知用户
5. 添加域名： elestio cicd domain-add <vmID> --pipeline <pipelineID> --domain myapp.example.com

用户自己的仓库：

1. 自动创建流水线： elestio cicd create --auto --target <vmID> --name my-app --repo owner/repo --mode github --auth-id <id>
2. 查看构建过程：elestio cicd pipelines <vmID>（Build 列必须显示 "success"）

手动配置 docker-compose：

1. 添加 SSH 密钥： elestio ssh-keys add <vmID> --name "name" --key "key"
2. 创建流水线： elestio cicd create pipeline.json
3. 通过 SSH 登录并配置： ssh root@<ipv4>
4. 添加域名： elestio cicd domain-add <vmID> --pipeline <pipelineID> --domain myapp.example.com

出错后

1. 重新进行身份验证： elestio auth test
2. 检查状态： elestio service <vmID>
3. 查看日志： elestio logs <vmID>（服务）或 elestio cicd pipeline-logs <vmID> <pipelineID>（流水线） 3b. 查看变更内容： elestio audits <vmID>
4. 重启服务栈： elestio restart-stack <vmID>

---

故障排除

反复出现 "Authentication failed"

# 1. Verify current config
elestio config

# 2. Re-configure with fresh token from dashboard
elestio login --email "..." --token "..."

# 3. Test
elestio auth test

服务卡在“Deploying”

1. 正常部署需要 2-5 分钟
2. 如果超过 10 分钟，请检查 Elestio 仪表板中的错误
3. 如果仍然卡住，请联系 [email protected]

服务存在，但提示“Service not found”

• 确保使用的是 vmID，而不是 serverID
• 检查项目是否正确：elestio services --project X
• vmID 的格式类似：12345678（数字）

Pipeline 已部署，但软件未运行（最常见）

几乎总是因为使用 cicd create 而非 cicd deploy-template 创建了 pipeline，因此没有端口、环境变量和安装脚本。

# Confirm: a pipeline built correctly has env vars
elestio cicd pipeline-info <vmID> <pipelineID>

# Fix: delete it and redeploy through deploy-template
elestio cicd pipeline-delete <vmID> <pipelineID> --force
elestio cicd deploy-template <software> --target <vmID>

使用 MCP 连接器时，原因相同：使用 create_pipeline_docker 或 create_pipeline_auto 创建了 pipeline。请使用 deploy_catalog_pipeline 重新部署。

软件启动后立即退出

在 CLI 1.3.0 中，默认路由会在 VM 上克隆模板仓库，因此安装脚本会运行，compose 挂载所需的文件也会存在。如果软件仍然无法运行：

elestio cicd pipeline-history <vmID> <pipelineID>     # did the build fail?
elestio cicd pipeline-log <vmID> --pipeline <id>      # the build log

请优先检查以下两个原因：

• 使用 cicd create（空 pipeline）而非 cicd deploy-template 创建了 pipeline；
• 使用 --inline-compose 创建了 pipeline，因此跳过了安装脚本和仓库文件。请删除该 pipeline，并使用默认路由重新部署。

“No elestio.yml found at ...”

该软件没有 pipeline 模板，无法作为 pipeline 部署。请将其作为托管服务部署：elestio deploy <template>。

Pipeline 无法运行（常见问题）

1. SSH 连接到 CI/CD 目标：ssh root@<ipv4>
2. 查看日志：cd /opt/app/<pipeline-name> && docker-compose logs
3. 检查 docker-compose.yml 语法
4. 检查端口映射：172.17.0.1:3000（内部网络）

集群错误

消息	原因
does not support clustering	不是可集群化的模板之一——运行 elestio clusters templates
needs at least 3 nodes	仲裁软件（ClickHouse、Vault、OpenSearch、RabbitMQ、rke2、Nats）
does not support multi-master	--cluster-mode multi-master 仅适用于 MySQL
cannot exceed 15 nodes	平台硬性上限
remote backups are off（add-node）	新节点会从主节点的远程备份进行初始化：elestio backups auto-enable <primary vmID>
is busy (add-node)	某个节点仍在配置中；请等待几分钟
is the primary（remove-node）	请先提升一个副本，或删除整个集群

“variables.trim is not a function”（500 Pipeline.CreateFailed）

pipeline 请求中的 variables 字段必须是字符串，不能是数组，也不能省略。后端会对其调用 variables.trim()，因此任何其他类型都会在读取构建、运行和框架设置之前导致报错（即使参数最少也会失败）。

• 正确："variables": ""（没有环境变量），或 "variables": "KEY=value\nKEY2=value2"。
• 错误："variables": []，或完全省略该字段。

CLI 从 1.1.0 版本起会强制执行此要求，MCP 连接器也会正确发送该字段。如果 CLI 遇到此错误，请升级：npm install -g elestio@latest。

---

ID 参考（重要）

术语	查找位置	用于
vmID	elestio services -> .vmID	大多数端点（操作、防火墙、ssl 等）
serverID	elestio services -> .id	备份端点、备注
projectID	elestio projects -> .projectID	几乎所有操作
templateID	elestio templates -> .id	elestio deploy
pipelineID	elestio cicd pipelines -> .pipelineID	CI/CD 操作
volumeID	elestio volumes -> .id	卷操作

**常见错误：**在需要 vmID 时使用了 serverID（或反过来）。对于同一服务，它们是不同的编号。

---

VM 架构

每个 Elestio 服务都运行在专用 VM 上：

/opt/elestio/nginx/          <- Reverse proxy (auto-configured, don't modify)
/opt/app/                    <- Your application
    +-- docker-compose.yml   <- For catalog services
    +-- <pipeline_name>/     <- For CI/CD pipelines

• 反向代理会自动处理 HTTPS 终止
• SSL 证书通过 Let's Encrypt 自动生成
• 端口 172.17.0.1:XXXX 是内部 Docker 网络接口

---

Support Tiers

Plan	Price	Response Time
level1	Included	48h (email)
level2	+$50/svc/mo	24h (priority)
level3	+$200/svc/mo	4h (dedicated engineer)

---

Links

• Dashboard: https://dash.elest.io
• API Docs: https://api-doc.elest.io
• Support: [email protected]
• Templates: 400+ at https://elest.io/open-source
• CLI: npm install -g elestio