Lazycat Lpk Builder

懒猫微服 LPK 应用打包与移植指南

你是一个专业的懒猫微服应用生态开发者。你的核心任务是协助用户将现有应用（如 Docker 镜像或源码）打包移植为懒猫微服支持的 lpk 格式。

当前推荐使用 LPK V2 (v1.5.0+) 规范，该规范实现了元数据与运行结构的分离。

核心流程 (Core Workflow)

打包和移植懒猫微服应用主要涉及编写以下核心配置文件：

1. 需求分析与准备

• 确认应用类型（源码构建或 Docker 镜像移植）。
• 梳理端口、持久化存储路径、环境变量及所需权限。

2. 编写元数据与权限声明 (package.yml)

该文件定义了应用的身份、版本及权限。

• 行动指令： 读取并遵循 references/package-spec.md。

3. 编写清单配置 (lzc-manifest.yml)

该文件描述应用的运行结构（服务、路由、注入等）。

• 注意： 在 LPK V2 中，package、version 等元数据不再放在此文件中。
• 行动指令： 读取并遵循 references/manifest-spec.md。

4. 编写构建配置 (lzc-build.yml & lzc-build.dev.yml)

定义构建逻辑及开发态差异。

• 行动指令： 读取并遵循 references/build-spec.md。

5. 使用 lzc-cli 打包与安装

打包应用:

# 默认使用 lzc-build.yml
lzc-cli project build -o release.lpk

安装应用:

lzc-cli app install release.lpk

开发调试 (Dev Mode):

# 优先使用 lzc-build.dev.yml 进行本地部署调试
lzc-cli project deploy

平台特定的规则与护栏 (Guardrails)

1. 服务间通信域名

• 跨服务调用的标准域名格式为：${service_name}.${lzcapp_appid}.lzcapp。

2. 持久化存储路径约束

• 任何持久化数据必须挂载在 /lzcapp/var 目录下。
• 私有文稿路径： 推荐使用 /lzcapp/documents (v1.5.0+)，废弃旧的 /lzcapp/run/mnt/home。

3. HTTP 路由转发前缀

• application.routes 默认会 Trim Location。如需保留前缀，请使用 application.upstreams 并设置 disable_trim_location: true。

4. 禁止使用的端口

• 除非极特殊情况，严禁通过 ingress 接管 80 和 443 端口。

5. 脚本注入 (Injects) 阶段

• 支持 browser, request, response 三个注入阶段，以实现更细粒度的页面控制或开发态代理。

平台兼容性说明

请务必利用 read_file 主动读取本技能包 references/ 目录下的相关规范文档（尤其是 package-spec.md 和 manifest-spec.md），以确保生成的配置符合 LPK V2 标准。

lzc-build.yml 规范 (LPK V2)

lzc-build.yml 定义了应用打包为 LPK 的过程。自 LPK V2 起，支持 lzc-build.dev.yml 进行开发态覆盖。

一、 构建配置文件

1. `lzc-build.yml`: 默认构建配置，即 Release 配置。 2. `lzc-build.dev.yml`: 开发态覆盖配置，只定义差异项。

lzc-cli project deploy 优先读取 .dev.yml。lzc-cli project release 仅读取 .yml。

二、 核心字段

三、 manifest build 预处理 (#@build)

在 lzc-manifest.yml 中支持条件编译指令（需写在 YAML 注释中）：

• #@build if profile=dev / profile=release
• #@build if env.KEY=VALUE
• #@build else
• #@build end
• #@build include ./path.yml

示例：

#@build if env.DEV_MODE=1
application:
  injects:
    - id: dev-proxy
      on: request
      do: "ctx.proxy.to('http://127.0.0.1:3000')"
#@build else
application:
  routes: ["/=file:///lzcapp/pkg/content/dist"]
#@build end

四、 开发态覆盖示例 (lzc-build.dev.yml)

pkg_id: cloud.lazycat.app.demo.dev
contentdir:   # 显式覆盖为空，不打包 content
envs:
  - DEV_MODE=1

lzc-manifest.yml 规范文档 (LPK V2)

一、 概述

lzc-manifest.yml 用于定义应用运行结构与部署相关配置。

重要说明：自 LPK V2 起，静态元数据（如 package, version, name, locales, permissions 等）必须放入 package.yml 中。lzc-manifest.yml 仅保留运行时相关的配置。

二、 顶层数据结构 ManifestConfig

三、 ApplicationConfig 配置

3.1 基础配置

3.2 路由与注入 (核心)

3.3 脚本注入 (Injects)

injects 允许在不修改源码的情况下注入逻辑。

• 阶段 (`on`): browser (默认), request (转发前), response (响应后)。
• 匹配: when (命中条件), unless (排除条件), prefix_domain (域名前缀)。
• 执行环境: request/response 在 lzcinit 沙盒中执行，支持 ctx.headers, ctx.body, ctx.proxy 等。

示例：

injects:
  - id: dev-proxy
    on: request
    when: ["/*"]
    do:
      - src: |
          ctx.proxy.to("http://127.0.0.1:3000", { use_target_host: true });

四、 UpstreamConfig 配置 (高级路由)

五、 ExtConfig 扩展配置

注意：LPK V2 推荐使用 permissions 声明 document.private 权限，此时私有路径为 /lzcapp/documents/$uid。

六、 示例

# package.yml 负责元数据
# lzc-manifest.yml 负责运行时
application:
  subdomain: myapp
  routes:
    - /=file:///lzcapp/pkg/content/dist
  upstreams:
    - location: /api
      backend: http://server:8080
      disable_trim_location: true

package.yml 规范 (LPK V2)

package.yml 用于定义 LPK 的静态包元数据，以及开发者声明的权限需求范围。自 LPK v2 起，静态元数据从 lzc-manifest.yml 移入此文件。

一、 核心字段

二、 权限声明 (Permissions)

必须在 package.yml 中显式声明应用所需的权限。

permissions:
  required:
    - net.internet      # 访问互联网
    - document.private  # 使用私有文稿目录 /lzcapp/documents/$uid
  optional:
    - device.dri.render # 访问 GPU
    - net.lan           # 访问局域网

常用权限 ID

• 网络: net.internet, net.lan, net.host, net.admin
• 存储:
• document.private: 私有文稿目录 (推荐使用 /lzcapp/documents)
• document.read / document.write: 用户公共文稿目录访问
• media.read / media.write: 系统媒体目录访问
• 设备: device.dri.render (GPU), device.usb, device.kvm, device.block
• 系统: compose.override (高危运行时覆盖), power.shutdown.inhibit (阻止关机)
• LightOS: lightos.use, lightos.manage

三、 多语言 (Locales)

locales:
  zh-CN:
    name: 示例应用
    description: 这是一个示例
  en-US:
    name: Demo App
    description: This is a demo

四、 最小示例

package: cloud.lazycat.app.demo
version: 1.0.0
name: Demo App
permissions:
  required:
    - net.internet
    - document.private

懒猫微服应用商店上架与发布规范

一、上架流程

1. 注册开发者

1. 在 懒猫社区 注册社区账号。 2. 访问 开发者中心，根据界面引导提交开发者审核申请。 3. 提交申请后建议通过客服群或 联系官方 加速审核。

2. 推送镜像到官方仓库

在上架之前，必须将 lpk 中引用的镜像推送到懒猫官方 registry，否则审核人员无法安装应用，会导致上架审核失败。

lzc-cli appstore copy-image <公网可以访问的镜像名称>
# 上传完成后将打印 registry.lazycat.cloud/<community-username>/<镜像名称>:<hash版本>

示例：

lzc-cli appstore copy-image alpine:3.18
# 输出: registry.lazycat.cloud/snyh1010/library/alpine:d3b83042301e01a4

官方镜像仓库 `registry.lazycat.cloud` 的使用限制： 1. 为保证稳定性，生成的镜像 tag 会被替换为 IMAGE_ID，每次执行 copy-image 都会在服务端强制执行一次 docker pull。 2. 被上传的镜像必须是公网可访问的，pull 操作在服务端进行，仅在本地存在的镜像无法被 copy-image。 3. 被上传镜像必须被至少一个商店应用引用，仓库会定期进行垃圾回收。 4. registry.lazycat.cloud 仅供微服内部使用，在微服外部使用会有限速。

上传完毕后，必须手动修改 `lzc-manifest.yml` 中的镜像地址为官方返回的 registry.lazycat.cloud/... 地址。

3. 提交审核

使用 lzc-cli（v1.2.54 及以上版本）提交：

lzc-cli project build
lzc-cli appstore publish ./your-app.lpk

二、应用上架审核指南（7 条红线规则）

提交应用前必须确保满足以下所有条件：

1. 应用资料完备性

• 应用的 logo、名称、描述及截图等信息必须完整无缺。
• 应用名称、描述和使用须知必须支持多语言，通过配置 locales 实现本地化。
• 语言 key 规范参考 BCP 47 标准。

2. 可安装与可加载性

• 应用必须能正常安装和加载。
• 若出现无法安装、安装后无法加载或加载后无响应等情况，将无法通过审核。
• 提交前需全面测试安装流程及初始加载功能，尤其检查应用安装所需的依赖是否能正常访问。

3. 应用质量稳定性

• 应避免出现严重崩溃、闪退现象。

4. 速度指标

• 应用的启动速度、响应时间等不得超过 5 分钟。

5. 特殊场景适配性

• 硬件搭配类应用：需在真实硬件环境下测试，并提供包含硬件型号信息的测试说明。
• 特殊场景类应用（如浏览器等）：需在对应场景下充分测试。
• 更新提示合理性：应用内的更新提示不应严重影响正常使用。若应用无法完成应用内更新，建议去掉更新提示。

6. 应用场景有效性

• 提交的应用必须具备对用户真实有效的应用场景。
• 开发库、中间件类的软件原则上不允许上架。
• 工具类应用需要和懒猫网盘里对应的文件类型做关联。

7. 应用数据持久化

• 需要持久化数据的应用，必须测试数据能否正常持久化。
• 重启应用或升级应用后，确保数据不会丢失。
• 对已上架的应用进行升级时，不要轻易做实例的变更（实例变更会导致存储路径变更）。如需变更，应做好数据的迁移和恢复工作。

三、不能上架的应用类型

• 黄、赌、毒、空投、破解软件或违反中国法律的软件不能上架。
• 对于需要用户名和密码的应用，若普通用户无法在懒猫商店获取相应凭证，则无法上架。

Docker 移植避坑指南与最佳实践

将现有的 Docker 镜像或 docker-compose.yml 移植到懒猫微服（lzc-manifest.yml）时，开发者经常会在以下几个关键点遇到问题。请在协助用户时，务必参考并应用这些最佳实践。

1. 权限与用户问题 (User & Permissions)

问题： 许多第三方 Docker 镜像默认使用普通用户（如 node, abc 等）运行，但在懒猫微服中，持久化目录 /lzcapp/var/ 和用户文稿目录 /lzcapp/run/mnt/home/ 默认需要 root 权限才能读写，这会导致 Permission denied 错误。

最佳实践：

• 首选方案： 尽可能让容器以 root 用户运行。如果镜像文档没有强制要求，这是最简单的解决路径。
• 次选方案（应用拒绝 root）： 如果应用本身（如某些数据库或特定服务）强制禁止 root 运行，你需要通过 setup_script 以 root 权限先处理好目录权限，或者在 services 块中使用 user: "1000" (注意：用户ID必须是带引号的字符串) 并在启动前调整权限。

2. 配置文件初始化与读写 (Config Files)

问题： 应用需要一个初始的配置文件（如 config.yml），该文件打包在 lpk 中（位于 /lzcapp/pkg/content/），且应用在运行时还需要修改它。如果直接把 /lzcapp/pkg/content/config.yml 通过 binds 挂载，会因为 /lzcapp/pkg/content 是只读 (Read-Only) 的而导致应用修改失败崩溃。

最佳实践：

• 绝不要 将 /lzcapp/pkg/content/ 下的文件直接作为读写配置挂载。
• 正确做法： 使用 setup_script。在容器启动执行原逻辑之前，先判断目标可写路径（如 /lzcapp/var/config.yml）是否存在。如果不存在，则将 /lzcapp/pkg/content/ 下的初始配置拷贝过去。

  services:
    app:
      image: xxx
      binds:
        - /lzcapp/var/conf:/app/conf # 挂载可写目录
      setup_script: |
        if [ ! -f /app/conf/config.yml ]; then
            cp /lzcapp/pkg/content/default-config.yml /app/conf/config.yml
        fi

3. 启动顺序与健康检查 (Startup & Healthcheck)

问题： 带有数据库的重量级应用首次启动时，初始化表结构可能耗时很久。如果不合理配置健康检查，容器可能在初始化完成前就被系统判定为 unhealthy 并 Kill 掉。

最佳实践：

• 不要单纯依赖硬等待 (`sleep`)： 强行拉长 start_period 并不能完美解决问题，且体验极差。
• 正确做法： 编写具有实际语义的健康检查探针。对于 Web 服务，使用 curl 检查实际的 API 接口；对于数据库（如 MySQL），应使用实际的 select 1 等 SQL 查询语句来判断服务是否真正就绪。
• 使用 services.[].healthcheck（而不是废弃的 health_check），并合理配置 retries, interval 和 start_period。

4. 特权与内核能力 (Privileged & Capabilities)

问题： 某些应用（如旁路由、VPN、需要 FUSE 挂载的应用）必须依赖 Docker 的特权模式 (privileged: true) 或特殊的 Capability (cap_add)。

最佳实践：

• 如果原应用确实依赖特权，在微服中可以直接果断地给予相关特权。
• 使用 lzc-build.yml 中的 compose_override 字段来注入这些底层 Docker 参数（如 privileged, cap_add, devices）。
• 商店审核： 带有这类特权需求的应用，只要功能合理，是允许上架懒猫官方应用商店进行审核的，无需为此担忧。

5. 局域网访问、跨域与 Host 头校验 (Host & CORS)

问题： 容器服务经常对 HTTP 请求的 Host Header 进行严格校验。如果不对，可能会报错或引发跨域问题。

最佳实践：

• 默认情况： 懒猫微服的 lzc-ingress 已经非常智能，绝大部分情况会自动处理好 Host 头和跨域问题，开发者通常不需要特殊配置。
• 特殊情况： 如果应用确实报了相关的域名或 Host 校验错误，可以在 application.upstreams 中配置相关的转发规则，并添加 use_backend_host: true，让上游服务看到它期望的 Host 头。