架构设计
Zlooks Monorepo 架构与部署运维指南
本文介绍基于 Lerna、Nx、pnpm workspaces、TypeScript 和 Hile 的 Zlooks monorepo 架构，涵盖认证、事件总线、Gateway、博客、用户中心、配置管理及基础设施等核心服务与共享包。同时说明 Node.js、PostgreSQL、Redis 和 Hile Registry 环境要求，以及线上安装、旧版数据迁移、Finch 小程序接入、日常更新、回滚和部署验证流程。
本文介绍基于 Lerna、Nx、pnpm workspaces、TypeScript 和 Hile 的 Zlooks monorepo 架构，涵盖认证、事件总线、Gateway、博客、用户中心、配置管理及基础设施等核心服务与共享包。同时说明 Node.js、PostgreSQL、Redis 和 Hile Registry 环境要求，以及线上安装、旧版数据迁移、Finch 小程序接入、日常更新、回滚和部署验证流程。
基于 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 执行。
@hile/cli 提供，服务启动前必须可访问）这种方式适合安装并运行站点。请先准备 PostgreSQL 和 Redis。
npm install --global pm2 @zlooks.cn/cli
zlooks --version
Registry 由 @hile/cli 提供，需要单独安装：
npm install --global @hile/cli
hile --version
运行 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无法完成。旧版数据库仅作为导出源，新版数据库作为导入目标；应先完成旧版数据导出，再启动新版服务。
直接启动会占用当前终端：
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 应使用服务节点能够访问的实际地址。
保持 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 校验来绕过证书问题。
全新站点可以跳过这一步。旧版 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 当前仅保留在导出目录中，等待对应插件导入，不会由本命令写入。
安装完成后检查服务和进程状态：
zlooks service list
pm2 list
浏览器访问地址以 zlooks setup 中配置的 public-host.origin 为准，默认值为 http://127.0.0.1:3000。
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，例如 https://www.zlooks.cn/mcp。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 配置。执行数据迁移前必须单独备份数据库并确认迁移的回退方案。
参与讨论
评论