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

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

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

![logo (1).png](https://dl.playground.lazycat.cloud/guidelines/789/679e5b97-0230-42ca-abe3-b3cd568d6903.png "logo (1).png")



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



账户密码：admin/admin123
---

## 目录

- [1. 快速入门](#1-快速入门)
  - [1.1 系统要求](#11-系统要求)
  - [1.2 首次登录](#12-首次登录)
  - [1.3 修改默认密码](#13-修改默认密码)
- [2. 仪表盘](#2-仪表盘)
- [3. 项目管理](#3-项目管理)
  - [3.1 创建项目](#31-创建项目)
  - [3.2 项目预设模板](#32-项目预设模板)
  - [3.3 查看和编辑项目](#33-查看和编辑项目)
  - [3.4 删除项目](#34-删除项目)
- [4. 流水线模板配置](#4-流水线模板配置)
  - [4.1 理解流水线步骤](#41-理解流水线步骤)
  - [4.2 编辑流水线模板](#42-编辑流水线模板)
  - [4.3 步骤详细配置](#43-步骤详细配置)
  - [4.4 Dockerfile 配置](#44-dockerfile-配置)
  - [4.5 Manifest 配置](#45-manifest-配置)
- [5. 运行流水线](#5-运行流水线)
  - [5.1 触发部署](#51-触发部署)
  - [5.2 实时日志查看](#52-实时日志查看)
  - [5.3 取消流水线](#53-取消流水线)
  - [5.4 单步重试](#54-单步重试)
  - [5.5 版本号管理](#55-版本号管理)
- [6. 系统设置](#6-系统设置)
  - [6.1 SSH 密钥配置](#61-ssh-密钥配置)
  - [6.2 Docker 镜像仓库凭据](#62-docker-镜像仓库凭据)
  - [6.3 懒猫微服社区账号](#63-懒猫微服社区账号)
  - [6.4 代理和镜像加速](#64-代理和镜像加速)
  - [6.5 系统状态检查](#65-系统状态检查)
- [7. 产物管理](#7-产物管理)
- [8. 用户权限](#8-用户权限)
- [9. 完整部署操作实战](#9-完整部署操作实战)
- [10. 常见问题 (FAQ)](#10-常见问题-faq)

---

## 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 修改默认密码

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

---

## 2. 仪表盘

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

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

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

---

## 3. 项目管理

### 3.1 创建项目

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

**第一步：选择项目预设**

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

**第二步：填写基本信息**

| 字段 | 必填 | 说明 | 示例 |
|------|------|------|------|
| 项目名称 | ✅ | 应用的显示名称 | `我的应用` |
| 应用包名 | ✅ | 懒猫应用唯一标识，格式：`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`，补全项目配置。

**第三步：确认创建**

点击 **创建项目** 后，系统会自动：
1. 创建项目记录
2. 根据预设生成默认流水线模板（含 Dockerfile、步骤配置等）
3. 后台异步解析仓库中的 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 编辑流水线模板

进入 **项目详情页 → 流水线模板** 区域：
1. 点击模板右侧的 **⚙️ 设置** 按钮进入编辑页
2. 左侧为步骤列表，可拖拽排序、添加/删除步骤
3. 点击某个步骤展开配置面板
4. 右侧为 Dockerfile 和 Manifest 编辑器
5. 编辑完成后点击 **保存**

### 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，例如：

```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` 是懒猫应用的清单文件，定义了应用的元数据和运行配置。

**关键字段说明：**

```yaml
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 触发部署

有两种方式触发：

**方式一：从项目详情页触发**
1. 进入项目详情页
2. 点击 **▶ 运行流水线** 按钮
3. 系统会自动检查是否缺少凭据配置，如有缺失会弹出提示
4. 确认后开始执行，自动跳转到流水线执行页面

**方式二：从项目列表页触发**
1. 在项目列表中找到目标项目
2. 点击该行的 **部署** 按钮

### 5.2 实时日志查看

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

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

### 5.3 取消流水线

在流水线执行页面点击 **取消** 按钮：
- 正在执行的进程会被终止（先 SIGTERM，5 秒后 SIGKILL）
- 所有待执行的步骤标记为 `cancelled`
- 已完成的步骤保留原状态

### 5.4 单步重试

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

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

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

### 5.5 版本号管理

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

---

## 6. 系统设置

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

### 6.1 SSH 密钥配置

SSH 密钥用于两个场景：
1. **Git SSH 认证** — 克隆私有仓库
2. **设备连接** — 安装 LPK 到懒猫设备

**配置步骤：**

**第一步：生成密钥（如果没有）**
1. 在 SSH 配置区域，点击 **生成密钥**
2. 输入密钥名称（如 `id_ed25519`）
3. 点击 **生成**，系统会使用 `ssh-keygen -t ed25519` 生成密钥对

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

**第三步：授权公钥到设备**
1. 点击 **生成授权链接**
2. 输入设备名称（如你的懒猫 NAS 名称）
3. 在浏览器中打开授权链接，完成授权

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

### 6.2 Docker 镜像仓库凭据

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

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

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

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

### 6.3 懒猫微服社区账号

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

**配置步骤：**
1. 前往 [懒猫开发者平台](https://developer.lazycat.cloud/manage) 注册账号
2. 在设置页面点击 **添加账号**
3. 填写用户名和密码
4. 点击 **验证并保存**

### 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 项目** 为例：

### 准备工作

确保以下条件满足：
- [x] 代码仓库准备好（GitHub/Gitee 等）
- [x] 仓库中有 Dockerfile（或使用系统生成的）
- [x] 仓库中有 `deploy/lazycat/lzc-manifest.yml`（或使用系统编辑）
- [x] Docker Hub 账号（或其他 Registry）
- [x] 懒猫微服社区开发者账号

### 步骤 1：配置系统设置

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

### 步骤 2：创建项目

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

### 步骤 3：配置流水线模板

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

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

4. 点击 **保存**

### 步骤 4：运行流水线

1. 返回项目详情页
2. 点击 **▶ 运行流水线**
3. 观察实时日志：
   ```
   克隆仓库: 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!
   ```
4. 所有步骤显示 🟢 即部署完成！

### 步骤 5：访问应用

部署成功后，在浏览器中访问：
```
https://my-app.你的设备名.heiyu.space
```

---

## 10. 常见问题 (FAQ)

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

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

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

---

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

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

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

---

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

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

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

---

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

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

**解决**：
1. 前往 **设置 → 懒猫微服社区账号**
2. 添加或更新账号密码
3. 点击 **验证** 确认登录成功

---

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

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

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

---

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

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

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

---

### Q: 流水线卡住不动

**解决**：
1. 点击 **取消** 按钮终止流水线
2. 检查 **设置 → 系统状态** 确认 Docker 和 lzc-cli 是否可用
3. 如果是网络问题（如 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