# 服务器上部署 TeamSpeak 音乐机器人指北

我自己的 TS 服务器一直缺个点歌的，索性把开源项目 teamspeak-music-bot（Node/TypeScript 写的，仓库 ZHANGTIANYAO1/teamspeak-music-bot，产品名 TSMusicBot）搭上。它是一体化方案：自带强制鉴权的 WebUI，内置网易云 / QQ音乐 / 哔哩哔哩 三个音源（另外还能选装 YouTube，需要额外的 yt-dlp），不用再自己拼一堆代理和脚本。目标很直接——在 TS 里打一句 !play 歌名 就有声。

这篇是纯部署手记，照着抄能跑起来。

前置条件

先把环境对齐，省得后面原生模块编译时炸一地：

• 一台 Linux 服务器（我这台同时在跑游戏服和语音服）。
• 已经在跑 TeamSpeak 服务端 ts3server，默认语音端口 9987（机器人最后是以语音客户端身份连本机这个端口）。
• Node 20，这是项目要求的版本。系统自带的 node 一般太老，别去动它，单独装一份隔离的 Node 20。
• 构建工具链：项目里有原生模块要现场编译，需要 build-essential 和 python3。
• 一个内网环境（可选）：方便好友和自己连接到 web 端使用；如果纯用指令操作，就不需要。

装一份隔离的 Node 20

我的做法是直接下官方二进制解压到一个固定目录，再把它的 bin 塞到 PATH 最前面，这样既能用上 Node 20，又不污染系统 node：

# 解压到 /root/home/node20（版本号按当时最新的 20.x 即可）
mkdir -p /root/home/node20
tar -xf node-v20.x.x-linux-x64.tar.xz -C /root/home/node20 --strip-components=1

# 当前会话临时把它放到 PATH 最前
export PATH=/root/home/node20/bin:$PATH
node -v   # 确认输出 v20.x.x

构建工具链用系统包管理器装一下（Debian/Ubuntu 系）：

apt update
apt install -y build-essential python3

build-essential 给原生模块（C++）提供编译器，python3 是 node-gyp 要用的。

拉取与安装依赖

把项目 clone 到一个固定目录，我放在 /root/home/teamspeak-music-bot：

git clone https://github.com/ZHANGTIANYAO1/teamspeak-music-bot /root/home/teamspeak-music-bot
cd /root/home/teamspeak-music-bot

# 用隔离的 node 20 装后端依赖
npm install

# 前端 WebUI 是独立的 Vue 工程，有自己的 package.json，要单独装
cd web && npm install && cd ..

后端这步会编译几个原生模块，重点是 better-sqlite3（本地数据库）和 @discordjs/opus（Opus 编码）。如果前面的 build-essential / python3 装好了，这里应该一次过。前端那步别漏，否则后面 vite 构建会因为缺依赖直接失败。pnpm 也行，看你顺手。

构建

构建分两步：后端 TypeScript 用 tsc 编译，前端 WebUI 用 vite 打包，产物都进 dist/。项目一般会把这两步串进一个脚本：

# 后端 tsc 编译 + 前端 WebUI vite 构建
npm run build

构建完检查一下 dist/ 里既有后端 index.js、又有前端 WebUI 静态产物，两样齐了才算对。

配置 data/config.json

配置文件在 data/config.json，第一次启动时会自动生成（老版本曾放在根目录，升级后会自动迁移到 data/，所以别再去改根目录那个）。它自带一份完整的默认模板，我们只改 webPort 这一项即可——它是 WebUI 的监听端口，我设成 3000：

{
  "webPort": 3000
}

注意上面只是示意「要改的那一项」，不要用这个单字段 JSON 整体覆盖文件，否则会把项目自带的其他必要默认配置全删掉。直接在生成好的 data/config.json 里把 webPort 改成你要的值就行。

启动后，进程会同时监听三个端口（端口都可在 config.json 里通过对应字段调整）：

• WebUI —— 3000（webPort，就是你刚配的那个）
• 网易云 API —— 3001（neteaseApiPort）
• QQ音乐 API —— 3200（qqMusicApiPort）

哔哩哔哩走内置服务，不单独占端口。记住这几个端口，下一步靠日志确认它们都起来了。

先手动跑一遍验证

别急着写 systemd，先用隔离的 node 手动把它拉起来，看日志：

cd /root/home/teamspeak-music-bot
/root/home/node20/bin/node dist/index.js

日志里应该能看到 3000 / 3001 / 3200 三个端口依次监听成功。看到了就说明后端、音源 API、WebUI 都活了。

接着从内网 / ZeroTier 打开浏览器访问 WebUI：

http://<ZEROTIER_IP>:3000

<ZEROTIER_IP> 就是 ZeroTier 给这台服务器分配的那个 10.x 内网地址（不确定的话用 zerotier-cli listnetworks 查自己的 10.x 地址）。第一次进去 WebUI 会让你创建管理员账号，建好就进后台了。

在 WebUI 里登录音源

进了后台，先把要用的音源登上，否则只能放免费片段。项目支持扫码登录网易云 / QQ音乐 / 哔哩哔哩——在 WebUI 对应音源点出二维码，用手机 App 扫一下，登录态会自动以 Cookie 形式持久化到 data/cookies/ 目录。

网易云：在 WebUI 里点出网易云的登录二维码，用网易云音乐 App 扫码确认即可。

哔哩哔哩：同样在 WebUI 里点出二维码，用哔哩哔哩 App 扫码登录。

QQ音乐可选，需要就按 WebUI 的提示扫码登一下，不用就跳过。

把机器人连上 TS 并实测

在 WebUI 里点「添加机器人」，填连接信息——这里填的是 TS 的语音端口，机器人会作为一个语音客户端连进来：

• 地址：127.0.0.1（机器人和 TS 服务端在同一台机器上，连本机最干净）
• 端口：9987（语音端口）
• 昵称：随意，比如 点歌姬

连上之后，机器人会作为语音客户端出现在你的 TS 频道里。这时候在 TS 的聊天框打：

!play 一首你爱听的歌

如果一切顺，你会听到声音 —— 这条链路是整段跑通了：音源拉到 PCM，经 Opus 编码，再推流进 TS 频道。

托管为开机自启（systemd）

手动验证没问题，最后交给 systemd 管，崩了自动拉起、重启服务器也自启。

新建 /etc/systemd/system/tsmusicbot.service：

[Unit]
Description=TeamSpeak Music Bot
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/root/home/teamspeak-music-bot
ExecStart=/root/home/node20/bin/node /root/home/teamspeak-music-bot/dist/index.js
Restart=on-failure
RestartSec=5
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

几个关键字段说明：ExecStart 用的是隔离的 node 20 绝对路径，这样不依赖 PATH，systemd 也能找对版本；WorkingDirectory 指到项目根目录，保证进程能正确找到 dist/ 和 data/（配置、cookies/、数据库都在 data/ 下）；Restart=on-failure + RestartSec=5 让它挂了 5 秒后重试。

然后加载并启用：

systemctl daemon-reload
systemctl enable --now tsmusicbot
systemctl status tsmusicbot

status 看到 active (running) 就成了。之后看实时日志用：

journalctl -u tsmusicbot -f

小结

到这一步，一个自托管的 TS 点歌机器人就齐活了：隔离的 Node 20 跑后端，WebUI 管音源和机器人，systemd 保证开机自启和崩溃自愈。

最后两句叮嘱：

• 歌单、登录 Cookie 这些状态都落在项目的 data/ 目录里（含 config.json、cookies/），备份的时候盯着这个目录就够，不用整盘搬。