白狗子的博客

「天上浮云如白衣，斯须改变如苍狗。」——杜甫

泰拉瑞亚灾厄服-Linux-Docker部署文档

2026年10月16日·Admin·1 次浏览
docker

泰拉瑞亚灾厄服 Linux Docker 部署文档

基于官方 tModLoader Dedicated Server Utils（方案二）
适用系统：Ubuntu / Debian / CentOS / Arch 等 x86_64 Linux
最后更新：2026-07-13

目录

  1. 概述
  2. 环境要求
  3. 安装 Docker
  4. 目录结构
  5. 下载官方文件
  6. 配置灾厄模组
  7. 配置 serverconfig.txt
  8. 配置 docker-compose.yml
  9. 构建与启动
  10. 日常运维
  11. 客户端连接
  12. 公网联机与防火墙
  13. 更新与备份
  14. 故障排查
  15. 附录：常用 Workshop ID

1. 概述

本文档介绍如何在 Linux 上使用 Docker 部署带 灾厄（Calamity Mod） 的泰拉瑞亚专用服务器。

架构说明

宿主机 Linux
├── /opt/terraria-tml/          # 项目根目录
│   ├── docker-compose.yml
│   ├── Dockerfile
│   └── tModLoader/             # 数据卷（持久化）
│       ├── Mods/
│       ├── Worlds/
│       └── serverconfig.txt
│
└── Docker 容器 (tml)
    ├── tModLoader 服务端
    ├── SteamCMD（下载创意工坊模组）
    └── 监听端口 7777

重要说明

角色 说明
Docker 容器 仅运行 专用服务器，不能用来玩游戏
玩家电脑 需安装 tModLoader 客户端，并启用与服务器相同的模组
灾厄模组 属于 tModLoader 模组，不能在 vanilla 泰拉瑞亚服务器上运行

2. 环境要求

项目 最低要求 推荐配置
CPU 架构 x86_64 (amd64) x86_64
内存 2 GB 4~8 GB
磁盘 5 GB 15 GB+
系统 Linux 64 位 Ubuntu 22.04 LTS
网络 可访问 GitHub、Steam CDN 稳定公网 IP（如需外网联机）

注意：官方暂不支持 ARM 架构（树莓派、部分云 ARM 实例等）。详见 ARM 支持说明。

3. 安装 Docker

Ubuntu / Debian

# 更新包索引
sudo apt update

# 安装依赖
sudo apt install -y ca-certificates curl gnupg

# 添加 Docker 官方 GPG 密钥
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# 添加 Docker 仓库
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装 Docker Engine 和 Compose 插件
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 将当前用户加入 docker 组（免 sudo）
sudo usermod -aG docker $USER
newgrp docker

验证安装

docker --version
docker compose version

预期输出示例：

Docker version 27.x.x
Docker Compose version v2.x.x

4. 目录结构

在部署前，需按官方要求准备好以下目录结构：

/opt/terraria-tml/
├── docker-compose.yml          # Docker Compose 配置
├── Dockerfile                  # 镜像构建文件
└── tModLoader/
    ├── Mods/
    │   ├── install.txt         # 创意工坊模组 ID（每行一个）
    │   └── enabled.json        # 启用的模组内部名称
    ├── Worlds/                 # 世界存档目录
    └── serverconfig.txt        # 服务器配置（强烈建议）

创建目录：

sudo mkdir -p /opt/terraria-tml/tModLoader/{Mods,Worlds}
sudo chown -R $USER:$USER /opt/terraria-tml
cd /opt/terraria-tml

5. 下载官方文件

从 tModLoader 官方仓库下载 Dockerfile 和 docker-compose.yml：

cd /opt/terraria-tml

curl -fsSL -o Dockerfile \
  "https://raw.githubusercontent.com/tModLoader/tModLoader/1.4.4/patches/tModLoader/Terraria/release_extras/DedicatedServerUtils/Dockerfile"

curl -fsSL -o docker-compose.yml \
  "https://raw.githubusercontent.com/tModLoader/tModLoader/1.4.4/patches/tModLoader/Terraria/release_extras/DedicatedServerUtils/docker-compose.yml"

官方源文件地址：

6. 配置灾厄模组

模组配置需要两个文件，均放在 tModLoader/Mods/ 目录下。

方式 A（推荐）：从客户端导出模组包

在本地电脑的 tModLoader 客户端中操作：

  1. 启动 tModLoader
  2. 主菜单 → Workshop → Mod Packs
  3. 安装并启用所需模组（至少包含灾厄本体和灾厄音乐）
  4. 点击 Save Enabled as New Pack（将已启用保存为新模组包）
  5. 点击 Open Pack Folder（打开模组包文件夹）
  6. 将文件夹内的 Mods/install.txt 和 Mods/enabled.json 复制到服务器的 tModLoader/Mods/ 目录
# 示例：从本地上传（在本地电脑执行）
scp Mods/install.txt Mods/enabled.json user@your-server:/opt/terraria-tml/tModLoader/Mods/

此方式可自动包含所有依赖模组，最不容易出错。

方式 B：手动编写（最小灾厄配置）

install.txt

每行一个 Steam 创意工坊 ID：

cat > /opt/terraria-tml/tModLoader/Mods/install.txt << 'EOF'
2824688072
2824688266
2669644269
2619954303
EOF
Workshop ID 模组名称 说明
2824688072 Calamity Mod 灾厄本体
2824688266 Calamity Mod Music 必需，灾厄官方要求
2669644269 Boss Checklist 可选，Boss 进度清单
2619954303 Recipe Browser 可选，配方浏览器

enabled.json

cat > /opt/terraria-tml/tModLoader/Mods/enabled.json << 'EOF'
[
  "CalamityMod",
  "CalamityModMusic",
  "BossChecklist",
  "RecipeBrowser"
]
EOF

注意：enabled.json 中使用的是模组内部名称（Internal Name），不是显示名称。
install.txt 中的每个 ID 都必须在 enabled.json 中有对应条目。

7. 配置 serverconfig.txt

serverconfig.txt 放在 tModLoader/ 目录下，用于实现无交互自动启动。

新建世界（首次部署推荐）

cat > /opt/terraria-tml/tModLoader/serverconfig.txt << 'EOF'
# 世界文件路径（容器内路径，必须使用此格式）
world=/tModLoader/Worlds/CalamityWorld.wld

# 世界不存在时自动创建：1=小 2=中 3=大
autocreate=3

# 世界名称
worldname=CalamityWorld

# 世界种子
seed=CalamityServer2026

# 难度：0=普通 1=专家 2=大师 3=旅途
difficulty=2

# 最大玩家数（1~255）
maxplayers=8

# 监听端口
port=7777

# 进服密码（留空则无密码）
password=your_password_here

# 欢迎语
motd=欢迎来到灾厄服务器！

# 语言
language=zh-Hans

# 降低怪物传送跳跃（建议 2~6，值越小越流畅但带宽占用越高）
npcstream=4

# 进程优先级：0=Realtime 1=High 2=AboveNormal 3=Normal
priority=1
EOF

使用已有世界存档

# 1. 将 .wld 和 .twld 文件上传到 Worlds 目录
cp /path/to/your/world.wld /opt/terraria-tml/tModLoader/Worlds/
cp /path/to/your/world.twld /opt/terraria-tml/tModLoader/Worlds/

# 2. 修改 serverconfig.txt
cat > /opt/terraria-tml/tModLoader/serverconfig.txt << 'EOF'
world=/tModLoader/Worlds/your_world.wld
maxplayers=8
port=7777
password=your_password_here
motd=欢迎来到灾厄服务器！
language=zh-Hans
npcstream=4
priority=1
EOF

路径规则：world= 必须使用容器内路径 /tModLoader/Worlds/xxx.wld，不能使用宿主机路径。

官方配置参考：serverconfig.txt 示例

8. 配置 docker-compose.yml

编辑 docker-compose.yml，设置正确的 UID/GID（与当前 Linux 用户一致）：

# 查看当前用户的 UID 和 GID
id
# 输出示例：uid=1000(user) gid=1000(user) groups=1000(user),...

编辑 compose 文件：

nano /opt/terraria-tml/docker-compose.yml

推荐配置：

version: "3.0"

services:
  tml:
    container_name: tml
    restart: unless-stopped
    build:
      context: .
      args:
        UID: 1000    # 改为你的 uid
        GID: 1000    # 改为你的 gid
        # 可选：锁定特定 tModLoader 版本
        # TMLVERSION: v2026.06.2.1
    ports:
      - 7777:7777
    tty: true
    stdin_open: true
    volumes:
      - ./tModLoader:/tModLoader

设置数据目录权限（Linux 必须执行）：

# 将 UID/GID 替换为你的实际值
sudo chown -R 1000:1000 /opt/terraria-tml/tModLoader

若权限不正确，容器可能无法写入世界存档和模组文件。

9. 构建与启动

首次构建

cd /opt/terraria-tml

# 构建镜像（首次约 5~15 分钟，需下载 tModLoader）
docker compose build

# 后台启动
docker compose up -d

查看启动日志

docker logs -f tml

启动流程说明

容器启动后会依次执行：

  1. 从 GitHub 安装 tModLoader 服务端
  2. 读取 install.txt，通过 SteamCMD 下载创意工坊模组
  3. 加载 enabled.json 中启用的模组
  4. 按 serverconfig.txt 创建或加载世界
  5. 在端口 7777 开始监听

成功标志

日志中出现类似以下内容即表示启动成功：

Loading mods...
Server started
Listening on port 7777

首次启动因需下载灾厄等大型模组，可能需要 10~30 分钟，请耐心等待。

按 Ctrl+C 退出日志查看（不会停止容器）。

10. 日常运维

查看容器状态

docker ps
docker compose ps

查看最近日志

docker logs --tail 100 tml

进入服务器控制台

docker attach tml
操作 按键
安全退出（不关闭服务器） Ctrl+P 松开，再按 Ctrl+Q
退出并关闭服务器 Ctrl+C

向服务器发送命令

# 发送聊天消息
docker exec -it tml execute "say 服务器将在 10 分钟后维护"

# 手动保存世界
docker exec -it tml execute "save"

# 踢出玩家
docker exec -it tml execute "kick 玩家名"

# 广播公告
docker exec -it tml execute "say 欢迎新玩家！"

命令必须整体用双引号包裹。

停止 / 启动 / 重启

cd /opt/terraria-tml

# 停止
docker compose stop

# 启动
docker compose start

# 重启
docker compose restart

# 停止并删除容器（数据保留在 tModLoader/ 目录）
docker compose down

设置开机自启

docker-compose.yml 中已配置 restart: unless-stopped，Docker 服务启动后容器会自动运行。

确保 Docker 服务开机自启：

sudo systemctl enable docker
sudo systemctl start docker

11. 客户端连接

客户端准备

  1. 在 Steam 安装 tModLoader（App ID: 1281930）
  2. 启动 tModLoader，安装并启用与服务器完全一致的模组
  3. 建议使用与服务器相同的模组包（见第 6 节方式 A）

连接方式

场景 地址
服务器本机测试 127.0.0.1:7777
局域网 服务器局域网IP:7777
公网 服务器公网IP:7777

连接步骤

  1. tModLoader 主菜单 → 多人游戏
  2. 选择 通过 IP 加入
  3. 输入服务器地址和端口
  4. 输入 serverconfig.txt 中设置的密码

模组一致性

客户端与服务器必须满足：

  • 启用的模组列表完全一致
  • 模组版本兼容（建议都用 Steam 创意工坊最新版）
  • tModLoader 版本相近

若提示 Mod mismatch 或无法加入，请检查客户端模组是否与服务器一致。

12. 公网联机与防火墙

云服务器安全组

在云控制台（阿里云、腾讯云、AWS 等）放行：

协议 端口 方向
TCP 7777 入站
UDP 7777 入站

UFW（Ubuntu）

sudo ufw allow 7777/tcp
sudo ufw allow 7777/udp
sudo ufw reload
sudo ufw status

firewalld（CentOS / RHEL）

sudo firewall-cmd --permanent --add-port=7777/tcp
sudo firewall-cmd --permanent --add-port=7777/udp
sudo firewall-cmd --reload

家庭宽带端口转发

若服务器在家庭网络内，需在路由器中配置端口转发：

  • 外部端口：7777
  • 内部 IP：Linux 服务器的局域网 IP
  • 内部端口：7777
  • 协议：TCP + UDP

13. 更新与备份

更新 tModLoader 和模组

cd /opt/terraria-tml

# 可选：重新下载最新 Dockerfile
curl -fsSL -o Dockerfile \
  "https://raw.githubusercontent.com/tModLoader/tModLoader/1.4.4/patches/tModLoader/Terraria/release_extras/DedicatedServerUtils/Dockerfile"

# 强制重建镜像
docker compose build --no-cache

# 重新启动
docker compose up -d

容器每次启动也会根据 install.txt 重新下载/更新创意工坊模组。

备份世界和配置

# 创建备份目录
mkdir -p ~/terraria-backups

# 备份（含时间戳）
tar czf ~/terraria-backups/terraria-$(date +%Y%m%d-%H%M%S).tar.gz \
  -C /opt/terraria-tml tModLoader/Worlds tModLoader/Mods tModLoader/serverconfig.txt

# 查看备份
ls -lh ~/terraria-backups/

恢复备份

# 停止服务器
cd /opt/terraria-tml && docker compose stop

# 解压恢复
tar xzf ~/terraria-backups/terraria-YYYYMMDD-HHMMSS.tar.gz -C /opt/terraria-tml

# 修复权限
sudo chown -R 1000:1000 /opt/terraria-tml/tModLoader

# 重新启动
docker compose up -d

定时自动备份（可选）

# 编辑 crontab
crontab -e

# 每天凌晨 4 点自动备份
0 4 * * * tar czf /home/user/terraria-backups/terraria-$(date +\%Y\%m\%d).tar.gz -C /opt/terraria-tml tModLoader/Worlds tModLoader/Mods tModLoader/serverconfig.txt

14. 故障排查

构建失败

# 查看详细构建日志
docker compose build --progress=plain 2>&1 | tee build.log

# 检查 Docker 服务
sudo systemctl status docker
docker info

常见原因：无法访问 GitHub 或 Steam CDN → 检查网络、配置代理后重试。

权限错误

日志中出现 Permission denied：

# 确认 UID/GID
id

# 修复权限
sudo chown -R $(id -u):$(id -g) /opt/terraria-tml/tModLoader

模组加载失败

日志示例：

ERROR: CalamityModMusic requires CalamityMod, which is not enabled.

处理：

  1. 检查 enabled.json 是否包含所有必需模组
  2. 确认 install.txt 中有对应 Workshop ID
  3. 优先使用第 6 节方式 A 从客户端导出完整模组包

世界路径错误

错误写法：

world=/opt/terraria-tml/tModLoader/Worlds/xxx.wld

正确写法：

world=/tModLoader/Worlds/xxx.wld

客户端无法连接

现象 可能原因 处理方法
连接超时 端口未开放 检查防火墙、安全组、端口转发
Mod mismatch 模组不一致 对齐客户端与服务器模组列表
密码错误 密码不匹配 核对 serverconfig.txt 中的 password
版本不兼容 tModLoader 版本差异过大 更新客户端或锁定服务器 TMLVERSION

查看容器内部文件

# 进入容器 shell
docker exec -it tml sh

# 查看模组目录
ls -la /tModLoader/Mods/

# 查看世界目录
ls -la /tModLoader/Worlds/

# 退出
exit

完全重置（保留配置，重装容器）

cd /opt/terraria-tml

docker compose down
docker compose build --no-cache
docker compose up -d

完全清除（删除所有数据）

cd /opt/terraria-tml

docker compose down
sudo rm -rf tModLoader/server tModLoader/steamapps
# 注意：这会删除已下载的模组，Worlds/ 中的世界存档会保留

15. 附录：常用 Workshop ID

Workshop ID 内部名称 模组名称
2824688072 CalamityMod 灾厄 Mod
2824688266 CalamityModMusic 灾厄音乐（必需）
2816188633 CalamityModMusicExtra 灾厄额外音乐（可选）
2669644269 BossChecklist Boss 清单
2619954303 RecipeBrowser 配方浏览器
2908170107 MagicStorage 魔法存储
2565639705 AlchemistNPCLite 炼金术士 NPC
2563309347 BossHealthBars Boss 血条

在 Steam 创意工坊页面 URL 中可找到任意模组的 ID：

https://steamcommunity.com/sharedfiles/filedetails/?id=2824688072
                                                              ^^^^^^^^^^
                                                              Workshop ID

快速部署命令汇总

以下为从零到运行的完整命令（复制执行前请根据实际情况修改密码和 UID/GID）：

# 1. 创建目录
sudo mkdir -p /opt/terraria-tml/tModLoader/{Mods,Worlds}
sudo chown -R $USER:$USER /opt/terraria-tml
cd /opt/terraria-tml

# 2. 下载官方文件
curl -fsSL -o Dockerfile \
  "https://raw.githubusercontent.com/tModLoader/tModLoader/1.4.4/patches/tModLoader/Terraria/release_extras/DedicatedServerUtils/Dockerfile"
curl -fsSL -o docker-compose.yml \
  "https://raw.githubusercontent.com/tModLoader/tModLoader/1.4.4/patches/tModLoader/Terraria/release_extras/DedicatedServerUtils/docker-compose.yml"

# 3. 写入模组配置（最小灾厄）
cat > tModLoader/Mods/install.txt << 'EOF'
2824688072
2824688266
2669644269
2619954303
EOF

cat > tModLoader/Mods/enabled.json << 'EOF'
[
  "CalamityMod",
  "CalamityModMusic",
  "BossChecklist",
  "RecipeBrowser"
]
EOF

# 4. 写入服务器配置
cat > tModLoader/serverconfig.txt << 'EOF'
world=/tModLoader/Worlds/CalamityWorld.wld
autocreate=3
worldname=CalamityWorld
seed=CalamityServer2026
difficulty=2
maxplayers=8
port=7777
password=ChangeMe123
motd=欢迎来到灾厄服务器！
language=zh-Hans
npcstream=4
priority=1
EOF

# 5. 设置权限
sudo chown -R $(id -u):$(id -g) tModLoader

# 6. 构建并启动
docker compose build
docker compose up -d

# 7. 查看日志
docker logs -f tml

参考链接

文档版本：1.0 | 基于 tModLoader 1.4.4 DedicatedServerUtils

← 返回首页

© 2025 My Blog. Built with Nuxt.js v4