Hyphanet 0.7.5 Docker Compose 部署指南

目标：读完本文你将能以 Docker Compose 部署 Hyphanet 0.7.5：确认"无官方镜像"的结论并自建镜像、编写以 hyphanet-0.7.5-stack 为项目名的 compose 编排、完成数据持久化与配置文件挂载，并掌握日常运维与卸载命令，已在 Ubuntu 22.04（OpenJDK 17）实测通过。

环境信息：本文宿主机环境实测如下；文中安装器交互、run.sh 行为、端口与启动验证环节均来自同一宿主机上的真实节点实测回显。Compose 编排与镜像构建本身未实际执行，属基于实测证据整理的完整方案，相关小节均以 ⚠️ 标注。

安装方式选型与裸机部署见 《Ubuntu 22.04 安装 Hyphanet 0.7.5 指南》；参数解释见 《Hyphanet 0.7.5 配置参数详解》。

一、镜像选型说明

1.1 官方不提供镜像

**结论先行：Hyphanet 没有官方镜像，也不存在可靠维护的社区镜像，Docker 化只能自建。**依据（查询日期 2026-10-26）：

• 官方下载页 https://www.hyphanet.org/pages/download.html 列出的发布形态只有三种：Windows 安装器（FreenetInstaller-1507.exe）、跨平台 Java 离线安装器（new_installer_offline_1507.jar）、Debian 包（freenet_0.7.5+1507-1_amd64.deb），无任何镜像产物；
• 官方 GitHub 组织 hyphanet 的 fred 仓库 Releases（标签 build01507）同样只有上述安装包与源码；
• 实测宿主机 docker images 中不存在任何 hyphanet 相关条目。

1.2 为什么不建议用第三方镜像

P2P 节点镜像并非"无状态服务打包"那么简单：镜像内置的节点会持有 master.keys 主密钥并参与转发不可审查的加密流量。来路不明的第三方镜像可能预置后门或收集密钥，因此本文不用任何第三方镜像，而是用官方离线安装器自建——构建过程可审计，安装包可做 sha256 校验（实测值 75043e4c0d5bb1d4b610729d571373c53c9215c2933feed57ff8683a153e301a）。

1.3 自建方案要点

• 基础镜像用官方 ubuntu:22.04，容器内安装 openjdk-17-jre-headless（与裸机实测版本一致，OpenJDK 17.0.20.1）；
• 构建期运行官方安装器 console 模式（其交互流程已实测，见 3.2 节）；
• 运行期以专用用户前台启动（run.sh 拒绝 root，实测回显 Do not run this script as root.）；
• 数据目录与配置文件全部卷挂载，容器可随时重建。

二、前置条件

2.1 宿主机安装 Docker 与 Compose

Ubuntu 22.04 直接安装 Docker Engine（含 compose 插件），安装后验证（实测回显）：

docker --version
docker compose version

Docker version 29.9.2, build a82e528
Docker Compose version v5.6.1

2.2 确认基础镜像

docker images ubuntu

实测本机已存在 ubuntu:22.04（119 MB）；若没有，docker pull ubuntu:22.04 拉取。

2.3 端口规划

TCP 两个管理端口默认只绑回环（fproxy.bindTo/fcp.bindTo=127.0.0.1），容器场景下映射到宿主机回环即可；UDP 两个互联端口需对公网开放，否则节点只能出站无法被别人连入（NAT 后 assumeNATed=true 也能工作，但连接效率低）。

三、部署步骤

⚠️ 本节 Dockerfile/compose 为完整整理方案，编排层未实际构建运行；其中的安装器交互、启动方式与验证手段均有裸机实测回显支撑，应答写法按实测交互逐条对应。

3.1 目录结构

/opt/hyphanet-stack/
├── Dockerfile
├── docker-compose.yml
└── data/                 # 持久化数据与挂载配置
    ├── datastore/        # 主存储（首次启动自动生成）
    ├── freenet.ini       # 挂载的节点配置
    └── wrapper.conf      # 挂载的 JVM 配置

3.2 Dockerfile

FROM ubuntu:22.04
ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update && apt-get install -y --no-install-recommends \
      openjdk-17-jre-headless wget ca-certificates curl \
    && rm -rf /var/lib/apt/lists/*

# 官方离线安装器（build01507），构建期校验 sha256
ADD https://www.draketo.de/dateien/freenet/build01507/new_installer_offline_1507.jar /tmp/installer.jar
RUN echo "75043e4c0d5bb1d4b610729d571373c53c9215c2933feed57ff8683a153e301a  /tmp/installer.jar" | sha256sum -c -

# run.sh 拒绝 root（实测回显 Do not run this script as root.），创建专用用户；
# console 安装器有两处交互：目标路径与确认，用管道应答（对应实测提示见下）
RUN useradd -m -u 1000 -s /bin/bash hyphanet \
    && printf '/opt/hyphanet\n1\n' | java -jar /tmp/installer.jar -console \
    && chown -R hyphanet:hyphanet /opt/hyphanet \
    && rm -f /tmp/installer.jar

USER hyphanet
WORKDIR /opt/hyphanet
EXPOSE 8888 9481 17420/udp 39121/udp
HEALTHCHECK --interval=60s --timeout=10s --start-period=180s \
  CMD curl -sf http://127.0.0.1:8888/diagnostic/ || exit 1
# 前台运行：start 子命令会把进程放到后台，不适合容器 PID 1
CMD ["./run.sh", "console"]

应答写法与实测交互的对应关系（裸机实测回显）：

Select target path [/tmp]        ← 第 1 行输入 /opt/hyphanet
press 1 to continue, 2 to quit, 3 to redisplay
1                                ← 第 2 行输入 1
[ Starting to unpack ]
[ Processing package: Base (1/3) ]
[ Processing package: License (2/3) ]
[ Processing package: Unix (3/3) ]

3.3 准备初始配置文件

挂载单文件要求宿主机上先存在该文件。首次部署可先取一版"生成默认配置"再挂载：

cd /opt/hyphanet-stack
docker build -t hyphanet:0.7.5-1507 .
docker run --rm --name hyphanet-bootstrap hyphanet:0.7.5-1507 sh -c \
  'timeout 60 ./run.sh console || true; sleep 2; cat /opt/hyphanet/freenet.ini'
docker cp hyphanet-bootstrap:/opt/hyphanet/freenet.ini data/freenet.ini 2>/dev/null || true

⚠️ 更稳妥的做法：直接使用裸机同版本安装生成的 freenet.ini/wrapper.conf（本文实测文件全文见《Hyphanet 0.7.5 配置参数详解》），拷入 data/ 并把 node.storeSize 调整为卷容量可承受的值（示例 50 GiB=53687091200）。

3.4 docker-compose.yml

name: hyphanet-0.7.5-stack

services:
  hyphanet:
    build: .
    image: hyphanet:0.7.5-1507
    container_name: hyphanet-0.7.5
    restart: unless-stopped
    stop_grace_period: 90s
    ports:
      - "127.0.0.1:8888:8888"
      - "127.0.0.1:9481:9481"
      - "17420:17420/udp"
      - "39121:39121/udp"
    volumes:
      - ./data/datastore:/opt/hyphanet/datastore
      - ./data/freenet.ini:/opt/hyphanet/freenet.ini
      - ./data/wrapper.conf:/opt/hyphanet/wrapper.conf
      - ./data/plugins:/opt/hyphanet/plugins
      - ./data/plugin-data:/opt/hyphanet/plugin-data
    logging:
      driver: json-file
      options:
        max-size: "20m"
        max-file: "3"

要点：

• name: hyphanet-0.7.5-stack 显式声明编排项目名，容器/网络命名不再依赖目录名；
• 管理端口绑定 127.0.0.1，Web 界面与 FCP 不暴露公网；
• stop_grace_period: 90s：节点优雅停机需要落盘队列与配置（裸机实测 Anchor file deleted. Shutting down. 后退出），留足时间避免强杀；
• restart: unless-stopped 替代裸机的 cron 自启。

3.5 构建与启动

docker compose up -d --build
docker compose ps
curl -sI http://127.0.0.1:8888/ | head -1

⚠️ 编排层未实跑；但第三步的验证判据是实测确定的——裸机同版本节点上 curl -sI http://127.0.0.1:8888/ 返回 HTTP/1.1 200 OK，/diagnostic/ 返回 Freenet 0.7.5 Build #1507 build01507。容器内出现同样输出即部署成功。首次启动需等待主存储预分配（默认约 17.4 GiB，视 storeSize 而定）与 Opennet 引导，预热期间 /strangers/ 页连接数从 0 逐步增长（实测裸机约一小时达 2/26）。

四、数据持久化

容器可随时销毁重建，必须持久化的数据：

注意 master.keys、bookmarks.dat、memory.autolimit 等散落在安装目录根部（非 datastore 内），默认随镜像销毁而丢失。两种对策：把整个 /opt/hyphanet 作为命名卷（简单但镜像内文件与卷混层）；或按本文方式仅挂载关键文件/目录，并在宿主机按《Hyphanet 0.7.5 常用 CLI 命令与工具详解》第六节的 tar + md5 流程定期备份 data/（实测包 1.7 MB，恢复校验一致）。

五、环境变量说明

Hyphanet 没有官方支持的环境变量：安装器与 run.sh 不读取任何自定义 ENV 来控制 JVM 内存、端口或存储大小，社区流传的 JAVA_OPTS 之类写法对它无效。配置途径只有两条：

构建期使用的 DEBIAN_FRONTEND=noninteractive 只是 apt 参数，与节点无关。若宿主机想反向控制容器资源，用 compose 的 mem_limit/cpus（见 10.4）。

六、配置参数

容器内配置体系与裸机完全一致，全部细节见 《Hyphanet 0.7.5 配置参数详解》。容器场景特别注意：

• fproxy.bindTo/fcp.bindTo 保持 127.0.0.1，由 compose 的端口映射决定暴露面，不要改成 0.0.0.0 后再 -p 8888:8888（等于对公网开放管理界面）；
• node.bindTo=0.0.0.0 保持不变（容器内需绑定全部接口，端口映射才可达）；
• node.storeSize 必须小于挂载卷所在宿主机分区容量，并给 minDiskFreeShortTerm/LongTerm（536 MB / 1 GiB）留出余量；
• 修改挂载的配置文件后执行 docker compose restart hyphanet 生效。

七、配置文件挂载细节

单文件 bind mount 的经典坑：宿主机用 vim 保存会替换 inode，容器内 bind mount 仍指向旧 inode，改动不生效。正确做法：

# 推荐：编辑副本后用 cp 覆盖内容（inode 不变）
cp data/freenet.ini data/freenet.ini.new
vi data/freenet.ini.new
cp data/freenet.ini.new data/freenet.ini
docker compose restart hyphanet

或退一步把配置整体放进一个挂载目录（./data/conf:/opt/hyphanet/conf + node.install.cfgDir=./conf），规避单文件挂载。属主与权限：挂载点属主需为 uid 1000（chown -R 1000:1000 data/），否则容器内普通用户写不进（run.sh 拒绝 root，实测）。

八、等价 docker run 命令

不用 compose 时，以下命令与 3.4 的编排等价：

docker run -d \
  --name hyphanet-0.7.5 \
  --restart unless-stopped \
  -p 127.0.0.1:8888:8888 \
  -p 127.0.0.1:9481:9481 \
  -p 17420:17420/udp \
  -p 39121:39121/udp \
  -v /opt/hyphanet-stack/data/datastore:/opt/hyphanet/datastore \
  -v /opt/hyphanet-stack/data/freenet.ini:/opt/hyphanet/freenet.ini \
  -v /opt/hyphanet-stack/data/wrapper.conf:/opt/hyphanet/wrapper.conf \
  hyphanet:0.7.5-1507

⚠️ 同样属未实跑的等价写法（与 compose 逐项对应）；验证手段同 3.5 节。

九、常用运维命令

docker compose ps                          # 状态（含健康检查）
docker compose logs -f --tail 100          # 跟踪容器 stdout（console 日志）
docker exec -it hyphanet-0.7.5 ./run.sh status   # 容器内节点状态（实测回显 Freenet 0.7 is running (PID).）
docker compose restart hyphanet            # 重启节点（改配置后）
docker compose stop hyphanet               # 停止（优雅，等待落盘）
docker compose up -d hyphanet              # 启动
docker compose down                        # 停止并移除容器与网络（数据在宿主机 data/ 不受影响）

升级流程：改 Dockerfile 中安装器 URL/校验值为新 build → docker compose build → docker compose up -d；数据卷不动，freenet.ini 由节点回写升级项。备份先行（第四节）。

十、常见问题（FAQ）

10.1 为什么 Docker Hub 上找不到 hyphanet 镜像

因为官方从未发布镜像（1.1 节证据）。搜到的同名第三方镜像均非官方，鉴于节点身份与流量的敏感性，不建议使用；本文的自建方案构建过程完全可审计。

10.2 容器启动即退出，日志提示 Do not run this script as root

Dockerfile 漏了 USER hyphanet，或挂载目录属主不是 uid 1000。run.sh 硬性拒绝 root（实测回显），确保两者都修正。

10.3 可以在容器里执行 run.sh stop 吗

不建议。容器进程即 run.sh console（前台），容器内 stop 会终止主进程导致容器退出重建，绕过 compose 的管控；启停一律用 docker compose stop/restart。裸机上 stop 后偶发的 anchor/pid 残留问题（实测需 kill -9 + 删 Freenet.anchor/Freenet.pid）在容器场景被"重建容器"天然解决。

10.4 容器内存限制和 JVM 堆怎么配

两者要分层理解：compose 的 mem_limit 限制整个容器（JVM 堆 + 堆外 + bloom 过滤器 + 存储 mmap）；wrapper.conf 的 maxmemory 只管 JVM 堆。经验配置（裸机实测 256/512 堆运行正常）：mem_limit: 1g + wrapper.java.maxmemory=512，余量留给 bloom 过滤器与非堆内存（wrapper.conf 官方注释明确提醒 bloom 过滤器内存在堆上限之外）。

10.5 改了 data/freenet.ini 重启后不生效

单文件挂载 inode 问题（第七节）：用 cp 覆盖内容而非 vim 直接保存；或改用目录挂载。确认生效方法：docker exec hyphanet-0.7.5 grep storeSize /opt/hyphanet/freenet.ini。

10.6 UDP 端口映射后连接数还是上不去

先在宿主机防火墙放行 UDP 17420/39121；云主机还需在安全组放行。若宿主机在 NAT 后且无法公网直连，保持 node.assumeNATed=true，节点会通过出站连接工作，只是被连入能力受限（裸机实测 NAT 环境约一小时连上 2/26）。极端网络环境可考虑 network_mode: host 简化 UDP（仅 Linux，且失去端口隔离）。

10.7 如何彻底卸载

docker compose down      # 移除容器与编排网络
docker rmi hyphanet:0.7.5-1507
rm -rf /opt/hyphanet-stack/data   # 删除主存储与密钥（确认退役时）

如需保留节点身份，先按第四节备份 master.keys 等文件。

十一、参考链接

• 官方下载页（发布形态证据）：https://www.hyphanet.org/pages/download.html（查询日期 2026-10-26）
• 本版发布标签：https://github.com/hyphanet/fred/releases/tag/build01507/
• Docker Compose 官方文档：https://docs.docker.com/compose/
• 本专栏《Ubuntu 22.04 安装 Hyphanet 0.7.5 指南》：《Ubuntu 22.04 安装 Hyphanet 0.7.5 指南》
• 本专栏《Hyphanet 0.7.5 配置参数详解》：《Hyphanet 0.7.5 配置参数详解》
• 本专栏《Hyphanet 0.7.5 常用 CLI 命令与工具详解》：《Hyphanet 0.7.5 常用 CLI 命令与工具详解》
• 本专栏《Hyphanet 0.7.5 介绍与选型指南》：《Hyphanet 0.7.5 介绍与选型指南》