devops

Admin DevOps - 远程基础设施（Alpha）

脚本路径解析：Claude Code 加载此文件时，会提供完整路径。根据此文件所在目录推导 SKILL_DIR。管理脚本（配置文件检查、日志记录、密钥）位于同级的 admin 技能目录中：${SKILL_DIR}/../admin/scripts/。

---

严重警告：密钥和 .env

• 切勿在任何技能文件夹中存储正在使用的 .env 文件或凭据。
• .env.template 文件只能放在技能目录中的 assets/ 内。
• 将正在使用的密钥存储在 ~/.admin/.env 中，并从该处引用。

密钥管理

有三种后端可用，通过 ~/.admin/.env 中的 ADMIN_SECRETS_BACKEND 配置：

后端	存储位置	最适用场景
infisical	Infisical Cloud	多设备、审计记录
vault（默认）	$ADMIN_ROOT/vault.age	单设备、离线
env	$ADMIN_ROOT/.env	旧版

回退链：infisical → vault → env。如果主后端不可用，脚本会自动尝试下一个。

CLI：使用 admin 技能的 secrets 脚本获取提供商 API 密钥：

# Retrieve a single provider token
HCLOUD_TOKEN=$(${SKILL_DIR}/../admin/scripts/secrets HCLOUD_TOKEN)

# Or if secrets is on PATH
export HCLOUD_TOKEN=$(secrets HCLOUD_TOKEN)

提供商密钥映射

密钥名称	Infisical URI	提供商	用途
HCLOUD_TOKEN	infisical://admin-operator/prod/providers/hetzner/HCLOUD_TOKEN	Hetzner	hcloud CLI 身份验证
DIGITALOCEAN_ACCESS_TOKEN	infisical://admin-operator/prod/providers/digitalocean/ACCESS_TOKEN	DigitalOcean	doctl 身份验证
CNTB_OAUTH2_CLIENT_SECRET	infisical://admin-operator/prod/providers/contabo/CLIENT_SECRET	Contabo	cntb 配置
CNTB_OAUTH2_PASS	infisical://admin-operator/prod/providers/contabo/OAUTH_PASS	Contabo	cntb 配置
LINODE_API_TOKEN	infisical://admin-operator/prod/providers/linode/API_TOKEN	Linode	linode-cli
VULTR_API_KEY	infisical://admin-operator/prod/providers/vultr/API_KEY	Vultr	vultr-cli
CF_API_TOKEN	infisical://admin-operator/prod/network/cloudflare/API_TOKEN	Cloudflare	Tunnel 设置

获取（v4.0+）：

# URI-based (recommended)
HCLOUD_TOKEN=$(resolve-secret-ref.sh "infisical://admin-operator/prod/providers/hetzner/HCLOUD_TOKEN")

# Multi-project secrets CLI
HCLOUD_TOKEN=$(secrets --project admin-operator --path /providers/hetzner HCLOUD_TOKEN)

# Legacy (still works via fallback chain)
HCLOUD_TOKEN=$(secrets HCLOUD_TOKEN)

指南：references/secrets-architecture.md（完整的 4 层模型）、references/infisical.md（Infisical 设置）、references/vault-guide.md（age vault 回退方案）

---

配置文件检查（必须首先执行）

执行任何操作前，先检查是否存在配置文件。没有配置文件，就没有服务器清单、偏好设置或日志路径。

${SKILL_DIR}/../admin/scripts/test-admin-profile.sh

返回 JSON：{"exists":true|false,"path":"...","device":"...","platform":"..."}

如果 exists: false，则停止并转交给 admin 技能执行 /setup-profile。没有配置文件时不得继续。

完整详情：references/profile-gate.md

---

任务资格判定（必须执行）

• 如果任务涉及本地操作系统/MCP/技能，则停止并转交给 admin。
• 如果任务涉及远程基础设施，则继续。
• 如果任务不明确，请先提出澄清问题。

任务路由

任务	参考
服务器清单	服务器操作（使用 profile.servers）
OCI 资源配置	→ 使用 oci 技能
Hetzner 资源配置	→ 使用 hetzner 技能
Linode 资源配置	→ 使用 linode 技能
DigitalOcean 资源配置	→ 使用 digital-ocean 技能
Contabo 资源配置	→ 使用 contabo 技能
Coolify 部署	→ 使用 coolify 技能
KASM 部署	→ 使用 kasm 技能
密钥 / Infisical 设置	→ 使用 admin 技能
本地机器任务	→ 使用 admin 技能

服务器操作

使用 profile.servers[] 管理清单；不要维护单独的列表。配置文件是唯一可信数据源。

资源配置工作流（5 个步骤）

1. 选择提供商
2. 通过 secrets CLI 加载密钥（提供商 API 密钥）
3. 执行提供商工作流（使用专用的提供商技能）
4. 更新 profile.servers[] 和 profile.deployments{}
5. 通过 log_admin_event 记录操作

日志记录（必须执行）

记录每项操作。日志脚本位于同级的 admin 技能目录中。

source "${SKILL_DIR}/../admin/scripts/log-admin-event.sh"
log_admin_event "Provisioned Hetzner server hzn-01-203-42" "OK"
log_admin_event "OCI provisioning failed: OUT_OF_HOST_CAPACITY" "ERROR"

级别：OK（成功）、INFO、WARN、ERROR

---

架构

与 admin 的关系

devops 是 admin 的卫星技能。它依赖 admin 提供以下功能：

• Profile 门禁（test-admin-profile.sh）— 必须执行的第一步
• 日志记录（log-admin-event.sh）— 必须执行的操作日志记录
• 密钥（secrets CLI）— 通过回退链检索提供商 API 密钥
• Profile 数据（profile.servers[]、profile.deployments{}）— 服务器清单

同级技能解析

plugins/admin-devops/
  skills/
    admin/      ← core (scripts, secrets, logging live here)
    devops/     ← this skill (references admin scripts via ../admin/)
    oci/        ← provider skill
    hetzner/    ← provider skill
    ...

Agent 名单

Agent	模型	职责
server-provisioner	sonnet	通过提供商 CLI 配置云 VM
deployment-coordinator	sonnet	端到端应用部署（Coolify/KASM）

两个 Agent 都会将 Profile 门禁作为第一步。

---

脚本 / 参考资料

• 提供商技能：此插件下的同级技能（oci、hetzner、coolify 等）
• 清单格式规范：references/INVENTORY_FORMAT.md
• 部署工作流：references/DEPLOYMENT_WORKFLOWS.md
• 故障排除：references/TROUBLESHOOTING.md