olares-chart

将你的代码或任意项目部署到 Olares

统一入口： 加载 ../olares-shared/SKILL.md，了解套件路由、活动配置文件选择和平台入口。编写 — from-compose、lint、package — 完全无需 Olares，因此可以直接开始；当工作涉及上传、安装或其他部署步骤时，再应用共享身份验证门控。仅在确实需要登录、切换配置文件、存储令牌或恢复身份验证时，才加载其身份验证参考文档。

标志和语法以 olares-cli chart <verb> --help 为准。移植前请阅读共享的 Olares 平台模型：chart 决策取决于其中的存储、uid-1000、命名空间、中间件和版本语义。

针对特定 Olares 构建时，必须在首次构建镜像前获取目标节点架构，而不是等到部署时再获取。

移植目标为 Olares 1.12.6+；编写 manifest/chart 版本和依赖字段前，请加载版本管理。

适用场景

• 将 repo / docker-compose / 通用 Helm chart 转换为 Olares 应用，或验证 OlaresManifest；打包其镜像；配置存储 / 中间件 / 入口 / env / GPU
• 在你自己的 Olares 上部署 / 运行应用（market upload + install）；在 olares-doctor 找出 chart 自身导致的根因后，修改、lint 并重新部署 chart
• 使用官方基础应用提供生成 / 聊天模型服务，集成 llm-init，或将嵌入应用路由到合适的 Market 安装项

此技能负责修改你的 chart。olares-doctor 用于查找运行时根因，olares-market 用于管理已发布应用，olares-router 用于在模型应用运行后配置并调用模型，而 olares-publish 用于准备公开上架内容。

工作内容 — 两条轴线

移植应用并非固定的 from-compose → lint → deploy 流程，而是分别推动两条相互正交但彼此耦合的轴线达到各自的就绪状态，并在约束浮现时循环调整（镜像中固化的 uid/路径会限制 chart 的挂载 / 权限；部署约束也可能让你返回并重新构建镜像）。从应用当前所处的状态开始，而不是从固定的第 1 步开始。两条轴线都就绪后，部署到当前 Olares — 自动执行上传 + 安装 + 诊断循环。

• 打包 — 镜像： 将应用构建为可拉取且架构正确的制品。Olares 只拉取镜像，不负责构建。
• 部署 — chart： 通过 lint 的 OlaresManifest + 模板。from-compose 只是其中一种入口方式。

第一步（不是流水线）： 在打包和部署状态表中确定应用当前所处的位置 → 推进相关事项直至就绪，并在约束浮现时循环调整 → 部署到你的 Olares。

轴 1 — 打包（镜像）

Olares 从镜像仓库拉取镜像，从不从源代码构建，因此每个工作负载都必须引用可公开拉取且架构与节点相符的镜像。镜像工作由 Agent 驱动：使用 olares-cli cluster node list 确定 目标 Olares 节点的架构，然后询问开发者使用哪个镜像仓库（Docker Hub / ghcr），检查 Docker 是否可用并已登录，然后自行构建并推送——只有在尚未通过身份验证时，才需要手动执行 docker login（参考）。构建时使用目标节点的架构（单架构），绝不要使用开发主机隐式采用的默认架构；多架构仅用于发布。

目标架构是构建输入，因此不能延后确定。 spec.supportArch 说明的是 chart 声称支持什么；没有任何步骤会打开镜像来检查它实际上是什么架构。因此，错误猜测会在构建、推送和 lint 后依然存在，直到集群中出现 exec format error 才会暴露——而在 Apple Silicon 上，未确定目标时会悄然默认为 arm64。查询节点，或让开发者说明架构；两者都没有时，应当询问，不要猜。 只有尚未部署的 chart 才不需要指定目标。

打包状态	操作	就绪条件
没有 Dockerfile（只有源代码）	编写 Dockerfile，然后构建并推送	—
有 Dockerfile，但没有可拉取的镜像	构建并推送（Docker Hub 或 ghcr）	—
已有可拉取的镜像	检查其架构；如果与目标 Olares 节点不符（olares-cli cluster node list），则重新构建	每个工作负载都有可拉取且架构匹配的镜像

轴 2 — 部署（chart）

目标是通过 lint 的 Olares chart。from-compose（kompose）只是其中一种入口方式——纯代码仓库、通用 Helm chart 或已有的 Olares chart，都可以从不同起点开始（见下方状态表）。本地编写（from-compose / lint / package）无需登录。

部署状态	操作	就绪条件
只有源代码（没有 compose）	根据代码编写 docker-compose（compose.md）	—
有 docker-compose	执行 chart from-compose，然后完善（from-compose.md）	—
通用 Helm chart（没有 OlaresManifest）	手动编写 OlaresManifest.yaml 并完善（跳过 from-compose）	—
已上传到 Olares，但没有保留本地副本	执行 market download <app> 并解压 .tgz，然后完善（olares-market，见 charts → chart 管理）	—
已有 Olares chart	直接进行验证	通过 chart lint 的 chart

部署到你的 Olares（完成步骤）

两个轴都就绪后 → 自动部署到当前 Olares。lint 证明 chart 在结构上有效；它不能证明应用能够拉取镜像、正确连接中间件并进入 running 状态——这需要通过部署循环验证。**lint 通过后，无需询问即可继续：**检查登录状态 → 验证 spec.supportArch 与 cluster node list 的结果有交集 → 打包 → market upload → market install -s upload --watch → 失败时获取日志 → 诊断 → 修复 chart 并重新运行 lint → 重试。架构导致的上传拒绝会一直存在，直到清单或镜像发生变化；绝不要对未更改的包递增版本后重试。只有当配置未通过 olares-shared 的身份验证就绪检查（invalidated / never）时才停止并询问——logged-in / expired 都可以继续。完整流程见：references/olares-chart-deploy.md。

部署到你自己的 Olares 时，只要 lint 通过，元数据可以保持为占位内容；但仍需完善功能（存储 / 中间件 / 入口）。

关注点索引

from-compose 会生成一个即使能通过 lint、也可能并非正确 Olares 应用的骨架。使用此索引，只加载当前移植工作涉及的参考资料。原有的全部 18 项关注点均已涵盖。

每次移植

触发条件	阅读内容
构建或选择每个工作负载镜像	镜像
确定进程 uid，然后确定挂载卷的所有权——这是两个独立问题，见下文	运行身份
映射持久化、入口、元数据和工作负载副本	清单
映射配置和平台值	环境变量，然后仅在需要时阅读默认值或系统值
处理密码、API 密钥或生成的密钥	机密
设置清单／chart 版本和依赖项	版本管理
chart 更改后进行验证	检查
在目标 Olares 上验证 chart	部署

清单参考将四项关注点分别介绍：存储、入口／端口、工作负载／副本和元数据。加上镜像、运行身份、环境变量、机密、版本管理、验证和部署，这些就是每次移植都要检查的 11 项关注点。

运行身份：回答两个问题

Q1（进程最终使用的 uid）和 Q2（进程写入的目录归谁所有）是相互独立的：每种 Q1 答案都可以与任一种 Q2 答案搭配。先回答两个问题，再打开运行身份参考了解具体做法。

问题	答案	操作
Q1 镜像的有效 uid 是什么？	1000	设置 spec.runAsUser: true；对于非主工作负载，还要自行设置 securityContext.runAsUser: 1000
	0，且入口点通过 PUID/PGID 降权	不要设置 spec.runAsUser，设置 PUID=PGID=1000，并验证最终进程
	0 且保持 root 身份，或任何其他非 1000 的 uid	尝试设置 securityContext.runAsUser: 1000；如果应用无法正常运行，则重建镜像
Q2 应用是否会写入用户空间挂载？	否	完成
	是	添加一个非递归的 init-permissions initContainer（使用 beclab/ 镜像，并在容器级别设置 runAsUser: 0）——如果采用 PUID/PGID 方案，请先查看启动日志，因为该入口点通常已经处理了权限

两条红线：运行时绝不要执行 chown -R，也绝不要显式设置 root securityContext——beclab/ 权限 initContainer 是唯一例外。

条件适用

触发条件	阅读内容
Compose 包含数据库／队列，或需要应用依赖项	中间件和依赖项
CUDA 镜像、模型配置或共享模型缓存	GPU 和模型
生成／聊天、自定义 llm-init 或嵌入服务	模型路由、模型操作、自定义集成
模型应用已在运行，但提供的内容不正确	olares-router — 阅读其中的卡片，而不是 chart
GPU／加速器调度模式或资源范围	加速器
应用必须运行 Docker 或 Compose	DinD
一个高负载后端为多个用户提供服务	共享后端
运行中的应用需要易记的路由或自定义 FQDN	自定义 URL

完整的组装顺序见工作流。

动词索引

olares-cli chart 的唯一子命令（权威来源：--help）。上文其他内容均与 docker 或同级技能有关。

动词	功能	触发时阅读
from-compose（别名 init）	将 kompose-convert compose 文件转换为 Olares chart 框架	from-compose.md
lint	使用 Market 摄取流水线验证 chart 目录或 .tgz	lint.md
package	将 chart 目录打包为用于上传的 <name>-<version>.tgz（类似 helm package，无需 helm 二进制文件）	workflow.md（D4）

特殊移植模式

此技能的大部分内容都假设应用是带有 HTTP 入口的 Web 应用。如果上游项目不符合这种情况，请先匹配已知模式；如果仍不确定，请参考官方移植的解决方案。

• 无头 CLI / 服务（无 Web UI） — 没有可指向入口的 GUI：添加 web-terminal sidecar 作为可见入口，并将 API/MCP 端口作为 invisible 内部入口公开。→ archetype-headless.md
• GUI 桌面应用（通过浏览器串流） — 没有 Web UI 的原生 Linux 桌面应用：将其封装在 web-desktop 基础映像中（默认使用 Selkies，旧硬件或静态 UI 使用 KasmVNC），将一个可见窗口入口指向 HTTP :3000，并根据 .Values.deviceName 控制是否启用可选的 iGPU/VAAPI 加速。→ archetype-gui.md
• 如果没有符合条件的文档化模式，请先检查 beclab/apps 中当前仍活跃的移植项目，再做判断：

gh search code --repo beclab/apps <keyword>      # find charts using a pattern (e.g. type: application, accelerator, appCommon)
# then browse https://github.com/beclab/apps/tree/main/<app> — its OlaresManifest.yaml + templates/

跳过可能造成误导的参考资料：

• OAC 根目录中带有 .suspend（或 .remove）控制文件的应用 — 已暂停分发或不再分发；不是当前可靠的模式。
• 通过 spec.subCharts[].shared: true + options.appScope.clusterScoped: true + appRef 表示共享的共享 / 集群范围 chart（ollamaserver/ollamav2 这种结构）。请从 apiVersion: v3 应用中复制共享应用模式，而不要参考这些应用。参见 shared.md。

注意事项（lint 无法检测的问题）

lint 会验证结构，而不是 Olares 的正确性。除了上方关注事项表中的内容，以下盲点也可能造成问题，且完全由你负责：

• metadata.name 必须与 chart 文件夹和 Chart.yaml 中的 name 一致，并符合 ^[a-z][a-z0-9]{0,29}$。确保 metadata.appid 与 metadata.name 相同（from-compose 会设置它）。重命名时要同时更改这四处。lint 和 market upload 都不要求设置 metadata.appid——不包含该字段的 chart 仍可通过 lint 并成功上传，平台会以确定性的方式填入其值。但还是要设置它：一个缺失、由其他部分代为决定的字段，会让你之后误读；值不匹配则比缺失更糟。它不会决定入口主机：平台会根据应用名称推导入口主机，因此请从 settings apps list 的 URL 列读取实际值，而不要自行计算。
• **集群上传要求 spec.supportArch 至少与一个当前节点的架构相符。**查询 olares-cli cluster node list；确保引用的镜像支持相同的目标架构。如果上传报告 architecture_incompatible，请修复并重新打包后再试。如果报告 cluster_arch_unavailable，请保持软件包和版本不变，并等待节点发现恢复。
• 声明的 .Values.userspace.appData/appCache/userData 挂载必须包含对应的 permission 字段，否则应用数据交叉检查会失败。
• hostPath 卷与滚动更新不兼容——请用上方的 userspace 卷替换主机挂载。
• 入口代理会将每个请求的时长限制为 options.apiTimeout 秒（默认为 15s）——即使 Pod 状态正常，较长的大模型流、较大的上传或较慢的报告仍会在入口处被中断（504 / 连接关闭）。设置 options.apiTimeout: 0 可禁用此限制，也可设置较大的有限值；负数并不表示“无限制”（会回退到 15s）。请参阅 Manifest 优化领域。

安全与升级处理

• lint 通过后，部署/调试循环就属于已授权的 chart 任务：安装、升级、重启、卸载以及全新重装该应用，无需每次重新确认。每次迭代都询问，会把一个循环变成一场面试。
• 遇到登录问题、缺少 registry 凭据、目标不明确，或任何超出该应用任务范围的情况时，请停止并交还处理。
• 用户未指定的 chart 属于他人的应用。可以查看，但不要覆盖部署。
• 绝不要将 registry 密码放在命令参数中——请使用 docker login --password-stdin 或凭据助手。