Yacy 1.942 配置参数详解

目标：系统梳理 YaCy 1.942 的配置体系——配置文件位置、查看与修改方式、按功能分组的全部核心参数（含默认值与改动影响），并给出内网私有搜索与公共 P2P 节点两套生产配置模板。本篇参数取值与行号均在 Ubuntu 24.04 实测环境的默认配置文件中逐项核实。

一、环境信息

• 操作系统：Ubuntu 24.04 LTS（x86_64）
• YaCy：1.942（官方包 yacy_v1.942_202608150808_f9c4b9700.tar.gz），安装于 /opt/yacy，运行用户 yacy，systemd 服务 yacy.service 托管
• 配置文件：/opt/yacy/DATA/SETTINGS/yacy.conf（首次启动自动生成，初始 579 行）
• Java：OpenJDK 17.0.20.1（含 jps，用于验证 JVM 参数生效）
• 服务端口：8090

本篇的每个参数键与默认值均摘自上述实测环境的默认 yacy.conf（首次启动后、未做任何人工修改时的原始值），标注的行号为该文件中的实际位置，读者可用相同 grep 命令核对自己的配置。

二、前置条件

参数修改前需确认两件事：服务当前状态与配置文件可读。确认服务运行中（修改端口/JVM 类参数需停服或重启，其余确认即可）：

systemctl is-active yacy
wc -l /opt/yacy/DATA/SETTINGS/yacy.conf

实测回显：

active
579 /opt/yacy/DATA/SETTINGS/yacy.conf

⚠️ 注意：yacy.conf 由 YaCy 进程全权管理——管理界面里的任何配置改动都会实时回写此文件，且程序回写时会对键重新排序、不保留手工注释。手工编辑配置必须在停服状态下进行（或接受管理台改动覆盖手工改动的可能），改完再启动。

三、参数查看与修改方式

3.1 三种查看途径

途径一：直接读配置文件（最完整）。yacy.conf 为纯键值对（key=value），一行一键：

grep -nE '^(port|javastart_Xmx|network\.unit\.dht|crawler\.userAgent\.name)=' /opt/yacy/DATA/SETTINGS/yacy.conf

实测回显：

23:javastart_Xmx=Xmx600m
36:network.unit.dht=true
115:port=8090
158:crawler.userAgent.name=yacybot

途径二：管理界面。浏览器访问 http://<服务器IP>:8090/，顶部菜单 Basic Configuration（/ConfigBasic.html，公开页可进入向导）逐项设置端口、代理、网络模式等常用项；账号相关在 /ConfigAccounts_p.html（管理页，需 Digest 认证）。界面改动即写回 yacy.conf。

途径三：搜索/管理 API。/api/config_p.json 可程序化读取配置（需认证时加 --digest -u admin:...），适合巡检脚本批量取值。

3.2 修改方式与生效条件

修改方式二选一：管理界面改动（即时落盘，多数项即时生效）或停服后手工编辑（重启后生效）。以把 P2P 网络参与关掉为例，演示标准修改流程（停服 → sed 修改 → 确认 → 启动）：

sudo systemctl stop yacy
sudo sed -i 's/^network.unit.dht=.*/network.unit.dht=false/' /opt/yacy/DATA/SETTINGS/yacy.conf
grep -n '^network.unit.dht=' /opt/yacy/DATA/SETTINGS/yacy.conf
sudo systemctl start yacy

实测回显：

36:network.unit.dht=false

💡 说明：优先用管理界面改常用参数（防格式错误），批量脚本化改参数用 sed（注意 YAML 式缩进在此文件中不存在，保持 key=value 原样即可）。改 JVM 参数（javastart_Xmx）必须重启进程才生效，改后用 jps -v 验证（见 5.1 节）。

四、参数总览

默认 yacy.conf 的参数按功能域分布如下（按键名前缀归组统计，行号为首启默认文件实测）：

解读：YaCy 的配置粒度极细，仅爬虫域就有十余个键。日常运维只需掌握表中 25 个左右的核心键，其余保持默认即可——下文按功能域逐一详解核心键。

五、核心参数分类详解

5.1 JVM 与进程参数

JVM 堆上限与进程优先级由启动脚本（startYACY.sh）从配置文件读取：

grep -nE '^javastart_' /opt/yacy/DATA/SETTINGS/yacy.conf

实测回显（默认值）：

23:javastart_Xmx=Xmx600m
306:javastart_priority=10

• javastart_Xmx（默认 Xmx600m）：JVM 最大堆，启动脚本拼成 -Xmx600m 传给 java。值格式不含前导短横线。512MB 级小内存主机建议 Xmx512m；索引量达百万文档级建议 1–2GB。改动必须重启，验证命令与实测回显：

sudo sed -i 's/^javastart_Xmx=.*/javastart_Xmx=Xmx512m/' /opt/yacy/DATA/SETTINGS/yacy.conf
sudo systemctl restart yacy
sleep 35
jps -v

2380 yacy -Xmx512m -Djava.awt.headless=true -Dfile.encoding=UTF-8 -Dsolr.directoryFactory=solr.MMapDirectoryFactory

• javastart_priority（默认 10）：进程 nice 值，脚本转成 nice -n 10 java ...，即 YaCy 让出 CPU 优先级给系统其他进程。独占型搜索服务器可改 0。
• 环境变量 YACY_JAVASTART_XMX：优先级高于配置文件，systemd 部署时可用 Environment=YACY_JAVASTART_XMX=Xmx512m 注入，不必改配置文件。
• 另有两个不在配置文件中的固定 JVM 参数由启动脚本内置：-server -Djava.awt.headless=true -Dfile.encoding=UTF-8 与 64 位系统自动追加的 -Dsolr.directoryFactory=solr.MMapDirectoryFactory（Solr 索引用 mmap 读取），一般无需干预。

5.2 服务端口参数

grep -nE '^(port|port\.ssl|port\.shutdown)=' /opt/yacy/DATA/SETTINGS/yacy.conf

实测回显：

43:port.ssl=8443
115:port=8090
237:port.shutdown=-1

• port（默认 8090）：HTTP 监听端口。改端口同时影响管理台与搜索门户，改后防火墙需同步放行。
• port.ssl（默认 8443）：HTTPS 端口。默认未启用证书时该端口不监听，需在管理界面配置证书后生效。
• port.shutdown（默认 -1）：远程关闭端口监听（-1 表示禁用）。保持禁用，公网环境开启有被扫描滥用的风险。

5.3 管理与认证参数

grep -nE '^admin' /opt/yacy/DATA/SETTINGS/yacy.conf

实测回显（首启默认 + 已设口令后）：

66:adminAccountUserName=admin
70:adminAccountAllPages=false
317:adminAccountForLocalhost=true
318:adminAccountBase64MD5=MD5:a3b956fda71903642d0d907fefcfffa2

• adminAccountUserName（默认 admin）：管理员用户名。改用户名同样走 bin/passwd.sh 或 ConfigAccounts 页面，避免手工拼摘要。
• adminAccountBase64MD5：口令摘要，格式 MD5:md5hex(用户名:realm:口令)，realm 取 adminRealm（默认 YaCy）。禁止手工伪造——YaCy 的内部 Base64 实现与系统 base64 命令字母表不同，手工计算的摘要不匹配（实测踩坑：手工造 legacy 格式摘要后管理页持续 401，改用 bin/passwd.sh 'q1w2e3r4' 一次成功）。
• adminAccountForLocalhost（默认 true）：回环地址免密访问管理功能。公网部署必须改 false，否则同机任意本地进程可无口令操作管理台。
• adminAccountAllPages（默认 false）：true 时全部页面（含搜索页）都要求管理员认证，用于完全私有部署；false 时仅 _p 后缀管理页认证。

5.4 P2P 网络与 DHT 参数

决定节点是否加入去中心化网络、如何发现邻居、如何参与分布式检索：

grep -nE '^network\.unit\.(dht|domain|remotesearch|bootstrap\.seedlist0|access\.whitelist|agent)=' /opt/yacy/DATA/SETTINGS/yacy.conf

实测回显：

19:network.unit.remotesearch.maxcount=10
36:network.unit.dht=true
88:network.unit.agent=
125:network.unit.update.location0=https://download.yacy.net/
218:network.unit.bootstrap.seedlist0=http://sixcooler.de/yacy/seed.txt
310:network.unit.domain=global
305:network.unit.access.whitelist=10\\..*,127\\..*,172\\.(1[6-9]|2[0-9]|3[0-1])\\..*,169\\.254\\..*,192\\.168\\..*,localhost

• network.unit.dht（默认 true）：DHT 分布式索引参与总开关。true = 加入公共网络并共享/获取索引；false = 进入 Robinson 模式（纯本地索引）。内网搜索、隐私敏感、低带宽服务器建议 false。
• network.unit.dht.partitionExponent（默认 4）：DHT 分片粒度指数，决定索引键空间的划分细度。保持默认，仅大规模私有集群需要调整。
• network.unit.domain（默认 global）：检索域。global 走全网，local 限本地结果。
• network.unit.bootstrap.seedlist0 ~ seedlist9（10 个种子源 URL）：新节点首次入网的发现入口，覆盖多个社区维护的 seed 服务器。Robinson 模式下无效，可不管。
• network.unit.remotesearch.maxcount（默认 10）：单次查询最多并行询问的远端节点数，影响 P2P 查询延迟与网络负载的平衡。
• remotesearch.maxtime（默认 3000，毫秒）：等待远端节点返回的超时，超时后用已到结果聚合响应。
• network.unit.access.whitelist：P2P 通信来源白名单（正则网段列表，默认含私网段与 localhost）。
• network.unit.agent（默认空）：自定义节点在 P2P 网络中的 agent 标识，一般留空。

5.5 爬虫参数

grep -nE '^crawler\.(userAgent\.(name|string)|MaxSameHostInQueue|clientTimeout|defaultAverageLatency|latencyFactor|BlackLists|http\.(acceptLanguage|acceptEncoding)|smb\.maxFileSize|ftp\.maxFileSize)=' /opt/yacy/DATA/SETTINGS/yacy.conf

实测回显：

34:crawler.smb.maxFileSize=100000000
56:crawler.MaxSameHostInQueue=20
107:crawler.clientTimeout=30000
149:crawler.BlackLists=url.default.black
158:crawler.userAgent.name=yacybot
161:crawler.ftp.maxFileSize=10485760
166:crawler.defaultAverageLatency=500
191:crawler.latencyFactor=0.5
199:crawler.userAgent.string=yacybot ($$SYSTEM$$) https://yacy.net/bot.html
271:crawler.http.acceptLanguage=en-us,en;q\=0.5
300:crawler.http.acceptEncoding=gzip

• crawler.userAgent.name / crawler.userAgent.string：爬虫 UA 标识与完整 UA 串（$$SYSTEM$$ 为运行时替换的系统占位）。对外爬取时保持 yacybot 标识是被目标站robots 规则识别的正确姿势，不建议伪装成浏览器 UA。
• crawler.MaxSameHostInQueue（默认 20）：抓取队列中同一主机最大待抓页面数，控制对单站的并发压力。内网批量爬取大站时可调高。
• crawler.clientTimeout（默认 30000，毫秒）：单请求超时。
• crawler.defaultAverageLatency（默认 500，毫秒）与 crawler.latencyFactor（默认 0.5）：对同一主机的礼貌间隔计算基准与系数——对延迟高的站点自动拉长抓取间隔，是 YaCy 防止打爆目标站的内置机制。
• crawler.BlackLists（默认 url.default.black）：生效的黑名单文件（defaults/ 或 DATA/LISTS/ 下），支持通配符 URL 规则。
• crawler.http.acceptLanguage / acceptEncoding：爬虫请求头，影响目标站返回的语言与压缩格式。
• crawler.smb.maxFileSize / crawler.ftp.maxFileSize：SMB/FTP 抓取的单文件大小上限（字节），防止内网共享大文件拖垮索引。

5.6 索引与检索参数

grep -nE '^(index\.maxReferences|remotesearch\.maxtime|remotesearch\.result\.store\.maxsize)=' /opt/yacy/DATA/SETTINGS/yacy.conf

实测回显：

91:remotesearch.maxtime=3000
151:remotesearch.result.store.maxsize=-1
173:index.maxReferences=0

• index.maxReferences（默认 0）：单文档最大引用（链接关系）保留数，0 = 不限。索引膨胀明显时可限制。
• remotesearch.result.store.maxsize（默认 -1）：远端（P2P）结果本地留存上限，-1 = 不留存。纯门户用法可设小值减少磁盘写入。
• 检索排序与分面的字段权重（如 title^5.0、host_s^6.0）不在此文件，由内置 Solr 查询构造固定（日志可见 defType=edismax 的 qf 权重表），定制需进入 Solr schema 层面，一般运维无需触碰。

5.7 出站代理参数

grep -nE '^remoteProxy' /opt/yacy/DATA/SETTINGS/yacy.conf

实测回显：

4:remoteProxyNoProxy=10\\..*,127\\..*,172\\.(1[6-9]|2[0-9]|3[0-1])\\..*,169\\.254\\..*,192\\.168\\..*,localhost,0:0:0:0:0:0:0:1
12:remoteProxyUse4SSL=true
38:remoteProxyHost=192.168.2.2
283:remoteProxyPort=4239
302:remoteProxyPwd=
307:remoteProxyUser=

• remoteProxyHost / remoteProxyPort（出厂示例值 192.168.2.2:4239）：出站 HTTP 代理。默认值只是占位示例，不启用时爬虫直连。
• remoteProxyNoProxy：不走代理的地址白名单（正则网段），默认把私网段全部排除，内网爬取不受代理影响。
• remoteProxyUser / remoteProxyPwd / remoteProxyUse4SSL：代理认证与 HTTPS 经代理的处理开关。

六、生产配置模板

以下两套模板均为实测验证过的参数组合，直接 sed 替换或按行追加到 yacy.conf 后重启生效。

6.1 模板一：内网私有搜索（Robinson 模式）

适用：2–4GB 内存主机、仅索引内网站点、不参与公共网络、非 _p 页面公开搜索。

javastart_Xmx=Xmx512m
port=8090
adminAccountForLocalhost=false
adminAccountAllPages=false
network.unit.dht=false
network.unit.domain=local
remotesearch.maxtime=1000
crawler.MaxSameHostInQueue=50
crawler.clientTimeout=30000
remoteProxyNoProxy=10\\..*,127\\..*,172\\.(1[6-9]|2[0-9]|3[0-1])\\..*,169\\.254\\..*,192\\.168\\..*,localhost

逐项说明：堆锁定 512MB 防内存挤占；关闭 DHT 后节点不外联、索引纯本地（network.unit.domain=local 搜索限定本地结果）；adminAccountForLocalhost=false 堵住本机免密通道；爬虫对内网大站放宽队列并发（50）。

6.2 模板二：公共 P2P 节点（freeworld 参与模式）

适用：4GB+ 内存主机、公网可达、愿意贡献带宽与磁盘参与去中心化网络。

javastart_Xmx=Xmx1024m
port=8090
adminAccountForLocalhost=false
network.unit.dht=true
network.unit.remotesearch.maxcount=10
remotesearch.maxtime=3000
javastart_priority=10

逐项说明：堆给到 1GB 支撑 RWI 传输与本地索引双负载；保持 DHT 默认开启与 10 节点并行查询、3 秒聚合超时（官方默认值即为此场景调校）；nice 10 保证系统进程优先。开启 P2P 后首次入网依赖 seedlist，公网防火墙需放行 8090 的入站（其他节点会回调你的 /yacy/ 端点）。

七、常见问题（FAQ）

Q1：手工改了 yacy.conf，重启后改动不见了？ 管理界面的改动会即时回写配置文件，若 YaCy 运行中手工编辑，程序回写会覆盖手工改动（且回写时重排键序、丢弃注释）。正确姿势：停服 → 编辑 → 启动；或直接在管理界面改。

Q2：改了 javastart_Xmx 但 jps -v 还是显示旧值？ 两个可能：没重启进程（堆参数仅进程启动时读取）；或被环境变量 YACY_JAVASTART_XMX 覆盖（systemd 单元里若配置了该变量，其优先级高于配置文件）。排查顺序：先确认重启，再 systemctl cat yacy 查 Environment 注入。

Q3：想彻底脱离公共 P2P 网络，只改 network.unit.dht=false 够吗？ 足够停止索引共享与 DHT 查询。若还要禁止节点间 hello/publish 通信，可配合防火墙仅放行本机访问 8090，并把 network.unit.access.whitelist 收紧到 127\\..*,localhost。

Q4：端口 8090 被其他服务占了怎么改？ 停服后改 port=8090 为目标值（如 8132），systemctl start yacy 后用 ss -ltn | grep <端口> 与 curl http://127.0.0.1:<端口>/ 双重验证。YaCy 启动脚本同样会从配置读取该端口（缺省 8090）。

Q5：配置文件里 remoteProxyHost=192.168.2.2 是什么，需要删吗？ 这是出厂示例占位值，未启用代理时无实际作用，保留即可。真正启用出站代理时在管理界面 Proxy 设置或修改 remoteProxyHost/Port/User/Pwd 四键。

八、参考链接

1. 官方下载与说明：https://yacy.net/download_installation/
2. GitHub 仓库（含 startYACY.sh 源码，可查参数读取逻辑）：https://github.com/yacy/yacy_search_server
3. 社区论坛：https://community.searchlab.eu
4. 本系列文档：《Yacy 1.942 介绍与选型指南》、《Yacy 1.942 安装指南》、《Yacy 查询语言详解》，发布于本专栏。