arokan/raspiheim Docker 镜像 - 轩辕镜像

raspiheim Docker镜像文档

镜像概述

raspiheim是一个专为树莓派设计的Docker镜像，用于简化Valheim（英灵神殿）游戏服务器的部署和管理。通过容器化方式，用户可快速在树莓派设备上搭建Valheim服务器，支持自定义服务器配置、数据持久化及自动更新等功能。

最低要求

• 硬件：Raspberry Pi 4（Raspberry Pi 5需特殊配置，见下文说明）
• 内存：至少4GB RAM
• 系统：64位操作系统

Raspberry Pi 5用户注意事项

由于Raspberry Pi 5的页面大小（16k）与容器依赖的box86/64默认支持的4k页面大小不兼容，需手动修改系统配置以确保容器正常运行：

1. 执行以下命令添加内核参数并重启：

   bash
   sudo echo "kernel=kernel8.img" >> /boot/firmware/config.txt && sudo reboot
   

核心功能与特性

• 支持自定义服务器名称、密码及世界名称
• 提供服务器公开性控制（公开/私有）
• 自动更新服务器软件
• 支持玩家无连接时暂停服务器以节省资源
• 数据持久化存储（存档、配置文件）
• 兼容Docker Compose编排
• 支持跨平台游戏（CROSSPLAY）及多种服务器难度预设

使用方法

Docker Run 快速部署

通过以下命令一键启动Valheim服务器：

bash
docker run -d \ 
--name raspiheim \
--hostname raspiheim \
-p 2456:2456/udp \
-p 2457:2457/udp \
-e SERVER_NAME=Raspiheim \
-e WORLD_NAME=Raspiworld \
-e SERVER_PASS=Raspipass \
-e PUBLIC=disabled \
-e UPDATE=enabled \
-e PAUSE=disabled \
-v /path/to/valheim/data:/data \
-v /path/to/valheim/server:/valheim \
--restart=unless-stopped \
arokan/raspiheim:latest

Docker Compose 编排部署

创建docker-compose.yml文件，配置如下：

yaml
version: "3"

services:
  raspiheim:
    image: arokan/raspiheim:latest
    container_name: raspiheim
    environment:
      - SERVER_NAME=Raspiheim          # 服务器在大厅中显示的名称
      - SERVER_PASS=Raspipass          # 服务器密码
      - WORLD_NAME=Raspiworld          # 存档世界名称
      - PUBLIC=disabled                # 是否公开显示（disabled=私有，enabled=公开）
      - CROSSPLAY=disabled             # 是否启用跨平台游玩（需Valheim客户端支持）
      - UPDATE=enabled                 # 是否自动检查并更新服务器软件
      - SAVE_INTERVAL=1800             # 自动存档间隔（秒，默认1800）
      - BOX86=default                  # box86版本（default=默认，latest=最新，或指定版本号）
      - BOX64=default                  # box64版本（同上）
      - NO_BUILD_COST=disabled         # 是否禁用建造消耗
      - PLAYER_EVENTS=disabled         # 是否启用玩家事件日志
      - PASSIVE_MOBS=disabled          # 是否仅生成被动生物
      - NO_MAP=disabled                # 是否禁用地图显示
      # - PRESET=normal                # 游戏难度预设（normal/casual/easy/hard/hardcore/immersive/hammer）
      # - MODIFIER_COMBAT=             # 战斗难度（veryeasy/easy/hard/veryhard）
      # - MODIFIER_DEATHPENATLY=       # 死亡惩罚（casual/veryeasy/easy/hard/hardcore）
      # - MODIFIER_RESOURCES=          # 资源数量（muchless/less/more/muchmore/most）
      # - MODIFIER_RAIDS=              # 突袭频率（none/muchless/less/more/muchmore）
      # - MODIFIER_PORTALS=            # 传送门限制（casual/hard/veryhard）
    ports:
      - "2456:2456/udp"                # Valheim服务器主端口
      - "2457:2457/udp"                # Valheim服务器查询端口
    volumes:
      - "/path/to/valheim/data:/data"  # 持久化存储服务器数据（存档、日志等）
      - "/path/to/valheim/server:/valheim"  # 存储服务器软件文件
    restart: unless-stopped

启动服务：

bash
docker-compose up -d

环境变量说明

容器行为说明

1. 首次启动：若未设置持久化卷（/valheim），容器会自动下载Valheim服务器软件，耗时约5-15分钟（树莓派5），请耐心等待。
2. 数据持久化：
   • 存档文件需放置于 /path/to/valheim/data/worlds_local/ 目录
   • 服务器配置及日志存储在 /path/to/valheim/data/
3. 内存占用：容器运行时最高占用约2.4GB RAM，建议配置至少2GB交换空间（ZRAM效果更佳，可减少磁盘I/O）。
4. 世界加载：新建世界比加载现有世界耗时更长。

Raspberry Pi 5 特殊配置

由于Raspberry Pi 5默认页面大小为16k（树莓派4为4k），与box86/64兼容性问题，需手动修改内核配置：

bash
sudo echo "kernel=kernel8.img" >> /boot/firmware/config.txt && sudo reboot

修改后重启设备即可正常运行容器。

已知问题

常见问题

• 存档大小问题：当存档文件接近100MB且设备RAM/存储速度不足时，服务器存档或内存管理可能导致玩家断开连接，此问题需Valheim官方修复。

罕见或已修复问题

• 多人在线时，若一名玩家退出，服务器可能崩溃（单人连接时无此问题，正在排查）。
• 探索新生物群系时可能加载异常，重启服务器即可解决。
• 启用暂停功能（PAUSE=enabled）时，若CPU负载过高，可能导致服务器误判无玩家而关闭。

更新日志

• 1.3.1：修改/etc/box64.box64rc配置，修复存档延迟和断开连接问题，服务器运行更稳定。
• 1.3：恢复完整功能；启动时间增加但在线性能提升；支持跨平台游玩（CROSSPLAY）；扩展服务器设置；统一参数格式（支持enabled/disabled和1/0）；支持手动指定box86/64版本。
• 1.2：新增无玩家连接时暂停服务器功能，日志存储于/data/logs。
• 1.1：修复steamcmd与box86版本不兼容导致无法更新/下载服务器软件的问题（升级box86至v0.2.5）。

致谢

• 本容器依赖 Box86/64 实现x86程序在ARM架构上的运行，感谢PiLabs开发的模拟器工具（***频道）。
• 感谢slipperman1对暂停功能的建议和技术支持。

反馈与支持

若使用中遇到问题或有功能建议，可通过***联系开发者：arokan13。