小智全栈装机手册

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

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

先把 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
  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`""

• 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'

• 5

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

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

  {
    "registry-mirrors": ["https://docker.m.daocloud.io"]
  }

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"

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

上游来源与官方文档汇总

• 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。

三种刷法，别搞混

刷完写服务地址

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

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

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

固件刷好、服务地址也写对了，设备的点歌行为仍然可能不对——因为工具该怎么用是靠提示词教的。 去小智智控台的智能体配置里，把下面这段追加到角色提示词末尾（落库是 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 后端可行，但上次那台是专业版。