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. 明确制作完成与上线的区别
主题制作完成需要有证据地通过五个阶段：
PRECHECK：目录与 CLI 能力检查。SCAFFOLDED：官方脚手架生成。DESIGNED：完成所需视觉与布局。LOCAL_VERIFIED：平台本地检查通过。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 可以辅助写代码和验证，但本地制作、模拟验收、真实站点验收与线上切换是不同步骤，不能互相替代。