懒猫应用部署 — 用户使用手册

LazyCAT Application Deployment 是一款运行在懒猫微服上的通用可视化部署流水线工具。
通过 Web 界面即可完成任意项目到懒猫微服的全流程部署：克隆 → 构建 → 推送 → 打包 → 安装。

logo (1).png

https://appstore.lazycat.cloud/#/shop/detail/cloud.lazycat.app.lazycat-deploy-pipeline

账户密码：admin/admin123

1. 快速入门

1.1 系统要求

本工具以 LPK 应用形式运行在懒猫微服设备上，安装后通过浏览器访问。

运行环境（由容器自带，用户无需安装）：

组件	版本	说明
Python	3.11+	后端运行时
Node.js	20+	lzc-cli 运行时
Docker CLI	27.x	镜像构建推送
lzc-cli	1.3+	LPK 打包和安装
Git	最新	代码克隆

浏览器支持：

Chrome / Edge（最新版）
Firefox（最新版）
Safari（最新版）

1.2 首次登录

应用安装完成后，在浏览器中打开部署流水线的访问地址。

默认管理员账号：

字段	默认值
用户名	`admin`
密码	`admin123`

⚠️ 安全提示：首次登录后请立即修改默认密码！

1.3 修改默认密码

点击左侧边栏底部的 用户头像 区域
在弹出菜单中选择 修改密码
输入旧密码和新密码
点击 确认修改

2. 仪表盘

登录后默认进入 仪表盘 页面，这里展示系统概览信息：

区域	内容
统计卡片	项目总数、活跃项目数（近 30 天有部署）、运行中流水线数
最近部署	最近 5 条部署记录，包含项目名、版本号、状态、时间
快捷操作	一键新建项目

点击统计卡片或部署记录，可以快速跳转到对应页面。

3. 项目管理

3.1 创建项目

点击 + 新建项目 按钮，按照向导填写信息：

第一步：选择项目预设

系统提供 4 种预设模板（详见 3.2 节），选择最接近你的项目类型。

第二步：填写基本信息

字段	必填	说明	示例
项目名称	✅	应用的显示名称	`我的应用`
应用包名	✅	懒猫应用唯一标识，格式：`cloud.lazycat.app.xxx`	`cloud.lazycat.app.my-app`
版本号	✅	语义化版本号，格式：`X.Y.Z`	`1.0.0`
描述	❌	项目简介	`一个示例应用`
Git 仓库地址	❌	代码仓库 HTTPS 或 SSH 地址	`https://github.com/user/repo.git`
Git 分支	❌	默认克隆的分支	`main`

💡 提示：如果填写了 Git 仓库地址，系统会自动尝试解析仓库中的 lzc-manifest.yml，补全项目配置。

第三步：确认创建

点击 创建项目 后，系统会自动：

创建项目记录
根据预设生成默认流水线模板（含 Dockerfile、步骤配置等）
后台异步解析仓库中的 manifest 配置

3.2 项目预设模板

预设	适用场景	默认步骤
标准部署	前后端分离的完整应用	克隆 → 构建前端 → 构建镜像 → 推送 → 复制 Registry → 构建 LPK → 安装
纯前端应用	Vue/React 等纯前端项目	克隆 → 构建前端 → 构建镜像 → 推送 → 复制 Registry → 构建 LPK → 安装
Python 后端	FastAPI/Flask 等 Python 项目	克隆 → 构建镜像 → 推送 → 复制 Registry → 构建 LPK → 安装
Node.js 后端/SSR	Express/Nest/Nuxt 等项目	克隆 → 构建前端 → 构建镜像 → 推送 → 复制 Registry → 构建 LPK → 安装

预设只是起点，你可以在创建后自由编辑流水线的每一步。

3.3 查看和编辑项目

项目列表页 (/projects)：

搜索：按项目名称搜索
表格：显示项目名、包名、版本号、状态、创建时间
操作：查看详情、编辑、触发部署

项目详情页 (/projects/:id)：

基本信息：项目名、包名、版本号、Git 仓库地址
流水线模板：查看和管理该项目的部署模板
部署历史：查看该项目的所有部署记录
快捷配置指引：如果模板尚未完整配置，页面会显示配置向导

编辑项目 (/projects/:id/edit)：

修改项目名称、包名、版本号、描述
修改 Git 仓库地址和分支

3.4 删除项目

在项目详情页或列表页点击删除：

将同时删除该项目的所有流水线模板、部署记录、构建产物
清理本地的 Docker 镜像和工作目录
此操作不可逆，请谨慎操作

4. 流水线模板配置

4.1 理解流水线步骤

一个完整的部署流水线通常包含以下步骤：

① 克隆仓库 → ② 构建前端 → ③ 构建 Docker 镜像
     → ④ 推送镜像 → ⑤ 复制到懒猫 Registry
     → ⑥ 构建 LPK 包 → ⑦ 安装到设备

步骤	类型	说明	前置依赖
克隆仓库	`clone`	从 Git 仓库拉取代码	无
构建前端	`build_frontend`	执行 `npm install && npm run build`	克隆仓库
构建 Docker 镜像	`build_docker`	使用 Dockerfile 构建镜像	克隆仓库
推送镜像	`push_image`	推送到 Docker Hub 或私有 Registry	构建镜像
复制到懒猫 Registry	`copy_registry`	通过 `lzc-cli` 复制到懒猫内部仓库	推送镜像
构建 LPK 包	`build_lpk`	打包为 `.lpk` 安装包	复制到 Registry
安装到设备	`install`	将 LPK 安装到懒猫设备	构建 LPK
自定义命令	`custom`	执行任意 Shell 命令	可配置

每个步骤可以单独 启用/禁用，并支持 条件执行：

条件	行为
`on_success`	仅在前序步骤全部成功时执行（默认）
`on_failure`	仅在前序步骤有失败时执行（用于失败处理）
`always`	无论前序步骤是否成功都执行（用于清理/通知）

4.2 编辑流水线模板

进入 项目详情页 → 流水线模板 区域：

点击模板右侧的 ⚙️ 设置 按钮进入编辑页
左侧为步骤列表，可拖拽排序、添加/删除步骤
点击某个步骤展开配置面板
右侧为 Dockerfile 和 Manifest 编辑器
编辑完成后点击保存

4.3 步骤详细配置

克隆仓库

配置项	说明	默认值
Git 仓库地址	HTTPS 或 SSH 格式	取自项目配置
Git 分支	克隆的目标分支	`main`
克隆目录名	自定义工作目录名称	包名
使用 SSH 认证	开启后自动将 HTTPS 转换为 SSH	关闭
Git 代理	加速 GitHub 访问	无

💡 仓库只在首次克隆，后续执行会自动 git fetch + reset --hard 更新到最新，避免重复下载。

构建前端

配置项	说明	默认值
工作目录	前端代码相对路径	`frontend`
包管理器	npm / yarn / pnpm	`npm`
安装命令	依赖安装命令	`install`
输出目录	构建产物目录名	`dist`
独立前端仓库	前端单独一个 Git 仓库	无
Node 版本	使用 nvm 切换版本	系统默认

构建 Docker 镜像

配置项	说明	默认值
Dockerfile	自定义 Dockerfile 内容（在编辑器中编辑）	预设生成
构建上下文	Docker build context 路径	`.`
镜像标签	自定义标签（不填则使用版本号）	版本号

系统会自动向 Dockerfile 注入 npm/pip 镜像加速配置（如果检测到 Node.js 或 Python 阶段）。

推送镜像

配置项	说明	默认值
Registry	Docker 仓库地址	`docker.io`
用户名/命名空间	Docker Hub 用户名或组织名	无（必填）
仓库名	镜像仓库名称	Git 仓库名
标签	镜像标签	版本号

⚠️ 推送前需要先在 系统设置 → Docker 凭据 中配置 Registry 的登录凭据。

复制到懒猫 Registry

此步骤调用 lzc-cli appstore copy-image，将 Docker Hub 的镜像复制到懒猫内部 Registry。

⚠️ 需要先在 系统设置 → 懒猫社区账号 中登录。

构建 LPK 包

配置项	说明	默认值
Manifest 目录	`lzc-manifest.yml` 所在目录	`deploy/lazycat`
应用图标	上传 PNG 格式图标（≥512×512）	仓库中的 `lzc-icon.png`

💡 构建时会自动将项目的 name、package、version 写入 manifest，并替换 services.*.image 为实际镜像地址。

安装到设备

配置项	说明	默认值
安装方式	自动（使用系统 SSH 配置）	`auto`

⚠️ 需要先在 系统设置 → SSH 配置 中选择 SSH 公钥并完成设备授权。

4.4 Dockerfile 配置

在模板编辑页右侧的 Dockerfile 编辑器 中编辑。

如果仓库中已有 Dockerfile：系统会自动读取并填入编辑器。

如果没有：预设模板会生成一个默认的多阶段 Dockerfile，例如：

# 阶段一：构建前端
FROM node:20-slim AS frontend-builder
WORKDIR /build
COPY frontend/package*.json ./
RUN npm install
COPY frontend/ ./
RUN npm run build

# 阶段二：最终镜像
FROM python:3.11-slim
WORKDIR /app
COPY backend/ ./
COPY --from=frontend-builder /build/dist ./static
RUN pip install -r requirements.txt
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

自动注入的加速配置：

检测到 Node.js 阶段 → 自动注入 ARG NPM_REGISTRY 和 RUN npm config set registry
检测到 Python 阶段 → 自动注入 ARG PIP_INDEX_URL

4.5 Manifest 配置

lzc-manifest.yml 是懒猫应用的清单文件，定义了应用的元数据和运行配置。

关键字段说明：

lzc-sdk-version: '0.1'
name: 我的应用               # 应用显示名称
package: cloud.lazycat.app.my-app  # 应用包名（唯一标识）
version: 1.0.0              # 版本号

application:
  subdomain: my-app          # 应用子域名
  multi_instance: false       # 是否多实例
  background_task: false      # 是否常驻后台
  privileged: false           # 是否需要特权模式
  routes:
    - /=http://my-app.cloud.lazycat.app.my-app.lzcapp:8000

services:
  my-app:
    image: registry.lazycat.cloud/user/my-app:1.0.0
    binds:
      - /lzcapp/var/data:/data
    environment:
      - KEY=VALUE

💡 流水线构建 LPK 时会自动同步 name、package、version 和 services.*.image，无需手动修改。

5. 运行流水线

5.1 触发部署

有两种方式触发：

方式一：从项目详情页触发

进入项目详情页
点击 ▶ 运行流水线 按钮
系统会自动检查是否缺少凭据配置，如有缺失会弹出提示
确认后开始执行，自动跳转到流水线执行页面

方式二：从项目列表页触发

在项目列表中找到目标项目
点击该行的部署按钮

5.2 实时日志查看

流水线执行页面 (/pipelines/:id) 提供：

步骤进度条：左侧显示所有步骤的执行状态
- 🔵 待执行 → 🟡 执行中 → 🟢 成功 / 🔴 失败 / ⏭️ 跳过
实时日志：右侧终端风格日志窗口，通过 WebSocket 实时推送
步骤切换：点击左侧步骤可查看该步骤的日志

5.3 取消流水线

在流水线执行页面点击取消按钮：

正在执行的进程会被终止（先 SIGTERM，5 秒后 SIGKILL）
所有待执行的步骤标记为 cancelled
已完成的步骤保留原状态

5.4 单步重试

当某个步骤失败时，可以单独重新执行该步骤：

在流水线执行页面，点击失败步骤的重试按钮
系统会检查该步骤的前置依赖是否满足
如果前置步骤都已成功，直接执行该步骤
执行成功后，如果所有步骤都已完成，流水线标记为成功

💡 单步重试会复用之前步骤的上下文（工作目录、Docker 标签等），无需重新执行整个流水线。

5.5 版本号管理

每次触发流水线时，版本号会自动递增 patch 版本（如 1.0.0 → 1.0.1）
也可以在触发时手动指定版本号
版本号格式必须为 语义化版本号（X.Y.Z）
版本号会自动同步到 lzc-manifest.yml 和 Docker 镜像标签

6. 系统设置

点击左侧导航栏的 ⚙️ 设置 进入系统设置页面。

6.1 SSH 密钥配置

SSH 密钥用于两个场景：

Git SSH 认证 — 克隆私有仓库
设备连接 — 安装 LPK 到懒猫设备

配置步骤：

第一步：生成密钥（如果没有）

在 SSH 配置区域，点击 生成密钥
输入密钥名称（如 id_ed25519）
点击生成，系统会使用 ssh-keygen -t ed25519 生成密钥对

第二步：选择公钥

设备安装用公钥：在下拉列表中选择一个公钥
Git SSH 用公钥：如果要克隆私有仓库，选择 Git SSH 公钥

第三步：授权公钥到设备

点击 生成授权链接
输入设备名称（如你的懒猫 NAS 名称）
在浏览器中打开授权链接，完成授权

⚠️ 公钥文件存储在 /data/ssh/ 目录（容器内持久化），重启不丢失。

6.2 Docker 镜像仓库凭据

用于 推送镜像 步骤登录 Docker Hub 或私有 Registry。

添加凭据：

点击 添加凭据
填写 Registry 地址（如 docker.io）、用户名和访问令牌/密码
点击保存

💡 建议使用 Docker Hub 的 Access Token 而非密码。获取方式：Docker Hub → Account Settings → Security → New Access Token

凭据存储安全：

令牌使用加密存储（非明文）
凭据仅在推送镜像时解密使用

6.3 懒猫微服社区账号

用于 复制到懒猫 Registry 步骤，将镜像从 Docker Hub 复制到懒猫内部仓库。

配置步骤：

前往懒猫开发者平台注册账号
在设置页面点击 添加账号
填写用户名和密码
点击 验证并保存

6.4 代理和镜像加速

系统支持配置镜像加速，加速 npm 和 pip 在 Docker 构建内的下载：

环境变量	作用	默认值
`PIPELINE_PROXY_NPM_MIRROR`	npm 镜像源	无（使用 npm 默认）
`PIPELINE_PROXY_PIP_MIRROR`	pip 镜像源	无（使用 pip 默认）

这些变量通过 系统设置 中的"代理配置"区域设置，会自动注入到 Docker 构建中。

6.5 系统状态检查

设置页面的 系统状态 区域显示：

检查项	含义
🟢 Docker 可用	Docker CLI 已连接并可用
🟢 lzc-cli 可用	lzc-cli 已安装并可执行
🟢 数据库正常	SQLite 数据库连接正常
项目总数	已创建的项目数量
流水线总数	历史运行总数

7. 产物管理

每次流水线运行会产生多种产物：

产物类型	说明	存储位置
日志文件	每个步骤的执行日志	`artifacts/{run_id}/logs/`
LPK 包	构建好的安装包	`artifacts/{run_id}/outputs/`
Docker 镜像	构建和推送的镜像标签	Docker 引擎中
源代码	克隆的仓库	`workspaces/{project_id}/`

在流水线详情页可以：

📥 下载 LPK 包
📄 下载日志文件
查看每个步骤的产物详情

💡 流水线结束后会自动清理本地 Docker 镜像（已推送到远程的），节省磁盘空间。

8. 用户权限

系统支持三种角色：

操作	Admin	Reviewer	Developer
管理用户	✅	❌	❌
系统设置（全局）	✅	❌	❌
创建项目	✅	✅	✅
编辑/删除项目	✅	✅	✅
触发部署	✅	✅	✅
审批部署请求	✅	✅	❌
跳过审核直接部署	✅	❌	❌
查看所有项目	✅	✅	仅自己的
下载产物	✅	✅	仅自己的

审核功能属于可插拔模块（开发者中心），可通过环境变量 ENABLE_DEVELOPER_CENTER=true/false 开启或关闭。

9. 完整部署操作实战

以部署一个 前后端分离的 Python + Vue 项目 为例：

准备工作

确保以下条件满足：

代码仓库准备好（GitHub/Gitee 等）
仓库中有 Dockerfile（或使用系统生成的）
仓库中有 deploy/lazycat/lzc-manifest.yml（或使用系统编辑）
Docker Hub 账号（或其他 Registry）
懒猫微服社区开发者账号

步骤 1：配置系统设置

进入设置页面
生成并选择 SSH 公钥，完成设备授权
添加 Docker Hub 凭据（Registry: docker.io，用户名，Token）
添加 懒猫社区开发账号

步骤 2：创建项目

点击 + 新建项目
选择 标准部署 预设
填写信息：
- 项目名称：我的应用
- 应用包名：cloud.lazycat.app.my-app
- 版本号：1.0.0
- Git 仓库地址：https://github.com/user/my-app.git
点击 创建项目

步骤 3：配置流水线模板

进入项目详情页
点击流水线模板的 ⚙️ 设置 按钮
逐步检查和配置：

步骤	需要配置
克隆仓库	确认 Git 地址和分支正确；私有仓库开启 SSH 认证
构建前端	确认前端目录路径（默认 `frontend`）
构建 Docker 镜像	检查 Dockerfile 内容是否正确
推送镜像	填写 Docker Hub 用户名和仓库名
复制到懒猫 Registry	一般无需额外配置
构建 LPK	上传应用图标（PNG ≥512×512）；确认 manifest 目录
安装到设备	一般无需额外配置（使用系统 SSH 配置）

点击保存

步骤 4：运行流水线

返回项目详情页
点击 ▶ 运行流水线

观察实时日志：

克隆仓库: https://github.com/user/my-app.git (分支: main)
仓库准备就绪
开始构建前端: frontend
前端构建成功
开始构建 Docker 镜像: cloud.lazycat.app.my-app:1.0.1
Docker 镜像构建成功
推送镜像: user/my-app:1.0.1
推送成功
复制镜像到懒猫 Registry
已复制到懒猫 Registry
开始构建 LPK 包...
LPK 包构建成功
开始安装 LPK 到设备
Installation successful!

所有步骤显示 🟢 即部署完成！

步骤 5：访问应用

部署成功后，在浏览器中访问：

https://my-app.你的设备名.heiyu.space

10. 常见问题 (FAQ)

Q: 克隆仓库失败，提示 Permission denied

原因：私有仓库需要 SSH 认证。

解决：

前往 设置 → SSH 配置，生成/选择 Git SSH 公钥
将公钥添加到你的 Git 平台（GitHub → Settings → SSH and GPG keys）
在克隆步骤中开启 使用 SSH 认证

Q: Docker 构建失败，提示 `unknown flag: --progress`

原因：懒猫设备上的 Docker 版本较旧，不支持 BuildKit 的 --progress 参数。

解决：系统已兼容此情况，如仍出现请确保使用最新版本的部署流水线工具。

Q: 推送镜像失败，提示 `denied: requested access to the resource is denied`

原因：Docker Hub 凭据不正确或未配置。

解决：

前往 设置 → Docker 镜像仓库凭据
确认 Registry 地址、用户名和 Token 正确
建议使用 Access Token 而非密码

Q: 复制到懒猫 Registry 失败，提示需要登录

原因：懒猫社区账号未配置或密码过期。

解决：

前往 设置 → 懒猫微服社区账号
添加或更新账号密码
点击验证确认登录成功

Q: 安装到设备失败，提示 "读取不到以下路径中的文件"

原因：SSH 公钥未配置或未授权到懒猫设备。

解决：

前往 设置 → SSH 配置
确认已选择公钥
点击 生成授权链接，输入设备名称
在浏览器中打开授权链接完成授权

Q: 版本号和 manifest 中的 package/name 没有被替换

原因：流水线会自动将项目配置的 name、package、version 同步到 lzc-manifest.yml，但如果构建 LPK 步骤被跳过或失败，替换不会生效。

排查：

检查构建 LPK 步骤的日志，是否有 📝 更新 manifest.name: 等输出
确认项目配置中的包名（如 cloud.lazycat.app.my-app）与仓库 manifest 中的不同时，才会触发替换
注意：application.subdomain 和 application.routes 中的旧包名引用目前需要手动同步

Q: 流水线卡住不动

解决：

点击取消按钮终止流水线
检查 设置 → 系统状态 确认 Docker 和 lzc-cli 是否可用
如果是网络问题（如 npm install 卡住），尝试配置镜像加速

Q: 如何跳过某个步骤？

在流水线模板编辑页面，点击对应步骤的开关将其禁用即可。禁用的步骤不会出现在执行流程中。

Q: 数据存储在哪里？如何备份？

数据	容器内路径	挂载点
数据库 + 产物	`/data`	`/lzcapp/var/data`
Git 工作目录	`/workspaces`	`/lzcapp/var/workspaces`

备份 /lzcapp/var/data 目录即可保留所有项目配置、部署记录和产物。

📌 更多帮助：如遇到未列出的问题，欢迎在商店评论区中反馈：
https://appstore.nasw.heiyu.space/#/shop/detail/cloud.lazycat.app.lazycat-deploy-pipeline

懒猫应用部署V1.0.0 — 用户使用手册