docker-to-sealos

Docker 到 Sealos 模板转换器

身份与发现

• 负责人： docker-to-sealos（/docker-to-sealos 以及 Compose、安装文档或 Sealos 模板转换请求）。
• 类别： local-artifact-mutation，并将经过验证的模板移交给 sealos-deploy。
• 金丝雀： DTS-RULE-PRECEDENCE、DTS-MUST-MAP 和 DTS-QUALITY-GATE。

范围与边界

接收 Docker Compose、安装文档或现有模板更新请求，并在 template/<app>/index.yaml 下写入指定的模板产物及归属的验证器证据。不要执行实时云端变更。将规则来源、数据库拓扑、资源顺序、已声明的输入和密钥边界保留在此技能中。只有通过所有必需关卡后，模板才可作为移交候选。

风险与确认

治理顺序仍为入口 MUST 规则、Sealos 规范／数据库模板，然后是映射／示例。references/must-rules-map.yaml 和 references/rules-registry.yaml 是相互关联的关键来源。公开暴露、破坏性变更、凭据变更和系统工具安装仍需明确确认；生成的值和连接数据仍须脱敏。

生命周期工作流

对于每项请求，分析输入、推断元数据、规划资源、应用转换规则、验证最终产物，并且只有在完整质量关卡通过后才移交。输出请求范围内的 success、stopped 或 error；每个结果都包含来源依据、产物路径、验证器证据和脱敏状态。现有的分析 → 推断 → 资源规划 → 转换工作流仍是下方领域扩展的一部分。

渐进式披露

核心金丝雀可见后，按需加载相关归属参考系列，深度为一级。保留 MUST 映射与规则注册表之间的关联、规则优先级和现有验证器脚本；不要用通用转换器或 railpack build 路径替代它们。

输出、停止与错误状态

• success：来源／来源依据、最终 Template YAML、转换摘要、已声明的输入、拓扑／存储／数据库证据、一致性／MUST 映射／注册表／质量关卡证据，以及脱敏结果。
• stopped：输入缺失、来源未解决或触及确认边界，并附上已观察到的证据、脱敏结果和安全的后续操作；不要移交未经验证的产物。
• error：规则、注册表、拓扑、产物或质量关卡失败，并附上具名来源／产物、已清理的诊断信息、脱敏结果和恢复操作。

移交

直接转换时，请发送以下完整的类型化移交内容。部署会重新检查自身的身份验证、范围和 Runtime Truth 关卡。

target: sealos-deploy
inputArtifact: final Template YAML plus consistency, MUST-map, registry, topology, and quality-gate evidence
allowedAction: deploy after required inputs and all downstream gates pass
failureReturn: failed rule, registry, topology, artifact, or quality-gate diagnostics
responseOwner: docker-to-sealos

验证

针对确切的最终模板运行一致性、MUST 覆盖率和 quality_gate.py。使用基准用例 docker-to-sealos-positive-quality-gate 和 docker-to-sealos-violating-missing-rule；缺少注册表／MUST 证据会阻止部署。

概述

将 Docker Compose 文件或安装文档转换为适用于生产环境的 Sealos 模板。 当所需输入和确认均已具备时，自动执行分析、转换、验证和输出；如果所需输入 缺失，或受控操作尚未解决，则停止并提供安全的后续操作。

治理与规则优先级

使用以下优先级来防止规则偏移：

1. SKILL.md MUST 规则（本文件）
2. references/sealos-specs.md 和 references/database-templates.md
3. references/conversion-mappings.md 和 references/example-guide.md

如果低优先级参考资料与高优先级 MUST 规则冲突，请更新低优先级文件。 不要保留相互冲突的示例。

来源优先级与分支边界

每次转换都使用以下来源优先级，并在转换报告中记录所选来源：

1. 现有模板拓扑，以及用户明确提出的更新意图。
2. 条目 MUST 规则，以及配套的 must-rules-map.yaml / rules-registry.yaml。
3. Kubernetes 官方安装/运行时文档。
4. 为请求选定的 Compose 或安装文档。
5. 仓库配置、README、Dockerfile 和锁文件证据。
6. 当仅准备分支提供相关信息时，使用规范化的 analysis.json.build_environment 证据。

原始 Railpack JSON 不是转换来源。在 brain-deploy-preview 上，保留显式配置/README/Dockerfile/锁文件的优先级，使用规范化的构建环境证据，并保留 Dockerfile 和沙箱 Kaniko 路径。预览流程不会用 railpack build、BuildKit 或实时部署行为替代此路径。

转换载荷

此载荷仅限当前请求，并使用相对于仓库的路径，以便部署流程可以复用发现结果：

source:
  kind: compose | install-doc | existing-template
  paths: selected source files
  precedence: ordered source list
inference:
  app: metadata and runtime bundle evidence
  topology: resource roles, feature conditions, and replica counts
resources:
  ordered: Template CR, storage, database, workloads, App resource
  database: KubeBlocks evidence when applicable
  storage: PVC or managed object-storage evidence
  secrets: declared inputs with redaction status
artifact:
  template: template/<app>/index.yaml
  topology_evidence: .sealos/topology-evidence/<app>.yaml when required
verification:
  consistency: pass | fail
  must_map: pass | fail
  registry: pass | fail
  quality_gate: pass | fail
terminal_state: success | stopped | error
safe_next_action: request-scoped recovery or handoff action

载荷和最终产物不得包含密码、令牌、kubeconfig 内容、环境变量值、完整连接字符串或仅供验证器使用的密钥。

工作流

步骤 1：分析输入

从 Docker Compose/文档中提取：

• 应用服务与数据库服务
• 卷/配置挂载/对象存储需求
• 端口、依赖关系、服务通信
• 环境变量和密钥用法
• 启动时对引导凭据、API 密钥、盐值、密钥和功能开关的验证规则
• 所选确切发行版的账户引导模式：功能性首用户注册、必需的引导凭据，或可选的 root 对账/引导
• 多服务 Web 角色：浏览器入口、REST API、OpenAI/API 网关、文档、工作进程和一次性任务
• 资源限制/请求和健康检查
• 如果有 Kubernetes 官方安装文档/清单，也提取其中的应用运行时行为（引导管理员字段、外部端点/协议假设、健康探针、启动/初始化流程、迁移顺序）
• 如果官方 Compose/文档提供多个协作服务，记录官方运行时套件来源、组件列表、镜像版本、公共入口路由和关键环境变量
• 记录所选来源拓扑：承载拓扑的资源角色、功能条件，以及应用或数据库组件副本数

步骤 2：推断元数据

推断并规范化：

• 应用名称、标题、描述、类别
• 官方 URL、gitRepo、图标来源（优先选择方形/圆形且以图标为主的资源，例如应用图标、favicon 或头像；避免矩形文字标识/文本 Logo）
• 区域设置/i18n 元数据

步骤 3：按严格顺序规划资源

按以下顺序生成资源：

1. Template CR
2. ObjectStorageBucket（如有需要）
3. 数据库资源（ServiceAccount → Role → RoleBinding → Cluster → Job，如有需要）
4. 应用工作负载资源（ConfigMap/Secret → Deployment/StatefulSet → Service → Ingress）
5. App 资源（最后）

步骤 4：应用转换规则

应用 references/conversion-mappings.md 中的字段级映射，包括：

• 镜像固定和注解映射
• 端口／服务／Ingress 转换
• 环境变量转换和依赖排序
• 存储转换和 vn 命名（scripts/path_converter.py）
• 服务名称到 Kubernetes FQDN 的转换
• 对于数据库 URL／DSN 环境变量（例如 *_DATABASE_URL、*_DB_URL），当 Kubeblocks endpoint 为 host:port 时，通过经批准的 secretKeyRef 环境变量注入 host／port／username／password，并使用 $(VAR) 展开来组合最终 URL
• 边缘网关规范化：当 Compose 包含类似 Traefik 的边缘代理和业务服务时，跳过代理工作负载，并通过 Sealos Ingress 直接公开业务服务
• Sealos Ingress 的 TLS 卸载规范化：当业务服务同时公开 80 和 443 时，从工作负载／服务端口中移除 443，并移除容器内的 TLS 证书挂载（例如 /etc/nginx/ssl、/etc/ssl、/certs），除非官方 Kubernetes 文档明确要求后端到服务的流量使用 HTTPS
• 多服务 Web 应用规范化：在 App 资源中公开已验证的浏览器入口；仅在 API／网关／文档站点是预期的公共入口时才公开它们；工作进程保持私有，不创建 Service／Ingress
• URL 拓扑：面向浏览器的环境变量必须使用公共 HTTPS URL，而服务间环境变量必须使用 Kubernetes Service FQDN，除非应用明确要求使用公共回调
• WebSocket Ingress 规范化：当公共入口为 ws://、wss://、CDP／Chrome DevTools、游戏套接字，或名称中带有 WebSocket 的端口／服务时，使用 WebSocket nginx Ingress 注解公开它
• StatefulSet 服务标识：对于没有文档说明的无头服务或稳定 Pod 独立 DNS 要求的单组件应用，使用公共应用 Service 作为 spec.serviceName，并确保工作负载、Service、根 Ingress 和管理器标识保持一致；保留有文档说明的 HA／无头服务作为控制服务，并通过单独的公共应用 Service 公开应用
• 优先使用 scripts/compose_to_template.py --kompose-mode always 作为确定性转换入口（要求使用 kompose 以便可重复地调整工作负载结构）
• 更新现有模板时，以当前模板中承载拓扑的资源、功能条件和副本数为基准
• 新建转换时，以选定的 Compose 服务和 deploy.replicas 值为拓扑基准
• 参考 Kubernetes 官方安装文档／清单，使应用运行时语义保持一致，例如引导字段、端点、探针和启动顺序
• 除非选定的源拓扑或用户明确意图中包含可选或推荐的工作进程、缓存和 HA 副本，否则不要将其纳入生成的拓扑
• 每个功能输入都必须限定在其文档说明的能力范围内；数据库和对象存储输入不得添加无关的工作负载、缓存或副本
• 当官方 Compose／文档定义了多组件运行时套件时，运行时所需组件、入口路由、关键环境变量和组件镜像版本必须与同一个官方版本／Compose 源保持一致
• 将主机目录挂载转换为持久化存储前，先确认镜像是否已在目标路径提供必需文件；避免使用全新的空 PVC 遮蔽镜像内置的清单、依赖列表或默认配置

步骤 5：应用数据库策略

• 数据库服务必须生成为 KubeBlocks Cluster 资源。不得将 PostgreSQL/MySQL/MongoDB/Redis/Kafka Compose 数据库服务转换为原始 Kubernetes Deployment 或 StatefulSet 工作负载。
• PostgreSQL 必须遵循固定的版本和结构要求。
• MySQL/MongoDB/Redis/Kafka 必须使用 references/database-templates.md 中的模板和密钥命名方式。
• 如果应用数据库需要引导初始化，则添加 DB init Job/initContainer。
• 对于自定义 PostgreSQL 数据库（非 postgres），init Job 必须在执行前等待 PostgreSQL 就绪，并以幂等方式创建目标数据库。
• 可在应用 initContainers 以及 init/migration/bootstrap Jobs 中使用数据库客户端镜像，用于就绪检查和引导初始化门控。
• 必须通过实时数据库状态验证关键应用兼容性对象。使用幂等的 initContainer 自愈应用每次冷启动都需要的兼容性视图、旧版表/视图、索引、扩展、搜索路径和引导初始化状态。
• 一次性 init Jobs 可以创建初始数据库或填充种子状态，但应用启动门控必须直接验证最终数据库对象。将 TTL 过期的 Jobs 视为历史证据，并依据数据库状态进行验收。
• 依赖应用迁移的 Worker、网关和后台服务必须等待所需表、迁移标记或应用专用就绪对象，而不能仅检查数据库端口。
• Redis 就绪探针或 initContainers 必须能够容忍经过身份验证的 Redis 响应，例如在就绪检查不需要凭据时出现的 NOAUTH 或 Authentication required。
• PostgreSQL 引导初始化 shell 必须使用安全的引号写法。尽可能优先使用 shell 层面的存在性检查和简单 SQL 语句。使用单引号 heredoc 或 SQL 文件进行 psql 变量插值；如果守卫查询能够表达相同逻辑，则避免在内联 shell 命令中使用 PL/pgSQL DO $$ 块。
• 不要使用 psql -c "..." 进行 :'var' 变量插值。使用 psql -v name=value <<'SQL' ... :'name' ... SQL，或传入已安全处理的字面量 SQL。

步骤 6：生成输出文件

始终生成：

• template/<app-name>/index.yaml
• 如果能够确定官方图标，则生成 template/<app-name>/logo.<ext>，优先选择以正方形/圆形图标为主体的图稿，避免使用矩形文字标识或含文字的 Logo

绝不要创建：

• template/<app-name>/README.md
• template/<app-name>/README_zh.md

README 编写不在此技能的范围内。如果 Template CR 要求 README URL，只在 index.yaml 中填写 URL 字段，并将文件创建工作留给专用的 README 技能。

步骤 7：输出前验证

交付模板输出前运行验证器和自测。 如果验证失败，先修复模板/规则/示例。 对于 Web 应用，实时验证必须包含运行时日志检查：首次就绪后、登录或设置后，以及某个已记录的 API 负向路由或唯一的缺失静态资源请求后，检查 init 和主容器日志。SPA 客户端路由可能以 HTTP 200 返回 HTML 外壳；即使 Pods 已就绪，反复出现类似 traceback 的警告仍表示模板未通过。 对于有登录门槛的 Web 应用，实时验证必须在调整资源或清理前，通过一个已认证的 API 或页面证明实际的凭据/会话流程。 对于托管或私有对象存储，实时验证必须通过经过身份验证的应用流程上传已知字节，读取或下载对象并比较其 SHA-256 摘要，确认对象可通过应用代理或有时限的预签名 URL 送达，并验证原始匿名对象请求仍受限制。对于可选对象存储，必须分别验证本地存储和托管存储桶分支。

必须遵守的规则（精简版）

命名和元数据

• 模板 metadata.name 必须硬编码为小写；不要使用 ${{ defaults.app_name }}。
• 模板 CR 文件夹名称必须与 metadata.name 一致。
• 模板 CR 必须包含必填的元数据字段（title、url、gitRepo、author、description、icon、templateType、locale、i18n、categories）。
• 模板 spec.readme 必须指向 https://raw.githubusercontent.com/labring-actions/templates/kb-0.9/template/<app-name>/README.md。
• 模板 spec.i18n.zh.readme 必须指向 https://raw.githubusercontent.com/labring-actions/templates/kb-0.9/template/<app-name>/README_zh.md。
• 这些 README 字段仅在 index.yaml 中作为 URL 引用；此技能不得创建或更新引用的 README 文件。
• icon URL 必须指向模板仓库中此应用在 kb-0.9 分支上的原始文件路径。
• template/<app-name>/logo.<ext> 必须使用方形或圆形、图标优先的图稿（例如应用图标、网站图标或头像），不得使用矩形文字标志。
• i18n.zh.description 必须使用简体中文编写。
• 如果 i18n.zh.title 与 title 相同，则省略。
• categories 只能使用预定义值（tool、ai、game、database、low-code、monitor、dev-ops、blog、storage、frontend、backend）。

应用资源

• App 资源必须使用 spec.data.url。
• App 资源的 spec.displayType 必须为 normal。
• App 资源的 spec.type 必须为 link。
• App 资源的 spec.data.url 必须是从全新启动的 Sealos 中可成功访问的浏览器入口 URL。对于具有 safe-path、setup-path 或 entrance-path 行为的应用，请验证配置的路径和根路径，然后选择无需先进行隐藏导航即可支持登录或首次运行设置的 URL。
• SSR/Next.js/React 服务端应用不得将会呈现服务端异常的路径用作 App URL 或 HTTP 探测路径。即使 HTTP 状态为 2xx/3xx，只要可见文本中包含 Application error、server-side exception、Internal Server Error 或 Unhandled Runtime Error，就应视为入口路径失败。
• App 资源中不得使用 spec.template。
• cloud.sealos.io/app-deploy-manager 标签值必须与资源的 metadata.name 相同。
• 对于受管应用工作负载，metadata.labels.app 标签值必须与资源的 metadata.name 相同。
• 对于受管应用工作负载，主要业务容器名称必须与工作负载的 metadata.name 相同；sidecar/辅助容器可以使用不同的描述性名称。
• 应用的 Service 资源必须定义 metadata.labels.app 和 metadata.labels.cloud.sealos.io/app-deploy-manager，且这两个标签都必须与 spec.selector.app 相同。
• 运行时组件范围内的 ConfigMap 资源必须定义 metadata.labels.app 和 metadata.labels.cloud.sealos.io/app-deploy-manager，且这两个标签都必须与 metadata.name 相同；仅供 init 容器将初始配置复制到持久化存储的引导专用 ConfigMap 不得定义这两个标签。
• 应用的 Service 资源必须在 metadata.name、metadata.labels.app、metadata.labels.cloud.sealos.io/app-deploy-manager 和 spec.selector.app 中使用相同的组件名称。
• 根路径 Ingress 资源（pathType: Prefix、path: /）必须在 metadata.name、metadata.labels.cloud.sealos.io/app-deploy-manager 和后端 service.name 中使用相同的组件名称；非根路径或非 Prefix 的 Ingress 规则可以路由到不同的后端服务。
• 根路径 Ingress 资源（pathType: Prefix、path: /）必须使用 backend.service.port.number，且该数值必须与所引用应用 Service 中声明的 spec.ports[*].port 相匹配。
• 根路径 Prefix 路由必须是每个 HTTP paths 列表中的第一项，以便 Launchpad 公共地址发现功能选择应用入口路由。
• 必须显式设置 Service spec.ports[*].name（多端口服务必需）。
• HTTP Ingress 必须包含必需的 nginx 注解（kubernetes.io/ingress.class、nginx.ingress.kubernetes.io/proxy-body-size、nginx.ingress.kubernetes.io/server-snippet、nginx.ingress.kubernetes.io/ssl-redirect、nginx.ingress.kubernetes.io/backend-protocol、nginx.ingress.kubernetes.io/client-body-buffer-size、nginx.ingress.kubernetes.io/proxy-buffer-size、nginx.ingress.kubernetes.io/proxy-send-timeout、nginx.ingress.kubernetes.io/proxy-read-timeout、nginx.ingress.kubernetes.io/configuration-snippet），并使用预期的默认值。
• WebSocket Ingress 必须包含必需的 nginx 注解（kubernetes.io/ingress.class、nginx.ingress.kubernetes.io/proxy-body-size、nginx.ingress.kubernetes.io/proxy-read-timeout、nginx.ingress.kubernetes.io/proxy-send-timeout、nginx.ingress.kubernetes.io/backend-protocol、nginx.ingress.kubernetes.io/ssl-redirect），其中 backend-protocol: WS，且读写超时均为 3600。
• CronJob 资源必须定义 cloud.sealos.io/cronjob、cronjob-launchpad-name 和 cronjob-type 标签；cloud.sealos.io/cronjob 必须与 metadata.name 相同，cronjob-launchpad-name 必须为 ""，且 cronjob-type 必须为 image。
• 如果有官方应用健康检查，则受管工作负载必须定义 livenessProbe、readinessProbe，并为启动缓慢的应用定义 startupProbe，且应与官方端点/命令一致。
• 对于已验证以非 root UID 运行的公共镜像，受管应用工作负载和 init Job 应设置兼容受限策略的安全上下文（runAsNonRoot、runAsUser、runAsGroup、fsGroup、seccompProfile: RuntimeDefault、allowPrivilegeEscalation: false、capabilities.drop: [ALL]），除非镜像需要 root 权限或额外能力。

官方 Kubernetes 对齐

• 如果有官方 Kubernetes 安装文档或清单，转换时必须参考这些资料，并在生成模板制品前对齐关键运行时设置。
• 当官方 Kubernetes 文档或清单与 Compose 不一致时，应用行为应优先遵循官方 Kubernetes 运行时语义（引导管理员字段、外部端点／环境变量／协议、健康探针），除非这样做会违反优先级更高的 Sealos MUST／安全约束。
• 对现有模板进行更新时，保留当前模板中决定拓扑的资源清单、条件和副本数；进行新转换时，保留所选 Compose 拓扑和 deploy.replicas 值。
• 使用官方 Kubernetes 文档或清单对齐应用运行时语义；仅当所选源拓扑或用户的明确意图包含可选或推荐的工作进程、缓存和高可用副本时，才添加这些内容。
• 每项应用功能输入只能控制该功能文档中所述的资源和设置；数据库和对象存储输入不得更改无关的工作负载清单或副本数。
• 拓扑敏感型验证必须提供 .sealos/topology-evidence/<app-name>.yaml 作为仅供验证器使用的 TopologyEvidence；最终 Sealos Template 制品中不得包含拓扑验证器元数据。
• 如果官方 Compose／文档提供多组件运行时套件，模板制品必须保留来自同一官方发布版本／Compose 源的运行时必需组件、公开入口路由、关键环境变量和镜像版本。
• 使用官方多组件运行时证据的模板，验证时必须提供单独的 RuntimeBundleEvidence YAML 文件；最终 Sealos Template 制品中不得包含运行时套件验证器元数据。

镜像和拉取策略

• 不得使用 :latest。
• 使用 crane 确定版本：优先使用明确的版本标签（例如 v2.2.0）；仅在没有确定性版本标签时，才回退到固定摘要。
• 避免使用浮动标签（例如 :v2、:2.1、:stable）；应使用明确的版本标签或摘要。
• 受管工作负载的镜像引用必须具体明确，且不得包含 Compose 风格的变量表达式（例如 ${VAR}、${VAR:-default}）；生成模板制品前，必须将其解析为明确的标签或摘要。
• 应用的 originImageName 必须与容器镜像一致。
• 已知的公开镜像受管应用工作负载不得设置 template.spec.imagePullSecrets；需要通过注册表身份验证的工作负载，只能引用应用范围内的 Secret ${{ defaults.app_name }}。
• 私有 GHCR 镜像的注册表拉取 Secret 由 sealos-deploy 使用本地 gh CLI 凭据在运行时管理；生成的模板中不得公开原始注册表凭据输入。
• 所有容器都必须显式设置 imagePullPolicy: IfNotPresent。

存储

• 不要使用 emptyDir。
• 需要存储时使用持久化存储模式（volumeClaimTemplates）。
• 使用 volumeClaimTemplates 的 StatefulSet 资源必须保留 app 和 cloud.sealos.io/app-deploy-manager 等标准工作负载标签，并且仅从 StatefulSet 的 metadata.labels 和 volumeClaimTemplates[].metadata.labels 中省略 cloud.sealos.io/deploy-on-sealos。
• volumeClaimTemplates[].metadata 必须包含由路径派生的 name、annotations.path 和 annotations.value: '1'，并且每个声明都必须与名称和路径相同的容器 volumeMount 相匹配。
• 除非源规范明确要求更小值，否则 PVC 请求必须 <= 1Gi。
• ConfigMap 数据键必须遵循 vn 命名方式（scripts/path_converter.py），包括 /、-、. 和其他特殊字符。
• 由托管 Deployment/StatefulSet 工作负载挂载的 ConfigMap，其 metadata.name 必须与工作负载的 metadata.name 相同。
• ConfigMap 工作负载卷必须使用 <workload-name>-cm，并且每个 ConfigMap data 键都必须作为独立的 volumeMount 挂载，且 subPath 必须与该键完全相同。
• 托管模板中省略 ConfigMap 卷的 defaultMode。通过 /bin/sh /path/script 调用挂载的脚本；如果应用确实需要可执行文件，则在 initContainer 中将文件复制到持久化存储并应用 chmod。
• 避免在 command/args 中使用冗长的内联启动脚本或 heredoc；将初始化脚本/启动脚本放入 ConfigMap 文件，并用简短命令调用。
• 生成输入前，须根据应用官方文档对对象存储进行分类：必需能力、应用层可选能力或外部托管存储。
• 如果上游应用中的对象存储/S3 集成属于 Enterprise、付费、商业、订阅或许可证限制功能，则公共模板必须使用社区支持的存储路径（例如 filesystem/PVC），并且不得为此功能提供标准 ObjectStorageBucket 或 S3 输入。
• 如果对象存储为必需项，且 Sealos S3 兼容性符合应用要求，则为文档规定的存储桶拓扑创建无条件的 ObjectStorageBucket 资源，并注入 Sealos 对象存储密钥。
• 使用托管 ObjectStorageBucket 的模板必须将其作为唯一的对象存储数据平面，并省略捆绑的 MinIO 服务端工作负载、Services、Ingresses、PVC 和本地对象存储凭据。
• 转换期间解析对象存储提供商/后端选择器输入，不得将托管 ObjectStorageBucket 与捆绑的 minio/minio、bitnami/minio 或 bitnamilegacy/minio 服务端镜像组合使用。
• 仅当官方协议证据要求进行请求适配时，才使用兼容性代理。
• 对象存储兼容性代理必须将 metadata.annotations.docker-to-sealos.object-storage-compatibility-proxy-source 声明为不含凭据的 HTTPS 源 URL 或 user-request:<reference>，保持无状态，并省略持久卷。
• 外部 S3/对象存储凭据输入必须将 metadata.annotations.docker-to-sealos.external-object-storage-source 声明为不含凭据的 HTTPS 源 URL 或 user-request:<reference>，且不得与 ObjectStorageBucket 共存。
• 对托管或私有对象存储的验收必须证明：应用已通过身份验证完成上传和读取/下载，内容匹配；通过应用代理或有时限的预签名方式交付；原始匿名访问受到限制。可选对象存储必须同时通过本地存储和托管存储桶两种分支的验证。

只有在针对最终模板通过一致性、MUST 映射覆盖率、镜像仓库、拓扑证据和 quality_gate.py 检查后，才会移交部署。缺失或过时的证据会产生 error，并退回给失败规则或产物负责人。

环境变量和密钥

• 非数据库敏感值/输入直接使用 env[].value。
• 如果官方运行时配置文件限制了环境变量值的格式或长度，则使用符合要求的字面值，或使用不带生成默认值的必填输入；对于受十六进制或编码格式约束的值，裸用 ${{ random(n) }} 无效。
• 如果官方运行时库可根据不透明熵确定性地派生内部凭据，则可在 spec.defaults 中使用带引号的实例种子；每个使用该种子的角色都必须派生并验证相同的最终值，在执行前移除种子，且不得提供最终派生值的用户输入。
• 标记为 docker-to-sealos.runtime-secret-contract: persisted 的持久化运行时密钥契约必须从持久化运行时熵生成密钥、通过原子替换设置严格权限、在执行前验证密钥，并避免在诊断信息中泄露最终密钥。
• 如果官方运行时配置文件选择了外部提供商，则工作负载必须为该提供商配置非空的必填凭据；默认值为空的可选输入无效。
• 业务容器必须通过 env[].valueFrom.secretKeyRef 从经批准的 Kubeblocks 数据库密钥中获取数据库连接字段（endpoint、host、port、username、password）；例外：如果 Redis 密钥仅暴露凭据，则 Redis 的 host/port 可使用 Sealos Redis 服务 FQDN 和 6379；如果 MongoDB 密钥仅暴露凭据，则 MongoDB 的 host/port 或连接 URL 可使用 Sealos MongoDB 服务 FQDN 和 27017。
• 业务容器不得使用自定义环境变量/卷的 Secret 引用，已批准的 Kubeblocks 数据库密钥和对象存储密钥除外。
• 仅私有镜像仓库的镜像可使用专用的应用级镜像拉取 Secret，且只能通过 template.spec.imagePullSecrets 引用；公共镜像不得添加拉取密钥。
• 数据库连接/引导配置可使用 Kubeblocks 提供的密钥，且不得通过自定义 Secret 资源重新定义保留的 Kubeblocks 数据库密钥名称。
• 环境变量必须先声明，再被引用（例如，先声明密码，再组合 URL）。
• 遵循官方应用环境变量命名规范；不得自创前缀。
• 对于拆分前端/API/网关的应用，应区分浏览器访问的公开 URL 和内部服务 URL。前端/浏览器回调变量使用 https://${{ defaults.<host> }}.${{ SEALOS_CLOUD_DOMAIN }}；后端到后端变量使用 http://<service>.$(SEALOS_NAMESPACE).svc.cluster.local:<port> 或完整渲染后的服务 FQDN。
• 如果应用要求通过基于文件的配置系统（例如 node-config config/default.json、PHP 配置文件）配置公开 URL，则创建 ConfigMap，其中包含公开 URL 设置为 https://${{ defaults.app_host }}.${{ SEALOS_CLOUD_DOMAIN }} 的配置文件，并将其挂载到应用的配置目录。ConfigMap 必须遵循标准命名和标签规范。
• 对于 PostgreSQL 自定义数据库（非 postgres），应包含 ${{ defaults.app_name }}-pg-init Job，并实现可安全用于启动且幂等的创建逻辑（等待就绪，并在创建前检查是否已存在）。
• 对于应用专属的数据库兼容性要求，应包含 initContainer 或启动门控，在业务容器启动前幂等地创建或修复所需的视图、别名、索引、扩展、权限、角色搜索路径和旧版兼容对象。
• 如果官方运行时配置文件声明了数据库最终状态要求，则应包含 initContainer 门控，在业务容器启动前等待数据库并验证所需的扩展或对象。
• 托管应用主容器的 command/args 必须尽量保持与镜像的官方入口点一致。仅保留官方启动命令、Compose 原生参数或简短的 exec 包装器；文件准备、权限修复、数据库引导配置和兼容性自修复应移至 initContainer、Job 或 ConfigMap 脚本中。
• 业务主容器中的 Shell 包装器必须对最终进程执行 exec，以确保信号处理正常。
• 数据库引导 SQL 必须能在 Shell 执行时安全运行：优先使用 Shell 级保护性查询和简单 SQL；对 psql 变量使用单引号 heredoc；避免使用未经保护的内联 DO $$ 块。
• psql -c 中不得包含 :'var' 这种 psql 变量语法；需要使用 -v 插值的 SQL 应使用 heredoc。

数据库专属约束

• 数据库服务必须使用 KubeBlocks Cluster 资源，不能使用应用 Deployment 或 StatefulSet 工作负载。StatefulSet 仅允许用于有状态应用组件，绝不能用于 PostgreSQL/MySQL/MongoDB/Redis/Kafka 数据库服务。
• 数据库客户端镜像可用于应用 initContainers，以及用于就绪检查和引导门控的初始化/迁移/引导 Job。
• PostgreSQL 版本：postgresql-16.4.0。
• PostgreSQL API：apps.kubeblocks.io/v1alpha1。
• PostgreSQL RBAC 统一命名：${{ defaults.app_name }}-pg。
• PostgreSQL RBAC 必须包含 app.kubernetes.io/instance 和 app.kubernetes.io/managed-by 标签。
• 每个 KubeBlocks 数据库 Cluster 都必须包含 kb.io/database、sealos-db-provider-cr 和 clusterdefinition.kubeblocks.io/name 标签；sealos-db-provider-cr 必须与 metadata.name 相同，以便 dbprovider 列出并分类数据库。关联的 Pod、Service 和 OpsRequest 应带有 app.kubernetes.io/instance=<database name>，以便在详情视图中展示。
• PostgreSQL 角色通配符权限要求仍按当前规范执行。
• PostgreSQL 集群必须包含必需的标签/字段（kb.io/database: postgresql-16.4.0、clusterdefinition.kubeblocks.io/name: postgresql、clusterversion.kubeblocks.io/name: postgresql-16.4.0、clusterVersionRef: postgresql-16.4.0、disableExporter: true、enabledLogs: [running]、switchPolicy.type: Noop、serviceAccountName）。
• MongoDB 集群必须遵循升级后的结构（componentDef: mongodb、serviceVersion: 8.0.4、kb.io/database 和 app.kubernetes.io/instance 标签）。
• MySQL 集群必须遵循升级后的结构（kb.io/database: ac-mysql-8.0.30-1、clusterDefinitionRef: apecloud-mysql、clusterVersionRef: ac-mysql-8.0.30-1、tolerations: []）。
• Redis 集群必须遵循升级后的结构（componentDef: redis-7、componentDef: redis-sentinel-7、serviceVersion: 7.2.7、主数据 PVC 为 1Gi、拓扑为 replication）。
• 除非源文档明确要求其他值，否则数据库集群组件资源必须使用 limits(cpu=500m,memory=512Mi) 和 requests(cpu=50m,memory=51Mi)。
• 所有受管理工作负载容器的资源都必须遵循 Sealos 资源阶梯：limits.cpu 仅可取 100m/200m/500m/1/2/3/4/8，limits.memory 仅可取 128Mi/256Mi/512Mi/1024Mi/2048Mi/4096Mi/8192Mi/16384Mi，且 requests 必须从 limits 推导，方法是去掉最后一个数字（500m→50m、512Mi→51Mi、1→100m、1024Mi→102Mi、4096Mi→409Mi）。不要自行编造不在阶梯中的值，也绝不能使用 2G/4G/8G/16G，因为 Sealos Template API 配额预览可能会将裸 G 内存解析为 0。
• 更新现有模板时，除非运行时证据表明存在临时存储压力，否则不要添加、删除或更改现有的 ephemeral-storage 资源字段；调整 CPU 和内存时保留原有请求/限制值。
• Secret 命名：
  • MongoDB：${{ defaults.app_name }}-mongo-mongodb-account-root（或当 MongoDB 集群名称使用 -mongodb 时，使用 ${{ defaults.app_name }}-mongodb-mongodb-account-root）
  • Redis：${{ defaults.app_name }}-redis-redis-account-default（为向后兼容，可接受旧版 ${{ defaults.app_name }}-redis-account-default）
  • Kafka：${{ defaults.app_name }}-broker-account-admin
  • 除受支持的例外情况外，不要使用旧版命名。

基线运行时默认值

除非源文档明确要求其他配置，否则将此轻量级应用阶梯项用作初始个人低负载候选配置：

• 容器限制：cpu=200m、memory=256Mi
• 容器请求：cpu=20m、memory=25Mi
• revisionHistoryLimit: 1
• 默认将 automountServiceAccountToken: false；仅当应用有明确的 Kubernetes API/服务账号令牌需求时才将其设为 true，相关证据包括 Kubernetes 集成设置、serviceAccountName 或 sealos.io/service-account-token-reason 工作负载注解。
• 如果工作负载产生 PodSecurity 准入警告，且镜像以非 root 用户身份运行，则添加兼容受限策略的安全上下文，然后再报告模板已就绪。

静态生成无法证明最终资源层级。将候选配置作为最终模板值之前，必须完成实时资源验证。

个人低负载资源验证

对每个应用的主容器、sidecar、initContainer 和 Job 分别应用资源阶梯：

• 最终 CPU 和内存限制必须是通过角色专属个人低负载验证的最低 Sealos 阶梯层级；但明确的源文档硬性最低要求仍是下限。
• 分别调优 CPU 和内存，每次只调整一个阶梯级别，并对每个候选配置进行全新部署或冷启动执行。
• 长期运行的工作负载要通过验证，必须完成冷启动、进入 Ready 状态、在适用时完成注册或登录、完成至少两项有代表性的低负载操作，并稳定运行 60 秒，期间不得出现 OOMKilled 终止、重启、就绪状态波动或资源相关超时。
• 一次性 initContainer 或 Job 要通过验证，必须在冷启动运行中成功完成，并使所有依赖工作负载都进入 Ready 状态。
• 如果较低层级未能满足任何验收信号，则使用下一个通过验证的层级，并通过全新部署重复最终验证。
• 将观测到的 CPU 和内存峰值及利用率百分比视为诊断证据；验收失败时应提升层级。
• 根据 Sealos 资源阶梯，从限制值推导请求值。

容器内浏览器 / 远程桌面验证

• 仅对运行 Chrome、Chromium、VNC、WebRTC 桌面、Xvfb、Selkies、noVNC、Kasm 或类似远程桌面技术栈的容器应用浏览器专属验证；通过浏览器访问的 Web 应用（如 Langflow）遵循通用个人低负载策略。
• 按照以下流程测试：冷启动直至就绪、轻量级页面、真实或中等复杂度页面、交互或搜索操作，以及 60 秒稳定性窗口。
• 对于采用 4K 最大显示分辨率的 Chrome + Xvfb + Selkies，从 limits(cpu=200m,memory=1024Mi) 和派生出的 requests(cpu=20m,memory=102Mi) 开始验证，然后在相同验收标准下测试相邻阶梯层级。

默认值与输入项

• defaults 用于生成的值（app_name、app_host、随机密码/密钥）。
• inputs 仅用于用户实际提供的运维值（电子邮件/SMTP/外部 API 密钥等）。
• 定义管理员输入项之前，先将所选版本的账户流程归类为功能完整的首位用户注册、强制引导凭据，或可选的 root 对账。
• 如果支持功能完整的首位用户注册，且可选的部署时管理员凭据存在超出 Template 输入架构的启动致命限制，则使用注册流程，并省略管理员/root 输入项及其引导环境变量/配置注入。
• 当强制引导凭据由部署者选择时，在 spec.inputs 中将文档规定的用户名或电子邮件及密码字段声明为必填输入项，不设置 default；用英文说明上游规定的具体限制；在部署 Template API 前验证收集到的值，并使用相同的值进行实时登录。数据库凭据保留在 KubeBlocks 密钥中。
• 当强制引导凭据由受支持的运行时生成时，按文档规定的确切格式确定性地构造并验证；除非文档说明可由用户选择，否则不设置管理员输入项；通过 Secret 或实时运行时来源保留解析出的凭据，并使用该凭据进行脱敏实时登录。
• 优先采用功能完整的首位用户注册，而不是可选的 root 对账。若所选来源要求强制引导流程（例如 Frappe），则予以保留。
• Template 工件中的每个 ${{ inputs.<name> }} 引用，都必须在同一 Template CR 中有对应的 spec.inputs.<name> 声明。
• Template CR 中的每个 spec.defaults.<name>.value 以及每个存在的 spec.inputs.<name>.default，反序列化后都必须是 YAML 字符串，无论声明的输入类型是什么；对于类似数字、布尔值和 null 的标量值，须加引号；必填输入项不设置 default 仍然有效。
• inputs.description 必须使用英文。
• 启动关键型生成默认值必须通过确定性的格式构造满足应用文档规定的验证。仅当所选运行时的文档说明支持确定性生成，且解析出的凭据可通过 Secret 或实时运行时来源获取以供脱敏登录时，才使用生成的强制引导凭据。首位用户注册的凭据应保留在注册流程中。
• 对启动配置验证退出进行分类，并在调整资源配置前修正账户流程约定。在部署前验证和实时登录之间，逐字节保留所有用户提供的凭据。
• 对官方来源文档说明的应用级可选对象存储，使用布尔输入项（例如 enable_s3_storage），并通过 inputs.<name> === 'true' 进行测试。在转换期间解析提供商/后端/类型/模式/驱动程序的选择，不要将这些选择器放入 spec.inputs。
• 可选对象存储输入项的 false 分支必须配置为官方来源文档说明的禁用存储/本地模式。
• 标记为 docker-to-sealos.database-mode: optional-managed 的可选托管数据库约定，必须在托管 Cluster 平面和数据库接线配置中共用一个布尔条件，同时定义文档规定的 SQLite 或本地 false 分支。

验证命令

最终回复前运行所有检查：

1. python scripts/path_converter.py --self-test
2. python scripts/test_check_consistency.py
3. python scripts/test_compose_to_template.py
4. python scripts/test_check_must_coverage.py
5. python scripts/check_consistency.py --skill SKILL.md --references references --rules-file references/rules-registry.yaml
6. 对现有模板更新和其他对拓扑敏感的转换，运行 python scripts/check_consistency.py --skill SKILL.md --references references --rules-file references/rules-registry.yaml --artifacts template/<app-name>/index.yaml,.sealos/topology-evidence/<app-name>.yaml
7. python scripts/check_must_coverage.py --skill SKILL.md --mapping references/must-rules-map.yaml --rules-file references/rules-registry.yaml
8. （CI / 一次性运行）运行 python scripts/quality_gate.py --require-topology-evidence --artifacts /abs/path/template/<app-name>/index.yaml,.sealos/topology-evidence/<app-name>.yaml，或运行 DOCKER_TO_SEALOS_ARTIFACTS=/abs/path/template/<app-name>/index.yaml,.sealos/topology-evidence/<app-name>.yaml python scripts/quality_gate.py --require-topology-evidence（未显式指定 artifacts 时，会扫描 template/*/index.yaml 和 .sealos/*evidence*.yaml；只有在开发/调试且没有 artifacts 时，才设置 DOCKER_TO_SEALOS_ALLOW_EMPTY_ARTIFACTS=1）
9. 线上部署验收：sealos-deploy 创建应用后，验证实际的 App URL、Web 应用的登录/设置流程、近期日志、已记录的 API 负向路由或唯一的缺失静态资源（且不产生嘈杂的回溯日志）、预期数据库对象，以及完整的资源占用情况，然后再报告成功。

check_consistency.py 由注册表驱动。保持 references/rules-registry.yaml 与已实现的规则同步。 注册表规则条目支持 severity 和可选的 scope.include_paths 元数据。

输出约定

转换完成后，提供：

1. 简要转换摘要
2. 目标文件路径（template/<app-name>/index.yaml）
3. 完整的模板 YAML
4. 仅在存在歧义时说明关键决策

请勿在此技能中创建或输出 README 内容。README 生成由另一项技能负责。

参考资料导航（渐进式加载）

仅加载当前任务所需的参考资料：

• references/sealos-specs.md
  • 权威的排序、标签、App/Ingress/ConfigMap 约定
• references/bootstrap-account-modes.md
  • 账号流程分类、Template 输入限制、引导凭据约定和验收检查
• references/conversion-mappings.md
  • Docker→Sealos 字段级映射和边缘转换
• references/database-templates.md
  • 数据库模板、RBAC 结构、密钥命名模式
• references/frappe-bench.md
  • Frappe/ERPNext/HRMS/bench 转换模式、初始化资源、幂等站点引导和常见故障特征
• references/runtime-log-hygiene.md
  • 运行时日志验收、无害的 404 回溯处理、静默依赖安装和受限安全上下文指导
• references/example-guide.md
  • 示例和模式演练（非权威）
• references/rules-registry.yaml
  • 机器可读的验证范围/规则列表
• references/must-rules-map.yaml
  • MUST 条目到执行机制的映射（rule 或 manual），用于防止偏差

脚本工具

• scripts/path_converter.py
  • 将路径转换为 vn 名称
  • 支持自测，用于回归检查
• scripts/compose_to_template.py
  • 用于将 compose/docs 确定性转换为模板的入口
  • 支持 --kompose-mode auto|always|never（默认值为 always），以复用 kompose convert 的工作负载结构
  • 生成 template/<app-name>/index.yaml
• scripts/test_compose_to_template.py
  • compose 转换行为的回归测试
• scripts/check_consistency.py
  • 由注册表驱动的一致性验证器
• scripts/test_check_consistency.py
  • 验证器行为的回归测试
• scripts/check_must_coverage.py
  • 根据注册表规则验证 MUST 条目覆盖映射
• scripts/test_check_must_coverage.py
  • MUST 覆盖率验证器的回归测试

边缘策略

• 切勿向用户询问缺失字段；应根据 compose/docs 和平台惯例进行推断。
• 保持 App 资源采用 spec.data.url 格式；切勿使用 spec.template。
• 保持 App 资源使用 spec.displayType: normal 和 spec.type: link；不要推断其他枚举值。
• 确保业务环境变量、对象存储和 DB 密钥策略符合 MUST 规则。
• 优先使用方形或圆形、以图标为主的 Logo 素材（应用图标/favicon/头像），避免使用矩形的文字标识或文字 Logo。
• 优先使用 Sealos 管理的 Ingress，而非捆绑的边缘代理：如果 Traefik 网关仅用作 Ingress/前置代理，且至少存在一个业务服务，则不要生成 Traefik 工作负载资源。
• 优先使用 Sealos Ingress 终止网关 TLS，而非在容器内终止 TLS：对于双端口 HTTP/HTTPS 工作负载，保留 HTTP 服务端口，并移除冗余的 HTTPS/证书挂载，除非官方文档要求使用 HTTPS 后端。
• 对公共的 ws://、wss://、CDP/Chrome DevTools、游戏套接字以及名称包含 WebSocket 的端口/服务，优先使用 WebSocket Ingress；使用 backend-protocol: WS 和 3600 读写超时。
• 切勿创建 template/<app-name>/README.md 或 template/<app-name>/README_zh.md；仅在模板架构要求时，于 index.yaml 中保留 README URL 引用。
• 出现冲突时，优先修正引用/示例，而非添加例外。
• 使用官方 Kubernetes 安装文档/清单来完善运行时语义，同时保留选定的源拓扑。
• 如果项目提及 Frappe、ERPNext、HRMS 或 bench，请在生成应用工作负载前加载 references/frappe-bench.md。