Hyphanet 0.7.5 常用 CLI 命令与工具详解

目标：读完本文你将掌握 Hyphanet 0.7.5 的全套命令行运维手段：run.sh 六个子命令、curl 访问 FProxy 诊断端点、FCP 协议探针与 freesite 插入、配置备份恢复、日志排查与卸载清理，已在 Ubuntu 22.04（OpenJDK 17）实测通过。

环境信息：本文所有命令与回显均在下列环境实测完成。

安装与配置见 《Ubuntu 22.04 安装 Hyphanet 0.7.5 指南》 与 《Hyphanet 0.7.5 配置参数详解》。

一、工具概览

Hyphanet 没有独立的"管理 CLI"，运维能力由四类工具组合而成：

二、前置条件

节点已安装并以普通用户运行（实测验证）：

cd /opt/hyphanet
./run.sh status
curl -sI http://127.0.0.1:8888/ | head -1

Freenet 0.7 is running (52573).
HTTP/1.1 200 OK

三、run.sh：节点控制脚本

3.1 命令集

run.sh 支持 6 个子命令（实测错误调用时的 usage 回显）：

Usage: ./run.sh { console | start | stop | restart | status | dump }

日常节奏（实测可用）：

./run.sh status
./run.sh restart
./run.sh status

第二次 status 回显：

Freenet 0.7 is running (53120).

脚本内置行为（实测确认）：拒绝 root（Do not run this script as root.）；自动探测 Java 并回写 wrapper.conf（日志 Your java executable at /bin/java seems suitable）；进程以 nice 10 低优先级运行。

3.2 前台运行（console）

./run.sh console

适合首次启动观察引导过程；Ctrl+C 即停止节点。后台常驻请用 start。

3.3 优雅停机机制与僵死处理

stop 的机制是删除 anchor 文件（Freenet.anchor），节点轮询到文件消失后自行退出。实测 bin/wrapper.log 回显：

STATUS | wrapper  | ... | Anchor file deleted. Shutting down.

实测遇到过一次 stop 后脚本挂起不返回，残留进程与 anchor/pid 文件会阻止下次启动，处理：

ps -ef | grep [f]reenet.node.NodeStarter   # 找到 PID
kill -9 <PID>
rm -f /opt/hyphanet/Freenet.anchor /opt/hyphanet/Freenet.pid
./run.sh start

3.4 快速核对 JVM 进程

openjdk-17-jre-headless 不含 jps（实测 jps -v 空输出），验证进程一律用：

ps -ef | grep [f]reenet.node.NodeStarter

实测回显（节选，可直接读出内存与参数）：

hyphanet  53120      1  2 10:31 ?  00:00:30 /usr/lib/jvm/java-17-openjdk-amd64/bin/java -Dnetworkaddress.cache.ttl=0 ... -Xss512k -Xms256m -Xmx512m ... freenet.node.NodeStarter freenet.ini

3.5 bin/ 附带小工具

bin/ 下除各架构 wrapper 二进制外，实测还有：

示例（端口排障）：

java -jar bin/bindtest.jar 17420

以上小工具为官方随包提供，本文实测确认文件存在；具体用法可用 java -jar <工具> --help 探索。

四、curl：FProxy 诊断端点速查

FProxy 全部端点均可 curl 访问，无需浏览器。实测（curl -s -o /dev/null -w "%{http_code} %{size_download}" http://127.0.0.1:8888<path>）：

版本诊断一例（curl -s http://127.0.0.1:8888/diagnostic/ | head -12）：

Freenet Version:
Freenet 0.7.5 Build #1507 build01507
Freenet-ext Build #29 rv29
System Information:
Used Java memory: 399 MiB
Allocated Java memory: 512 MiB
Maximum Java memory: 512 MiB
Running threads: 87/1000
Available CPUs: 6
Java Version: 17.0.20.1

带宽与限速复核（/stats/ 页对应字段）：

Input Rate:  20.8 KiB/s (of 1.0 MiB/s)
Output Rate: 21.0 KiB/s (of 160 KiB/s)
Payload Output: 71%

五、FCP 协议探针与 freesite 插入

5.1 端口与协议要点

FCP 监听 127.0.0.1:9481（fcp.port）。它是纯文本行协议，不是 HTTP——curl 无法与其对话（实测确认），环境中若无 nc，用 python3 标准库 socket 即可。

关键协议行为（实测踩坑结论）：单独发送 ClientHello 不会得到响应（实测超时），必须把 ClientHello 与业务消息在同一条连接上一次性发送。

5.2 NodeHello + NodeData 探针脚本

import socket, time
s = socket.create_connection(("127.0.0.1", 9481), 10)
msg = (b"ClientHello\nName=cli-probe\nExpectedVersion=2.0\nEnd\n"
       b"GetNode\nIdentifier=cli-probe\nGiveOpennetRef=false\nWithPrivate=false\nEnd\n")
s.sendall(msg)
buf = b""
deadline = time.time() + 20
while time.time() < deadline:
    s.settimeout(max(1, deadline - time.time()))
    try:
        c = s.recv(65536)
    except socket.timeout:
        break
    if not c:
        break
    buf += c
    if b"NodeData" in buf and b"Version=" in buf:
        break
print(buf.decode("utf-8", "replace")[:1600])

实测回显（节选）：

NodeHello
CompressionCodecs=4 - GZIP(0), BZIP2(1), LZMA(2), LZMA_NEW(3)
Version=Fred,0.7,1.0,1507
Build=1507
ConnectionIdentifier=b0d4364c11d411384a75dccac8740bb3
Testnet=false
FCPVersion=2.0
NodeLanguage=ENGLISH
ExtBuild=29
EndMessage
NodeData
identity=Ld1~6csuvt6pou1-i-8mi5gK6KWds1JRxYpQUDV6Ohg
myName=Freenet node with no name #7361848122103977527
location=0.169...
lastGoodVersion=Fred,0.7,1.0,1475
physical.udp=10.89.58.2:17420
ark.pubURI=SSK@.../ark
EndMessage

这是最可靠的"节点活着且 FCP 可用"探针：Build=1507 确认版本，NodeData 暴露节点引用要点。

5.3 插入 freesite 实测（ClientPutComplexDir）

用 FCP 插入一个双文件测试站点（index.html + style.css），关键消息结构：先 ClientHello，随后 ClientPutComplexDir（DefaultName=index.html、Persistence=forever），每个文件以 Files.N.Name/UploadFrom=direct/Metadata.ContentType/DataLength 描述并跟随二进制数据块。实测结果：

• 插入成功，返回站点内容寻址密钥（CHK）：

CHK@POSwr3DtF3mmq1hQ1dfo5zWRl607i8KSVAQQ5cY29~8,1p9wXobPJ0DtmnqV1e5-NZ5rz1Rcef5gCkvNSL1RUWs,AAMC--8

• FProxy 访问验证：GET /CHK@POSwr3DtF3mmq1hQ1dfo5zWRl607i8KSVAQQ5cY29~8,1p9wXobPJ0DtmnqV1e5-NZ5rz1Rcef5gCkvNSL1RUWs,AAMC--8/index.html 返回 HTTP 200，233 字节页面原文返回。

单个文件插入（ClientPut）同样成功，返回 CHK@DpGJIpFA1yIFzuvjatGeiauT~HftCILwqHYpNbs7KnU,...。注意实测行为：直接 GET 裸 CHK 会得到 301（Give more path components in URI），需要补路径/类型（如 /CHK@.../index.html）才能取回内容。

Persistence=forever 的插入在节点重启后仍会继续执行（队列落盘），这也是 6.x 节强调备份 master.keys 的原因。

六、配置备份与恢复（实测）

6.1 备份

先停节点（保证文件一致性），打包密钥与配置（实测命令）：

cd /opt/hyphanet
./run.sh stop
tar czf /tmp/hyphanet-config-backup-20261026.tar.gz \
  master.keys client.dat.crypt client-throttle.dat node-throttle.dat \
  bookmarks.dat freenet.ini wrapper.conf memory.autolimit \
  Sharesite.db plugin-data plugins
ls -lh /tmp/hyphanet-config-backup-20261026.tar.gz

实测回显：包大小 1.7 MB。清单说明：

6.2 恢复与校验

解包到全新目录后逐文件 md5 对比（实测命令与结果）：

mkdir /tmp/restore-test && tar xzf /tmp/hyphanet-config-backup-20261026.tar.gz -C /tmp/restore-test
md5sum master.keys freenet.ini | awk '{print $1}'
md5sum /tmp/restore-test/master.keys /tmp/restore-test/freenet.ini | awk '{print $1}'

实测两侧一致（节选）：

217215b3...（master.keys）
85a135d9...（freenet.ini）

恢复即"把备份文件放回安装目录（保持属主与 600 权限）再启动节点"；迁移到新机时同样先装好同版本节点，再覆盖这些文件。

七、日志查看与排查

7.1 日志文件布局（实测）

7.2 常用命令

tail -f logs/freenet-latest.log                # 实时跟踪
grep -i "error" logs/freenet-latest.log        # 错误检索
zgrep -i "disconnect" logs/freenet-*.log.gz    # 压缩日志检索
tail -50 bin/wrapper.log                       # 启停/异常退出排查

临时调高日志级别：fproxy/config 页 logger 分区或停机改 freenet.ini 的 logger.priority（如 MINOR/DEBUG），排障后调回 WARNING。

八、卸载清理命令

完整卸载流程（自启 → 停止 → 官方卸载器 → 数据清理）：

cd /opt/hyphanet
bin/remove_cronjob.sh                    # 1. 取消开机自启
./run.sh stop                            # 2. 停止节点
java -jar Uninstaller/uninstaller.jar    # 3. 官方卸载器（交互式）
rm -rf /opt/hyphanet                     # 4. 彻底清理程序与数据（确认退役时）

说明：卸载器文件实测存在（Uninstaller/uninstaller.jar，167,101 字节），但卸载动作本身未实跑；全部数据都在安装目录内，第 4 步 rm -rf 即可清掉 17.4 GiB 主存储。退役前如需保留身份请先按第六节备份。

九、注意事项

• 编辑配置必须停机：freenet.ini 在节点关闭时被回写，运行中手改会被覆盖（见《Hyphanet 0.7.5 配置参数详解》）；
• FCP 客户端必须先 ClientHello，且与业务消息同连接发送；curl/HTTP 工具对 9481 无效；
• 裸 CHK 访问返回 301：取回插入内容要带路径成分；
• master.keys 权限 600，包含节点身份，不要外发；备份介质同样妥善保管；
• kill -9 属最后手段，正常优先 ./run.sh stop（优雅停机会把内存队列与配置落盘）。

十、常见问题（FAQ）

10.1 FCP 探针一直超时

对照三点：连接的是 9481 而非 8888；ClientHello 与业务消息同连接一次发送（实测分开发送无响应）；fcp.allowedHosts 是否包含来源 IP（默认仅回环）。

10.2 curl 访问 9481 挂起无输出

正常：FCP 不是 HTTP，curl 发送的请求无法被识别响应。改用 5.2 节的 socket 探针。

10.3 status 显示 running 但 Web 打不开

先看监听（fproxy.bindTo=127.0.0.1 时只能本机访问，跨机访问需按配置文档放宽 bindTo/allowedHosts）；再 curl -sI http://127.0.0.1:8888/ 确认；仍无响应则查 bin/wrapper.log 是否反复重启。

10.4 备份恢复后下载队列/书签没了

检查恢复清单是否包含 client.dat.crypt（持久队列）与 bookmarks.dat；且恢复时节点已停止、文件属主与权限（600）正确。

10.5 dump / console 有什么区别

console 是前台运行整个节点；dump 是对后台运行中的 JVM 请求线程转储（写入日志），用于节点卡死时分析线程栈，不中断服务。

十一、参考链接

• FCP 协议说明（官方 Wiki）：https://github.com/hyphanet/wiki/wiki/FCPv2（查询日期 2026-10-26）
• 官方 Wiki 主页：https://github.com/hyphanet/wiki/wiki
• 本专栏《Hyphanet 0.7.5 配置参数详解》：《Hyphanet 0.7.5 配置参数详解》
• 本专栏《Ubuntu 22.04 安装 Hyphanet 0.7.5 指南》：《Ubuntu 22.04 安装 Hyphanet 0.7.5 指南》
• 本专栏《Hyphanet 0.7.5 介绍与选型指南》：《Hyphanet 0.7.5 介绍与选型指南》