docker-to-sealos

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Docker to Sealos Template Converter

Docker转Sealos模板转换器

Overview

概述

Convert Docker Compose files or installation docs into production-grade Sealos templates. Execute end-to-end automatically (analysis, conversion, validation, output) without asking users for missing fields.

将Docker Compose文件或安装文档转换为生产级Sealos模板。端到端自动执行（分析、转换、校验、输出），无需向用户询问缺失的字段。

Governance and Rule Priority

治理与规则优先级

Use the following precedence to prevent rule drift:

```
SKILL.md
```
MUST rules (this file)

references/sealos-specs.md

and

references/database-templates.md

references/conversion-mappings.md

and

references/example-guide.md

If lower-priority references conflict with higher-priority MUST rules, update the lower-priority files. Do not keep conflicting examples.

遵循以下优先级避免规则偏移：

```
SKILL.md
```
中的必须规则（即本文档）

references/sealos-specs.md

和

references/database-templates.md

references/conversion-mappings.md

和

references/example-guide.md

如果低优先级引用文件与高优先级必须规则冲突，请更新低优先级文件。不要保留存在冲突的示例。

Workflow

工作流程

Step 1: Analyze input

步骤1：分析输入

Extract from Docker Compose/docs:

application services vs database services
volumes/config mounts/object storage requirements
ports, dependencies, service communication
env vars and secret usage
resource limits/requests and health checks
if official Kubernetes installation docs/manifests are available, also extract app-runtime behavior from them (bootstrap admin fields, external endpoint/protocol assumptions, health probes, startup/init flow)

从Docker Compose/文档中提取以下内容：

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

Step 2: Infer metadata

步骤2：推断元数据

Infer and normalize:

app name, title, description, categories
official URL, gitRepo, icon source
locale/i18n metadata

推断并标准化以下内容：

应用名称、标题、描述、分类
官方URL、git仓库地址、图标来源
本地化/国际化元数据

Step 3: Plan resources in strict order

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

Generate resources in this order:

Template CR
ObjectStorageBucket (if needed)
Database resources (ServiceAccount → Role → RoleBinding → Cluster → Job if needed)
App workload resources (ConfigMap → Deployment/StatefulSet → Service → Ingress)
App resource (last)

按以下顺序生成资源：

模板CR
ObjectStorageBucket（如有需要）
数据库资源（ServiceAccount → Role → RoleBinding → Cluster → 按需生成Job）
应用工作负载资源（ConfigMap → Deployment/StatefulSet → Service → Ingress）
App资源（最后生成）

Step 4: Apply conversion rules

步骤4：应用转换规则

Apply field-level mappings from

references/conversion-mappings.md

, including:

image pinning and annotation mapping
port/service/ingress conversion
env var conversion and dependency ordering
storage conversion and vn naming (
```
scripts/path_converter.py
```
)
service-name to Kubernetes FQDN conversion
for DB URL/DSN envs (for example
```
*_DATABASE_URL
```
,
```
*_DB_URL
```
), when Kubeblocks
```
endpoint
```
is host:port, inject
```
host
```
/
```
port
```
/
```
username
```
/
```
password
```
via approved
```
secretKeyRef
```
envs and compose the final URL with
```
$(VAR)
```
expansion
edge gateway normalization: when Compose includes Traefik-like edge proxy plus business services, skip the proxy workload and expose business services via Sealos Ingress directly
TLS offload normalization for Sealos Ingress: when a business service exposes both 80 and 443, drop 443 from workload/service ports and remove in-container TLS certificate mounts (for example
```
/etc/nginx/ssl
```
,
```
/etc/ssl
```
,
```
/certs
```
) unless official Kubernetes docs explicitly require HTTPS backend-to-service traffic
prefer
```
scripts/compose_to_template.py --kompose-mode always
```
as deterministic conversion entrypoint (require
```
kompose
```
for reproducible workload shaping)
when official Kubernetes installation docs/manifests exist, perform a dual-source merge: use Compose as baseline topology, then align app-runtime semantics with official Kubernetes guidance

应用

references/conversion-mappings.md

中的字段级映射规则，包括：

镜像版本固定与注解映射
端口/Service/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端口时，从工作负载/Service端口中移除443端口，并删除容器内的TLS证书挂载（例如
```
/etc/nginx/ssl
```
、
```
/etc/ssl
```
、
```
/certs
```
），除非官方Kubernetes文档明确要求后端到服务的流量使用HTTPS
优先使用
```
scripts/compose_to_template.py --kompose-mode always
```
作为确定性转换入口（需要
```
kompose
```
保证工作负载生成可复现）
当存在官方Kubernetes安装文档/清单时，执行双源合并：以Compose作为基线拓扑，然后将应用运行时语义与官方Kubernetes指导对齐

Step 5: Apply database strategy

步骤5：应用数据库策略

PostgreSQL must follow the pinned version and structure requirements.
MySQL/MongoDB/Redis/Kafka must use templates and secret naming from
```
references/database-templates.md
```
.
Add DB init Job/initContainer when application database bootstrap requires it.
For PostgreSQL custom databases (non-
```
postgres
```
), the init Job must wait for PostgreSQL readiness before execution and create the target database idempotently.

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

Step 6: Generate output files

步骤6：生成输出文件

Always produce:

```
template/<app-name>/index.yaml
```
```
template/<app-name>/logo.<ext>
```
when official icon is resolvable

始终输出以下内容：

```
template/<app-name>/index.yaml
```
当可获取官方图标时输出
```
template/<app-name>/logo.<ext>
```

Step 7: Validate before output

步骤7：输出前校验

Run validator and self-tests before delivering template output. If validation fails, fix template/rules/examples first.

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

MUST Rules (Condensed)

必须规则（精简版）

Naming and metadata

命名与元数据

Template
```
metadata.name
```
must be hardcoded lowercase; do not use
```
${{ defaults.app_name }}
```
.
Template CR folder name must match
```
metadata.name
```
.

Template CR must include required metadata fields (

title

url

gitRepo

author

description

icon

templateType

locale

i18n

categories

Template

spec.readme

must be

https://raw.githubusercontent.com/labring-actions/templates/kb-0.9/template/<app-name>/README.md

Template

spec.i18n.zh.readme

must be

https://raw.githubusercontent.com/labring-actions/templates/kb-0.9/template/<app-name>/README_zh.md

```
icon
```
URL must point to template repo raw path for this app on
```
kb-0.9
```
branch.
```
i18n.zh.description
```
must be written in Simplified Chinese.
Omit
```
i18n.zh.title
```
when it is identical to
```
title
```
.

categories

must only use predefined values (

tool

ai

game

database

low-code

monitor

dev-ops

blog

storage

frontend

backend

模板
```
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

）。

App resource

App资源

App resource must use
```
spec.data.url
```
.
App resource
```
spec.displayType
```
must be
```
normal
```
.
App resource
```
spec.type
```
must be
```
link
```
.
Never use
```
spec.template
```
in App resource.

cloud.sealos.io/app-deploy-manager

label value must equal resource

metadata.name

```
metadata.labels.app
```
label value must equal resource
```
metadata.name
```
for managed app workloads.
```
containers[*].name
```
must equal workload
```
metadata.name
```
for managed app workloads.

Application

Service

resources must define

metadata.labels.app

and

metadata.labels.cloud.sealos.io/app-deploy-manager

, and both labels must match

spec.selector.app

Component-scoped

ConfigMap

resources must define

metadata.labels.app

and

metadata.labels.cloud.sealos.io/app-deploy-manager

, and both labels must match

metadata.name

Application

Service

resources must use the same component name across

metadata.name

metadata.labels.app

metadata.labels.cloud.sealos.io/app-deploy-manager

, and

spec.selector.app

Application

Ingress

resources must use the same component name across

metadata.name

metadata.labels.cloud.sealos.io/app-deploy-manager

, and backend

service.name

Service
```
spec.ports[*].name
```
must be explicitly set (required for multi-port services).

HTTP Ingress must include required nginx annotations (

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

) with expected defaults.

When official application health checks are available, managed workloads must define
```
livenessProbe
```
,
```
readinessProbe
```
, and (for slow bootstrap apps)
```
startupProbe
```
, aligned with official endpoints/commands.

App资源必须使用
```
spec.data.url
```
。
App资源
```
spec.displayType
```
必须为
```
normal
```
。
App资源
```
spec.type
```
必须为
```
link
```
。
不要在App资源中使用
```
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
```
必须显式设置（多端口服务必填）。

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
```
，与官方端点/命令对齐。

Official Kubernetes alignment

官方Kubernetes对齐

If official Kubernetes installation docs/manifests are available, conversion must reference them and align critical runtime settings before emitting template artifacts.
When official Kubernetes docs/manifests and Compose differ, prefer official Kubernetes runtime semantics for app behavior (bootstrap admin fields, external endpoint/env/protocol, health probes), unless doing so violates higher-priority Sealos MUST/security constraints.

如果存在官方Kubernetes安装文档/清单，转换时必须参考这些内容，并在生成模板产物前对齐关键运行时配置。
当官方Kubernetes文档/清单与Compose存在差异时，优先采用官方Kubernetes的应用运行时语义（启动管理员字段、外部端点/环境变量/协议、健康探针），除非这样做违反更高优先级的Sealos必须规则/安全约束。

Images and pull policy

镜像与拉取策略

Do not use
```
:latest
```
.
Resolve versions with
```
crane
```
: prefer an explicit version tag (for example
```
v2.2.0
```
), and fallback to digest pin only when a deterministic version tag is unavailable.
Avoid floating tags (for example
```
:v2
```
,
```
:2.1
```
,
```
:stable
```
); use an explicit version tag or digest.
Managed workload image references must be concrete and must not contain Compose-style variable expressions (for example
```
${VAR}
```
,
```
${VAR:-default}
```
); resolve to explicit tag or digest before emitting template artifacts.
Application
```
originImageName
```
must match container image.
All containers must explicitly set
```
imagePullPolicy: IfNotPresent
```
.

不要使用
```
:latest
```
标签。
使用
```
crane
```
解析版本：优先使用明确的版本标签（例如
```
v2.2.0
```
），仅当无确定版本标签时才回退到摘要固定。
避免使用浮动标签（例如
```
:v2
```
、
```
:2.1
```
、
```
:stable
```
）；使用明确的版本标签或摘要。
托管工作负载的镜像引用必须是具体的，不得包含Compose风格的变量表达式（例如
```
${VAR}
```
、
```
${VAR:-default}
```
）；在生成模板产物前解析为明确的标签或摘要。
应用
```
originImageName
```
必须与容器镜像匹配。
所有容器必须显式设置
```
imagePullPolicy: IfNotPresent
```
。

Storage

存储

Do not use
```
emptyDir
```
.
Use persistent storage patterns (
```
volumeClaimTemplates
```
) where storage is needed.
PVC request must be
```
<= 1Gi
```
unless source spec explicitly requires less.
ConfigMap keys and volume names must follow vn naming (
```
scripts/path_converter.py
```
).

不要使用
```
emptyDir
```
。
需要存储的场景使用持久化存储模式（
```
volumeClaimTemplates
```
）。
PVC请求容量必须
```
<= 1Gi
```
，除非源规范明确要求更小的容量。
ConfigMap键名和存储卷名称必须遵循vn命名规则（
```
scripts/path_converter.py
```
）。

Env and secrets

环境变量与密钥

Non-database sensitive values/inputs use direct
```
env[].value
```
.
Business containers must source database connection fields (
```
endpoint
```
,
```
host
```
,
```
port
```
,
```
username
```
,
```
password
```
) from approved Kubeblocks database secrets via
```
env[].valueFrom.secretKeyRef
```
.
Business containers must not use custom
```
Secret
```
or
```
secretKeyRef
```
except approved Kubeblocks database secrets and object storage secrets.
Database connection/bootstrap may use Kubeblocks-provided secrets, and reserved Kubeblocks database secret names must not be redefined by custom
```
Secret
```
resources.
Env vars must be declared before referenced (for example password before URL composition).
Follow official app env var naming; do not invent prefixes.
When the application requires its public URL configured via a file-based config system (e.g., node-config
```
config/default.json
```
, PHP config files), create a ConfigMap containing the config file with the public URL set to
```
https://${{ defaults.app_host }}.${{ SEALOS_CLOUD_DOMAIN }}
```
, and mount it to the application's config directory. The ConfigMap must follow standard naming and label conventions.
For PostgreSQL custom databases (non-
```
postgres
```
), include
```
${{ defaults.app_name }}-pg-init
```
Job and implement startup-safe/idempotent creation logic (readiness wait + existence check before create).

非数据库敏感值/输入直接使用
```
env[].value
```
。
业务容器必须通过
```
env[].valueFrom.secretKeyRef
```
从已批准的Kubeblocks数据库密钥中获取数据库连接字段（
```
endpoint
```
、
```
host
```
、
```
port
```
、
```
username
```
、
```
password
```
）。
除了已批准的Kubeblocks数据库密钥和对象存储密钥外，业务容器不得使用自定义
```
Secret
```
或
```
secretKeyRef
```
。
数据库连接/初始化可以使用Kubeblocks提供的密钥，预留的Kubeblocks数据库密钥名称不得被自定义
```
Secret
```
资源重定义。
环境变量必须在被引用前声明（例如密码要在URL拼接前声明）。
遵循官方应用的环境变量命名规则；不要自创前缀。
当应用需要通过基于文件的配置系统设置公共URL时（例如node-config的
```
config/default.json
```
、PHP配置文件），创建包含配置文件的ConfigMap，将公共URL设置为
```
https://${{ defaults.app_host }}.${{ SEALOS_CLOUD_DOMAIN }}
```
，并将其挂载到应用的配置目录。该ConfigMap必须遵循标准命名和标签规范。
针对PostgreSQL自定义数据库（非默认
```
postgres
```
库），添加
```
${{ defaults.app_name }}-pg-init
```
Job并实现启动安全/幂等创建逻辑（就绪等待 + 创建前存在性检查）。

Database-specific constraints

数据库专属约束

PostgreSQL version:
```
postgresql-16.4.0
```
.
PostgreSQL API:
```
apps.kubeblocks.io/v1alpha1
```
.
PostgreSQL RBAC unified naming:
```
${{ defaults.app_name }}-pg
```
.

PostgreSQL RBAC requires

app.kubernetes.io/instance

and

app.kubernetes.io/managed-by

labels.

PostgreSQL role wildcard permission requirement remains as defined in current spec.

PostgreSQL cluster must include required labels/fields (

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 cluster must follow upgraded structure (

componentDef: mongodb

serviceVersion: 8.0.4

, labels

kb.io/database

and

app.kubernetes.io/instance

MySQL cluster must follow upgraded structure (

kb.io/database: ac-mysql-8.0.30-1

clusterDefinitionRef: apecloud-mysql

clusterVersionRef: ac-mysql-8.0.30-1

tolerations: []

Redis cluster must follow upgraded structure (

componentDef: redis-7

componentDef: redis-sentinel-7

serviceVersion: 7.2.7

, main data PVC

1Gi

, topology

replication

Database cluster component resources must use
```
limits(cpu=500m,memory=512Mi)
```
and
```
requests(cpu=50m,memory=51Mi)
```
unless source docs explicitly require otherwise.

Secret naming:

MongoDB:

${{ defaults.app_name }}-mongodb-account-root

Redis:

${{ defaults.app_name }}-redis-redis-account-default

Kafka:

${{ defaults.app_name }}-broker-account-admin

Do not use legacy naming outside supported exceptions.

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)
```
，除非源文档明确要求其他配置。

密钥命名规则：

MongoDB：

${{ defaults.app_name }}-mongodb-account-root

Redis：

${{ defaults.app_name }}-redis-redis-account-default

Kafka：

${{ defaults.app_name }}-broker-account-admin

除支持的例外情况外，不要使用旧版命名。

Baseline runtime defaults

基线运行时默认值

Unless source docs explicitly require otherwise, use:

container limits:
```
cpu=200m
```
,
```
memory=256Mi
```
container requests:
```
cpu=20m
```
,
```
memory=25Mi
```
```
revisionHistoryLimit: 1
```
```
automountServiceAccountToken: false
```

除非源文档明确要求其他配置，否则使用以下默认值：

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

Defaults vs inputs

默认值与输入

```
defaults
```
for generated values (
```
app_name
```
,
```
app_host
```
, random passwords/keys).
```
inputs
```
only for truly user-provided operational values (email/SMTP/external API keys, etc.).
```
inputs.description
```
must be in English.

```
defaults
```
用于生成值（
```
app_name
```
、
```
app_host
```
、随机密码/密钥）。
```
inputs
```
仅用于真正由用户提供的运营值（邮箱/SMTP/外部API密钥等）。
```
inputs.description
```
必须使用英文。

Validation Commands

校验命令

Run all checks before final response:

python scripts/path_converter.py --self-test

python scripts/test_check_consistency.py

python scripts/test_compose_to_template.py

python scripts/test_check_must_coverage.py

python scripts/check_consistency.py --skill SKILL.md --references references --rules-file references/rules-registry.yaml

python scripts/check_consistency.py --skill SKILL.md --references references --rules-file references/rules-registry.yaml --artifacts template/<app-name>/index.yaml

python scripts/check_must_coverage.py --skill SKILL.md --mapping references/must-rules-map.yaml --rules-file references/rules-registry.yaml

(CI / one-shot)

python scripts/quality_gate.py

(requires

template/*/index.yaml

by default; set

DOCKER_TO_SEALOS_ALLOW_EMPTY_ARTIFACTS=1

only for dev/debug without artifacts)

check_consistency.py

is registry-driven. Keep

references/rules-registry.yaml

in sync with implemented rules. Registry rule entries support

severity

and optional

scope.include_paths

metadata.

在最终响应前运行所有检查：

python scripts/path_converter.py --self-test

python scripts/test_check_consistency.py

python scripts/test_compose_to_template.py

python scripts/test_check_must_coverage.py

python scripts/check_consistency.py --skill SKILL.md --references references --rules-file references/rules-registry.yaml

python scripts/check_consistency.py --skill SKILL.md --references references --rules-file references/rules-registry.yaml --artifacts template/<app-name>/index.yaml

python scripts/check_must_coverage.py --skill SKILL.md --mapping references/must-rules-map.yaml --rules-file references/rules-registry.yaml

（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

元数据。

Output Contract

输出约定

When conversion is complete, provide:

brief conversion summary
target file path (
```
template/<app-name>/index.yaml
```
)
complete template YAML
key decisions only where ambiguity existed

转换完成后，提供以下内容：

简短的转换总结
目标文件路径（
```
template/<app-name>/index.yaml
```
）
完整的模板YAML
仅在存在歧义的场景下说明关键决策

Reference Navigation (Progressive Loading)

参考文件导航（渐进式加载）

Load only needed references for current task:

```
references/sealos-specs.md
```
- authoritative ordering, labels, App/Ingress/ConfigMap conventions
```
references/conversion-mappings.md
```
- Docker→Sealos field-level mappings and edge conversions
```
references/database-templates.md
```
- database templates, RBAC structures, secret naming patterns
```
references/example-guide.md
```
- examples and pattern walkthroughs (non-authoritative)
```
references/rules-registry.yaml
```
- machine-readable validation scope/rules list
```
references/must-rules-map.yaml
```
- MUST bullet to enforcement mapping (
```
rule
```
  or
```
manual
```
  ) for drift control

仅加载当前任务需要的参考文件：

```
references/sealos-specs.md
```
- 权威排序、标签、App/Ingress/ConfigMap约定
```
references/conversion-mappings.md
```
- Docker→Sealos字段级映射与边缘场景转换规则
```
references/database-templates.md
```
- 数据库模板、RBAC结构、密钥命名模式
```
references/example-guide.md
```
- 示例与模式演练（非权威）
```
references/rules-registry.yaml
```
- 机器可读的校验范围/规则列表
```
references/must-rules-map.yaml
```
- 必须条款与执行方式的映射（
```
rule
```
  或
```
manual
```
  ），用于偏移控制

Script Utilities

脚本工具

```
scripts/path_converter.py
```
- convert paths to vn names
- self-test support for regression checks

scripts/compose_to_template.py

deterministic compose/docs-to-template generator entrypoint

supports

--kompose-mode auto|always|never

(

always

is default) to reuse

kompose convert

workload shapes

emits
```
template/<app-name>/index.yaml
```

```
scripts/test_compose_to_template.py
```
- regression tests for compose conversion behavior
```
scripts/check_consistency.py
```
- registry-driven consistency validator
```
scripts/test_check_consistency.py
```
- regression tests for validator behavior
```
scripts/check_must_coverage.py
```
- validate MUST bullet coverage mapping against registry rules
```
scripts/test_check_must_coverage.py
```
- regression tests for MUST coverage validator

```
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
```
- 校验必须条款在注册规则中的覆盖映射
```
scripts/test_check_must_coverage.py
```
- 必须条款覆盖校验器的回归测试

Edge Policies

边缘场景策略

Never ask users for missing fields; infer from compose/docs and platform conventions.
Keep App resource in
```
spec.data.url
```
format; never use
```
spec.template
```
.
Keep App resource
```
spec.displayType: normal
```
and
```
spec.type: link
```
; do not infer alternative enum values.
Keep business-env, object storage, and DB-secret policy consistent with MUST rules.
Prefer Sealos-managed ingress over bundled edge proxies: if a Traefik gateway is only acting as ingress/front-proxy and at least one business service exists, do not emit Traefik workload resources.
Prefer gateway TLS termination in Sealos Ingress over in-container TLS: for dual-port HTTP/HTTPS workloads, keep HTTP service port and remove redundant HTTPS/certificate mounts unless official docs require HTTPS backend.
Prefer fixing references/examples over adding exceptions when conflicts appear.
If official Kubernetes installation docs/manifests exist for the target app, do not ignore them; use them to refine runtime semantics beyond Compose defaults.

永远不要向用户询问缺失字段；从compose/文档和平台约定中推断。
保持App资源使用
```
spec.data.url
```
格式；永远不要使用
```
spec.template
```
。
保持App资源
```
spec.displayType: normal
```
和
```
spec.type: link
```
；不要推断其他枚举值。
保持业务环境变量、对象存储和数据库密钥策略与必须规则一致。
优先使用Sealos托管的Ingress而非捆绑的边缘代理：如果Traefik网关仅作为Ingress/前端代理，且至少存在一个业务服务，则不要生成Traefik工作负载资源。
优先在Sealos Ingress中完成网关TLS终止而非容器内TLS：对于同时暴露HTTP/HTTPS端口的工作负载，保留HTTP服务端口，移除冗余的HTTPS/证书挂载，除非官方文档要求后端使用HTTPS。
出现冲突时，优先修复参考文件/示例而非添加例外。
如果目标应用存在官方Kubernetes安装文档/清单，不要忽略它们；使用这些内容优化Compose默认值之外的运行时语义。