快速开始

第一步不是装东西，而是决定走哪条路。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 \
  -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）。密码：

docker logs snowluma 2>&1 | grep -E "远程桌面密码:|remote desktop password:" | tail -n 1

远程桌面里 QQ 已自动启动，用手机 QQ 扫码。

3. 打开 WebUI

浏览器打开 http://<服务器IP>:5099/。完整 Compose、多账号见 Docker 部署。

实验性：一键安装脚本（Alpha）

curl -fsSL https://raw.githubusercontent.com/SnowLuma/SnowLuma.Docker.Framework/main/install.sh | bash

curl -fsSL https://raw.githubusercontent.com/SnowLuma/SnowLuma.Docker.Framework/main/install.sh | bash -s -- --mode docker --yes

交互会问模式；--yes 且不写 --mode 时默认 docker。细节、sidecar、本机模式见 一键安装（实验性）。

登录与首次访问

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

• 扫码登录：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 支持在地址里带上登录密码直接进入：

http://<服务器IP>:5099/?token=<你的WebUI登录密码>

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

接下来

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