finallf/terraria

核心功能  •  最低要求  •  快速部署  •  环境变量  •  动态初始物品  •  持久化卷  •  安全与权限

---

🖥️ 关于项目

这是一个高性能的Terraria服务器Docker镜像，集成TShock插件，专注自动化、数据安全、详细监控，且完全采用无root（Rootless）架构。

https://hub.docker.com/r/finallf/terraria   https://hub.docker.com/r/finallf/terraria   https://hub.docker.com/r/finallf/terraria   https://hub.docker.com/r/finallf/terraria

https://github.com/finallf/terraria   https://github.com/finallf/terraria   https://github.com/finallf/terraria   https://github.com/finallf/terraria

---

🪶 核心功能

内部架构（无Supervisor）

• ✅ 原生轻量执行，针对高性能Linux和容器环境优化，完全无root。

健壮日志系统

• ✅ 完整捕获STDOUT/STDERR日志，带高精度时间戳，支持从启动到关闭的全审计。

配置管理

• ✅ 使用jq操作JSON文件，确保设置（如初始物品）修改无文件损坏风险。

命名管道交互

• ✅ 支持外部安全发送命令到服务器控制台，便于脚本和Web界面集成。

优雅 shutdown

• ✅ SIGTERM信号捕获系统，确保Docker终止前服务器保存世界进度。

---

❓ 为什么选择此镜像？

• 若您在专业Docker环境中管理服务器，可知可见性至关重要。
• 本镜像为需要可靠日志和动态环境变量配置的管理员设计，同时保持docker-compose的简洁性。

---

⚒️ 最低要求

[!IMPORTANT] ✔️ 正常运行的Docker环境
✔️ 基础Docker知识

---

🧰 快速部署

若需测试容器，使用以下命令：

bash
docker run --rm -di --name terraria finallf/terraria:latest

推荐使用Docker Compose运行服务器：

1. 创建compose.yml文件，调整卷路径至您的环境：

yml
services:
  terraria:
    image: finallf/terraria:latest
    container_name: terraria
    stdin_open: true
    tty: false
    environment:
      - SERVER_PASSWORD=yourpassword123
      - WORLD_NAME=我的Terraria世界
    volumes:
      # 映射目录以持久化数据
      - ./terraria/config:/tshock/config
      - ./terraria/logs:/tshock/logs
      - ./terraria/crashes:/tshock/crashes
      - ./terraria/plugins:/tshock/plugins
      - ./terraria/worlds:/tshock/worlds
    ports:
      - "7777:7777" # 游戏端口
      - "7878:7878" # REST API端口（可选）
    restart: unless-stopped

以上是最低配置，更多设置请参考环境变量部分。

2. 确保主机目录对UID 1000有正确权限（容器默认运行UID为1000）。

3. 在compose.yml所在目录执行：

bash
docker compose up -d

容器运行后，打开Terraria客户端，使用主机IP和默认端口7777连接。首次运行因世界创建可能耗时较长。

4. 监控启动日志：

bash
tail -f ./terraria/logs/container_init.log

[!NOTE] 5. 首次启动注意事项（管理员设置）：
首次启动时，查看容器日志（docker logs terraria）获取TShock生成的Setup Code，游戏内使用/setup命令需此代码。

---

⚙️ 环境变量

可通过compose.yml或docker run的-e参数配置服务器行为：

[!TIP]

点击查看完整compose.yml和.env示例

compose.yml:

yml
networks:
  terraria:
    external: false
    name: terraria

services:
  terraria:
    image: finallf/terraria:latest
    container_name: terraria
    user: 1000:0
    stdin_open: true
    tty: false
    environment:
      - LOG_INIT=true
      - SERVER_PASSWORD=123456
      - MAX_SLOTS=16
      - REST_API_ENABLED=true
      - LOG_REST=true
      - DISABLE_UUID_LOGIN=true
      - AUTO_SAVE=true
      - SSC_ENABLED=true
      - SSC_SAVE=1
      - PLAYER_APPEARANCE=true
      - STARTINGINVENTORY=true
      - WORLD_NAME=ReloadeD服务器
      - WORLD_FILE=my_world.wld
      - AUTO_CREATE=3
      - DIFFICULTY=2
      - WORLD_EVIL=crimson
      - SEED=fortheworthy
      - FORCE_UPDATE=true
      - MOTD=欢迎来到我的服务器！
      - SECURE=true
      - LANG=zh-Hans
      - TZ=Asia/Shanghai
    volumes:
      - ${SSD}/config:/tshock/config
      - ${SSD}/logs:/tshock/logs
      - ${SSD}/crashes:/tshock/crashes
      - ${SSD}/plugins:/tshock/plugins
      - ${SSD}/worlds:/tshock/worlds
    ports:
      - "7777:7777"
      - "7878:7878"
    networks:
      - terraria
    stop_grace_period: 30s
    restart: unless-stopped

.env

SSD=/path/on/host/terraria

[!CAUTION] 请根据实际情况调整配置。

---

🎒 动态初始物品（STARTINGINVENTORY）

动态初始物品系统允许定义新玩家首次加入时的物品，无需手动编辑文件，启动时通过jq原子化处理。

🔹 选项1：基础套件
设置为true时，自动注入默认初始物品：99荧光棒、99铁皮药剂、1鞋扣、1冰镜、1掘墓铲。

yml
environment:
  - STARTINGINVENTORY=true

🔹 选项2：自定义套件
使用紧凑字符串格式定义物品：ID,PREFIX,QUANTITY（用冒号分隔）。
语法：netID,prefix,stack:netID,prefix,stack:...
示例：给新玩家1把铂金斧（ID:3482）、10火把（ID:8）、5小治疗药剂（ID:28）：

yml
environment:
  - STARTINGINVENTORY=3482,0,1:8,0,10:28,0,5

🔹 选项3：移除物品
使用remove:ID移除指定物品：
示例：移除铂金斧（ID:3482）：

yml
environment:
  - STARTINGINVENTORY=remove:3482

[!TIP] 物品ID可参考Terraria官方 wiki：Item IDs。

---

💾 持久化卷结构

为确保服务器重启或镜像更新后数据不丢失，需映射以下5个核心卷：

• 📁 /tshock/config
  • 内容： JSON配置文件和SQLite数据库（config.json、sscconfig.json、tshock.sqlite）。
  • 用途： 服务器规则核心，启动脚本在此动态修改配置（如初始物品）。

• 📁 /tshock/logs（可选）
  • 内容： container_init.log和TShock原生日志。
  • 用途： 审计与诊断，无需访问Docker控制台即可查看启动过程和错误。

• 📁 /tshock/crashes（可选- legacy）
  • 内容： 意外崩溃的内存转储文件。
  • 用途： 插件开发或深度调试时使用。

• 📁 /tshock/plugins（可选）
  • 内容： TShock插件与扩展。
  • 用途： 自定义服务器功能（如区域保护），无需重建镜像。

• 📁 /tshock/worlds
  • 内容： 世界文件（.wld）和自动备份。
  • 用途： 存储世界数据，无此卷则重启后世界重置。

[!TIP] 主机目录建议结构：

Plaintext
/path/on/host/terraria/
├── config/
├── logs/
├── crashes/
├── plugins/
└── worlds/

---

🔐 安全与权限（无root架构）

本镜像采用无root（Rootless）标准，TShock服务器和内部脚本均不以root身份运行，防止游戏漏洞影响主机。需正确配置映射目录权限：

🔹 静态UID/GID说明
容器默认以UID 1000、GID 0运行。GID 0（root组）是推荐实践，允许主机目录无需严格匹配UID，只要组权限允许读写即可。

🔹 主机目录权限配置

• 方法1：调整容器UID（推荐）
  在compose.yml中设置用户为您主机的UID（替换1000）：

yml
services:
  terraria:
    user: 1000:0

• 方法2：调整主机目录所有者
  将主机目录所有者改为容器UID：

bash
sudo chown -R 1000:1000 ./terraria

• 方法3：组权限配置
  授予GID 0读写权限：

bash
sudo chgrp -R 0 ./terraria
sudo chmod -R g+rwX ./terraria

---

🛡️ 监控与日志

本镜像强调全可观测性，每一步初始化和命令均带时间戳记录：

📁 日志位置
映射卷保存日志：

yml
volumes:
  - /path/to/host/logs:/tshock/logs

主要日志文件为container_init.log，包含启动脚本执行、命名管道创建、TShock控制台输出等。

🕒 高精度时间戳
每条日志前缀带时间戳：
[2026-04-05 14:30:05] [INFO] 初始物品注入成功。

📟 命名管道交互
不使用docker attach，通过命名管道发送命令（如kick、ban、save）：

bash
docker exec -i [container_name] sh -c 'echo "say 欢迎来到Terraria世界！" > /tmp/terraria_input'

🛑 优雅 shutdown
执行docker stop时，容器捕获信号并自动保存世界，防止数据丢失。

---

☕ 支持项目

若本项目对您有帮助，欢迎***更新与维护：

🇧🇷 PIX密钥：25d1d528-df10-4005-bb28-2acf89706243

---

💪 贡献指南

[!NOTE] 贡献步骤：

1. Fork项目
   
2. 创建新分支：git checkout -b my-feature
   
3. 提交修改：git commit -m "feature: 我的新功能"
   
4. 推送分支：git push origin my-feature

---

🛠️ 使用技术

• Docker、Bash、TShock、Debian、Terraria、HTML5、CSS3

---

🧑‍💻 贡献者

感谢所有贡献者：

---

🧙‍♂️ 作者

  <br>
  <br>
  
  &nbsp;
  
  &nbsp;
  
  &nbsp;
  

---

📝 许可证

[!WARNING] 本项目采用https://github.com/finallf/terraria?tab=GPL-3.0-1-ov-file%E3%80%82