为多个 Docker 化 TeamSpeak 服务器部署 teamspeak-management-tools

为多个 Docker 化 TeamSpeak 实例配置 teamspeak-management-tools 自动化管理与 IP 白名单
发布于
作者是 GEMILUXVII · 收录在 TeamSpeak · 标签 tech、 docker、 teamspeak · 约 9 分钟阅读 · 这里是

前言#

在部署了多个 TeamSpeak 服务器后，用户总会有想要创建个私人频道的冲动，但是一个个手动去开实在是太低效👎。幸运的是，社区提供了 teamspeak-management-tools 这样的开源工具，可以自动化创建临时子频道。本文便是基于此工具讲述如何在服务器上配置相关功能，实现自动化创建子频道、自动为用户提权至频道管理员等等。

如果尚未部署多个实例，可以先阅读：基于 Docker 在服务器上部署多个 TeamSpeak 服务器。

一、环境与目标#

在开始之前，请确保您具备以下条件：

  • 环境：一台运行 Docker 和 Docker Compose 的 Linux 服务器（本文以 Ubuntu 为例）
  • 目标：您的服务器上已通过不同的 docker-compose.yml 文件部署了多个（例如三个）独立的 TeamSpeak 3 服务
  • 工具：teamspeak-management-tools 的预编译二进制文件
KunoiSayami/teamspeak-management-tools.rs View this repository on GitHub — —
  • 信息：
    • 每个 TeamSpeak 服务器的 ServerQuery 管理员（serveradmin）密码
    • 每个服务器上用于触发自动创建子频道的“入口频道”ID

入口频道可使用 Telnet 连接到 TeamSpeak 服务器的 ServerQuery 端口进行获取，默认端口为 10011/TCP。

步骤如下：

  1. 首先你需要有一个 Telnet 客户端，Xshell、PuTTY 都可以，此处使用的是 PuTTY。

  2. 使用 PuTTY 连接到服务器 ServerQuery 端口。

PuTTY 连接 TeamSpeak ServerQuery 的配置

如图，输入 TeamSpeak 服务器的公网 IP 以及 ServerQuery 端口，选择 Telnet，点击连接即可。连接成功后能看到如下字样：

TS3
Welcome to the TeamSpeak 3 ServerQuery interface, type "help" for a list of commands and "help <command>" for information on a specific command.
  1. 依次输入如下指令：
login serveradmin password
use 1
channellist

输入完成后大致如下图：

TeamSpeak ServerQuery 频道列表查询结果

其中 cid 即为要开启自动创建临时频道功能所需的入口频道 ID。

二、为 TeamSpeak 服务器配置 IP 白名单#

管理工具会以较高的频率与 TeamSpeak 服务器的 ServerQuery 端口通信。为防止被 TeamSpeak 的防洪（Anti-Flood）机制误判为攻击，我们必须将管理工具的 IP 地址加入服务器的白名单。

  1. 定位 query_ip_allowlist.txt 文件

    这是部署过程中的第一个关键选择点和易错点。您需要找到每个 TeamSpeak 容器在主机上的真实数据目录。

    • 选择 A：使用了主机目录挂载（Bind Mount） - [推荐] 如果您的 docker-compose.yml 中包含类似以下的 volumes 配置：

      volumes:
  - ./ts-data:/var/ts3server/

      那么您的数据目录就是主机上与 docker-compose.yml 同级的 ts-data 文件夹，白名单文件路径为：./ts-data/query_ip_allowlist.txt。

    • 选择 B：使用了匿名卷（Anonymous Volume） - [有风险] 如果您的 docker-compose.yml 中没有 volumes 部分，Docker 会为您创建一个匿名卷。您需要通过以下命令找到它的真实路径：

      # 1. 找到容器的准确名称
$ docker-compose ps
# 2. 使用容器名查找其数据卷的"Source"路径
$ docker inspect [容器名] | grep '"Source":'

      输出的路径（如 /var/lib/docker/volumes/long_id_string/_data）就是您的数据目录。

  2. 编辑白名单

    进入每个 TeamSpeak 服务器的真实数据目录，创建或编辑 query_ip_allowlist.txt 文件，并添加以下内容：

    127.0.0.1
::1
172.16.0.0/12  # 覆盖Docker默认的内部网络地址范围

  3. 重启 TeamSpeak 服务

    这是最容易被忽略但至关重要的一步。白名单配置必须在重启后才能生效。

    # 进入每个TeamSpeak项目的目录
$ cd /path/to/your/teamspeak_project
$ docker-compose restart # 使用restart命令，安全且高效

三、安装与配置管理工具#

我们将采用一个管理工具实例，通过多配置文件模式来同时监控所有服务器。

  1. 下载并准备工具

    # 创建一个专用目录
$ sudo mkdir -p /opt/ts-manager
$ cd /opt/ts-manager

# 从GitHub Releases下载适用于Linux x86_64的二进制文件
$ sudo wget [下载链接] -O ts-manager.tar.gz
$ sudo tar -xzvf ts-manager.tar.gz
# 将可执行文件重命名为简短的名称
$ sudo mv [解压出的长文件名] ts-manager
# 赋予执行权限
$ sudo chmod +x ts-manager

  2. 配置多服务器监控

    我们将创建一个主配置文件（config.toml）和多个附加配置文件。

    • 主配置文件 config.toml（负责第一个服务器）

      # 通过绝对路径加载其他服务器的配置，这是最稳妥的方式
additional = ["/opt/ts-manager/config_ts2.toml", "/opt/ts-manager/config_ts3.toml"]

# --- 服务器1的配置 ---
[server]
server-id = 1
channel-id = [10] # 示例：服务器1的入口频道ID
privilege-group-id = 5
leveldb = "ts1.db" # 为每个服务器指定独立的数据库文件

[misc]
interval = 5

[raw-query]
server = "127.0.0.1"
port = 10012 # 示例：服务器1暴露在主机上的ServerQuery端口
user = "serveradmin"
password = "SERVER1_ADMIN_PASSWORD"

    • 附加配置文件 config_ts2.toml（负责第二个服务器）

      # --- 服务器 2 的配置 ---
[server]
server-id = 1
channel-id = [20] # 示例：服务器 2 的入口频道 ID
privilege-group-id = 5
leveldb = "ts2.db"

[raw-query]
server = "127.0.0.1"
port = 10011 # 示例：服务器2暴露在主机上的ServerQuery端口
user = "serveradmin"
password = "SERVER2_ADMIN_PASSWORD"

四、通过 systemd 实现后台运行#

将工具作为 systemd 服务运行，可以确保其稳定性和开机自启。

  1. 创建服务文件

    $ sudo nano /etc/systemd/system/ts-manager.service

    将以下内容粘贴进去：

    [Unit]
Description=TeamSpeak AutoChannel Management Tool
After=network.target docker.service
Requires=docker.service

[Service]
Type=simple
User=root
# 明确指定工作目录和可执行文件的绝对路径
WorkingDirectory=/opt/ts-manager
ExecStart=/opt/ts-manager/ts-manager
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

  2. 启动并验证服务

    # 重新加载systemd配置
$ sudo systemctl daemon-reload
# 启动服务
$ sudo systemctl start ts-manager.service
# 设置开机自启
$ sudo systemctl enable ts-manager.service
# 检查服务状态
$ sudo systemctl status ts-manager.service

    如果服务状态显示 active (running)，恭喜您，部署成功！

五、故障排查#

如果在启动服务时遇到问题（例如状态为 activating (auto-restart) ），请遵循以下步骤：

  1. 停止服务： sudo systemctl stop ts-manager.service ，防止其无效重启

  2. 查看详细日志： sudo journalctl -u ts-manager.service -e --no-pager ，找到具体的错误信息

  3. 在前台手动运行： cd /opt/ts-manager && sudo ./ts-manager ，这会直接在屏幕上打印出最清晰的错误

    • Error: No such file or directory : 通常是 additional 路径错误，或leveldb配置问题 请使用绝对路径并为每个服务指定 DB 文件

    • Error: invalid loginname or password : 密码或用户名错误 请重新核对

    • Error: connection failed, flood ban : 对应服务器的白名单未生效 请检查白名单文件内容并重启该 TeamSpeak 服务

  4. 解决问题后，再重新启动 systemd 服务

附录：将 TeamSpeak 数据迁移到安全的主机目录挂载#

如果您还在使用匿名卷，强烈建议进行以下一次性迁移操作，以保障数据安全

以迁移一个服务器为例：

  1. 完整备份： sudo docker cp [容器名]:/var/ts3server/ /path/to/temp_backup/

  2. 停止并删除旧容器： cd /path/to/project && sudo docker-compose down

  3. 创建本地数据目录： mkdir ./ts-data

  4. 修改 docker-compose.yml：在 teamspeak 服务下添加 volumes: - ./ts-data:/var/ts3server/

  5. 恢复数据： sudo cp -a /path/to/temp_backup/ts3server/. ./ts-data/

  6. 重新启动服务： sudo docker-compose up -d

完成此操作后，您的所有服务器数据都将安全地存放在主机上，易于管理和备份。

相关教程：

上一篇：
下一篇：

评论