docker-to-sealos

Docker 到 Sealos 模板转换器

概述

将 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：分析输入

从 Docker Compose／文档中提取：

• 应用服务与数据库服务
• 卷／配置挂载／对象存储需求
• 端口、依赖关系、服务间通信
• 环境变量和密钥用法
• 资源限制／请求和健康检查
• 如果有官方 Kubernetes 安装文档／清单，还要提取应用运行时行为（引导管理员字段、外部端点／协议假设、健康探针、启动／初始化流程）

步骤 2：推断元数据

推断并规范化：

• 应用名称、标题、描述、类别
• 官方 URL、gitRepo、图标来源
• 语言区域／i18n 元数据

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

按以下顺序生成资源：

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

步骤 4：应用转换规则

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

• 镜像固定和注解映射
• 端口／服务／Ingress 转换
• 环境变量转换和依赖顺序
• 存储转换和 vn 命名（scripts/path_converter.py）
• 服务名称到 Kubernetes FQDN 的转换
• 对于 DB 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 流量
• 优先使用 scripts/compose_to_template.py --kompose-mode always 作为确定性转换入口（为确保工作负载形态可复现，需使用 kompose）
• 当存在官方 Kubernetes 安装文档／清单时，执行双来源合并：以 Compose 作为基础拓扑，再依据官方 Kubernetes 指引对齐应用运行时语义

步骤 5：应用数据库策略

• PostgreSQL 必须遵循固定的版本和结构要求。
• MySQL/MongoDB/Redis/Kafka 必须使用 references/database-templates.md 中的模板和密钥命名。
• 当应用程序需要初始化数据库时，添加 DB 初始化 Job/initContainer。
• 对于自定义数据库（非 postgres）的 PostgreSQL，初始化 Job 必须等待 PostgreSQL 就绪后再执行，并以幂等方式创建目标数据库。

步骤 6：生成输出文件

始终生成：

• template/<app-name>/index.yaml
• template/<app-name>/logo.<ext>（当官方图标可解析时）

步骤 7：输出前验证

交付模板输出前，运行验证器和自测。 如果验证失败，先修复模板／规则／示例。

MUST 规则（精简版）

命名和元数据

• 模板的 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。
• icon URL 必须指向模板仓库中此应用在 kb-0.9 分支上的原始文件路径。
• i18n.zh.description 必须使用简体中文撰写。
• 如果 i18n.zh.title 与 title 相同，则省略。
• categories 只能使用预定义值（tool、ai、game、database、low-code、monitor、dev-ops、blog、storage、frontend、backend）。

应用资源

• 应用资源必须使用 spec.data.url。
• 应用资源的 spec.displayType 必须为 normal。
• 应用资源的 spec.type 必须为 link。
• 应用资源中不得使用 spec.template。
• cloud.sealos.io/app-deploy-manager 标签值必须与资源的 metadata.name 相同。
• 对于受管理的应用工作负载，metadata.labels.app 标签值必须与资源的 metadata.name 相同。
• 对于受管理的应用工作负载，containers[*].name 必须与工作负载的 metadata.name 相同。
• 应用 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 相同。
• 应用 Service 资源的 metadata.name、metadata.labels.app、metadata.labels.cloud.sealos.io/app-deploy-manager 和 spec.selector.app 必须使用相同的组件名称。
• 应用 Ingress 资源的 metadata.name、metadata.labels.cloud.sealos.io/app-deploy-manager 和后端 service.name 必须使用相同的组件名称。
• 必须显式设置 Service 的 spec.ports[*].name（多端口 Service 必需）。
• 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），并使用预期的默认值。
• 如果有官方应用健康检查，则受管理的工作负载必须定义 livenessProbe、readinessProbe，并为启动较慢的应用定义 startupProbe，且与官方端点或命令保持一致。

与官方 Kubernetes 规范对齐

• 如果有官方 Kubernetes 安装文档或清单，在生成模板文件之前，必须参考这些资料并使关键运行时设置与之对齐。
• 当官方 Kubernetes 文档或清单与 Compose 不一致时，应用行为应优先遵循官方 Kubernetes 运行时语义（引导管理员字段、外部端点／环境变量／协议、健康探针），除非这会违反优先级更高的 Sealos MUST／安全要求。

镜像与拉取策略

• 不要使用 :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）。
• 除非源规范明确要求更小的值，否则 PVC 请求量必须 <= 1Gi。
• ConfigMap 键和卷名称必须遵循 vn 命名规范（scripts/path_converter.py）。

环境变量与密钥

• 非数据库敏感值/输入使用直接的 env[].value。
• 业务容器必须通过 env[].valueFrom.secretKeyRef，从获准的 Kubeblocks 数据库密钥中获取数据库连接字段（endpoint、host、port、username、password）。
• 业务容器不得引用自定义环境变量/卷 Secret，但获准的 Kubeblocks 数据库密钥和对象存储密钥除外。
• 允许使用应用专属的注册表拉取 Secret，且只能通过 template.spec.imagePullSecrets 引用。
• 数据库连接/引导可以使用 Kubeblocks 提供的密钥，且不得通过自定义 Secret 资源重新定义保留的 Kubeblocks 数据库密钥名称。
• 环境变量必须先声明，再被引用（例如，先声明密码，再组合 URL）。
• 遵循应用官方环境变量命名规范；不要自行发明前缀。
• 如果应用要求通过基于文件的配置系统（例如 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，并实现可安全启动且幂等的创建逻辑（等待就绪，并在创建前检查是否已存在）。

特定数据库的约束

• 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 标签。
• 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)。
• Secret 命名：
  • MongoDB：${{ defaults.app_name }}-mongodb-account-root
  • Redis：${{ defaults.app_name }}-redis-redis-account-default
  • Kafka：${{ defaults.app_name }}-broker-account-admin
  • 除支持的例外情况外，不得使用旧版命名。

基线运行时默认值

除非源文档明确要求其他配置，否则使用：

• 容器 limits：cpu=200m、memory=256Mi
• 容器 requests：cpu=20m、memory=25Mi
• revisionHistoryLimit: 1
• automountServiceAccountToken: false

默认值与输入

• defaults 用于生成的值（app_name、app_host、随机密码/密钥）。
• inputs 仅用于确实由用户提供的运维值（电子邮件/SMTP/外部 API 密钥等）。
• inputs.description 必须使用英文。

验证命令

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

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
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（默认要求存在 template/*/index.yaml；仅在没有制品的开发/调试场景中设置 DOCKER_TO_SEALOS_ALLOW_EMPTY_ARTIFACTS=1）

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

输出约定

转换完成后，提供：

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

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

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

• references/sealos-specs.md
  • 权威的排序、标签、App/Ingress/ConfigMap 约定
• references/conversion-mappings.md
  • Docker → Sealos 的字段级映射和边缘转换
• references/database-templates.md
  • 数据库模板、RBAC 结构、密钥命名模式
• references/frappe-bench.md
  • Frappe/ERPNext/HRMS/bench 转换模式、初始化资源、幂等站点引导，以及常见故障特征
• 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／文档到模板生成器入口
  • 支持 --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／文档和平台约定推断。
• 保持 App 资源采用 spec.data.url 格式；切勿使用 spec.template。
• 保持 App 资源使用 spec.displayType: normal 和 spec.type: link；不要推断其他枚举值。
• 确保业务环境变量、对象存储和数据库密钥策略符合 MUST 规则。
• 优先使用 Sealos 管理的 Ingress，而不是捆绑的边缘代理：如果 Traefik 网关仅用作 Ingress／前置代理，且至少存在一个业务服务，则不要输出 Traefik 工作负载资源。
• 优先使用 Sealos Ingress 终止网关 TLS，而不是容器内 TLS：对于双端口 HTTP/HTTPS 工作负载，保留 HTTP 服务端口，并移除多余的 HTTPS／证书挂载，除非官方文档要求后端使用 HTTPS。
• 出现冲突时，优先修正规范／示例，而不是添加例外。
• 如果目标应用有官方 Kubernetes 安装文档／清单，不要忽略；应使用这些资料完善 Compose 默认值以外的运行时语义。
• 如果项目提到 Frappe、ERPNext、HRMS 或 bench，生成应用工作负载前请加载 references/frappe-bench.md。