注册并连接服务器

注册服务器、分类新工作负载放置，并完成首次连接性测试。

目标

把一台你拥有的 Linux 服务器注册为 Appaloft 的部署目标，并确认 Appaloft 能通过 SSH 安全连接它。

适用场景

第一次接入一台新服务器。
需要迁移到新机器，或者临时排查某台服务器的连通性问题。

前置条件

一台可以通过 SSH 访问、你拥有 root 或 sudo 权限的 Linux 服务器。
一个 SSH key（推荐使用专用的部署 key，而不是你的个人登录 key）。

输入与默认值

输入	说明	默认值
`host`	明确的 hostname、IPv4 或 IPv6 地址	无，必填；不接受 CIDR、URL 或 `host:port` 形式
`port`	SSH 端口	`22`
`user`	用于连接的系统用户	无，必填
凭据	SSH key 路径 / 已保存凭据 / 一次性输入	无，必填
显示名称 / 标签	帮助你在列表中区分服务器	可选
工作负载角色	新工作负载类别的放置意图	空集合：通用，可接收所有工作负载类型

服务器注册输入里不应该出现资源、环境或域名相关字段——那些是独立的配置层。

工作负载角色

工作负载角色声明服务器打算接收哪些类别的新工作负载。它表达放置意图，不证明服务器健康、就绪或具备技术能力。可以组合选择以下规范值：

deployment-runtime：可以接收新的应用运行时放置。
artifact-builder：记录将来在受治理的 builder 放置路径存在时接收构件构建执行的意图。它不表示当前已提供或已准备好远程构建执行。
sandbox-worker：可以接收新的 Sandbox 放置，但隔离和 provider 能力检查仍须独立通过。

不声明任何角色表示 General purpose (all workload types)（通用，可接收所有工作负载类型）。API 和结构化 CLI 输出将此状态保留为 workloadRoles: []；list/show 输出不会隐藏空数组，也不会把它解释为没有能力。

角色变更只影响新的放置。它不会 drain、停止、移动、取消或重新解释当前工作负载和历史放置记录。生命周期、连接、就绪、容量、tenant 和 provider 检查仍须独立通过。未知或重复角色会被拒绝。

注册分类服务器时，可重复传入 --workload-role：

appaloft server register \
  --name primary \
  --host 203.0.113.10 \
  --workload-role deployment-runtime \
  --workload-role artifact-builder

注册后，使用专用命令完整替换角色集合：

appaloft server configure-workload-roles srv_primary \
  --workload-role deployment-runtime \
  --workload-role sandbox-worker

不传任何角色选项可恢复通用放置：

appaloft server configure-workload-roles srv_primary

注册或配置后，可用 appaloft server list 或 appaloft server show <serverId> 读取规范化角色数组。如果新部署因为所选服务器不允许 deployment-runtime 而失败，可以改选合适的服务器、为目标配置该角色，或恢复为空集合的通用服务器。修改角色不会修复运行时就绪状态，也不会增加远程构建或 Sandbox 能力。

Web 操作步骤

进入 Servers，点击 Register server。
填写 host、port、user、SSH 凭据和可选工作负载角色。
提交后，检查规范化角色集合和连接测试结果。

CLI 操作步骤

推荐先用一条任务命令完成本机或 SSH 服务器接入：

# 本机 Mac/Linux direct target
appaloft server enroll --local --name "Local machine"

# 使用本地 SSH agent 接入 VPS
appaloft server enroll ssh://[email protected]:22 --name primary

# 或从本地文件读取私钥；私钥内容不会进入 argv、输出或 Server readback
appaloft server enroll ssh://[email protected] \
  --private-key-file ~/.ssh/appaloft_deploy

# 也可以复用已保存的 SSH credential
appaloft server enroll ssh://[email protected] \
  --credential-id sshcred_primary

enroll 依次复用注册、凭据绑定、连接诊断、runtime prepare 和 Server show。注册成功后会先输出 server-enrollment-checkpoint/v1 和 serverId；只有 runtime prepare 返回 ready 并完成真实 readback 才输出 server-enrollment/v1。后续步骤失败时不会自动删除 Server，可用该 id 继续执行 server credential、server doctor、server runtime prepare 或 server show。

SSH target 只接受 ssh://user@host[:port]。含 password、path、query、fragment 或其他 scheme 的输入会在注册前被拒绝。

以下粒度命令仍适合脚本和手动修复：

# 注册一台 IPv4 服务器
appaloft server register \
  --name primary \
  --host 203.0.113.10 \
  --port 22 \
  --provider generic-ssh \
  --target-kind single-server

# 注册一台仅 IPv6 的服务器
appaloft server register \
  --name ipv6-primary \
  --host 2001:db8::1 \
  --port 22 \
  --provider generic-ssh

# 手动重新运行连接测试
appaloft server test srv_primary

# 查看服务器详情（不会触发新的连接测试）
appaloft server show srv_primary

# 重命名（只影响显示名称）
appaloft server rename srv_primary --name "Primary SSH server"

# 完整替换工作负载角色集合
appaloft server configure-workload-roles srv_primary \
  --workload-role deployment-runtime \
  --workload-role sandbox-worker

# 恢复通用放置
appaloft server configure-workload-roles srv_primary

Docker Swarm 等集群目标需要显式声明形态：

appaloft server register \
  --name swarm-cluster \
  --host 203.0.113.20 \
  --provider docker-swarm \
  --target-kind orchestrator-cluster

现有 Kubernetes 集群

Kubernetes 集群也是 orchestrator-cluster，但连接信息由 Runtime Target Profile 独立持有。Profile 只保存 URI 形式的不透明引用，不接受 kubeconfig YAML、token、certificate、namespace 或 manifest 作为注册/部署输入。

先注册集群目标，再配置连接引用：

appaloft server register \
  --name production-cluster \
  --host kubernetes.invalid \
  --port 6443 \
  --provider kubernetes \
  --target-kind orchestrator-cluster

appaloft server configure-runtime-target-profile srv_cluster \
  --connection-reference file:///absolute/path/to/kubeconfig \
  --routing-policy-reference builtin://kubernetes/ingress-controller/traefik-k3s

公共本机 composition 默认只解析绝对 file:// kubeconfig 引用；它不会把文件内容复制进 Server readback。需要独立凭据保管时，可同时配置 --credential-reference secret://...，但运行时必须注入能够解析该引用的 credential-aware adapter；否则 readiness 和部署都会 fail closed，不会回退到本机 Docker 或其他目标。

需要路由的 workload 还必须配置明确的 routing policy reference。上面的 public 内置引用只允许 kube-system 中 Pod selector 精确等于 app.kubernetes.io/name=traefik 的 controller 入站，不允许通配 namespace、Pod selector 或 CIDR。使用其他 ingress topology 的集群需要为自己的不透明策略引用注入 resolver；缺失、未知或非法策略都会在 apply 前保持 blocked。

配置后执行无副作用的 readiness 检查：

appaloft server readiness srv_cluster

结果固定返回 API reachability、版本、授权、namespace isolation、routing 与 storage 六项规范化检查，不会返回 Kubernetes API DTO 或原始凭据。Web 的 Server 详情页对 cluster target 提供相同的 Profile 配置对话框与 readiness readback；HTTP/API、SDK 和 MCP 使用相同 operation schema。

当 Resource 绑定命名 StorageVolume 时，Kubernetes backend 使用稳定 storage scope 创建 StatefulSet 与 PVC。新的 Deployment receipt 会复用同一 workload/PVC，清理旧 receipt 不会删除持久卷；现有 StorageVolume backup/restore operation 可备份该 PVC，并默认恢复到新的独立 PVC。

helm-chart source 通过同一个 deployment operation 进入 typed Helm lifecycle，而不是接受原始 manifest。Chart reference、version、values secret references、hook policy 与 timeout 都属于 source binding；执行先做脱敏 render，再使用 atomic upgrade/wait，失败后必须证明回到上一份 manifest。 cleanup 使用精确 release identity 和 foreground uninstall。例如：

appaloft deploy oci://registry.example.com/charts/storefront \
  --method helm \
  --helm-chart-version 1.7.3 \
  --helm-values-secret-ref secret://helm/storefront/production \
  --helm-hook-policy bounded \
  --helm-timeout-seconds 420

也可以在仓库中提交不含原始 values 的同等配置：

source:
  type: helm
  chart: oci://registry.example.com/charts/storefront
  version: 1.7.3
  valuesSecretReferences:
    - secret://helm/storefront/production
  hookPolicy: bounded
  timeoutSeconds: 420
runtime:
  strategy: helm

公共 Helm lifecycle 接受绝对 file://、OCI 或 HTTPS chart 引用。默认本机 values resolver 只接受绝对 file:// 引用；Cloud/Enterprise 可为托管 secret reference 注入 credential-aware values resolver。

出站 Server Worker

如果 Mac/VPS 不能或不应该开放 inbound SSH，可以让设备主动建立一条 mTLS Worker 连接。它附着到现有 public Server；Worker 的连接、generation、lease 和证书状态是独立 readback，revoke Worker 不会删除或重命名 Server。

已通过 appaloft login 登录 Cloud/self-hosted profile 时：

appaloft server worker enroll --server srv_primary --name "My Mac"
appaloft server worker run

enroll 通过当前 authenticated profile 申请一次性短期 token，在设备上生成 private key/CSR，再交换短期 mTLS certificate。private key 不离开设备；token 不进入 argv、输出、长期 credential 或 Server readback。对于由管理员转交 token 的 self-hosted 流程，仍可从 stdin 输入：

printf '%s' "$ONE_TIME_TOKEN" | appaloft server worker enroll \
  --server srv_primary --name "Build VPS" --token-stdin

server worker run 保持前台出站连接，适合交给设备自己的 service manager。默认只允许 Docker/容器执行；如果设备 owner 确认允许 Appaloft 在该机器直接运行 Workspace/Dev host 命令，需要在启动 Worker 的本机环境显式设置：

APPALOFT_SERVER_WORKER_ALLOW_HOST_SHELL=true appaloft server worker run

这项 opt-in 只在设备本地生效，Cloud 不能远程打开。可用 APPALOFT_SERVER_WORKER_ROOTS 进一步把可访问路径限制为由平台 path delimiter 分隔的 owned roots。端口转发也只接受控制面签发的短期、单目标 capability，不是通用 VPN。

appaloft server worker status --json
appaloft server worker revoke

revoke 会关闭当前连接、围栏旧 generation 并删除本机 Worker credential；Server 和持久 Workspace 数据仍遵循各自生命周期。连接后可运行 appaloft dev . --server srv_primary；完整 Dev 流程见本地开发会话。

预期输出与状态

连接测试会检查：DNS/IP 与端口是否可达、SSH 凭据是否可用、目标用户是否有部署所需权限、基础运行环境是否满足要求，必要时还会返回代理或 Docker 相关诊断。测试结果会区分主机名解析失败、网络/主机不可达、认证失败和 host-key 验证失败几类原因，而不是笼统报错。

验证

命令或 Web 界面显示连接测试通过。
运行 appaloft server show srv_primary，确认状态、Provider 和 workloadRoles 符合预期。

回滚 / 恢复

现象	恢复方式
连接超时	检查 host、port、防火墙和网络路径
认证失败	检查 SSH key、user 和服务器上的 authorized_keys
权限不足	确认目标用户能执行部署所需命令
运行环境缺失	按诊断提示安装或切换到受支持的 Provider/运行时

连接测试通过后，继续配置 SSH 凭据管理和代理就绪与终端会话。

不再需要某台服务器时，先停用再删除：

appaloft server deactivate srv_primary
appaloft server delete-check srv_primary
appaloft server delete srv_primary --confirm srv_primary

删除前的安全检查会阻止删除仍处于活跃状态、仍有部署历史、资源、域名、证书或审计保留记录的服务器；删除本身也不会自动清理这些记录。

目标