yaoyao/docs/npm-install.md

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 使用已保存的配置重启。

升级

npm update -g @lsamien/yaoyao
yaoyao service restart
yaoyao --version

Web 界面中的「系统更新」入口面向源码/发布包安装；npm 安装的服务请直接用上述 npm 命令升级，避免两套版本并存。

与其他安装方式的关系

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

已知限制

• Linux 的 service install（systemd user unit）尚未实现，当前 CLI 在 Linux 上会提示不支持；临时做法：手动运行 npm root -g 定位包目录，用进程管理器守护 node dist-server/server/index.js（工作目录设为包根目录）。
• 通过 npm 安装的服务端不支持在 Web 界面内自更新（版本由 npm 管理）。