npm 安装服务端

适用于已有 Node.js 24 环境、希望在非 Docker 环境运行夭夭服务端的场景。macOS 与 Linux 均可。

安装

npm install -g @lsamien/yaoyao

要求 Node.js 24 或更高版本（node -v 确认）。安装过程约 300 个依赖包；其中 Playwright 供托管浏览器功能使用，浏览器内核不随包安装，首次使用相关功能时按提示安装。

Windows 用户注意

@parcel/watcher 的原生编译提示可以忽略：它只服务于开发模式的热更新，生产服务端不经过 Vite，缺失时自动回落，不影响运行。

启动服务

yaoyao service install

macOS：注册 LaunchAgent（com.samien.hermes-yaoyao）并立即启动，开机自启。
Linux：需要 systemd 支持（尚未提供，参见下文路线）。

安装后访问 http://127.0.0.1:15300，首次打开自行创建管理员账号。

其他命令：

yaoyao service status     # 查看运行状态
yaoyao service stop       # 停止服务
yaoyao service start      # 启动服务
yaoyao service restart    # 重启服务；已停止的服务会重新启动
yaoyao service uninstall  # 卸载服务（数据保留）
yaoyao --version          # 查看已安装的 npm 包版本

版本查询也支持 yaoyao version 和 yaoyao -v，无需安装或启动服务。

配置

环境变量	作用	默认
`YAOYAO_HOME`	数据目录	`~/.yaoyao`
`HERMES_YAOYAO_PORT`	Web 端口	`15300`
`HERMES_YAOYAO_UPSTREAM`	Hermes 上游地址	`http://127.0.0.1:9119`

LaunchAgent 安装时的环境会写入 plist；修改环境变量配置后，执行 yaoyao service install 重新写入配置并启动服务。yaoyao service restart 使用已保存的配置重启。

从界面升级

macOS 通过 yaoyao service install 注册的独立服务可进入「我的设置 → 更新与回滚」升级：

检查 npm 仓库的新版本，点击「下载更新」。
安装包通过 SHA-512 校验后，安装到独立版本目录并准备依赖；当前服务继续运行。
显示「重启服务器」后，由管理员点击生效。后台进程等待任务结束、备份数据、切换版本并验证服务；启动失败会恢复旧版本。
更新成功后页面自动刷新。旧程序目录保留，可以在数据库结构兼容时回滚上一版本；手动回滚保留更新后写入的数据。

准备状态保存在服务器，即使关闭页面也不会自动重启，重新打开设置仍可继续。已准备更新的重启不依赖 npm 仓库在线。远程升级默认关闭，需要显式设置 HERMES_YAOYAO_ALLOW_REMOTE_UPDATE=1；接口仍要求管理员登录、Origin 和 CSRF 校验。

程序保存在 ~/.local/share/hermes-yaoyao/releases/，current 指向正在使用的包目录。npm 全局安装保留为启动器，yaoyao --version 显示全局包版本；界面的「当前 Web」显示实际服务版本。yaoyao service restart 使用已保存的服务入口，不会切回全局旧包。

首次使用需要先安装包含界面更新功能的 npm 版本。旧版本可用命令升级：

npm install -g @lsamien/yaoyao@latest
yaoyao service install

已经迁移到版本目录的服务，重复执行全局包的 service install 会重新指定服务入口；日常重启使用 service restart，后续升级使用界面。

默认 npm 安装自动使用 npm:@lsamien/yaoyao 发布源，检查遵循 npm 仓库配置；显式自定义的 Git 仓库继续使用 Git 更新流程。也可设置 HERMES_YAOYAO_RELEASE_SOURCE=npm:@lsamien/yaoyao。

与其他安装方式的关系

Docker（Docker 部署说明）：隔离性好，含电脑环境等全部能力，适合专用服务器。
源码运行（见 README）：开发与贡献场景。
npm 安装与 Docker 安装不要共用同一个数据目录。

已知限制

Linux 的 service install（systemd user unit）尚未实现，当前 CLI 在 Linux 上会提示不支持；临时做法：手动运行 npm root -g 定位包目录，用进程管理器守护 node dist-server/server/index.js（工作目录设为包根目录）。
Linux 的界面内切换与重启仍需部署管理器支持；当前 npm 界面升级适用于 macOS LaunchAgent 服务。

npm-install.md 4.3 KB Lịch sử Raw