Vibe打金计划（1）： 小白学打包应用

### 如果你懂技术，没有什么必要读这篇文章。 请直接前往：[懒猫微服文集推荐](https://developer.lazycat.cloud/wangjishanren-lazycat-developer-startup.html) 阅读 @忘机山人 大佬的专业文章。 其中的这两篇： * [懒猫微服开发篇（零）：上架应用需要哪些知识](https://mp.weixin.qq.com/s?__biz=MzI3NTY4MjcxNg==&mid=2247486919&idx=1&sn=8c7c8d10c02574346eec147e526cede2&chksm=eb004934dc77c02216bb8047e665ff716ad7de0f6fd1e28243a46f4b83d5e9cdf1eafbf82144#rd) * [懒猫微服开发篇（一）：懒猫微服全栈上架指南，一步打包，一键发布](https://mp.weixin.qq.com/s?__biz=MzI3NTY4MjcxNg==&mid=2247487023&idx=1&sn=2b40ee494b6e1ffe09473df5362eb21b&chksm=eb004adcdc77c3ca8204cdc4f9cff5854c756de6c33468dd5f26c35d735dcb57e6de0c381908#rd) 已经能很好地对打包应用进行指导。 --- 而本文的内容，主要是从“技术小白”或我这样的外行纯“Vibe Coder"角度出发的。 因为在开发大神们（包括官方的大神们）的眼中，技术上有太多的“常识”。很多技术内容对于“他们”可能就是一个关键词而已，而对于“我们”这些外行却是要去翻查尝试和学习很久的，甚至AI都解释不清。再加上经常在其他的常识上踩坑，“我们”的前进之路可能会比“他们”要艰难得多。 而官方文档，为了简洁全面，总是把尽可能多的可能性、极端情况与各种高端应用都写进去，对于基础知识比较少的“我们”来说，会显得很复杂，而且经常会被误导，以为一定要用某种高端的方式才能实现某些其实很基础的功能。 本文也可以当作是小白的我对于忘大佬攻略或官方文档的**学习笔记**，我也会补充一些我做为小白踩到的坑。 另外，我会尝试一边写这篇攻略，一边在AI的协助下整理进一步的提示词和资料，以达到让AI可以指导我们打包的目的，在此依然会用到Refly。 https://appstore.lazycat.cloud/#/shop/detail/iamxiaoe.lzcapp.refly 另外会用到这个神器： https://appstore.lazycat.cloud/#/shop/detail/in.zhaoj.devaihelper --- # 基础信息 首先我向神器开发者文档助手询问了如下问题： >我想了解懒猫应用的打包机制和应用包的执行流程 得到的答复是： >基于提供的资料，懒猫应用的打包机制和应用包执行流程如下所述，每个陈述均严格引用资料原文： 懒猫应用的打包机制涉及准备特定文件：包括 lzc-build.yml（构建脚本）、lzc-manifest.yml（应用元信息配置）和图标文件（如 icon.png），这些文件需放置在同一目录下；随后使用 lzc-cli project build 命令构建输出 .lpk 安装包文件[3]。 资源文件（如模型文件）可打包到镜像或 .lpk 中：若资源文件较小（<200M），可直接打包到 .lpk 中，应用运行时通过只读目录 /lzcapp/pkg/content 访问；但资源文件不能放在 /lzcapp/ 目录下，因该目录在运行时会被覆盖[1]。 在 devshell 开发模式下，默认不会打包 lzc-build.yml 中指定的 contentdir 内容；如需打包，需使用 lzc-cli project devshell --contentdir 命令显式启用[1]。 应用包安装流程：通过 lzc-cli app install <lpk文件> 命令安装 .lpk 包；安装后，包内容会被解压到微服系统的 /data/system/pkgm/apps/$appid 目录下[2]。 执行前渲染机制：安装后，在应用启动前，系统根据运行时信息（如用户ID）动态渲染 manifest.yml 文件：使用 Go 的 text/template 模板引擎，结合内置参数（如用户参数、系统域名等），将渲染结果输出到 /data/system/pkgm/run/appid 目录；渲染支持函数如 stable_secret 生成稳定密码[2]。 最终运行流程：渲染后的 manifest.yml 被转换为 Docker 规范，系统据此启动并运行相关容器；重启或多实例场景下会重新渲染[2]。 由于神器的系统提示可能是要求严格引用资料，所以这些内容都是在开发者文档中可以找到的，必然是精确的内容。但是其中的渲染动态manifest部分，虽然看上去应该有用，但其实以我目前的水平还用不到，只属于“不明觉厉”的程度。 --- # AI分析 由于担心会干扰到AI的理解，于是我会只选用基础的部分喂给AI。 直接上画布：  提示语： >请仔细理解和分析附件中的文档和链接内容，总结一份关于懒猫微服应用的打包技术要点文档，要求准确细致，关键技术点必须使用原文本，只在逻辑顺序调整、阅读引导和分析解释时使用合适的语言能力 在我整理了许多关于打包知识点之后（官方文档节选、官方标准链接、攻略链接及节选、示例代码、我自己写的理解思路），我把它们统统喂给了AI，由Claude Sonnet 4和GPT4.1分别分析之后，得到了这样两篇文档： * [懒猫微服应用打包技术要点Claud版](https://refly.ai/share/doc/doc-nlfc76asbl4oa3v6cnrws12i) **注意：AI生成文档不建议做标准参考** * [懒猫微服应用打包技术要点GPT版](https://refly.ai/share/doc/doc-nlfc76asbl4oa3v6cnrws12i) **注意：AI生成文档不建议做标准参考** 大致浏览下来，虽然结构上还不尽人意，但是由于我在提示中要求严格遵照原文，所以应该不会出什么大的错误。(如果某些技术大佬或官方大佬有空，不妨帮忙校正一下，但从结构和内容来说价值似乎不大。) --- # 验证 我把这个生成的综合文档，又喂给Refly中另一个画板，这个画板中我搭建了一个懒猫应用，具体的细节我会在下一章中详细说明。在这里，我只是希望AI帮我写打包文件和启动脚本，用以作为对上面文档的验证。 提示词 >请根据附件中的打包技术要点，帮我准备打包这个应用的相关配置文件以及启动脚本  得到了这样两个指导文档： * [打包指导Claude版](https://refly.ai/share/doc/doc-oiqg93zt2cm3vvwmid0l25mn) **注意：AI生成文档不建议做标准参考** * [打包指导GPT版](https://refly.ai/share/doc/doc-iy3lvkqal4ra92nvc5ohqp1f) **注意：AI生成文档不建议做标准参考** 看下来，还是理解错误了不少，比如路由并没有写好，比如依赖里装了php（我之前的喂上的项目是node的）。 真正的打包文件可能需要细调，或直接使用前文的神器：开发者文档AI助手 但是，看上去AI似乎对于打包流程已经能够有正确的理解了，如果我在下一个项目的开发前就导入这些资料，也有可能会得到更好一些的结果。 任务完成度，可以说70%吧，至少对我这样的小白来说还是不错。 孔子曰：遇事不决不能全靠AI。在这个过程中我自己也学到了很多，所以这项工作还是有价值的。 --- # 我理解的整个流程 我在前文给AI喂料的时候写的这个，全是基于我的摸索和理解，不一定正确，还往各位一定不要相信我。 ## 1.功能开发 选用适合的技术栈，后端主推Node.js / PHP，前端主推React.js / Vue.js。(这句是写给AI看的，是我的技术偏好) 其他技术在必要时也都可以使用，也可以直接使用Docker镜像。 ## 2.Devshell调试 （略） ## 3.编写lzc-build.yml lzc-build.yml 定义打包配置参数。 在打包前会自动运行buildscript所指定的脚本，可进行打包前的依赖安装，模板化构建，以及其他打包前需执行的文件处理等。 ## 4.编写lzc-manifest.yml lzc-manifest.yml 定义应用元信息配置。其中最重要的是application.route。 ## 5.使用lzc-cli打包 使用 lzc-cli project build 将项目打包到lpk包中 程序首先会运行buildscript中的脚本（可能是bash命令，也可能是.sh文件） 然后将文件打包进一个.lpk包 ## 6.安装到懒猫微服 使用lzc-cli app install将lpk安装到懒猫微服中 ## 7.运行应用 在懒猫微服客户端打开应用，系统会直接访问lzc-manifest.yml里设置的application.route中/所指定的路由。 如果是exec:格式的路由，比如: - /=exec:// {端口},{脚本} 系统会在运行指定的启动脚本后访问指定的端口，所以对于应用后端的初始化及启动命令可以放在这个脚本里。 其实在你的应用安装好后，它就自动开始运行了，所以安装依赖和初始化是在你点开图标之前就已经在做了，所以新安装的应用启动通常要稍久一点。 --- # 其他 最后抛开上面的流程，也抛开官方技术，说点我自己这个小白（白痴的白）走的弯路： 1.路由：我一开始完全没有理解路由机制，就从参考样例开始折腾，抱着搞网站的思路，非要搞一个前端和一个后端的感觉，但其实绝大多数项目并不需要前后端分离成两个路由。 2.启动脚本：我在devshell里尝试的node应用没问题了，打包应用时突然卡住了，要怎么搞npm run start啊？好像不会自动启动……后来才搞清楚一下要搞个run.sh做启动脚本（也可能有自启机制？），而且我把启动脚本放在某个文件夹中，结果总是说找不到，我也不知怎么搞的。后来就放根目录没毛病。 3.依赖：alpine实在是太干净了，在本地好容易在AI指导下搭的环境，devshell里也装了，结果应用启动时还要安装，这种就是前文大神们的常识，但在我原本的理解里其实有点奇怪的。 4.权限：我之前几个零散的小应用是在Mac里写的，所以没有什么感觉。近来因为换了Windows，又折腾不太会WSL，就直接在Powershell里打包。结果打包了应用不能运行，甚至官方的Helloworld我这里都试不成功。排查了一整天，才发现日志里明明写着启动脚本没有执行权限！问了AI，原来windows是没有linux的执行权限的，即使在WSL里做了chmod，回到windows打包一样不行。最后的方法是在我的旧Mac机里打包，一点问题没有！ 这些也不算什么坑，给大家看看我闹的笑话而已。 下一篇我打算直接Vibe出一个用于测试的懒猫应用来。

应用商店版本落后？教你用 LPK 自助升级

 ## 懒猫微服商店里的应用没及时更新怎么办？ 以 Calibre-Web Automated 为例：商店里是 3.0.5，而最新版已经到 3.1.4。作为不更新会死星人，自然要自己动手。 官方路径有两条： 1. 等待提供者更新（或客服联系开发者更新） 2. 自己修改 LPK 包，更换镜像版本 本文走第 2 条，几分钟搞定升级。 ## 准备工作 ### 需要工具： - [懒猫应用查看器](https://lazycat.cloud/appstore/detail/top.j0k3r.lpk-inspector)（用于导出/查看 LPK） - [lzc-cli](https://developer.lazycat.cloud/lzc-cli.html)（开发者命令行工具，需注册开发者账号） - [开发者文档AI助手](https://appstore.lazycat.cloud/#/shop/detail/in.zhaoj.devaihelper)（可用来查命令/规格） ## 步骤一：获取 LPK 安装并打开“懒猫应用查看器（LPK Inspector）” 导出 Calibre-Web Automated 的 LPK 文件 ## 步骤二：解包并查看 manifest.yml 用任意解压软件打开 LPK（本质是 zip） 找到并打开 manifest.yml，原始片段类似： ```yaml lzc-sdk-version: 0.1 package: cloud.lazycat.app.calibreweb version: 3.0.5 name: Calibre-Web Automated description: Calibre-Web，但自动化且具有 Calibre 功能 license: https://choosealicense.com/licenses/gpl-3.0/ homepage: https://github.com/crocodilestick/Calibre-Web-Automated author: CrocodileStick application: subdomain: calibreweb user_app: true routes: - /=http://server.cloud.lazycat.app.calibreweb.lzcapp:8083 services: server: image: >- registry.lazycat.cloud/longixaoyi/crocodilestick/calibre-web-automated:bdf3dbf10be5a22c environment: - PUID=0 - PGID=0 - TZ=Asia/Shanghai binds: - /lzcapp/var/config:/config - /lzcapp/var/cwa-book-ingest:/cwa-book-ingest - /lzcapp/var/calibre-library:/calibre-library - /lzcapp/var/books:/books - >- /lzcapp/pkg/content/auto-library.py:/app/calibre-web-automated/scripts/auto-library.py ``` 可以看到 `image` 使用的是 `registry.lazycat.cloud` 的仓库，意味着我们需要先把新版镜像同步到该仓库。 ## 步骤三：把上游镜像同步到懒猫镜像仓库 使用 lzc-cli（需要开发者账号登录）执行（示例）： `lzc-cli appstore copy-image crocodilestick/calibre-web-automated:V3.1.4` 命令执行成功后，会返回一个 registry.lazycat.cloud 上的完整镜像地址（包含命名空间与标签/摘要）。**记下这个地址**。 #### 提示： - 平台通常要求走 registry.lazycat.cloud 拉取，直接改 docker.io/ghcr.io 不一定能拉到，因此用 copy-image 最稳。 - 确认镜像是否包含你的 CPU 架构（amd64/arm64）。 ## 步骤四：修改 manifest.yml 的镜像地址 - 将 services.server.image 改为上一步返回的 registry.lazycat.cloud 完整地址（3.1.4 对应的 tag/摘要）。（顺便把version 也改成3.1.4吧） - 其他项一般不需要变动，但建议检查： - 环境变量（PUID/PGID/TZ 是否仍适用，新版是否有新增/废弃） - 端口（仍为 8083 即可） - 数据卷路径（/config、/books、/calibre-library、/cwa-book-ingest 等是否一致） - 兼容性脚本（auto-library.py 的挂载路径未变化） ## 步骤五：重新打包为 LPK - 将修改后的文件“就地压缩”为 zip（注意把目录内容打包到根层级，而不是再套一层目录） - 把后缀 .zip 改为 .lpk，例如 calibreweb-3.1.4.lpk 可选：若这是一个完整项目，也可用 lzc-cli 构建（开发手册示例） ``` lzc-cli project build -o release.lpk lzc-cli app install release.lpk ``` ## 步骤六：安装并验证 安装新包：`lzc-cli app install calibreweb-3.1.4.lpk` 提示安装成功后，打开 Calibre-Web Automated，检查应用内“关于/版本”或首页标注，确认已是 3.1.4。 ## 故障排查与回滚 - 拉取失败/403：重试 copy-image，或检查是否输错上游 tag（V3.1.4 大小写要一致）。 - 架构不匹配：确认镜像支持你的设备架构。 - 启动报错：对照新版 README/Changelog，检查环境变量、卷挂载、健康检查端点是否变化。 - 快速回滚：把 image 改回旧地址，重新打包并安装；原数据卷位于 /lzcapp/var/*，不会随升级丢失（建议重要数据先备份）。 ## 贴士 - 商店更新节奏有时会滞后，“自己改 LPK + 同步镜像”是当前最省事的临时方案。 - 想省去手工压包，亦可在熟悉 lzc-cli 后把此流程脚本化。 ## 用到的工具 - 懒猫应用查看器（LPK Inspector）：https://lazycat.cloud/appstore/detail/top.j0k3r.lpk-inspector - 开发者文档AI助手（查命令/规范更快）：https://appstore.lazycat.cloud/#/shop/detail/in.zhaoj.devaihelper - lzc-cli（开发者工具） ## 参考 - https://lazycat.cloud/playground/guideline/652 - https://lazycat.cloud/playground/guideline/662 - https://lazycat.cloud/playground/guideline/753 - https://developer.lazycat.cloud/lzc-cli.html