• 云原生
• 后端
• 运维

本文基于 Olares（Terminus）开源仓库的发布技能文档，系统讲解应用从"本地跑通"到"进入公开 Olares Market"必须满足的全部要求。Olares Market 是无审核制（permissionless）的应用市场——没有评审委员会决定你的应用是否"够好"，自动化检查（olares-cli chart lint与 GitBot）只审查形式，不评判实质。文章将上架要求按违背后果分成硬门槛（Hard gates）、功能可达性（Functional reach）、上架质量（Listing quality）三档，逐项给出字段规则、源码实现证据与检查清单，读完即可对照自己的OlaresManifest.yaml完成一次可上架、可安装、值得被安装的公开提交。

按后果分层，而不是按复选框分层

在开始填写字段之前，先建立正确的心理模型：Olares Market 的要求不是一张扁平清单。把它当作一张清单，正是许多提交者觉得上架"比实际更重"的原因。正确的组织方式是按"搞错之后会发生什么"来分层：

只有第一档会真正挡住你。这意味着：一个最小但诚实的上架可以先上线、再逐步改进——这条路径是 Google Play 这类有审核的商店不提供的，也正是向 Olares Market 发布比看上去更轻松的主要原因。

从源码看，lint与 GitBot 的分工非常清晰：chart lint 命令 直接调用 oac.Lint 跑完整管道：文件夹布局检查、OlaresManifest.yaml结构与跨字段校验、helm dry-run + 工作负载完整性检查、资源限额检查、以及Chart.yaml与 manifest 的版本一致性检查。而 PR 阶段的文件夹/标题/分类校验由chartfolder.CheckWithTitle承担（见后文），这正是"本地 lint 干净但 PR 仍被拒"的根源。

Tier 1：硬门槛

硬门槛由两道闸门强制执行：本地/CI 的olares-cli chart lint，以及 PR 合并时的 GitBot。两道闸门检查的内容不重叠，必须分别满足。

由olares-cli chart lint强制执行

以下字段在 validateAppMetaData 中被逐一校验，缺一不可：

源码层面的细节值得注意：metadata.icon的校验规则是isHTTPURL（"must be a valid http(s) URL"），metadata.title与metadata.name都限定 1–30 字符，metadata.version走isSemver。lint只校验 icon URL 的形式，不校验它能否解析——一个拼错域名的主机可以顺利通过lint，然后在 Market 里显示为一张坏图。因此提交前务必确认 URL 真的能打开。

lint的退出码就是信号：0表示通过（打印<path>: OK），非零表示失败。可对单个文件或.tgz运行，也支持按需跳过单项检查（详见 chart lint 参考）。

由 GitBot 在 PR 阶段强制执行

GitBot 检查的是机械性策略，它不验证产品质量、截图真实性或安全声明——这些由提交者自负。PR 阶段强制的内容包括：

• 文件夹名：仅小写字母和数字，不允许连字符（-），不超过 30 个字符
• PR 标题格式：[PR 类型][文件夹名][版本] 标题内容
• PR 标题中的版本段必须等于Chart.yaml的version
• 文件范围：只允许改动 PR 标题声明的 chart 文件夹下的内容
• 不能有重复的开放 PR（同一 chart 文件夹只能有一个 Open/Draft PR）
• OAC 根目录不得有游离的.suspend/.remove控制文件
• metadata.categories必须合法——这是唯一一个 GitBot 做枚举校验、而本地lint不做的元数据字段

最后一条是本地提交最容易踩的坑：一个本地lint完全干净、本地也能跑起来的 chart，可能带着 GitBot 会拒绝的 stub categories 上 PR。完整的提交流程细节在父级 SKILL.md。

源码可以印证 GitBot 的校验范围。PR 流程使用的CheckWithTitle（folder.go）同时检查四件事：

1. 文件夹名、Chart.yamlname、PR 标题中的文件夹段、metadata.name四者一致；
2. metadata.version、Chart.yamlversion、PR 标题版本段三者一致；
3. metadata.categories的每个值都落在固定枚举内（AI/Blockchain/Utilities/Social Network/Data/Entertainment/Productivity/Lifestyle/Developer/Multimedia，见 validCategories）；
4. 文件夹名不在保留名单上（user/system/space/default/os/kubesphere/kube/kubekey/kubernetes/gpu/tapr/bfl/bytetrade/project/pod，见 isReservedWord）。

文件夹名的合法性正则^[a-z0-9]{1,30}$定义在 isValidFolderName。这些规则在 oac 的 README §3.5 中有完整说明：CheckConsistency校验目录名 == Chart.yaml name == metadata.name、metadata.version == Chart.yaml version；CheckWithTitle则额外加上 categories 枚举与保留字检查，且仅在 PR 流程使用、不在根包暴露。

Tier 2：功能可达性

这一档没有任何检查会验证这些声明是否为真：lint要求spec.supportArch存在且格式良好，但没有任何检查会打开镜像看实际构建了什么。它们决定的是"点击 Install 的用户，应用到底能不能装起来"。

supportArch与镜像平台必须双向一致：声明了你没有构建的架构会安装失败；漏掉你确实构建了的架构，则会把这部分用户挡在门外（应用对他们不可见）。

从源码看lint对spec.supportArch的校验非常严格（validateAppSpec）：

• Required：缺失即报spec.supportArch is required；
• 长度规则：空列表报spec.supportArch must contain at least one item；
• 每个元素必须是"amd64"或"arm64"（validateSupportArchEntry）；
• 不允许重复项（uniqueSupportArches）。

而spec.accelerator（YAML 键名；lint错误信息里叫spec.resources，是同一个东西）与supportArch之间存在模式 → 架构的交叉校验，实现在 resources.go 的 specResourceCrossFieldRules 中。模式到必需架构的映射表定义在 modeArchRequirement：

交叉校验的规则是：声明了某个 mode，其对应的架构必须出现在spec.supportArch中，否则报spec.resources[i]: mode=<mode> requires spec.supportArch to contain "<arch>"。此外：只有独立显卡模式（nvidia/amd-gpu/intel-gpu）允许声明requiredGPUMemory/limitedGPUMemory显存配额字段，统一内存/SoC 模式声明这些字段会直接lint失败。本地部署时只声明本节点实际广播的 mode（节点通过gpu.bytetrade.io/<mode>标签广播能力）；公开上架时则要为上游真正支持的每个后端声明一个 mode 条目（每个后端通常对应一个独立的镜像/构建变体）。完整模式表与本地 vs 上架的取舍见 accelerator 参考。

镜像侧的执行依据：Olares 通过拉取镜像安装应用，从不从源码构建，所以每个工作负载都必须引用"目标节点架构可公开拉取"的镜像。查询目标架构用olares-cli cluster node list（该命令输出含 ARCHITECTURE 列，实现见 node list）。多架构构建在发布到公开 Market 时才要求：docker buildx build --platform linux/amd64,linux/arm64，并与spec.supportArch: [amd64, arm64]匹配。详细的可拉取性验收（构建、inspect 架构、匿名拉取验证）见 镜像参考。

一个真实的对照示例是仓库测试数据里的 codex manifest：spec.supportArch声明amd64与arm64两项，metadata.icon使用https://app.cdn.olares.com/appstore/codex/icon.png形式的合法 URL，spec.developer/website/sourceCode/submitter/locale等 Tier 3 字段齐全，可以作为上架清单的样板参照。

Tier 3：上架质量

这一档没有任何机制强制。它决定的是"你的上架是被安装，还是被划过去"。

关于文案的几个硬性约定：metadata.description用一句短语回答"What is this?"，句首用具体产品类别名词短语（如 "A web app for ..."），句尾不加标点；fullDescription开头段落让非专业人士也能看懂输入、动作与结果，避免把 chart 实现细节（init 容器、UID、探针、内部接线）写成特性；upgradeDescription前三行给出最重要的变更摘要，只收录对用户可见的行为变化，chart diff 只是证据而非发布文案。本地化时只有四个字段可翻译（metadata.title/metadata.description/spec.fullDescription/ 有条件的spec.upgradeDescription），且必须从已批准的英文源翻译，不能从另一种译文转译；Olares、LarePass、Vault等专名、代码、URL、版本号一律保持原样。

因为这一档完全不被强制执行，它也是最安全可以推迟的内容：先上线，再改进。图标则例外——metadata.icon是唯一被平台强制要求的 listing 资产（chart lint没有它就失败），规格为 PNG/WEBP、256x256、≤512 KB，且必须是项目真实的标志（从上游仓库或官网抓取，绝不可 AI 生成），制作流程见图标参考。

Pre-PR 门禁清单

提交 PR 之前，逐项确认：

• Tier 1 干净：olares-cli chart lint ./<app>通过；文件夹名合法；categories对 OS 1.11 和 1.12 都使用被接受的取值
• Tier 2 诚实：镜像为spec.supportArch中的每个架构构建过，且没有漏掉实际构建的架构
• Tier 3 尽力而为——其中没有任何一项会阻塞你
• owners文件：chart 根目录下存在无扩展名的owners文件，内含提交者的 GitHub 用户名
• 版本：metadata.version=Chart.yaml的version；更新时两者一起 bump
• 文案：英文源文案事实准确、面向用户；upgradeDescription仅在确有升级说明时存在，且不包含 chart 维护日志
• 语言：根 manifest 与英文 locale 的漂移已解决；spec.locale与完整 locale 文件匹配；受保护 token 与 Markdown 结构完好
• 每次编辑后重新lint，并确认应用在一台真实 Olares 上仍能安装到running

然后进入父级 SKILL.md 的提交流程。

从"本地能跑"到"公开上架"

完整路径分六步：

1. 确认本地安装已到running（通过 olares-chart 部署流程）。
2. 修复 Tier 1——这是那份最短的清单，也是唯一能拒绝你的清单。
3. 重建多架构镜像（当前是单架构的话），然后把spec.supportArch改成与之匹配。
4. 定稿事实性的英文 Manifest 文案，然后只本地化已声明的目标语言；补充你有证据和素材的其余 Tier 3 材料。
5. 重新lint→package：

   olares-cli chart lint ./<app> olares-cli chart package ./<app>

   package把目录打成<name>-<version>.tgz，布局与helm package一致，可直接被chart lint与market upload接受（实现见 package 命令）。注意：PR 提交的是文件夹而非.tgz，打包是可选的。

6. 开 PR。不要跳过重新验证：一个本地能跑的 chart 仍可能携带 GitBot 会拒绝的 stub categories。

功能层面的打磨（存储 / 中间件 / entrances）应当已在本地阶段完成——通常这里不需要改动。

付费上架（pay-to-download）补充

付费应用 =公开 Market 应用+price.yaml+VERIFIABLE_CREDENTIAL许可证校验。它不是对普通上架要求的替代，而是叠加：一切公开分发的要求仍然适用，额外增加两项 chart 级配置与一次性的链上身份注册（RSA 公钥绑定到你的 Olares ID，注册是 Optimism 链上写入、消耗小额 gas）。仅支持"付费下载"；应用内购买与订阅尚未实现。完整流程见付费应用参考，入口在父级 SKILL 的 paid-app route。

延伸阅读

• 父级发布技能 SKILL.md：整体心智模型、决策与安全边界
• 提交流程：PR 到 beclab/apps：PR 标题格式、GitBot 标签含义、生命周期管理
• Manifest 文案撰写 与 本地化
• 图标、上架图片 与 图片版式
• chart lint 参考、镜像参考、accelerator 参考

• 云原生
• 后端
• 运维