Zlooks Monorepo 架构与部署运维指南

本文介绍基于 Lerna、Nx、pnpm workspaces、TypeScript 和 Hile 的 Zlooks monorepo 架构,涵盖认证、事件总线、Gateway、博客、用户中心、配置管理及基础设施等核心服务与共享包。同时说明 Node.js、PostgreSQL、Redis 和 Hile Registry 环境要求,以及线上安装、旧版数据迁移、Finch 小程序接入、日常更新、回滚和部署验证流程。

Zlooks

基于 Lerna、Nx、pnpm workspaces、TypeScript 和 Hile 的 monorepo。

当前工作区包含:

  • @zlooks.cn/auth-extension-contract:认证扩展发现、事务与可信内部身份凭据协议;当前内部网格不使用扩展签名密钥。
  • @zlooks.cn/public-host-contract:跨服务共享的非敏感公网 Origin Registry 契约,不包含 Gateway 私有监听或认证配置。
  • @zlooks.cn/registry-config:通用 Registry 配置订阅与启动参数解析;具体配置契约由各服务或对应 shared 包负责。
  • @zlooks.cn/event-bus:领域事件定义与严格事件信封基础契约,不包含任何具体领域事件目录。
  • @zlooks.cn/event-client:中心事件服务的稳定 Micro 合约与生产/消费 typed client。
  • @zlooks.cn/event-server:以 PostgreSQL 持久化事件、订阅、租约、重试和 dead letter 的中心内部服务。
  • @zlooks.cn/gateway-server:唯一公网 Gateway,通过 Hile Registry 自动发现并承载内部 RSC 插件和 MCP Provider。
  • @zlooks.cn/global-config-server:通过 MCP 管理版本化全局产品配置,以 PostgreSQL 为真源并向 Registry 发布只读公共快照。
  • @zlooks.cn/global-config-shared:全局配置服务的稳定 namespace、MCP 管理契约与有界 RSC 公共快照。
  • @zlooks.cn/blog-server:博客分类、文章、标签、评论与友情链接的内部服务;领域 Model 由稳定 Micro 用例编排,MCP 与 Browser HOM 适配器共同调用这些 Micro 能力。
  • @zlooks.cn/browser-api:/-/{namespace}/{...paths} Browser Controller 路径、JSON envelope、请求 Context 与 Cookie effect 的通用契约;不维护领域路由或 Browser Provider 目录。
  • @zlooks.cn/user-server:用户、身份、会话与动态认证方式目录的内部控制面,并发布独立用户中心 RSC 组件。
  • @zlooks.cn/user-shared:user-server 的唯一共享边界,提供稳定 namespace、Gateway 调用所需的版本化 Micro wire contract、领域事件定义及其强类型 Consumer 注册方法,不包含认证行为。
  • @zlooks.cn/password-auth-server:邮箱密码登录、邮箱验证码登录、验证邮箱注册、找回密码及独立 RSC 组件的参考扩展。
  • @zlooks.cn/images-server:图片元数据、原图存储、公开二进制读取和 MCP 管理能力的内部服务。
  • @zlooks.cn/sitemap-server:发现各领域 Sitemap Provider、后台聚合并通过稳定 Micro 操作提供站点 Sitemap 的内部服务。
  • @zlooks.cn/baidu-submit-server:可选的百度链接自动提交服务;消费文章发布/公开更新事件并提供 MCP 提交记录查询与显式重试。
  • @zlooks.cn/infrastructure:共享 PostgreSQL、Redis、SMTP 邮件投递等基础设施配置契约与窄适配边界。
  • @zlooks.cn/ui:共享 Ant Design 主题、Provider 契约与可复用业务展示组件。
  • @zlooks.cn/utils:无副作用、无运行时依赖的跨包同步辅助函数。

开发验证

仓库使用 ESLint 9 flat config 统一检查所有 package 的源码、package 测试和根测试:

pnpm lint
pnpm typecheck
pnpm test
pnpm build

pnpm lint:fix 只处理 ESLint 明确支持的安全自动修复,并可能修改源码,运行后必须审查 diff。pnpm release:check 会依次执行发布契约测试、lint、类型检查、测试、构建、RSC 产物验证和真实 tarball 审计。

TypeScript 7 不提供旧版编译器 API,因此 lint 按 TypeScript 官方方案通过 @typescript/typescript6 使用兼容 API;构建和 pnpm typecheck 仍由并行安装的 @typescript/native 7.0.2 执行。

环境要求

  • Node.js 24+
  • Hile Registry(由 @hile/cli 提供,服务启动前必须可访问)
  • PostgreSQL(博客、用户中心与密码凭证的一致性真源)
  • Redis(短期认证状态、分布式锁与限流)

安装

线上部署流程

这种方式适合安装并运行站点。请先准备 PostgreSQL 和 Redis。

1. 安装 Zlooks CLI 和 PM2

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

2. 安装 Hile Registry

Registry 由 @hile/cli 提供,需要单独安装:

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

3. 生成 Registry 和服务配置

运行 Zlooks 交互式配置:

zlooks setup

配置过程会创建以下机器级文件:

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

[!WARNING] 如果需要从旧版 zlooks.cn 迁移数据,zlooks setup 中应为新版配置一个与旧版不同的 PostgreSQL 数据库名。不要让新版服务连接旧版数据库;新版服务启动时会同步当前表结构,可能与旧表发生冲突并导致后续 zlooks export 无法完成。旧版数据库仅作为导出源,新版数据库作为导入目标;应先完成旧版数据导出,再启动新版服务。

4. 启动 Hile Registry

直接启动会占用当前终端:

hile registry

部署时可以交给 PM2 长期托管:

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

pm2 status
pm2 logs hile-registry

如果需要在机器重启后恢复 Registry,先运行 pm2 startup,按其输出执行对应的系统命令,然后保存当前进程清单:

pm2 startup
pm2 save

前台命令应保留当前终端,PM2 命令则会在后台运行。默认监听 127.0.0.1:9876,启动成功时日志会输出 registry started on port 9876。如果 zlooks setup 使用了其他地址或端口,请在上述命令的 registry 后增加 --host <地址> --port <端口>;REGISTRY_HOST 必须能够解析或连接到该监听地址,REGISTRY_PORT 必须与监听端口一致。跨主机部署时,--host 应使用服务节点能够访问的实际地址。

5. 安装并启动 Zlooks 服务

保持 Registry 运行,确认 PostgreSQL 和 Redis 也可访问后执行:

zlooks install

zlooks install 会把静态安装目录与 npm 全局已安装包进行比较,只展示尚未安装的项目。九个内置服务是必装项,出现时默认选中且不可取消;百度链接提交服务是默认不选的可选项。已经全局安装的项目不会显示,也不会由本次命令解析或改动。安装完成后可按提示立即由 PM2 启动;如果本次从列表中选择了可选服务,启动确认会提示先检查配置并默认不启动。使用 --start 可以显式跳过最后的启动询问:

zlooks install --start

zlooks install -f 是上述“只显示尚未安装项目”的显式例外:它保留原有行为,展示并强制重装九个必装服务,但不会把可选的百度服务变成必装项。强制重装单个扩展时使用 zlooks install <package> -f。

百度链接提交不会因九个必装服务而自动安装;可以在上述列表中勾选,也可以显式安装。安装后通过服务命令完成交互配置,再用 CLI 纳入 PM2 管理:

zlooks install @zlooks.cn/baidu-submit-server --skip-start
zlooks-baidu-submit-server config
zlooks restart @zlooks.cn/baidu-submit-server

zlooks restart 不带包名时重启当前 PM2 中的全部 Zlooks 服务;传入一个有效的全局安装包时,如果它已经在 PM2 中则只重启该进程,如果尚未进入 PM2 则连同缺失的已安装依赖一起启动。npm 全局不存在的包会被拒绝并提示先安装。

config 只询问百度站点地址和搜索资源平台推送 Token,并通过 hile registry configs set 更新 zlooks.cn 配置文件中的 baidu-submit 顶层组,随后把该配置文件权限收紧为 0600。服务只记录提交接口的本地处理状态;accepted 不表示已经被百度收录。MCP 提供状态/单条记录 Resource、记录搜索/显式重试 Tool,以及带风险说明和用户确认步骤的重试 Prompt。当前没有接入逐 URL 收录状态查询,因为 Baidu 未提供适合该用途的公开稳定 API。

[!WARNING] 百度当前公开的链接提交端点使用传统 HTTP 传输,Token 会经过网络传输。仅在网络路径可信且风险可接受时启用;服务不会通过关闭 TLS 校验来绕过证书问题。

6. 可选:从旧版 zlooks.cn 导入数据

全新站点可以跳过这一步。旧版 zlooks.cn 默认安装在 ~/.zlooks/,环境文件为 ~/.zlooks/.env。需要迁移旧站数据时,先在旧站机器安装 Zlooks CLI,并停止旧站写入,然后执行:

zlooks export --source-env ~/.zlooks/.env

导出固定写入 ~/.zlooks.cn/export。如果该目录已经存在,命令会拒绝覆盖。导出目录包含用户、文章、分类、标签、评论、友情链接、站点配置,以及含明文私钥和保管口令的 key-vault.json;必须通过受控通道传输到新机器,禁止提交到 Git、上传到公开存储或写入日志。

在新机器完成前五步,并让所有已选服务至少成功启动一次以创建当前数据库表。将导出目录安全复制到新机器后,停止 Zlooks 服务、执行导入,再恢复服务:

zlooks stop
zlooks import \
  --source ~/.zlooks.cn/export \
  --env ~/.zlooks.cn/.env
zlooks restart

导入期间必须保持 Hile Registry 和 PostgreSQL 可访问,恢复服务前还要确认 Redis 可访问。zlooks stop 只停止 PM2 中 zlooks 命名空间的服务,不会停止前面放在 hile 命名空间的 Registry。导入会先校验完整导出目录,再在一个 PostgreSQL 事务中写入;完全相同的数据会跳过,已有数据冲突会中止整个事务而不会覆盖。

导入完成时会输出 DONE inserted=<数量> skipped=<数量>。旧密码不会迁移为可登录密码,用户需要通过找回密码设置新密码;key-vault.json 当前仅保留在导出目录中,等待对应插件导入,不会由本命令写入。

7. 验证安装

安装完成后检查服务和进程状态:

zlooks service list
pm2 list

浏览器访问地址以 zlooks setup 中配置的 public-host.origin 为准,默认值为 http://127.0.0.1:3000。

Finch 支持

Zlooks 提供 Finch 小程序 Zlooks Admin,通过 Gateway 的统一 MCP 管理博客内容。使用前需要 Finch 1.6.1 或更高版本、可从 Finch 访问的 Zlooks 公网地址,以及 zlooks setup 中配置的 Gateway MCP Bearer Token。

安装小程序:

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

安装完成后,在 Finch 的“小程序”中找到 Zlooks Admin,启用并授予所需权限。如果设置菜单暂时不可用,请关闭 Zlooks Admin 后重新启用一次。

打开 Zlooks Admin 的设置菜单,选择 配置连接,填写:

  • MCP 地址:Gateway 公网地址加 /mcp,例如 https://www.zlooks.cn/mcp。
  • Bearer Token:与 zlooks setup 中 Gateway 配置使用的 MCP Bearer Token 相同。

在部署机器上可以使用以下命令查看当前 MCP Bearer Token(需要已安装 jq):

hile registry configs get zlooks.cn --json \
  | jq -r '.gateway.mcpBearerToken'

该命令会把完整 Token 输出到终端,只应在受控的本地终端执行;执行后不要复制到聊天、日志或截图中,并及时清理终端显示。

线上环境必须使用 HTTPS。Bearer Token 只应填写到 Finch 的加密 Secrets 输入框,不要发送到对话、截图、日志或普通配置文件中。连接完成后,应显示“连接正常”;也可以从设置菜单打开 连接诊断,查看不包含 Token 的诊断信息。

更新已安装的 Zlooks Admin:

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

日常更新

更新前确认 Hile Registry、PostgreSQL、Redis 均可访问,并且 pm2 list 中当前 Zlooks 服务全部为 online。先创建本次更新的回滚点:

zlooks deploy start
zlooks deploy status

创建回滚点后,先停止 Zlooks 服务,再检查并安装当前发布通道中的更新:

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

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

相关文章

评论

登录后即可参与讨论

暂无评论。