浏览器改个文件，LPK 应用包自动构建发布

# 懒猫微服 CI 模板使用指南 - 快速构建 LPK 应用包

本指南介绍如何使用 懒猫微服 CI 模板快速搭建 LPK 应用包的构建和发布流程。面向希望快速上手的开发者，以及需要维护大量应用包的开发者，帮助你通过统一的模板和自动化工作流，高效地构建、发布和维护 LPK 应用包。

**项目地址**: https://github.com/lazycatapps/hack

**参考** [使用 Github Actions 实现 Docker 应用的自动更新和发布](https://lazycat.cloud/playground/guideline/572)

## 目录

- [前提条件](#前提条件)
- [你将获得什么](#你将获得什么)
- [整体流程概览](#整体流程概览)
- [场景一：从零开始创建新项目](#场景一从零开始创建新项目)
- [场景二：迁移现有项目到模板](#场景二迁移现有项目到模板)
- [日常开发流程](#日常开发流程)
- [GitHub Actions 自动化构建](#github-actions-自动化构建)
- [模板升级与同步](#模板升级与同步)
- [常见问题](#常见问题)

## 前提条件

### 账号要求

- **GitHub 账号**：用于托管代码和使用 GitHub Actions
- **懒猫微服开发者账号**：用于发布应用到懒猫应用商店
  - 需要开发者账号和密码
  - 建议提前在本地使用 `lzc-cli appstore login` 验证账号可用性

### 技术要求

需要具备以下基础知识：

- **Bash 脚本**：能够理解和执行 shell 命令
- **Makefile**：了解 Make 构建系统的基本用法
- **Git**：掌握基本的版本控制操作

### 工具安装

在开始之前，确保你的开发环境已安装以下工具：

```bash
# 必需工具
- bash
- curl
- make
- git
- Node.js & npm

# 懒猫 CLI 工具
npm install -g @lazycatcloud/lzc-cli

# Docker 相关(仅 docker-lpk 项目需要)
- docker
npm install -g docker2lzc
```

验证工具安装：

```bash
# 在项目初始化后可以运行
make check-tools
```

## 你将获得什么

使用本模板，你将获得以下能力：

### 1. 快速启动

- **一分钟创建项目**：通过单条命令快速创建符合规范的项目结构
- **开箱即用的工作流**：预配置的 GitHub Actions 自动构建和发布流程
- **统一的构建命令**：所有项目使用相同的 Make 命令，降低学习成本

### 2. 本地与 CI 双重构建

- **本地快速验证**：使用 `make lpk` 和 `make deploy` 快速构建并测试
- **CI 自动发布**：推送代码即可触发自动构建，发布到应用商店无需手动操作
- **浏览器直接修改**：甚至可以在 GitHub 网页上修改几个文件，就能自动构建新版本

### 3. 大规模项目维护

- **批量管理**：统一模板管理多个应用包项目
- **一键同步升级**：当模板更新功能或修复 bug 时，执行 `make config-sync` 即可获得最新改进
- **降低维护成本**：避免在每个项目中重复编写构建脚本和工作流

### 4. 灵活定制

- **保留自定义**：模板更新时不会覆盖你的项目特定配置
- **分层架构**：触发层可自定义，复用层统一维护
- **渐进式采用**：可以只同步部分模板文件，不必全盘接受

## 整体流程概览

### 核心设计理念

本模板之所以能做到快速开发、批量维护和一键升级，核心在于以下设计：

#### 1. 模板与项目分离

**我们做了什么**：
- 将通用的构建逻辑提取到 `base.mk` 中
- 将 CI 工作流拆分为"触发层"和"复用层"
- 提供同步脚本，可以随时拉取最新模板

**为什么能做到复用**：
- 项目只需通过 `include base.mk` 引入通用能力
- 复用层工作流由模板统一维护，项目无需关心实现细节
- 触发层可自定义，不影响核心构建逻辑

**我们没做什么**：
- 不侵入你的业务代码
- 不强制特定的项目结构
- 不限制你自定义构建流程

#### 2. 分层工作流架构

```
GitHub Actions 工作流
├── 触发层 (Trigger Layer)
│   ├── 定义何时触发构建 (push/tag/PR)
│   ├── 准备构建上下文参数
│   └── 项目可自由修改，同步时不覆盖
│
└── 复用层 (Reusable Layer)
    ├── 包含实际的构建步骤
    ├── 统一的 LPK 打包逻辑
    └── 模板更新时自动同步
```

**为什么这样设计**：
- 触发条件因项目而异，需要灵活定制
- 构建逻辑应该统一，避免每个项目重复维护
- 分层后，模板升级不会破坏你的自定义配置

#### 3. 默认目标 + 覆写机制

`base.mk` 中所有目标都以 `-default` 结尾：

```makefile
# base.mk 中定义
lpk-default:
    lzc-cli project build

# 通过通配规则路由
%: %-default
    @ true
```

**项目中覆写**：
```makefile
# 项目的 Makefile
include base.mk

# 覆写 lpk 目标，添加测试
lpk: test-default
    @echo "Running tests before build"
    lzc-cli project build
```

**为什么能做到复用**：
- 默认行为在 `base.mk` 中统一定义
- 项目可选择性覆写部分目标
- 更新 `base.mk` 不会影响已覆写的目标

#### 4. 浏览器直接修改即可构建

**如何实现**：
- 所有构建逻辑都在 GitHub Actions 中
- 修改代码后 push 自动触发 CI
- 无需在本地安装任何工具

**为什么能这样做**：
- CI 环境已预装所有必需工具
- 工作流自动处理构建、打包、发布全流程
- 修改配置文件（如 `lzc-manifest.yml`）同样会触发构建

#### 5. 一键升级模板

**如何实现**：
```bash
make config-sync
```

**为什么能这样做**：
- 模板文件通过 HTTP 远程拉取
- 同步脚本会智能判断哪些文件应该更新
- 触发层工作流受保护，不会被意外覆盖

**升级时会发生什么**：
- ✅ `base.mk` 总是更新到最新版本（**不要修改此文件**）
- ✅ 复用层工作流（`reusable-*.yml`）总是更新（**不要修改这些文件**）
- ✅ 通用配置文件（`.gitignore`、`.editorconfig`）在缺失时恢复
- ⚠️ 触发层工作流（`lpk-package.yml`、`docker-image.yml`）默认保留，除非你使用 `--sync-include-init`
- ⚠️ 项目 `Makefile` 不会被覆盖
- ⚠️ 项目自有文件（`lzc-manifest.yml`、`icon.png` 等）不受影响

### 整体工作流程

```
1. 初始化项目 (一次性)
   ├── 远程执行脚本或交互式初始化
   ├── 自动下载模板文件到项目目录
   ├── 生成 Makefile、工作流等基础结构
   └── 可选初始化 Git 仓库

2. 本地开发
   ├── 编写业务逻辑代码
   ├── 配置 lzc-manifest.yml
   ├── make lpk          # 本地构建测试
   └── make deploy       # 安装到本地验证

3. 推送到 GitHub
   ├── git add & commit
   ├── git push origin main  # 构建 LPK，上传为 Artifact
   └── git tag v1.0.0        # 创建标签
       git push origin v1.0.0  # 构建并发布到应用商店

4. 模板升级（按需）
   └── make config-sync      # 同步最新模板，获得新功能和修复
```

### 项目类型选择

模板支持两种项目类型：

| 项目类型 | 适用场景 | 包含内容 |
|---------|---------|---------|
| **lpk-only** | 不需要在 CI 中构建镜像的应用（如迁移他人应用、仅同步镜像到懒猫微服） | LPK 打包工作流 |
| **docker-lpk** | 需要在 CI 中自动构建 Docker 镜像的应用 | Docker 镜像构建 + LPK 打包工作流 |

选择建议：
- 如果你需要在 CI 中自动构建 Docker 镜像，选择 `docker-lpk`
- 如果你只需要打包现成的应用（不需要构建镜像），选择 `lpk-only`

> **注意**：
> - 本指南主要聚焦 `lpk-only` 类型，因为这是最容易上手的方式。关于 `docker-lpk` 项目的详细介绍，如果大家有强烈的诉求，我们会再单独提供文档。
> - **docker-lpk 限制**：目前 docker 类型的模板只支持构建单个 Docker 镜像，暂不支持构建多个镜像的场景。

## 场景一：从零开始创建新项目

### 方法 1：交互式初始化（推荐新手）

适合第一次使用模板的开发者，提供逐步引导：

```bash
bash  **提示**：如果你需要将 Docker Compose 应用转换为懒猫应用，可以使用 `docker2lzc` 工具辅助生成清单文件：
   > - NPM：https://www.npmjs.com/package/docker2lzc
   > - Gitee：https://gitee.com/fzlrkj/docker2lzc

3. **编写业务代码**：根据项目类型编写代码

4. **本地测试**：
   ```bash
   # 查看可用命令
   make help

   # 查看项目信息
   make info

   # 构建 LPK
   make lpk

   # 构建并安装到本地验证
   make deploy

   # 卸载应用（保留数据）
   make uninstall
   ```
   
![Shot 2026.01.03 at 15.31.04.png](https://dl.playground.lazycat.cloud/guidelines/703/92856abe-fcf5-4bdf-9b1c-6a6004b0f4e1.png "Shot 2026.01.03 at 15.31.04.png")


5. **推送到 GitHub**：
   ```bash
   git remote add origin https://github.com/yourusername/my-project.git
   git push -u origin main
   ```

6. **配置 GitHub Secrets**（见下文"GitHub Actions 自动化构建"）

## 场景二：迁移现有项目到模板

如果你已经有一个现成的项目，想要使用本模板的构建系统和工作流，可以通过同步功能实现。

### 步骤 1：备份现有配置

在同步之前，建议备份可能被覆盖的文件：

```bash
# 备份重要文件
cp Makefile Makefile.backup
cp -r .github/workflows .github/workflows.backup
```

### 步骤 2：执行同步

进入项目目录，执行同步脚本：

```bash
cd your-existing-project

# 同步所有文件
bash  如果你没有测试用的 lzc-manifest.yml 可以从这里获取一份：https://github.com/lazycatapps/loki/blob/main/lzc-manifest.yml

![Shot 2026.01.03 at 15.44.52.png](https://dl.playground.lazycat.cloud/guidelines/703/059f5cc7-e672-440a-8d29-38d95c2270cf.png "Shot 2026.01.03 at 15.44.52.png")

### 其他可用命令

查看项目支持的所有命令：

```bash
make help
```

模板还为 Docker 项目和 Go 项目提供了额外的便捷命令，详见 `make help` 输出。

### 版本管理

项目版本会自动从 Git 标签推断：

```bash
# 查看当前版本
make version

# 创建新版本
git tag v1.0.0
git push origin v1.0.0

# 版本号会自动更新到构建产物
make lpk
```

版本推断规则：
- 有 Git 标签时使用标签（如 `v1.0.0`）
- 无标签时使用最新提交的短 hash（如 `a3c8f47`）
- 工作区有未提交改动时添加 `-dirty` 后缀

## GitHub Actions 自动化构建

### 配置 Secrets

在 GitHub 仓库设置中配置以下 Secrets（用于发布到应用商店）：

路径：`Settings -> Secrets and variables -> Actions -> New repository secret`

**必需的 Secrets**：
- `LAZYCAT_USERNAME`：懒猫开发者账号用户名
- `LAZYCAT_PASSWORD`：懒猫开发者账号密码


![Shot 2026.01.03 at 15.47.38.png](https://dl.playground.lazycat.cloud/guidelines/703/974238ec-207d-41ed-acdc-58a2f23f4576.png "Shot 2026.01.03 at 15.47.38.png")

**组织级别配置**（推荐）：
如果你在一个组织下维护多个项目，建议在组织级别配置 Secrets，避免逐仓库重复设置。

路径：`https://github.com/organizations/YOUR_ORG/settings/secrets/actions`

### 触发规则

模板提供的默认触发规则：

**LPK 打包工作流**（`lpk-package.yml`）：
- Push 到 `main` 分支 → 构建 LPK，上传为 Artifact
- 创建新的 Tag → 构建 LPK，**自动发布到应用商店**
- 手动触发（`workflow_dispatch`）

**自定义触发规则**：

触发层工作流可以根据需要修改，同步时不会被覆盖：

```yaml
# .github/workflows/lpk-package.yml
on:
  push:
    branches:
      - main
      - develop  # 添加 develop 分支也触发构建
  pull_request:
    branches:
      - main     # 添加 PR 时也构建（但不发布）
```

### 发布流程

#### 日常开发提交

```bash
git add .
git commit -m "feat: add new feature"
git push origin main
```

- ✅ CI 会自动构建 LPK 包
- ✅ 构建产物上传为 GitHub Artifacts
- ❌ **不会**发布到应用商店

![Shot 2026.01.03 at 15.50.48.png](https://dl.playground.lazycat.cloud/guidelines/703/05360188-4188-4f1c-bda7-a361b6bc3e31.png "Shot 2026.01.03 at 15.50.48.png")

#### 发布新版本到应用商店

```bash
# 创建版本标签
git tag v1.0.0
git push origin v1.0.0
```

- ✅ CI 会自动构建 LPK 包
- ✅ **自动发布到懒猫应用商店**

**重要提示**：只有推送 Tag 时才会触发发布流程，日常 push 到分支只会构建但不发布。


![Shot 2026.01.03 at 15.50.06.png](https://dl.playground.lazycat.cloud/guidelines/703/221d1131-9e9e-4182-a390-3e73d07def19.png "Shot 2026.01.03 at 15.50.06.png")

### 查看构建状态

在 GitHub 仓库的 Actions 标签页查看工作流执行状态：

```
https://github.com/YOUR_USERNAME/YOUR_PROJECT/actions
```

- 绿色勾号：构建成功
- 红色叉号：构建失败，点击查看日志
- 黄色圆点：正在构建

### 下载构建产物

非发布版本的构建产物会保存在 Artifacts 中：

1. 进入 Actions 标签页
2. 选择对应的工作流运行
3. 在页面底部的 Artifacts 区域下载 LPK 文件

## 模板升级与同步

### 为什么需要同步？

[hack 仓库](https://github.com/lazycatapps/hack) 的模板会持续改进，可能包括：
- 新功能：支持新的构建选项、新的工作流
- Bug 修复：修复构建脚本中的错误
- 性能优化：提升构建速度、减少资源消耗
- 安全更新：修复安全漏洞

通过同步，你的项目可以低成本地获得这些改进。

**关注仓库更新**：建议 Watch 或 Star https://github.com/lazycatapps/hack 以获得最新改进通知。

### 同步方式

#### 方法 1：使用 Make 命令（推荐）

```bash
# 在项目根目录执行
make config-sync
```

默认会同步所有文件，触发层工作流保持不变。

![Shot 2026.01.03 at 15.51.26.png](https://dl.playground.lazycat.cloud/guidelines/703/abf3c489-ed21-4318-86c9-507e01cb2e17.png "Shot 2026.01.03 at 15.51.26.png")

#### 方法 2：使用脚本直接同步

```bash
bash  Secrets and variables -> Actions -> Variables
   REGISTRY = registry.cn-hangzhou.aliyuncs.com/my-namespace
   ```

2. 或者在 Makefile 中直接设置：
   ```makefile
   REGISTRY := registry.cn-hangzhou.aliyuncs.com/my-namespace
   ```

3. 配置对应的 Docker Hub Secrets：
   - `DOCKERHUB_USERNAME`：你的阿里云账号
   - `DOCKERHUB_TOKEN`：你的阿里云访问令牌

### Q7：如何添加自定义的清理规则？

**场景**：你的项目生成了一些额外的临时文件，想在 `make clean` 时一并清理。

**解决方案**：在 Makefile 中设置 `CLEAN_EXTRA_PATHS`：

```makefile
PROJECT_NAME := my-app
PROJECT_TYPE := lpk-only

# 添加额外的清理路径
CLEAN_EXTRA_PATHS := temp/ logs/ *.log

include base.mk
```

### Q8：本地安装的 LPK 包在哪里？

base.mk 中的 `deploy` 目标会自动选择可用的安装工具：

**使用 lpk-manager**（推荐）：
```bash
# 列出已安装的应用
lpk-manager list

# 应用数据目录
~/lpk/apps//
```

**使用 lzc-cli**：
```bash
# 安装和卸载命令已在 make deploy / make uninstall 中集成
# lzc-cli 会根据你的 Box 配置确定数据目录
```

### Q9：同步后触发层工作流丢失了怎么办？

**原因**：使用了 `--sync-include-init` 选项。

**解决方案**：

方法 1：从备份恢复
```bash
cp .github/workflows.backup/docker-image.yml .github/workflows/
```

方法 2：从模板重新下载
```bash
curl -fsSL https://raw.githubusercontent.com/lazycatapps/hack/main/workflows/docker-lpk/docker-image.yml \
  -o .github/workflows/docker-image.yml
```

方法 3：重新初始化（仅复制缺失的触发层）
```bash
bash <(curl -fsSL https://raw.githubusercontent.com/lazycatapps/hack/main/scripts/lazycli.sh) \
  --sync --sync-target workflows --sync-workflow-type docker-lpk
```

### Q10：如何为不同环境（开发/生产）使用不同配置？

**建议的做法**：

1. 使用环境变量：
   ```bash
   # 本地开发
   export ENV=dev
   make docker-run

   # 生产环境
   export ENV=prod
   make docker-run
   ```

2. 在 Makefile 中根据环境变量调整参数：
   ```makefile
   ENV ?= dev

   ifeq ($(ENV),prod)
       DOCKER_RUN_ARGS := -p 80:80 --restart always
   else
       DOCKER_RUN_ARGS := -p 8080:80
   endif

   include base.mk
   ```

3. 在 CI 中使用不同的工作流文件：
   - `.github/workflows/deploy-dev.yml`
   - `.github/workflows/deploy-prod.yml`

### Q11：官方模板不满足需求，可以自定义吗？

**可以！** 高级用户可以 fork hack 仓库并自定义：

**步骤**：
1. Fork https://github.com/lazycatapps/hack 到你的账号
2. 修改 `base.mk`、工作流模板等以满足你的需求
3. 使用 `HACK_REPO_MODE=local` 或自定义 `LAZYCLI_SYNC_SCRIPT_URL` 使用你的模板

**详细方法**：见"总结"部分的"进阶选项"

**贡献建议**：
如果你的改进具有通用性，欢迎提交 PR 到上游仓库！我们欢迎在不破坏已有兼容性的前提下，满足更多场景的贡献。

## 总结

通过本指南，你应该已经掌握：

1. ✅ 如何快速创建新的 LPK 项目
2. ✅ 如何将现有项目迁移到模板
3. ✅ 如何在本地开发和测试
4. ✅ 如何配置 GitHub Actions 自动构建
5. ✅ 如何同步模板获得最新改进
6. ✅ 如何解决常见问题

### 下一步

- **加入社区**：与其他开发者交流使用经验
- **贡献模板**：发现问题或有改进建议？欢迎提交 Issue 或 Pull Request
  - 在不破坏已有兼容性的前提下，我们欢迎满足更多场景的 PR
- **查看官方文档**：深入了解懒猫微服平台能力

### 进阶选项

**构建你自己的 hack 仓库**

如果官方模板不能完全满足你的需求，高级用户可以 fork 本仓库并自定义：

1. **Fork 仓库**：
   ```bash
   # Fork https://github.com/lazycatapps/hack 到你的账号
   git clone https://github.com/YOUR_USERNAME/hack.git
   ```

2. **自定义模板**：
   - 修改 `base.mk` 添加你的通用目标
   - 调整工作流模板适配你的 CI 需求
   - 添加你组织特有的配置文件

3. **使用自定义模板**：
   ```bash
   # 方法 1: 使用本地 hack 仓库
   cd ../your-project
   HACK_REPO_MODE=local ../hack/scripts/lazycli.sh --sync

   # 方法 2: 修改同步 URL
   LAZYCLI_SYNC_SCRIPT_URL=https://raw.githubusercontent.com/YOUR_USERNAME/hack/main/scripts/lazycli.sh \
     make config-sync
   ```

4. **保持与上游同步**：
   ```bash
   cd hack
   git remote add upstream https://github.com/lazycatapps/hack.git
   git fetch upstream
   git merge upstream/main
   ```

**贡献回上游**

如果你的改进具有通用性，我们非常欢迎你提交 Pull Request 到 https://github.com/lazycatapps/hack：
- 确保不破坏现有项目的兼容性
- 添加必要的文档说明
- 在 PR 中描述你的使用场景和改进点
- 提交地址：https://github.com/lazycatapps/hack/pulls

这样整个社区都能受益于你的贡献！

### 相关链接

- **hack 仓库**：https://github.com/lazycatapps/hack
  - 项目主页：https://github.com/lazycatapps/hack
  - 提交 Issue：https://github.com/lazycatapps/hack/issues
  - 提交 PR：https://github.com/lazycatapps/hack/pulls
- **懒猫 CLI**：`npm info @lazycatcloud/lzc-cli`
- **docker2lzc 工具**：
  - NPM：https://www.npmjs.com/package/docker2lzc
  - Gitee：https://gitee.com/fzlrkj/docker2lzc
- **GitHub Actions 文档**：https://docs.github.com/actions

---

**祝开发愉快！** 🚀

如有问题或建议，请在 [hack 仓库](https://github.com/lazycatapps/hack/issues) 提交 Issue。