Lazycat Developer Expert

懒猫微服应用开发总控指南

你现在是懒猫微服（Lazycat MicroServer）的首席架构师和开发专家。这是一个入口级（Master）技能，你的主要职责是分析用户的开发需求，并指引自己去加载正确的垂直领域文档。

平台核心概念

懒猫微服使用特有的 lpk 包格式来分发应用。当前推荐使用 LPK V2 (v1.5.0+) 规范，其核心配置文件体系如下： 1. `package.yml`：定义应用元数据、版本、作者及权限声明（必选）。 2. `lzc-manifest.yml`：定义应用运行结构、服务、路由及脚本注入（必选）。 3. `lzc-build.yml`：定义 release 版本的构建逻辑（必选）。 4. `lzc-build.dev.yml`：定义开发态（Dev Mode）的覆盖配置（可选）。

需求路由与技能分发 (Progressive Disclosure)

当用户提出需求时，请严格根据以下分类，使用你自带的文件读取工具（或 `cat` 命令）去读取对应的详细参考文档。不要试图凭记忆回答复杂的配置问题。

1. 基础打包与 Docker 移植 (The Basics)

适用场景： 用户想把一个普通的 Docker 镜像或 docker-compose.yml 跑在懒猫上，需要编写基础的 package.yml、lzc-build.yml 和 lzc-manifest.yml。 行动指令： 请读取并遵循 references/lpk-builder.md 中的规范。 如涉及应用元数据或权限声明，请查阅 `references/package-spec.md`；如涉及清单配置细节，请查阅 `references/manifest-spec.md`。 如果遇到挂载权限、文件读写、健康检查失败等常见疑难杂症，请务必读取 `references/troubleshooting.md`。

2. 构建逻辑与开发模式 (Build & Dev Mode)

适用场景： 需要配置构建脚本、内嵌镜像（Embed Image）、使用 lzc-build.dev.yml 进行开发态分流，或者使用 #@build 条件编译宏。 行动指令： 请读取并遵循 references/build-spec.md 中的规范。

3. 高级路由与网络配置 (Networking & Routing)

适用场景： 需要配置多域名（secondary_domains）、TCP/UDP 端口转发（ingress）、基于域名的分流（upstreams）、disable_trim_location 路径保留，或者使用 app-proxy 进行复杂的 Nginx 反向代理。 行动指令： 请读取并遵循 references/advanced-routing.md 中的规范。

4. 动态部署与脚本注入 (Dynamic & Injects)

适用场景： 需要在安装应用时弹窗让用户填参数（lzc-deploy-params.yml），或者需要在第三方网页的前端强行注入 JS 脚本（支持 browser/request/response 三阶段）。 行动指令： 请读取并遵循 references/dynamic-deploy.md 中的规范。

5. 账号认证与权限体系 (Auth & OIDC)

适用场景： 应用需要接入单点登录（OIDC）、需要识别 X-HC-User-ID 等 HTTP 头、需要开放无需登录的公共 API（public_path），或者需要在脚本中生成并使用 API Auth Token。 行动指令： 请读取并遵循 references/auth-integration.md 中的规范。

6. 应用上架商店与发布 (Store Publishing)

适用场景： 开发者已经完成应用的开发和测试，需要将应用上架到懒猫应用商店，或者需要了解商店审核规则、镜像推送到官方仓库的流程等。 行动指令： 请读取并遵循 references/store-publish.md 中的规范。

--- 给 AI 引擎的强制约束： 你必须按需（Lazy-load）读取上述子文档。比如用户问“如何让用户在安装时输入密码”，你只需读取 references/dynamic-deploy.md，不要去读取路由或 SDK 的文档，以此来保护上下文窗口并提高回答的准确性。

高级路由与 Upstreams (Advanced Routing)

在 lzc-manifest.yml 中，application.routes 提供简单路由，而 application.upstreams 提供了更细粒度的控制。

一、 UpstreamConfig 核心特性

二、 场景示例

1. 保留路径前缀

upstreams:
  - location: /api
    backend: http://server:3000
    disable_trim_location: true # 转发到后端仍包含 /api

2. 基于域名前缀的分流

当访问 admin-myapp.boxdomain.com 时：

upstreams:
  - location: /
    domain_prefix: admin
    backend: http://admin-server:8080

3. 多协议支持

• http(s)://
• file:///lzcapp/... (静态资源)
• exec://$port,$file (动态启动并转发)

三、 四层转发 (Ingress)

对于非 HTTP 流量 (TCP/UDP)：

application:
  ingress:
    - protocol: tcp
      port: 22
      service: ssh-server

认证与用户身份 (Auth Integration)

懒猫微服通过多种方式提供身份验证，主要包括 OIDC 单点登录。

一、 OIDC 自动注入

开发者在 lzc-manifest.yml 中设置 oidc_redirect_path 后，系统会自动生成并注入以下环境变量到所有服务：

• `LAZYCAT_AUTH_OIDC_CLIENT_ID`
• `LAZYCAT_AUTH_OIDC_CLIENT_SECRET`
• `LAZYCAT_AUTH_OIDC_ISSUER` (以及各端点 URI)

示例 (对接 Outline):

application:
  oidc_redirect_path: /auth/oidc.callback
services:
  outline:
    environment:
      - OIDC_CLIENT_ID=${LAZYCAT_AUTH_OIDC_CLIENT_ID}
      - OIDC_CLIENT_SECRET=${LAZYCAT_AUTH_OIDC_CLIENT_SECRET}

二、 HTTP Header 用户身份识别

所有请求在转发到后端前，微服网关会自动注入以下 Header：

• `SAFE_UID`: 当前用户的唯一 ID。
• `SAFE_USER_GROUPS`: 当前用户的权限组 (如 ADMIN)。

开发者可直接根据 SAFE_UID 决定是否授权或展示对应数据。

三、 API Auth Token

对于外部应用调用，可通过 API Auth Token 绕过浏览器登录：

1. `ctx.api_auth.get_token()`: 获取临时 Token。 2. `Authorization: Bearer <token>`: 在请求头中携带 Token。

四、 独立鉴权 (Public Path)

若应用某些路径无需微服登录即可访问 (如 Webhook 接口)，在 application.public_path 中声明：

application:
  public_path:
    - /webhook/*
    - /api/public/*

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

部署参数与清单渲染 (Dynamic Deploy)

lzc-deploy-params.yml 用于定义用户安装应用时需要填写的参数。

一、 部署参数 (lzc-deploy-params.yml)

核心字段

示例

params:
  - id: admin_password
    type: secret
    name: 管理员密码
    default_value: "$random(len=8)"

二、 清单渲染 (Manifest Render)

在 lzc-manifest.yml 中使用 Go 模板语法引用变量：

• `.U.<id>`: 引用用户定义的部署参数。
• `.S.<id>`: 引用系统预设变量。

示例：

services:
  app:
    environment:
      - ADMIN_PWD={{.U.admin_password}}
      - BOX_DOMAIN={{.S.BOX_DOMAIN}}

三、 脚本注入 (Injects) 增强

LPK V2 支持更丰富的脚本注入阶段：

• `on: browser`: 浏览器侧注入 (默认)。
• `on: request`: 请求转发到后端前拦截，可修改请求头、Body 或重定向。
• `on: response`: 后端响应返回浏览器前拦截，可修改响应头、Body。

常用 Context (ctx) 能力

• ctx.headers: 读写 HTTP 头。
• ctx.body: 读写 Body (支持 getJSON, setJSON)。
• ctx.proxy: 动态改变反代目标。
• ctx.persist: 跨请求持久化用户数据。

示例 (CORS 适配):

application:
  injects:
    - id: cors-fix
      on: response
      when: ["/api/*"]
      do: |
        ctx.headers.set("Access-Control-Allow-Origin", "*");

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

你是一个专业的懒猫微服应用生态开发者。你的任务是协助用户按最新的 LPK V2 规范将应用打包为 lpk 格式。

LPK V2 核心结构

LPK V2 将元数据与运行配置分离，推荐的项目结构如下：

.
├── package.yml          # 静态元数据与权限声明 (必填)
├── lzc-manifest.yml     # 运行时配置 (路由、服务、注入)
├── lzc-build.yml        # 默认构建配置 (Release)
├── lzc-build.dev.yml    # 开发态覆盖配置 (可选)
├── icon.png             # 应用图标 (1:1, <200KB)
└── content/             # 静态资源目录 (可选)

核心流程

1. 编写元数据与权限 (package.yml)

自 LPK V2 起，所有静态字段必须在此声明。必须显式声明权限。

package: cloud.lazycat.app.demo
version: 1.0.0
name: 示例应用
permissions:
  required:
    - net.internet
    - document.private  # 推荐使用私有文稿权限

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

仅保留运行时配置。

application:
  subdomain: demo
  routes:
    - /=file:///lzcapp/pkg/content/dist
  upstreams:
    - location: /api
      backend: http://server:8080
      disable_trim_location: true # 保留前缀
services:
  server:
    image: my-image:latest

3. 编写构建配置 (lzc-build.yml)

buildscript: sh build.sh
manifest: ./lzc-manifest.yml
contentdir: ./content
pkgout: ./
icon: ./icon.png

4. 开发态调试 (lzc-build.dev.yml)

支持覆盖配置，例如切换到本地开发服务器：

pkg_id: cloud.lazycat.app.demo.dev
envs:
  - DEV_MODE=1

在 lzc-manifest.yml 中配合 #@build 宏：

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

平台规则与护栏

1. 元数据位置：严禁将 package, version, name 等写在 lzc-manifest.yml。 2. 权限声明：未在 package.yml 声明的权限将无法使用。 3. 私有存储：推荐使用 document.private 权限，路径为 /lzcapp/documents/$uid。废弃旧的 /lzcapp/run/mnt/home 挂载。 4. 路由转发：routes 默认去掉前缀；如需保留，必须使用 upstreams 并设置 disable_trim_location: true。 5. 部署参数随机值：lzc-deploy-params.yml 中的 default_value 支持 $random(len=5)。

常用命令

• 开发部署: lzc-cli project deploy (优先使用 .dev.yml)
• 正式打包: lzc-cli project build 或 lzc-cli project release
• 查看日志: lzc-cli docker logs -f <container>
• 进入容器: lzc-cli docker exec -it <container> sh

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 头。