首页 / Zlooks:程序介绍与安装指南

Zlooks:程序介绍与安装指南

了解 Zlooks 的功能、环境要求与安装部署流程,以及如何连接 Finch 管理站点、创建和验证自己的博客主题。

Zlooks:程序介绍与安装指南

Zlooks 是一套基于 TypeScript 和 Hile 构建的模块化站点程序。你可以用它搭建自己的博客,发布文章与单页,管理分类、标签、评论、友情链接和图片,并通过 Finch 中的 Zlooks Admin 小程序管理内容。

项目采用 Lerna、Nx 与 pnpm workspaces 组织代码。各内部服务通过 Hile Registry 发现与协作,由统一 Gateway 对外提供访问入口。

你可以用它做什么

  • 搭建个人博客:管理文章、分类、标签、评论和友情链接。
  • 发布独立单页:编写关于、程序介绍等内容。
  • 管理用户与登录:提供邮箱密码登录、邮箱验证码登录、注册及找回密码。
  • 管理图片资源:存储图片文件与元数据,并提供公开读取能力。
  • 使用 AI 辅助管理:通过 Zlooks Admin 连接 Gateway MCP,在 Finch 中管理站点内容。
  • 按需扩展:例如安装可选的百度链接提交服务。

获取与安装方式

线上部署通过 npm 安装 Zlooks CLI,再由 CLI 安装和管理服务,无需先下载整个源码仓库。

本文以新站点安装为主。请准备好服务器、数据库连接信息和计划使用的访问地址;不要把数据库密码、邮件凭据或 MCP Token 发到聊天或公开日志中。

一、准备运行环境

安装前需要准备:

  • Node.js 24 或更高版本。
  • PostgreSQL:持久化业务数据。
  • Redis:保存短期认证状态,并用于分布式锁与限流。
  • Hile Registry:服务发现与配置基础设施,下面会说明安装方式。

先确认 PostgreSQL 和 Redis 已启动,并且部署机器能够访问。线上环境还应准备域名与 HTTPS;涉及邮件验证码和找回密码时,需要配置可用的邮件投递服务。

二、安装 CLI、PM2 和 Registry

安装 Zlooks CLI 与进程管理工具 PM2:

npm install --global pm2 @zlooks.cn/cli
zlooks --version

单独安装提供 Registry 的 Hile CLI:

npm install --global @hile/cli
hile --version

三、生成站点配置

运行交互式配置:

zlooks setup

按提示配置 Registry、PostgreSQL、Redis、公共访问地址、Gateway 和邮件等项目。

配置过程会创建:

  • ~/.zlooks.cn/.env:Registry 地址、npm 源和正式/测试发布通道。
  • ~/.registry/configs/zlooks.cn.config.yaml:数据库、Redis、公共 Origin、Gateway 与邮件配置。

服务专属配置由对应服务命令维护。请妥善保护这些文件,不要提交到公开代码仓库。

四、启动 Hile Registry

临时测试可在前台运行,运行期间需要保留终端:

hile registry

长期部署建议交由 PM2 托管。前台与 PM2 两种方式选一种,不要重复启动同一监听地址:

pm2 start hile \
  --name hile-registry \
  --namespace hile \
  -- registry

pm2 status
pm2 logs hile-registry

默认监听 127.0.0.1:9876,成功日志为 registry started on port 9876。

如果配置了其他监听地址或端口,在命令的 registry 后追加 --host <地址> --port <端口>。REGISTRY_HOST 必须能连接该监听地址,REGISTRY_PORT 必须与监听端口一致。跨主机部署时,使用服务节点能够访问的实际地址。

如需开机恢复,运行:

pm2 startup

按终端输出执行对应的系统命令。全部服务安装并启动完成后,再执行本文验证步骤中的 pm2 save 保存进程清单。

五、安装并启动站点服务

确保 Registry、PostgreSQL 和 Redis 均可访问,然后按顺序执行:

zlooks install @zlooks.cn/password-auth-server --skip-start
zlooks-password-auth-server config
zlooks install
zlooks restart @zlooks.cn/password-auth-server

首次安装先配置密码服务的验证码密钥,再安装其余内置服务。zlooks install 中可按提示启动服务,最后一条命令启动或重启密码服务及缺失的已安装依赖。

已有密码认证配置时,无需重复运行 config。替换密钥会使尚未完成的验证码失效。

安装列表中:

  • 九个内置服务为必装项,默认选中且不可取消。
  • 已全局安装的项目不会再次显示。
  • 百度链接提交服务为可选项,默认不选。
  • 选中可选服务后,应先完成其配置,再启动。

若希望显式跳过最后的启动询问,可使用 zlooks install --start;但它不能替代可选服务的配置步骤。

六、验证安装

检查服务和进程:

zlooks service list
pm2 list

浏览器访问 zlooks setup 中设置的 public-host.origin,默认是:

http://127.0.0.1:3000

这是部署机器的本地地址;其他设备访问时,应使用已配置并可连通的站点地址。

确认服务正常后,保存 PM2 进程清单:

pm2 save

建议继续验证首页访问、文章阅读,以及已配置的登录和邮件功能。仅看到进程在线,不代表所有业务功能都已验证完成。

七、可选:连接 Finch 管理站点

Zlooks 提供 Zlooks Admin 小程序,通过 Gateway 的统一 MCP 接口管理博客内容。

尚未安装 Finch?请前往 Finch 官网 或 下载页面,选择适合你操作系统的安装包。

前提条件:

  • Finch 1.6.1 或更高版本。
  • Finch 能够访问你的 Zlooks 地址。
  • 已准备 Gateway 配置中的 MCP Bearer Token。

安装小程序:

npx --yes @finchtoys/minitools add @zlooks.cn/finch

安装后,在 Finch 的「小程序」中启用 Zlooks Admin,授予所需权限,再打开设置菜单中的「配置连接」:

  • MCP 地址:你的 Gateway 公网地址加 /mcp,例如 https://你的域名/mcp。
  • Bearer Token:填写 Gateway 配置使用的 MCP Bearer Token。

线上连接必须使用 HTTPS。Token 只应填写到 Finch 的加密 Secrets 输入框,不要发送到对话、截图、日志或普通配置文件中。

连接成功后应显示「连接正常」。遇到问题可使用「连接诊断」;如果设置菜单暂不可用,可关闭小程序后重新启用。

更新小程序:

npx --yes @finchtoys/minitools update zlooks-admin

八、日常更新与回滚

更新前确保 Registry、PostgreSQL、Redis 均可访问,且当前 Zlooks 进程全部为 online。

先创建回滚点,再停止服务并更新:

zlooks deploy start
zlooks deploy status
zlooks stop
zlooks update

zlooks update 会展示版本与更新计划,在确认后安装,但不会自动重启服务。

若版本说明没有要求迁移数据,直接恢复运行:

zlooks restart

若版本说明明确要求迁移,先单独备份 PostgreSQL,在服务保持停止时执行:

zlooks db migrate
zlooks restart

检查进程、日志与站点功能:

pm2 list
pm2 logs --nostream --lines 100

确认正常后完成部署,删除本次回滚点:

zlooks deploy complete

若更新或重启失败,保留回滚点并执行:

zlooks deploy rollback
pm2 list

回滚会恢复 npm 包版本和 PM2 服务拓扑,但不会回滚数据库迁移、.env 或 Registry YAML 配置。执行迁移前必须单独备份数据库,并确认迁移的回退方案。

可选服务

百度链接提交需单独安装、配置并启用。它记录提交接口的处理结果,accepted 不代表已被百度收录;启用前还需评估其传统 HTTP 提交端点带来的 Token 网络传输风险。

需要启用百度链接提交时,请按对应版本 README 中的完整流程操作。

九、创建自己的博客主题

Zlooks 的主题不是一份配色文件,而是独立的主题服务包。它负责博客的视觉、布局和交互,通过官方 SDK 获取内容,并由 Gateway 承载页面。

主题开发应以部署版本的 MCP 契约为准。Zlooks Admin 连接成功后,可通过 MCP 获取:

  • 开发契约 Resource:hile://blog/theme-authoring-contract。
  • 完整创建工作流 Prompt:blog.create-blog-theme。
  • 主题目录 Resource:hile://blog/themes。
  • 切换工作流 Prompt:blog.switch-blog-theme。

这些是 MCP 资源与工作流名称,不是终端命令。开发前先读取实时契约,不要只凭本文或旧的示例猜测接口。

1. 确定主题信息

准备以下信息:

  • 主题 ID:例如 my-theme。
  • 显示名称:例如「我的主题」。
  • 描述与设计要求:配色、布局、字体风格、移动端体验等。
  • 本地目录:选择一个不存在的新目录,避免覆盖已有文件。

第三方主题包名遵循 zlooks-theme-<themeId>-server。例如,上述主题对应 zlooks-theme-my-theme-server;@zlooks.cn/* 是官方保留 scope,不应用于自己的主题包。

2. 使用官方脚手架

先检查 CLI 是否支持主题命令:

zlooks theme --help

确认有 create 和 verify 后,在计划存放项目的父目录执行:

zlooks theme create my-theme 'zlooks-theme-my-theme-server' \
  --display-name '我的主题' \
  --description '清爽、注重阅读体验的个人博客主题'

cd zlooks-theme-my-theme-server

如果 CLI 不支持这些命令,应先确认当前 npm 源中可用的最新正式版 CLI;不能用手写的猜测项目代替官方脚手架。

3. 调整设计,保留完整能力

脚手架只是起点。可以调整生成项目中的 JSX、Ant Design 组件组合与 theme.css,但不能为了视觉简化而删除功能或替换为假数据。

主题需保留以下七类页面:

页面对外路径
博客首页/blog
文章详情/blog/posts/[slug]
文章归档/blog/archives
独立单页/blog/pages/[slug]
分类文章/blog/categories/[slug]
标签文章/blog/tags/[slug]
友情链接/blog/friends

每条路由都需要独立的 metadataEntry,提供标题、描述、canonical 等文档元数据。

数据和运行时遵循官方边界:

  • 服务端首屏数据使用 @zlooks.cn/blog-theme/rsc。
  • Node/Hile 启动使用 @zlooks.cn/blog-theme/runtime。
  • 浏览器交互在 'use client' 文件中通过 @zlooks.cn/blog-theme/client 的 createBlogThemeClient 完成。
  • 保留搜索、点赞、取消点赞、读取评论与提交评论能力;只有已登录用户可提交评论。
  • 使用共享 UI 的用户入口、站点配置、导航及浅色/深色/自动三态偏好,不另造认证或主题状态。
  • Markdown 禁用 raw HTML,不使用 dangerouslySetInnerHTML 渲染正文。
  • 不新增独立的公网 HTTP、Next 或 MCP 监听器,不直连业务数据库、Redis、Registry 或内部 Micro 接口。

侧边栏单页也属于验收范围:首页应展示 sidebarPages 中每个页面的真实标题、摘要和链接;顶部导航与侧边栏位置按模型分别处理,不能把所有单页都放进顶部导航。

4. 执行本地验证

在主题目录执行:

zlooks theme verify . --json

平台检查依次覆盖项目结构、依赖安装、测试、类型检查、构建与 RSC 产物验证,并实际打包检查发布内容。

只有结果满足 ok=true、stage=LOCAL_VERIFIED,且 artifact.verified 与 package.packed 通过,才继续运行验证。自己编写的测试不能代替平台检查。

5. 启动本地预览

pnpm run dev

该脚本调用 btp,不是 btp start。它使用生产兼容的 RSC 构建,运行真实 Gateway 与当前主题,并提供模拟博客、用户和站点配置;预览本身不需要 PostgreSQL 或 Redis。

预览仅允许本地 loopback Registry 和本地 public-host Origin。请使用隔离的本地开发配置,不要为了预览修改线上配置;同一本地环境中与模拟能力冲突的真实服务提供者需要先停止。

保持预览进程运行,等待终端显示:

<package> preview ready: <origin>/blog

然后实际打开输出的地址,确认 HTTP 200、当前主题内容正常,以及终端没有 RSC 错误。仅构建成功不代表运行验证通过。

按需检查不同场景,每次先停止上一个预览实例:

# 空数据
pnpm exec btp --scenario empty

# 长标题等边界数据
pnpm exec btp --scenario edge

# 模拟已登录用户
pnpm exec btp --user authenticated

# 模拟用户服务不可用
pnpm exec btp --user unavailable

模拟环境中的评论和点赞只存在于当前预览进程,不代表真实站点的数据或验收结果。

修改源码后,等待 Theme rebuilt; refresh the browser 再刷新页面。每次修复代码后,应重新执行完整本地验证并复验运行时。

6. 明确制作完成与上线的区别

主题制作完成需要有证据地通过五个阶段:

  1. PRECHECK:目录与 CLI 能力检查。
  2. SCAFFOLDED:官方脚手架生成。
  3. DESIGNED:完成所需视觉与布局。
  4. LOCAL_VERIFIED:平台本地检查通过。
  5. RUNTIME_VERIFIED:预览可访问且当前构建正确渲染。

真实内容验收 FUNCTION_VERIFIED 是可选阶段,应单独记录。没有账号、测试文章或写入授权时,标为「未验证」,不能伪造通过,也不必为了完成主题制作创建账号或文章。

制作完成不会自动发布 npm 包、部署到服务器或替换线上主题。需要上线时,另行确认发布和安装方案;待主题服务运行并被 Registry 发现后,读取 hile://blog/themes 检查目标健康状态,再按 blog.switch-blog-theme 工作流确认切换、执行并回读验证。

十、如何利用 Finch 创建主题

1. 准备开发空间与连接

先安装 Finch,并按前文连接 Zlooks Admin。

为主题开发准备一个本地父目录,在 Finch 中建立绑定该目录的 Space,让代码、项目规则与后续修改保持在同一工作区。主题本身应生成到父目录下尚不存在的新子目录。

2. 用自然语言说明需求

可以向 Finch 发送下面这段需求,并替换其中的主题信息:

请通过 Zlooks Admin 的 MCP 读取实时主题开发契约,并获取 blog.create-blog-theme 工作流。我要创建主题 ID 为 my-theme、显示名为「我的主题」的博客主题,生成到当前工作区下尚不存在的 zlooks-theme-my-theme-server 目录。

设计方向:清爽、注重阅读,支持浅色/深色/自动模式;桌面端使用双栏布局,手机端单栏。保留完整页面、搜索、评论、点赞、账户入口、导航和侧边栏单页。

先检查目标目录与 CLI 能力,再使用官方脚手架,完成设计、本地验证和运行预览。请按开发契约记录各阶段证据。不要发布 npm 包、部署线上、切换线上主题或写入真实站点数据;这些操作等我另行确认。

Finch 获取工作流时,需要填写 themeId、displayName 和 description,可补充 targetDirectory 与 gatewayOrigin。其中 Gateway 地址应按实际验收环境提供,不能把线上地址当成本地预览配置。

3. 在预览中迭代

打开 Finch 给出的本地预览地址后,可以继续描述修改要求,例如:

正文区域再窄一些,增加行距;侧边栏保留单页入口,显示标题和摘要;手机端将侧边栏内容放在正文之后。不要删除现有功能,改完重新验证。

也可以提供设计参考图,说明希望借鉴的配色或布局。视觉调整后仍应保留真实数据、交互、响应式与可访问性,并重跑必要验证。

4. 查看报告,再决定上线

要求 Finch 最后分别列出:

  • 五个必需阶段的结果、执行命令及证据。
  • 实际预览地址与当前运行状态。
  • 可选真实内容验收的覆盖情况及未验证项。
  • 尚未执行的发布、部署和主题切换操作。

Finch 可以辅助写代码和验证,但本地制作、模拟验收、真实站点验收与线上切换是不同步骤,不能互相替代。

返回博客 →