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 或文档中提取：

• 应用服务与数据库服务
• 卷/配置挂载/对象存储需求
• 端口、依赖项、服务通信
• 环境变量和密钥的使用情况
• 启动时对引导凭据、API 密钥、盐值、密钥和功能标志的验证规则
• 多服务 Web 角色：浏览器入口、REST API、OpenAI/API 网关、文档、工作进程和一次性任务
• 资源限制/请求和健康检查
• 如果有官方 Kubernetes 安装文档/清单，也要提取应用运行时行为（引导管理员字段、外部端点/协议假设、健康探针、启动/初始化流程、迁移顺序）

步骤 2：推断元数据

推断并规范化：

• 应用名称、标题、描述、类别
• 官方 URL、gitRepo、图标来源（优先选择方形/圆形且以图标为主的资源，例如应用图标、网站图标或头像；避免使用矩形字标/文本 Logo）
• locale/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
• 多服务 Web 规范化：在 App 资源中公开经过验证的浏览器入口；仅在 API/网关/文档属于预期的公开接口时公开；工作进程保持私有，不配置 Service/Ingress
• URL 拓扑：面向浏览器的环境变量必须使用公开 HTTPS URL；除非应用明确要求公开回调，否则服务器间环境变量必须使用 Kubernetes Service FQDN
• 优先使用 scripts/compose_to_template.py --kompose-mode always 作为确定性的转换入口（为确保工作负载塑形可复现，需要 kompose）
• 当存在官方 Kubernetes 安装文档/清单时，执行双来源合并：以 Compose 作为拓扑基线，再根据官方 Kubernetes 指南调整应用运行时语义

步骤 5：应用数据库策略

• 数据库服务必须生成为 KubeBlocks Cluster 资源。请勿将 Compose 中的 PostgreSQL/MySQL/MongoDB/Redis/Kafka 数据库服务转换为原始 Kubernetes Deployment 或 StatefulSet 工作负载。
• PostgreSQL 必须遵循固定版本和结构要求。
• MySQL/MongoDB/Redis/Kafka 必须使用 references/database-templates.md 中的模板和密钥命名方式。
• 如果应用数据库引导需要初始化，请添加 DB init Job/initContainer。
• 对于自定义 PostgreSQL 数据库（非 postgres），init Job 必须在执行前等待 PostgreSQL 就绪，并以幂等方式创建目标数据库。
• 必须在实时数据库状态中验证关键应用兼容对象。对于应用在每次冷启动时都需要的兼容视图、旧版表/视图、索引、扩展、搜索路径和引导状态，请使用幂等的 initContainer 进行自愈。
• 一次性 init Job 可以创建初始数据库或植入初始状态，但应用启动门控必须直接验证最终数据库对象。将 TTL 到期的 Job 视为历史证据，并以数据库状态作为验收依据。
• 依赖应用迁移的 Worker、gateway 和后台服务必须等待所需表、迁移标记或应用专用就绪对象，而不能只等待数据库端口就绪。
• 如果就绪不依赖凭据，Redis 就绪探针或 initContainer 必须能够容忍经过身份验证的 Redis 响应，例如 NOAUTH 或 Authentication required。
• PostgreSQL 引导 shell 必须采用安全的引用方式。尽可能优先使用 shell 级存在性检查和简单 SQL 语句。对于 psql 变量插值，请使用单引号 heredoc 或 SQL 文件；如果守卫查询可以表达相同逻辑，请避免在内联 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：输出前验证

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

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

命名和元数据

• 模板的 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> 必须使用方形或圆形、以图标为主的图稿（例如应用图标、favicon、头像），不得使用矩形文字标志。
• 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.data.url 必须是从全新启动的 Sealos 中可成功访问的浏览器入口 URL。对于具有 safe-path、setup-path 或 entrance-path 行为的应用，请验证配置的路径和根路径，然后选择一个无需隐藏的先前导航即可支持登录或首次运行设置的 URL。
• SSR/Next.js/React 服务端应用不得将会渲染服务端异常的路径用作应用 URL 或 HTTP 探测路径。即使 HTTP 状态为 2xx/3xx，只要可见文本中出现 Application error、server-side exception、Internal Server Error 或 Unhandled Runtime Error，就应视为入口路径失败。
• 不得在应用资源中使用 spec.template。
• cloud.sealos.io/app-deploy-manager 标签值必须与资源的 metadata.name 相同。
• 对于受管应用工作负载，metadata.labels.app 标签值必须与资源的 metadata.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 相同；仅供 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 规则可以路由到不同的后端服务。
• 必须显式设置 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），并使用预期的默认值。
• 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，并与官方端点或命令保持一致。

与官方 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 }}。
• 注册表拉取 Secret 由 sealos-deploy 在运行时使用本地 gh CLI 凭证为私有 GHCR 镜像管理；请勿在生成的模板中公开原始注册表凭证输入。
• 所有容器都必须显式设置 imagePullPolicy: IfNotPresent。

存储

• 不要使用 emptyDir。
• 需要存储时，请使用持久化存储模式（volumeClaimTemplates）。
• 配置了 volumeClaimTemplates 的 StatefulSet 资源必须设置 metadata.labels.cloud.sealos.io/deploy-on-sealos: ${{ defaults.app_name }}，并且每个 volumeClaimTemplates[].metadata.labels.cloud.sealos.io/deploy-on-sealos 都必须设置为 ${{ defaults.app_name }}，以便 Template 跟踪和清理 PVC。
• PVC 请求必须 <= 1Gi，除非源规范明确要求更小的值。
• ConfigMap 数据键必须遵循 vn 命名规则（scripts/path_converter.py），包括 /、-、. 和其他特殊字符。
• 由受管理 Deployment/StatefulSet 工作负载挂载的 ConfigMap，其 metadata.name 必须与工作负载的 metadata.name 相同。
• ConfigMap 工作负载卷必须使用 <workload-name>-cm，并且每个 ConfigMap data 键都必须作为独立的 volumeMount 挂载，其 subPath 必须与该键完全相同。
• 避免在 command/args 中内联冗长的启动脚本或 heredoc；请将初始化脚本和启动脚本放入 ConfigMap 文件中，并使用简短命令调用。

环境变量和机密信息

• 非数据库的敏感值/输入使用直接的 env[].value。
• 业务容器必须通过 env[].valueFrom.secretKeyRef，从获批的 Kubeblocks 数据库机密信息中获取数据库连接字段（endpoint、host、port、username、password）；例外情况：如果 Redis 机密信息仅公开凭据，Redis 的 host/port 可以使用 Sealos Redis Service FQDN 和 6379；如果 MongoDB 机密信息仅公开凭据，MongoDB 连接 URL 可以使用 Sealos MongoDB Service FQDN 和 27017。
• 业务容器不得引用自定义的 env/volume 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> 或完整渲染后的 Service 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 或启动门控，以幂等方式创建或修复所需的视图、别名、索引、扩展、权限、角色搜索路径和旧版兼容对象。
• 托管应用主容器的 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 数据库服务绝不能使用。
• 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 列出并分类数据库。相关 Pods、Services 和 OpsRequests 应携带 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。
• 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 证明。

如需更多资源，只能切换到另一个允许的 limits 阶梯项，并根据该 limits 值重新计算 requests。

浏览器／远程桌面资源验证

对于浏览器、VNC、WebRTC 桌面、Xvfb、Selkies、noVNC、Kasm 或远程桌面类容器：

• 不要将简短的冒烟测试视为稳定最低内存值的证明。
• 使用全新部署验证内存，而不只是修补现有的热 Pod。
• 测试冷启动直至就绪、轻量级页面、真实／中等负载页面、交互式／搜索页面，以及冒烟测试后 60 秒的稳定性检查。
• 如果冒烟测试期间观测到的 cgroup 内存超过限制的 80%，则提升到下一个允许的 Sealos 内存阶梯值。
• 按照 Sealos 资源阶梯，根据限制值推导请求值。

示例：

• 错误：Chrome 在 512Mi 下通过了简短的冒烟测试，但内存达到 503Mi；将 512Mi 作为稳定的最低值不安全。
• 正确：提高到 1024Mi，将请求值设为 102Mi，然后重新运行冒烟测试和稳定性检查。

对于最大显示分辨率为 4K 的 Chrome + Xvfb + Selkies，至少使用：

• 限制：cpu=200m、memory=1024Mi
• 请求：cpu=20m、memory=102Mi

默认值与输入值

• defaults 用于生成的值（app_name、app_host、随机密码／密钥）。
• inputs 仅用于真正由用户提供的运维值（电子邮件／SMTP／外部 API 密钥等）。
• 当用户明确要求输入应用管理员凭据时，在 spec.inputs 中声明管理员用户名／密码，将其作为直接环境变量传入，并通过应用文档说明的引导或初始化路径应用这些值。数据库凭据应保留在 KubeBlocks 密钥中。
• 模板产物中的每个 ${{ inputs.<name> }} 引用，都必须在同一个 Template CR 中有对应的 spec.inputs.<name> 声明。
• inputs.description 必须使用英文。
• 对启动至关重要的 inputs[*].default 值必须符合应用文档所述的启动验证要求。对于有复杂度规则的管理员／引导密码，不要使用 ''、弱密码示例或单独的 ${{ random(n) }}，因为生成的字符可能不包含必需的字符类别；应在随机部分周围包含确定的必需字符类别，例如 "AppName@${{ random(16) }}!1"。
• 如果应用会在必需输入较弱或为空时退出，则应将输入默认值视为运行时契约的一部分。实时验证必须包含首次启动日志，以及使用生成的默认值进行的登录／设置流程。
• 对于二进制对象存储选项，使用布尔型输入（例如 enable_s3_storage），并通过 inputs.<name> === 'true' 进行测试。

验证命令

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

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）
8. 实时部署验收：sealos-deploy 创建应用后，在报告成功前，验证实际的 App URL、Web 应用的登录／设置流程、近期日志、预期数据库对象以及完整资源占用情况。

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/conversion-mappings.md
  • Docker→Sealos 字段级映射和边缘转换
• references/database-templates.md
  • 数据库模板、RBAC 结构和 Secret 命名模式
• 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/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；不要推断其他枚举值。
• business-env、对象存储和 DB-secret 策略应与 MUST 规则保持一致。
• 优先选择方形/圆形、以图标为主的 Logo 素材（应用图标/favicon/avatar），避免使用矩形文字商标或文字 Logo。
• 优先使用 Sealos 管理的 Ingress，而非捆绑的边缘代理：如果 Traefik 网关仅用作 Ingress/前置代理，且至少存在一个业务服务，则不要输出 Traefik 工作负载资源。
• 优先在 Sealos Ingress 中终止网关 TLS，而非在容器内终止 TLS：对于双端口 HTTP/HTTPS 工作负载，应保留 HTTP 服务端口，并移除冗余的 HTTPS/证书挂载，除非官方文档要求 HTTPS 后端。
• 绝不创建 template/<app-name>/README.md 或 template/<app-name>/README_zh.md；仅在模板架构要求时，于 index.yaml 中保留 README URL 引用。
• 出现冲突时，优先修正参考资料/示例，而不是增加例外。
• 如果目标应用有官方 Kubernetes 安装文档/清单，不要忽略；应使用这些资料在 Compose 默认值之外完善运行时语义。
• 如果项目提及 Frappe、ERPNext、HRMS 或 bench，生成应用工作负载前必须先加载 references/frappe-bench.md。