环境要求¶

装之前先花三分钟对一遍这张表。不满足的地方写清了怎么补，不用凭感觉猜。

一分钟结论¶

操作系统：桌宠要 Windows 10 / 11（64 位）；只跑后端的话 Linux 或 Windows Server 都行
Python：3.11 或更新。不用自己装，uv 会自动下载对应版本
Node.js：22 或更新（构建工具的最低要求是 20.19 / 22.12，用 22 LTS 最省事）。只有要桌宠、或要在这台机器上构建管理面板时才需要
磁盘：留出 3 GB 以上（依赖约 1 GB，聊天与记忆数据随时间增长）
内存：4 GB 以上
网络：能访问模型厂商的 API（默认是阿里云百炼）与 GitHub
账号：一个模型厂商的 API Key、一个当机器人用的 QQ 小号

操作系统 —— 后端本体是纯 Python，Windows、Linux、macOS 都能跑。桌宠外壳基于 Electron，只在 Windows 上可用；在别的系统上后端照常工作，只是没有立绘。服务器部署通常选 Linux，下文所有命令在两者上通用，差异会单独标出。

Python —— 项目要求 3.11 及以上，实际由 uv 按 pyproject.toml 声明自动准备，你机器上原来装没装、装的是哪个版本都不影响。不需要手动建虚拟环境，uv sync 会在项目目录下建好 .venv。

Node.js —— 只有两种情况下需要：要桌宠，或要在这台机器上构建管理面板。服务器部署可以完全跳过 Node：在任意一台有 Node 的机器上跑一次 npm run build，把生成的 out/ 拷过去即可，见无头部署。

磁盘 —— 依赖大约 1 GB；data/ 目录会随着聊天记录、记忆和向量索引增长，长期运行的实例建议留 10 GB 以上。生图管线（把一张参考图跑成整套角色素材）另外需要下载模型权重，那是一次性的额外占用。

内存 —— 后端常驻约 300 MB；同时开着桌宠与浏览器面板，4 GB 机器够用，8 GB 更从容。本地跑嵌入模型做向量召回会明显吃内存，功能开关见功能配置。

网络 —— 月璃本体不依赖公网，只有调用模型厂商 API 时需要出网。 QQ 协议端与月璃在同一台机器上时，它们之间走 127.0.0.1，不需要公网端口。国内访问 GitHub 可能不稳定，装依赖时如果卡住，先换一个能连通 GitHub 的网络环境。

一个 API Key —— 默认预填的是阿里云百炼（DashScope）。到百炼控制台开通并创建一个 API Key，形如 sk-xxxxxxxx。用别的厂商也可以，见 providers.toml；换厂商要同时改模型 ID，不是只换一个地址。

两个不同的 QQ 号 —— 一个是机器人号（建议用小号，接入 QQ 有账号风险，协议正文见仓库根目录的 AGREEMENT.md），另一个是你自己的号，用来跟她私聊、在群里点名。两个号必须不同，协议端登录的和配置里写的必须一致，否则连接时会报身份不匹配。

对完了就往下走：下载与安装。