懒猫微服开发篇（零）：上架应用需要哪些知识

版本提示
本文记录的是 2025 年写作时的懒猫微服开发环境。lzc-cli 命令、lzc-build.yml / lzc-manifest.yml 字段、基础镜像、OIDC 环境变量、路由方式和应用商店流程都可能随系统与 SDK 更新而变化。动手前请先对照当前官方开发文档，并以本机命令帮助、实际日志和最终生成的配置为准。

懒猫微服的可玩性在于可以让开发人员放开手脚来做一些事情，等于是提供了一个可靠的基础设施。那么理所当然我们可以把开源的知识应用到上面，比如开发或者移植应用，或者干脆部署一些好玩的东西。这在传统 NAS 上实现起来很困难，甚至都没有包管理工具。

我们看一看开发懒猫应用，需要什么样的知识？

那么，开发懒猫微服的应用需要掌握哪些技能呢？

npm

懒猫微服的 CLI 本质上是一个通过 npm 全局安装的工具包，因此掌握一些基本的 npm 使用方法是必要的。

1	npm install -g @lazycatcloud/lzc-cli

这个工具是用 JavaScript 编写的，但如果你只是为了使用而非开发，那么并不需要掌握这门语言。当然，你也可以选择使用 pnpm 或 Yarn 作为包管理工具，或者通过 nvm 来管理 Node.js 版本。

如果在 macOS/Linux 上遇到了权限不足的问题，其实不一定要使用 sudo。默认情况下，npm 的全局目录是 /usr/local，普通用户对其没有写权限。比如可以看到：

 ll /usr/
total 0
drwxr-xr-x  918 root  wheel    29K  6  5 14:05 bin/
drwxr-xr-x   32 root  wheel   1.0K  6  5 14:05 lib/
drwxr-xr-x  417 root  wheel    13K  6  5 14:05 libexec/
drwxr-xr-x    8 root  wheel   256B  6 10 09:31 local/
drwxr-xr-x  230 root  wheel   7.2K  6  5 14:05 sbin/
drwxr-xr-x   43 root  wheel   1.3K  6  5 14:05 share/
drwxr-xr-x    5 root  wheel   160B  6  5 14:05 standalone/
lrwxr-xr-x    1 root  wheel    25B  6  5 14:05 X11@ -> ../private/var/select/X11
lrwxr-xr-x    1 root  wheel    25B  6  5 14:05 X11R6@ -> ../private/var/select/X11

因此我们可以通过设置 npm 的全局安装目录，规避权限问题。在当前用户目录中创建一个文件夹并添加到环境变量中即可：

 npm config get prefix
/usr/local
mkdir ~/.npm_packages
npm config set prefix ~/.npm_packages/
npm config get prefix
/Users/home/.npm_packages

export PATH="$HOME/.npm_packages/bin:$PATH"

开发的技能是可选的，如果你只是移植现有的应用的话，那么具备一些 Docker Compose 的知识就足够了，这个我们后面再说。

如果是开发原创 App，那么无论是 Vue、React、Go 还是 Python 都有用武之地。只要 Web 应用能够在本地运行，或者打包成 Docker 镜像，就能上架商店。相信很多开发者也会接触一些 DevOps 工作，这部分技能可以直接迁移过来。

Linux

很多 NAS 是基于 FreeBSD 或 Linux 改造的，懒猫微服则基于 Debian 12。虽然设计之初面向非专业玩家，但后来也开放了 SSH 和 root 权限，可以像使用其他 Linux 系统一样操作文件、配置网络、查看分区、监控系统负载。

所以不是只有树莓派或者自己笔电装机才能学 Linux，懒猫微服的系统重启之后会复原（除了 root 目录和网络设置），所以请随便折腾。

虽然有了一套很完善的图形客户端，但是相信很多专业的玩家还是更加喜欢用传统 Linux 的方式来看待这个微服，我管他叫做拆解系统设计。

举个例子：用 htop 查看负载、用 nmtui 配置网络、用 lsblk 查看磁盘分区、用 systemctl 设置服务自启。系统定制得够深，内核和 GRUB 这些东西压根不用管，甚至连 Samba、WebDAV 这些服务都不用自己安装。

Docker

Docker 对 NAS 玩家几乎是必需品，无论是群晖还是威联通都绕不开。与传统 NAS 不一样的是，懒猫微服集成了三套 Docker 环境，分别用于系统组件、Playground 和应用商店。

Playground 就是我们通常理解的 Docker 环境，这里叫作 pg-docker，所以需要懂一些 Docker 的知识，比如下载、打包和上传镜像，以及数据卷挂载和 Docker Compose 的使用。

应用商店也是基于 Docker 运行的。

上架软件时有两种方式：

直接打包：一般用于原创应用，或者移植没有现成 Docker 镜像的开源应用。调试时可以使用懒猫内置 Docker Registry 中的镜像进行测试，颇有 VS Code Remote 的风格。这个调试模式叫作 Devshell。
Docker 镜像迁移：一般用于迁移已有的 Docker 镜像。由于国内网络访问境外镜像仓库时可能失败，所以需要先使用懒猫提供的 Docker Registry 复制镜像，再配置目录映射。

OIDC

这部分稍微有点跑题，前面讲的都是传统 DevOps 技能。OIDC 全称 OpenID Connect，是建立在 OAuth 2.0 之上的身份认证协议，常用于单点登录。SAML 也可以用于企业单点登录；OAuth 2.0 本身解决的是授权问题，并不直接说明“访问者是谁”。OIDC 在 OAuth 2.0 之上增加了 ID Token，通常采用 JWT 格式。应用需要验证 ID Token 的签名和声明，再据此确认用户身份。大致流程如下：

OIDC 的基本流程可以拆成用户授权、获取令牌和访问资源三个阶段：