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

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

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

参考 使用 Github Actions 实现 Docker 应用的自动更新和发布

目录

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

前提条件

账号要求

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

技术要求

需要具备以下基础知识：

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

工具安装

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

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

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

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

验证工具安装：

# 在项目初始化后可以运行
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 结尾：

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

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

项目中覆写：

# 项目的 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. 一键升级模板

如何实现：

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 <(curl -fsSL https://raw.githubusercontent.com/lazycatapps/hack/main/scripts/lazycli.sh)

脚本会引导你：

1. 选择项目类型（lpk-only / docker-lpk）
2. 输入项目名称
3. 确认配置
4. 是否初始化 Git 仓库

执行后会在当前目录创建项目文件夹。

方法 2：快速模式（推荐熟练用户）

如果你已经知道要创建什么类型的项目，可以直接指定参数：

# 创建 LPK 项目
bash <(curl -fsSL https://raw.githubusercontent.com/lazycatapps/hack/main/scripts/lazycli.sh) \
  --type lpk-only --name my-cli-tool

# 创建 Docker + LPK 项目
bash <(curl -fsSL https://raw.githubusercontent.com/lazycatapps/hack/main/scripts/lazycli.sh) \
  --type docker-lpk --name my-web-service

方法 3：自定义应用 ID 前缀

默认应用 ID 前缀为 cloud.lazycat.app.，如果你需要自定义：

# 设置自定义应用 ID 前缀
APP_ID_PREFIX="com.mycompany.app." \
  bash <(curl -fsSL https://raw.githubusercontent.com/lazycatapps/hack/main/scripts/lazycli.sh) \
  --type lpk-only --name my-tool

生成的应用 ID 将会是：com.mycompany.app.my-tool

初始化后的项目结构

my-project/
├── .github/
│   └── workflows/           # GitHub Actions 工作流
│       ├── cleanup-artifacts.yml        # 定期清理旧构建产物 [⚠️ 同步时覆盖]
│       ├── reusable-lpk-package.yml    # LPK 打包复用层 [⚠️ 同步时覆盖]
│       └── lpk-package.yml             # LPK 打包触发层 [✅ 可自定义]
│       # docker-lpk 项目还包括:
│       ├── docker-image.yml            # Docker 镜像构建触发层 [✅ 可自定义]
│       ├── reusable-docker-image.yml   # Docker 镜像构建复用层 [⚠️ 同步时覆盖]
│       └── cleanup-docker-tags.yml     # 清理旧 Docker 标签 [⚠️ 同步时覆盖]
├── base.mk                  # 核心 Makefile [⚠️ 不要修改，同步时覆盖]
├── Makefile                 # 项目 Makefile [✅ 可自定义，不会被覆盖]
├── lzc-build.yml            # 懒猫构建配置 [✅ 可自定义]
├── lzc-manifest.yml         # 应用清单 [✅ 项目文件，需手动创建]
├── icon.png                 # 应用图标 [✅ 项目文件，替换为你的图标]
├── .gitignore               # Git 忽略配置 [⚠️ 缺失时恢复]
├── .editorconfig            # 编辑器配置 [⚠️ 缺失时恢复]
└── README.md                # 项目说明 [✅ 项目文件]

文件说明：

• [⚠️ 同步时覆盖]：这些文件由模板维护，执行 make config-sync 时会自动更新，不要手动修改
• [✅ 可自定义]：这些文件可以根据项目需要自定义，同步时不会被覆盖
• [⚠️ 缺失时恢复]：通常不需要修改，如果文件缺失会从模板恢复
• [✅ 项目文件]：项目自有文件，不受模板同步影响

后续步骤

1. 进入项目目录：

   cd my-project
   

2. 创建应用清单：
   创建 lzc-manifest.yml 文件，定义应用的元数据、权限等信息。

   提示：如果你需要将 Docker Compose 应用转换为懒猫应用，可以使用 docker2lzc 工具辅助生成清单文件：

   • NPM：https://www.npmjs.com/package/docker2lzc
   • Gitee：https://gitee.com/fzlrkj/docker2lzc

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

4. 本地测试：

   # 查看可用命令
   make help
   
   # 查看项目信息
   make info
   
   # 构建 LPK
   make lpk
   
   # 构建并安装到本地验证
   make deploy
   
   # 卸载应用（保留数据）
   make uninstall
   

5. 推送到 GitHub：

   git remote add origin https://github.com/yourusername/my-project.git
   git push -u origin main
   

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

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

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

步骤 1：备份现有配置

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

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

步骤 2：执行同步

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

cd your-existing-project

# 同步所有文件
bash <(curl -fsSL https://raw.githubusercontent.com/lazycatapps/hack/main/scripts/lazycli.sh) --sync

同步时会提示你选择要同步的内容：

1. 全部文件（All files）
2. 仅 Makefile（Makefile only）
3. 仅工作流（Workflows only）
4. 仅通用配置（Common configs only）

重要提示：

• 只要是非全部文件 就 不会覆盖触发层工作流（如 lpk-package.yml），以保留你的自定义配置
• 复用层工作流（如 reusable-lpk-package.yml）会被更新
• 如果你想完全重置为模板初始状态，使用 --sync-include-init 或选择上面的 全部文件：

bash <(curl -fsSL https://raw.githubusercontent.com/lazycatapps/hack/main/scripts/lazycli.sh) \
  --sync --sync-include-init

步骤 3：非交互式同步（适合脚本）

如果你在 CI 或脚本中执行同步，可以使用非交互模式：

# 仅同步工作流，指定项目类型
bash <(curl -fsSL https://raw.githubusercontent.com/lazycatapps/hack/main/scripts/lazycli.sh) \
  --sync --sync-target workflows --sync-workflow-type docker-lpk

# 仅同步 Makefile
bash <(curl -fsSL https://raw.githubusercontent.com/lazycatapps/hack/main/scripts/lazycli.sh) \
  --sync --sync-target makefile

# 仅同步通用配置文件（.gitignore、.editorconfig 等）
bash <(curl -fsSL https://raw.githubusercontent.com/lazycatapps/hack/main/scripts/lazycli.sh) \
  --sync --sync-target configs

短参数版本：

# 使用短参数（推荐脚本使用）
bash <(curl -fsSL https://raw.githubusercontent.com/lazycatapps/hack/main/scripts/lazycli.sh) \
  -s -T workflows -W docker-lpk

步骤 4：恢复自定义配置

同步完成后，检查并恢复你需要保留的自定义部分：

# 对比备份文件
diff Makefile.backup Makefile
diff -r .github/workflows.backup .github/workflows

# 有选择地恢复必要的自定义

步骤 5：验证

# 查看可用目标
make help

# 检查项目信息
make info

# 测试构建
make lpk

日常开发流程

本地开发循环

# 1. 编写代码或修改配置
vim lzc-manifest.yml

# 2. 本地构建测试
make lpk

# 3. 安装到本地验证功能
make deploy

# 4. 卸载测试（保留数据）
make uninstall

# 5. 完全卸载（清除数据）
make uninstall-clean

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

其他可用命令

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

make help

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

版本管理

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

# 查看当前版本
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：懒猫开发者账号密码

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

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

触发规则

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

LPK 打包工作流（lpk-package.yml）：

• Push 到 main 分支 → 构建 LPK，上传为 Artifact
• 创建新的 Tag → 构建 LPK，自动发布到应用商店
• 手动触发（workflow_dispatch）

自定义触发规则：

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

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

发布流程

日常开发提交

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

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

发布新版本到应用商店

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

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

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

查看构建状态

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

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

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

下载构建产物

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

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

模板升级与同步

为什么需要同步？

hack 仓库 的模板会持续改进，可能包括：

• 新功能：支持新的构建选项、新的工作流
• Bug 修复：修复构建脚本中的错误
• 性能优化：提升构建速度、减少资源消耗
• 安全更新：修复安全漏洞

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

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

同步方式

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

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

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

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

bash <(curl -fsSL https://raw.githubusercontent.com/lazycatapps/hack/main/scripts/lazycli.sh) --sync

方法 3：选择性同步

# 仅同步 Makefile
make config-sync SYNC_TARGET=makefile

# 仅同步工作流
make config-sync SYNC_TARGET=workflows

# 仅同步通用配置
make config-sync SYNC_TARGET=configs

方法 4：完全重置（包括触发层）

bash <(curl -fsSL https://raw.githubusercontent.com/lazycatapps/hack/main/scripts/lazycli.sh) \
  --sync --sync-include-init

警告：这会覆盖你对触发层工作流的自定义，请谨慎使用。

同步策略说明

模板采用分层同步策略：

文件类型	是否可修改	默认同步行为	包含 --sync-include-init
base.mk	❌ 不要修改	总是更新	总是更新
复用层工作流(reusable-*.yml)	❌ 不要修改	总是更新	总是更新
触发层工作流(lpk-package.yml 等)	✅ 可自定义	保留不覆盖	覆盖为模板版本
通用配置文件(.gitignore 等)	⚠️ 通常不改	仅在缺失时创建	总是更新
项目 Makefile	✅ 可自定义	仅在缺失时创建	覆盖为模板版本
项目文件(lzc-manifest.yml 等)	✅ 项目文件	不受影响	不受影响

⚠️ 重要提醒：

• 不要修改 base.mk：此文件会在每次同步时被覆盖，你的修改会丢失。如需自定义构建行为，请在项目的 Makefile 中覆写目标。
• 不要修改复用层工作流：以 reusable- 开头的工作流文件会在同步时被覆盖。如需自定义 CI 行为，请修改触发层工作流。
• 触发层工作流可以修改：lpk-package.yml、docker-image.yml 等触发层文件可以自由修改，默认同步不会覆盖。

这种设计允许你：

• 自定义触发条件（何时触发构建）
• 自定义构建参数（传递给复用层）
• 同时保持构建逻辑与模板同步

检查模板版本

# 查看当前 base.mk 版本
make base-mk-version

输出示例：

[INFO] base.mk version: 2025-11-01 11:00:00

常见问题

Q1：如何在浏览器上直接修改文件完成版本更新？

场景：你只需要修改应用的配置文件或清单，不想在本地克隆整个仓库。

步骤：

1. 在 GitHub 网页上导航到需要修改的文件（如 lzc-manifest.yml）
2. 点击右上角的编辑按钮（铅笔图标）
3. 修改文件内容（如更新版本号、描述等）
4. 填写 Commit 信息，直接提交到 main 分支
5. GitHub Actions 会自动触发构建流程
6. 如果想发布新版本，在网页上创建新的 Release，打上 Tag

注意：这种方式适合小的配置修改，如果涉及代码逻辑修改，建议在本地完整测试后再推送。

Q2：lzc-cli box default 无法检测到 Box 名称怎么办？

原因：未安装 lzc-cli 或未配置默认 Box。

解决方案：

方法 1：手动设置环境变量

export LAZYCAT_BOX_NAME=your-box-name
export REGISTRY=registry.your-box-name.heiyu.space
make info

方法 2：在 Makefile 中设置

LAZYCAT_BOX_NAME := your-box-name
REGISTRY := registry.your-box-name.heiyu.space

方法 3：安装并配置 lzc-cli

npm install -g @lazycatcloud/lzc-cli
lzc-cli box set-default your-box-name

Q3：如何覆盖 base.mk 中的默认目标？

场景：你想自定义某个 Make 目标的行为，比如在 lpk 之前先运行测试。

⚠️ 重要：不要直接修改 base.mk 文件，它会在同步时被覆盖！

正确做法：在项目的 Makefile 中定义同名目标（不带 -default 后缀）：

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

include base.mk

# 覆盖默认的 lpk 目标
lpk: test-default
	@echo "Running custom lpk build with tests"
	lzc-cli project build

工作原理：

• base.mk 中所有默认目标都以 -default 结尾
• 文件末尾的 %: %-default 规则负责路由
• 当你定义 lpk 目标时，会优先使用你的定义
• 更新 base.mk 不会影响你在 Makefile 中的覆写

Q4：构建失败，如何调试？

步骤：

1. 查看 CI 日志：

   • 进入 GitHub Actions 标签页
   • 点击失败的工作流
   • 展开失败的步骤查看详细日志

2. 本地复现：

   # 清理旧产物
   make clean
   
   # 重新构建
   make lpk
   
   # 查看详细错误信息
   

3. 检查工具版本：

   make check-tools
   lzc-cli --version
   docker --version
   

4. 检查清单文件：

   # 验证 lzc-manifest.yml 格式
   cat lzc-manifest.yml
   

Q5：如何管理多个应用包项目？

建议的目录结构：

workspace/
├── hack/                  # 克隆模板仓库(可选)
├── app1-cli-tool/
├── app2-web-service/
├── app3-backend-api/
└── scripts/
    └── sync-all.sh        # 批量同步脚本

批量同步脚本示例（scripts/sync-all.sh）：

#!/bin/bash

PROJECTS=(
  "app1-cli-tool"
  "app2-web-service"
  "app3-backend-api"
)

for project in "${PROJECTS[@]}"; do
  echo "Syncing $project..."
  cd "$project"
  make config-sync
  cd ..
done

Q6：如何在 CI 中使用不同的 Docker 仓库？

场景：你想使用私有 Docker 仓库或阿里云容器镜像服务。

解决方案：

1. 在仓库变量中设置 REGISTRY：

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

2. 或者在 Makefile 中直接设置：

   REGISTRY := registry.cn-hangzhou.aliyuncs.com/my-namespace
   

3. 配置对应的 Docker Hub Secrets：

   • DOCKERHUB_USERNAME：你的阿里云账号
   • DOCKERHUB_TOKEN：你的阿里云访问令牌

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

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

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

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

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

include base.mk

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

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

使用 lpk-manager（推荐）：

# 列出已安装的应用
lpk-manager list

# 应用数据目录
~/lpk/apps/<app-id>/

使用 lzc-cli：

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

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

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

解决方案：

方法 1：从备份恢复

cp .github/workflows.backup/docker-image.yml .github/workflows/

方法 2：从模板重新下载

curl -fsSL https://raw.githubusercontent.com/lazycatapps/hack/main/workflows/docker-lpk/docker-image.yml \
  -o .github/workflows/docker-image.yml

方法 3：重新初始化（仅复制缺失的触发层）

bash <(curl -fsSL https://raw.githubusercontent.com/lazycatapps/hack/main/scripts/lazycli.sh) \
  --sync --sync-target workflows --sync-workflow-type docker-lpk

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

建议的做法：

1. 使用环境变量：

   # 本地开发
   export ENV=dev
   make docker-run
   
   # 生产环境
   export ENV=prod
   make docker-run
   

2. 在 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 仓库：

   # Fork https://github.com/lazycatapps/hack 到你的账号
   git clone https://github.com/YOUR_USERNAME/hack.git
   

2. 自定义模板：

   • 修改 base.mk 添加你的通用目标
   • 调整工作流模板适配你的 CI 需求
   • 添加你组织特有的配置文件

3. 使用自定义模板：

   # 方法 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. 保持与上游同步：

   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 仓库 提交 Issue。