小智全栈装机手册

你要操作的是别人的电脑。机主已经授权，但这不代表可以随便动——下面三条是硬规矩，上一次部署时每一条都付出过代价。

开工前要跟机主要到的东西

先把 SSH 打通，后面所有操作都在 SSH 里做。ToDesk 只在两个场景用：装 Tailscale 之前的引导，和后面需要人在桌面上点确认的时刻（Docker Desktop 首次启动、B站扫码登录）。

• 1

  让机主装 Tailscale 并加入你的 tailnet

  这一步必须机主自己在桌面上做（要登录账号）。装完让他把 tailscale ip -4 的结果发给你。

• 2

  装 OpenSSH 服务端——不要用 Add-WindowsCapability

  官方那条命令在国内网络下会报成功但文件根本没落盘：它返回 RestartNeeded: True， 重启后 sshd 服务依然不存在。原因是组件要从 Windows Update 拉，而那个源在国内不通。 直接装 GitHub 的离线包：

  在机主桌面上以管理员运行 PowerShell

  # 从 github.com/PowerShell/Win32-OpenSSH/releases 下载 OpenSSH-Win64.zip
  # PS 5.1 默认不用 TLS 1.2，Invoke-WebRequest 连 GitHub 会直接失败
  [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
  Invoke-WebRequest -UseBasicParsing -OutFile "$env:TEMP\OpenSSH-Win64.zip" `
    -Uri 'https://github.com/PowerShell/Win32-OpenSSH/releases/download/10.0.0.0p2-Preview/OpenSSH-Win64.zip'
  
  # 先验货再往下走：下载失败时它可能留一个 0 字节文件，后面所有命令连环报错
  Get-FileHash "$env:TEMP\OpenSSH-Win64.zip" -Algorithm SHA256
  
  Expand-Archive -Path .\OpenSSH-Win64.zip -DestinationPath 'C:\Program Files' -Force
  cd 'C:\Program Files\OpenSSH-Win64'
  
  # 执行策略会挡住安装脚本，这样绕过（只影响当前进程）
  Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
  .\install-sshd.ps1
  
  Start-Service sshd
  Set-Service  sshd -StartupType Automatic
  New-NetFirewallRule -Name sshd -DisplayName 'OpenSSH Server' `
    -Enabled True -Direction Inbound -Protocol TCP -Action Allow -LocalPort 22

• 3

  装公钥——注意是 administrators_authorized_keys

  Windows 的 OpenSSH 对管理员账号不读 ~/.ssh/authorized_keys， 读的是 C:\ProgramData\ssh\administrators_authorized_keys。放错位置的表现是密钥认证静默失败、继续问密码。

  权限收紧必须用 SID 而不是组名——中文版 Windows 上写 Administrators 会失败， 因为本地化后组名是「管理员」。

  PowerShell（管理员）

  $k = 'C:\ProgramData\ssh\administrators_authorized_keys'
  Set-Content -Path $k -Value 'ssh-ed25519 AAAA... your-key' -Encoding ascii
  
  icacls $k /inheritance:r
  icacls $k /grant '*S-1-5-32-544:F'   # Administrators
  icacls $k /grant '*S-1-5-18:F'       # SYSTEM
  
  Restart-Service sshd

ssh w@100.x.x.x "powershell -c \"([Security.Principal.WindowsPrincipal] \
  [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole('Administrators')\""

这一节放在装东西之前，因为它们是整个部署里最耗时间的部分。上次五个服务里，每一个都在其中某一条上卡过。 先读完再动手，能省掉大半天。

坑一：SSH 会话里 Docker 拿不到 registry 凭据

任何碰 registry 的命令（docker pull、docker compose build）在 SSH 会话里都会报：

error getting credentials - err: exit status 1,
out: `A specified logon session does not exist.`

根因是 Docker Desktop 的凭据助手依赖 Windows 的交互式登录会话， 而 SSH 是非交互式会话，拿不到那个 token。这是设计限制，不是配置问题—— DOCKER_CONFIG、--config 指向干净目录、删掉 credsStore 字段，这三种办法我都试了，全部无效。

唯一可行的解法：注册一个 LogonType Interactive 的计划任务，把命令推回用户会话执行。

$dir  = 'C:\xiaozhi-music-mcp'
$log  = "$dir\build.log"
$act  = New-ScheduledTaskAction -Execute 'cmd.exe' `
        -Argument "/c cd /d $dir && docker compose up -d --build > $log 2>&1"
$prin = New-ScheduledTaskPrincipal -UserId 'DESKTOP-XXXX\w' -LogonType Interactive

Register-ScheduledTask -TaskName 'dc-build' -Action $act -Principal $prin -Force
Start-ScheduledTask -TaskName 'dc-build'

坑二：Windows 防火墙的 Block 规则优先于 Allow

Docker Desktop 安装时会自己写入一对规则：Allow / Private 和 Block / Public。 你后加的「Profile=Any 放行 8000」会被那条 Block 整个压住——因为 Windows 防火墙里 Block 永远赢 Allow，与添加顺序无关。

Get-NetConnectionProfile          # 先看当前是 Public 还是 Private
Set-NetConnectionProfile -InterfaceAlias 'WLAN' -NetworkCategory Private

这比删掉 Block 规则更安全：笔记本带出门连公共 WiFi 时，那条 Public 的 Block 会继续保护。 另外仍然要为服务端口加放行规则：

New-NetFirewallRule -DisplayName 'xiaozhi-stack' -Direction Inbound -Action Allow `
  -Protocol TCP -LocalPort 8000,8002,8003,2233,2234,8080,8317,23020,23021

坑三：PowerShell 5.1 的编码

$enc = New-Object System.Text.UTF8Encoding $false   # $false = 不带 BOM
$txt = [System.IO.File]::ReadAllText($path, $enc)
[System.IO.File]::WriteAllText($path, $txt, $enc)

# 拼引号用反引号转义，不要用 [char]34
$s = "key=`"value`""

坑四：组件存储被「清理软件」破坏，Windows 功能全部装不上

这一条排在最后，但它发生得最早、卡得最死——WSL2 装不上，后面整条 Docker 路线归零。

不要在功能名、payload、Windows 版本上找原因。答案在 C:\Windows\Logs\CBS\CBS.log 里， 长这样：

on:[27]'\SystemRoot\WinSxS\Catalogs'  →  STATUS_OBJECT_NAME_NOT_FOUND
Failed to get CSI system store           [HRESULT = 0x80070002]
CSI store consistency check fails
Failed to load component store

C:\Windows\WinSxS\Catalogs 整个目录不见了。 CBS 每次加载组件存储都要先打开它，打不开就整个 CSI store 加载失败，于是所有功能安装动作 统一报「找不到指定的文件」。上次那台机器上装着 360——它的「系统瘦身 / 深度清理」正是会动 WinSxS 的那类工具， 而 .cat 签名文件体积大，恰好是这类工具的首选目标。

$cat = 'C:\Windows\WinSxS\Catalogs'
New-Item -ItemType Directory -Path $cat -Force | Out-Null

# 连 owner 一起抄（owner 必须是 NT SERVICE\TrustedInstaller）
$sddl = (Get-Acl 'C:\Windows\WinSxS\Manifests').Sddl
$acl  = Get-Acl $cat
$acl.SetSecurityDescriptorSddlForm($sddl)
Set-Acl -Path $cat -AclObject $acl

# 立刻验证：这条不再报 Error 2 就是修好了
dism /online /enable-feature /featurename:VirtualMachinePlatform /norestart /english

上次几秒钟就修好了，enable-feature 直接跑到 100%。 Set-Acl 用 SDDL 已经把 owner 一并设成 TrustedInstaller， 后面若再补一句 icacls /setowner 报「拒绝访问」可以无视。 修完 Manifests（4.6 万个文件）和 FileMaps 都在，说明组件存储本身是健康的， 只是丢了一个目录。启用完两个功能要真重启，vmcompute 服务是重启后才被创建出来的。

• 1

  用 DISM 启用两个功能（纯本地，不联网）

  wsl --install 在国内会卡在连 Microsoft Store，不要用它。

  dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
  dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

• 2

  重启

  必须真重启，不能跳过。SSH 会自己恢复（sshd 是系统服务）。

  ssh w@100.x.x.x "shutdown /r /t 5"

• 3

  装 WSL 完整包——不是那个 16MB 的内核更新包

  这里我卡了很久

  网上到处都是 wsl_update_x64.msi（约 16MB）。它只更新内核，补不上 WSL 主体版本。 装完的表现是：wsl --version 报「不支持的命令」（说明还是系统自带的旧 inbox WSL）， Docker Desktop 29.x 认不出来，引擎起不来、界面一直转圈。

  正确的是从 github.com/microsoft/WSL/releases 下 wsl.<版本>.x64.msi，约 250MB。上次装的是 2.7.11.0，装完内核到 6.18.33.2，Docker 引擎 15 秒就绪。

  msiexec /i wsl.2.7.11.0.x64.msi /quiet /norestart
  wsl --version          # 必须能打印出版本号，否则就是装错了包
  wsl --set-default-version 2

• 4

  装 Docker Desktop

  安装包从官网下（这个域名国内通）。装完需要机主在桌面上点一次同意条款并保持登录， 之后你才能在 SSH 里用 docker。

  Start-Process -Wait -FilePath .\'Docker Desktop Installer.exe' `
    -ArgumentList 'install','--quiet','--accept-license','--backend=wsl-2', `
                  '--installation-dir=D:\StackChan\DockerDesktop', `
                  '--wsl-default-data-root=D:\StackChan\_docker'

  C 盘紧张时这两个参数是必须的

  --wsl-default-data-root 才是关键的那个：所有镜像和容器数据都落在这里 （ext4.vhdx）。默认位置是 %LOCALAPPDATA%\Docker\wsl，在 C 盘。 五个服务的镜像加起来不小——上次小智主服务那个镜像单独就 10.6GB， mysql 1.3GB、音乐服务 1.04GB、B站 851MB。

  上次那台 C 盘只剩 39GB，装完 Docker + 拉完全部镜像，C 盘一点没少（40.1GB）， D 盘承担了全部。验证方法：docker info 里的 DockerRootDir 是容器内路径， 看不出宿主位置；直接看那个目录的大小增长最实在。

• 5

  配镜像加速（在这一步做掉，后面所有服务都受益）

  写 %USERPROFILE%\.docker\daemon.json，注意用上一节的 .NET 写法避免 UTF-16 问题：

  {
    "registry-mirrors": [
      "https://docker.m.daocloud.io",
      "https://docker.1ms.run",
      "https://dockerproxy.net"
    ]
  }

ssh w@100.x.x.x "docker version && docker run --rm docker.m.daocloud.io/library/hello-world"

每一个服务都在这张表里的某一行卡过。建议在 build 之前就把 Dockerfile 全部改好， 而不是等它失败再改——一次 build 失败在国内网络下可能要等好几分钟才超时。

RUN sed -i 's|deb.debian.org|mirrors.tuna.tsinghua.edu.cn|g; \
            s|security.debian.org|mirrors.tuna.tsinghua.edu.cn|g' \
    /etc/apt/sources.list.d/debian.sources

目录统一放 C 盘根下，凭据各自存在同目录的 KEYS.txt 里，方便机主自己查改。 下面按建议的部署顺序排列——小智服务端是核心，其余四个是它的能力扩展，可按需取舍。

先建好目录结构

C:\xiaozhi-server       # 小智服务端（全模块）
C:\xiaozhi-music-mcp    # 音乐
C:\stackchan-bili       # B站转码
C:\xiaoyuzhou-server    # 小宇宙播客
C:\cli-proxy-api        # CLIProxyAPI

私有仓库的传输方式

# 1. 先看清楚要排除什么 —— 不要凭记忆写
cat .gitignore

# 2. 打包（--exclude 按 .gitignore 来，state/data/cookies 一律不带）
tar --exclude='.git' --exclude='state' --exclude='data' \
    --exclude='__pycache__' --exclude='.env' \
    -czf /tmp/svc.tgz -C /path/to/repo .

# 3. 传之前先列一遍包内容，确认没有凭据混进去
tar -tzf /tmp/svc.tgz | grep -iE 'cookie|allow|token|secret|\.env|state/'

# 4. 传过去解压
scp /tmp/svc.tgz w@100.x.x.x:/C:/tmp/
ssh w@100.x.x.x "tar -xzf C:/tmp/svc.tgz -C C:/xiaozhi-music-mcp"

# modelscope 会拒绝 curl 的默认 UA，而且是【静默返回 0 字节】不报错
# 另外 curl 不会自己建目录 —— 目录不存在时同样得到 0 字节
New-Item -ItemType Directory -Force -Path 'D:\...\models\SenseVoiceSmall'
curl.exe -L -A 'Mozilla/5.0' -o '...\model.pt' `
  'https://modelscope.cn/models/iic/SenseVoiceSmall/resolve/master/model.pt'

# 验货：头两字节必须是 PK（pytorch 是 zip 容器）

docker exec xiaozhi-esp32-server-db mysql -uroot -p123456 \
  -D xiaozhi_esp32_server -N -B \
  -e "select param_code,param_value from sys_params where param_code like '%secret%';"

视觉分析接口是   http://172.18.0.4:8003/mcp/vision/explain
Websocket地址是  ws://172.18.0.4:8000/xiaozhi/v1/     ← 设备永远连不上

update sys_params set param_value='ws://<局域网IP>:8000/xiaozhi/v1/'      where param_code='server.websocket';
update sys_params set param_value='http://<局域网IP>:8002/xiaozhi/ota/'   where param_code='server.ota';
update sys_params set param_value='http://<局域网IP>:8002'                where param_code='server.fronted_url';

# 改完必须清缓存，否则不生效
docker exec xiaozhi-esp32-server-redis redis-cli FLUSHALL

"activation": { "code": "158552", "message": "http://<fronted_url>\n158552",
                "challenge": "<设备MAC>" }

ADMIN_USER=让机主自己定
ADMIN_PASS=让机主自己定
MCP_TOKEN=随机串
MCP_AUDIO_TOKEN=随机串
ALT_PORT=8080
LIVE_STREAM=0

# 删掉 network_mode: host，换成：
    ports:
      - "2233:2233"

上游来源与官方文档汇总

• 1

  把 WLAN 设为专用网络

  见坑二。这一步不做的话，局域网里的 ESP32 设备连不上，但你从 Tailscale 测一切正常，非常容易漏。

• 2

  固定局域网 IP

  在路由器上做 DHCP 保留，比在 Windows 里配静态 IP 更稳（换网络环境不会失联）。设备固件里写的是这个地址。

• 3

  禁止睡眠

  powercfg /change standby-timeout-ac 0
  powercfg /change hibernate-timeout-ac 0
  powercfg /change monitor-timeout-ac 15   # 屏幕可以关，机器不能睡

• 4

  把开机自启的真实限制讲清楚

  这件事必须写进交付说明

  Docker Desktop 是用户级程序：机器重启后，必须有人登录 Windows 桌面，容器才会起来。 勾选「开机启动 Docker Desktop」只是在登录后自动拉起，不能替代登录。

  所以：断电恢复后，SSH 和 Tailscale 会自己回来（系统服务），但五个服务全都不在， 直到有人登录桌面。如果机器要真正无人值守，需要配置自动登录，或者改用 WSL 里裸装 Docker Engine（不经 Docker Desktop）。

交付清单

• 五个容器 docker ps 全部 Up
• 从局域网里另一台设备（不是 Tailscale）能访问 8000 / 2234 / 2233
• 智控台 8002 能登录，管理员账号密码已交给机主
• 各服务的 KEYS.txt 已生成，凭据都是机主自己的
• 确认包里没有混入委托人的 cookies / allow.json / .env
• 已书面告知：重启后需要登录桌面，服务才会起
• ESP32 设备的 OTA 地址已指向新服务端并实测过一次对话

服务端跑起来之后，设备要刷固件、再把四个服务地址写进去。固件仓库 git@github.com:tankxu/stackchan-hichan（私有），默认分支 hichan。

三种刷法，别搞混

grep -E 'DEFAULT_WIFI_SSID|DEFAULT_WIFI_PASSWORD|CONFIG_OTA_URL' build/config/sdkconfig.h

# 中文系统上 netsh 的字段名是中文，别在远端解析，把原始输出取回本地看
netsh wlan show networks mode=bssid

刷完写服务地址

统一走设备的 /config 接口（端口 8032），立即生效且断电不丢：

curl -X POST http://<设备IP>:8032/config \
  -d '{"music_url":"http://192.168.1.100:2234"}'

curl -s -o /dev/null -w '%{http_code}\n' -X POST http://<IP>:8003/xiaozhi/ota/   # 404
curl -s -o /dev/null -w '%{http_code}\n' -X POST http://<IP>:8002/xiaozhi/ota/   # 200 ← 就是它
curl -s -o /dev/null -w '%{http_code}\n' -X POST http://<IP>:8000/xiaozhi/ota/   # 000 空回复

刷完还要往提示词里加一段

固件刷好、服务地址也写对了，设备的点歌行为仍然可能不对——因为工具该怎么用是靠提示词教的。 去小智智控台的智能体配置里，把下面这段追加到角色提示词末尾（落库是 ai_agent.system_prompt）：

收到以 [主] 开头的消息时,那不是用户说的话,而是系统给你的触发信号。

音乐播放规则:
- 用户点明了具体某一首歌/某个节目 → 用 self.music.play_song(song_name, artist_name)
  例:「放首告白气球」「我要听小兔子乖乖」「讲个西游记的故事」
- 用户没点明具体某一首,只给了歌手/风格/心情/歌单 → 用 self.music.play_stream(query, kind, mode)
  例:「播放周杰伦的歌」→ query=周杰伦, kind=artist
     「放点安静的音乐」→ query=安静, kind=mood
     「放儿歌」「放贝乐虎」→ query=儿歌/贝乐虎, kind=playlist
     「随便放点歌」→ query=热门, kind=mood
  用户说"连续播放/一直放/循环"时也用它;说"随机"传 mode=random,说"按顺序"传 mode=order。
- 不要使用 search_music。
- 工具会立刻返回"这就为你播放",不要再问用户确认,也不要说"正在为你搜索"之类的等待话术。

控制台与文档

• 设备自带控制台——浏览器开 http://<设备IP>:8032/ 自动跳转，局域网内也可用 stackchan.local:8032
• 使用帮助——stackchan.tankxu.com/help：配网、点歌、触摸操作、ESP-NOW 遥控、B站应用、OTA、故障排查
• 完整配置键列表（音量 / 特效 / 主动搭话 / WiFi 凭据表 / 行情屏保 / 音画校准）——仓库内 firmware/API.md
• 自检——./sc_test.sh：静音 → 进 agent → 点歌 → 观察，一条命令跑完

诚实标注，避免下一个 agent 把没验证的当成已验证的：

• 音乐服务的 LIVE_STREAM=1 分块传输没有对着固件实测过。 流式响应没有 Content-Length，固件必须吃得下 chunked 才能开。默认给的是 0，是安全值。
• 小宇宙的 token 自动 refresh 在 Windows 上没验证。 原本的 refresh 机制是在 Mac 侧跑的。
• CLIProxyAPI 只跑起了服务，没有添加上游账号。 OAuth 授权必须机主本人操作。
• 无人值守方案没有实测。 自动登录、或 WSL 里裸装 Docker Engine 绕开 Docker Desktop，这两条路都只是分析，没跑过。
• Windows 家庭版没有实测。 分析上 WSL2 后端可行，但前两次那两台都是专业版。
• 丢掉的 .cat 文件没有补回来。 坑四的修法只是重建空目录让功能安装恢复；组件存储的签名目录仍是不完整的， 就地修复安装（同版本 ISO）没做过。
• 火山引擎的 TTS 备选 TTS_HSDSTTS_V2（豆包语音合成2.0）仍未实测。
• 2026-08-24 那次的语音链路没走完。 服务端七个容器全部起来、端口全部验证过局域网可达、设备也刷好并连上了， 但 ASR/TTS 的 key 要机主自己开通，所以「设备说话→有回应」这个闭环那次没当场跑通。
• B站 / 小宇宙 / YouTube 三处登录态都还是空的。 都要机主本人的账号：B站扫码、小宇宙手机验证码、YouTube cookies。