快速开始#

第一步不是装东西，而是决定走哪条路。SnowLuma 的核心是把 hook 注入真实 QQ 进程，因此你需要一个能跑 QQ + 注入 + 扫码登录的环境。下面这张表按你手上的环境直接给出推荐路径，照着点进去即可。

我该走哪条路？#

拿不准就选 Docker on Linux，这是官方推荐、最容易跑起来的方式。完整对比见选择部署方式。

最快上手（Docker）#

最常见的路径是在 Linux 上用官方镜像。三步：

1. 拉起容器

docker run -d \
  --name snowluma \
  --restart unless-stopped \
  --shm-size=1g \
  --cap-add=SYS_PTRACE \
  --security-opt seccomp=unconfined \
  -e VNC_PASSWD=改成你自己的密码 \
  -p 6081:6081 -p 5099:5099 -p 3000:3000 -p 3001:3001 \
  -v qq-gateway-data:/app/data \
  -v qq-client-config:/app/.config \
  -v qq-client-data:/app/.local/share \
  motricseven7/snowluma:latest

2. 扫码登录

浏览器打开 http://<服务器IP>:6081/（noVNC），输入上面设置的 VNC_PASSWD。远程桌面里 QQ 已自动启动，用手机 QQ 扫码登录。登录后 hook 会自动从被动观察切到工作模式。

3. 打开 WebUI

浏览器打开 http://<服务器IP>:5099/ 进入 SnowLuma WebUI。

更完整的 Compose 写法、多账号、运维命令见 Docker 部署。

登录与首次访问#

无论哪条路径，首次上手都绕不开这几件事：

• 扫码登录：SnowLuma 只支持扫码登录，没有 CLI 登录。在无头环境里必须通过 VNC / noVNC 看到 QQ 窗口才能扫码。

• 找 WebUI 临时密码：首次用全新数据目录启动时，日志里会打印一次性管理员密码。Docker：

  docker logs snowluma 2>&1 | grep -E "临时密码|initial credentials" | tail -n 1
  INFO

  临时密码只在全新数据目录首次启动时输出一次，重启或复用旧数据不会重新生成。

• 开放端口：要从外部访问，放行 WebUI（5099）和你用到的 OneBot 端口（3000 / 3001）。

免密登录（URL token）#

每次手输密码很烦？WebUI 支持在地址里带上登录密码直接进入：

• 参数名是 token，值就是你平时登录 WebUI 的密码。SnowLuma 会用它走登录接口，密码正确即直达主页。
• 用后即清：密码读取后会立即从地址栏移除（history.replaceState），避免经浏览器历史 / 访问日志 / Referer 头泄露。
• 服务端照常校验，密码错误只会退回登录页，不存在绕过。

接下来#

• 选择部署方式 —— 各路径详细对比。
• 配置参考 —— 改端口、access token、适配器。
• 更新 —— 升级而不丢登录态。