项目定位与目标

YaCy 是一个去中心化的对等网络（P2P）搜索引擎，每个节点同时承担索引服务器、网页爬虫、Web 前端三个角色。如 README.md 所述，单个 YaCy 实例既可以作为个人/企业内网搜索的独立工具，也可以加入全球 P2P 网络共享索引。社区长期关注的“将 Web 端口与对等数据交换端口分离”（#315 与 #791）正是围绕这套多层网络架构展开的。

核心分层

应用骨架与请求生命周期

YaCy 由若干核心 Java 包组成：net.yacy.search（调度与爬虫）、net.yacy.server（HTTP 服务器骨架）、net.yacy.cora（协议与编码工具）。请求进入节点后，先由 HTTP 服务器接收，再分发至 Switchboard 处理业务逻辑（如搜索、爬取、API 调用）。Web 页面和 API 响应通过 TemplateEngine 渲染，并使用 serverObjects 收集模板变量。

serverObjects 类提供 putWiki 系列方法，把 Wiki 源码自动转成 HTML 后写入模板；这样页面作者既能复用 Wiki 语法，也能直接嵌入静态内容（source/net/yacy/server/serverObjects.java）。其 inc 方法用于计数器场景，getParams 方法把同名 POST 字段展开成字符串数组，方便批量处理分页与列表参数。

模板渲染与本地化

source/net/yacy/server/http/TemplateEngine.java 负责从 htroot/ 目录读取模板，应用变量替换并输出 UTF-8 编码的 HTML。模板中常见三种占位符：

• #[var]#：纯变量替换；
• #(expr)#::true::false#(/expr)#：条件分支；
• #{list}#…#{/list}#：列表循环。

htroot/api/yacydoc.html 与 htroot/api/citation.html 即是 API 页面模板，分别用于展示文档元数据与文档引用片段。多语言资源通过 source/net/yacy/utils/translation/GenerateMasterXliff.java 把 locales/*.lng 汇总为 XLIFF 主文件，方便后续翻译协作。

爬虫/索引/API 子系统

source/net/yacy/htroot/api/ 下的类与同名 *.html 模板构成 API 层。每个 servlet 通常存在两份实现：_p.java（新版，输出 XML/JSON）与已废弃的旧版（例如 source/net/yacy/htroot/api/getpageinfo.java 已标记 @Deprecated，应使用 source/net/yacy/htroot/api/getpageinfo_p.java）。其它重要端点包括：

每个 servlet 接收 RequestHeader、serverObjects post、serverSwitch env 三个参数：前者携带 HTTP 头，serverObjects 收集请求字段，serverSwitch 是访问全局配置的桥接对象（serverSwitch 接口由 Switchboard 实现）。

网络可达性与 UPnP 映射

要让外部 peer 连入，YaCy 默认会通过 UPnP 在家庭路由器上映射端口。source/net/yacy/utils/upnp/UPnP.java 调用 GatewayDiscover 发现 IGD 设备并创建映射；source/net/yacy/utils/upnp/UPnPMappingType.java 目前仅区分 HTTP 与 HTTPS 两种协议；source/net/yacy/utils/upnp/UPnPMapping.java 把 yacy.config 中的端口键、开关键等元数据打包成不可变值对象，从而在运行时按需开启/关闭端口映射。

RobotsTxtConfig（RobotsTxtConfig.java）则控制搜索引擎是否允许抓取 wiki、blog、bookmarks 等子模块；其 LOCKED 与 PROFILE 默认 Disallowed，从而阻止外部爬虫窥探管理面板与个人资料，这一机制同时也是内置的访问控制层。

数据流概览

flowchart LR
    Browser[浏览器 / peer] -->|HTTP| HTTPSrv[serverCore + TemplateEngine]
    Peer[其他 YaCy peer] -->|P2P 协议| Switchboard
    UPnP[UPnP 路由器] -->|端口映射| HTTPSrv
    HTTPSrv --> Servlet[htroot/api/* servlet]
    Servlet --> Switchboard
    Switchboard --> Index[(本地索引 / RWI)]
    Switchboard --> Crawler[爬虫队列]
    Servlet -->|serverObjects + 模板| Browser

配置、构建与部署

构建使用 Apache Ant：build.xml 会读取 Git 信息写入 yacy_version 标签，再用 Ivy 解析依赖。社区曾报告构建失败（#788）以及 Docker 容器中 yacy_v1.941_fatal: not a git repository 的损坏版本号（#796），其根因均在于构建脚本对 Git 工作树状态的依赖——在无 .git 的环境中需要注入虚拟的版本元数据。

部署方面，charts/README.md 描述了官方 Helm Chart：可选用 yacy/yacy_search_server:latest 镜像，也可在 localhost:5000 本地仓库构建自定义镜像。社区多次提出“公网端口与监听端口分离”的需求（#315 与 #791），目前主要通过反向代理 + staticIP/port 配置变通实现，而 YACY_ 环境变量对驼峰式键的支持也存在缺陷（#794）。

See Also

• API wiki page
• YaCy forum: https://community.searchlab.eu
• Related source modules: net.yacy.search.Switchboard、net.yacy.crawler.CrawlSwitchboard、net.yacy.server.serverCore

概述

YaCy 是一个完全分布式的点对点(P2P)网页搜索引擎，使用 Java 实现。整个项目以单一可执行 JAR 形式分发，同时也提供多架构 Docker 镜像用于容器化部署。根据 README.md 的描述，每个 YaCy 实例既可以作为独立搜索引擎运行，也可以加入全球 P2P 集群共享索引。其部署形态涵盖了从家庭单节点、企业内网，到 Kubernetes 集群代理反代等多种场景。

部署相关的工作流主要由以下几个层次构成：

1. 构建与打包：通过 Apache Ant 的 build.xml 编译并打包为可分发产品。
2. 运行时配置：支持 Web 界面、yacy.conf 文件、以及 YACY_ 前缀的环境变量三种方式。
3. 网络可达性：通过 UPnP 协议自动进行端口映射，以便 P2P 节点互联。
4. 可观测性与共享 API：通过 /api/status_p.html、/api/share.html 等 servlet 暴露运行时状态。

构建与打包

YaCy 仓库根目录下的 build.xml 是顶层构建入口。根据社区反馈(如 issue #788)，构建流程包括下载 Ivy 依赖、编译 /source 下的所有 Java 类，并将成品发布到 /release。源码组织遵循按子系统分包的命名约定：

如 source/net/yacy/server/http/TemplateEngine.java 所示，模板渲染逻辑独立于网络层，这使得 YaCy 在 Servlet 容器之外也能独立组装响应。

运行时配置

配置加载方式

YaCy 的配置在 source/net/yacy/server/serverObjects.java 中通过 serverObjects 类作为统一的 key/value 容器。它既用于接收 HTTP POST 参数，也用于在 servlet 与模板之间传递数据。

社区 issue #794 指出，YACY_ 前缀的环境变量在处理包含 camelCase 键名(如 staticIP、browserPopUpTrigger)时存在解析差异。小写全字母的键(如 port、upnp.enabled)能够正确映射，而 camelCase 形式的键可能无法覆盖运行期默认值。生产部署建议同时设置 yacy.conf 文件，以获得稳定的可重复配置。

关键运行时参数

下表汇总了部署时最常调整的几项配置(基于 SwitchboardConstants 与 RobotsTxtConfig)：

robots.txt 与爬虫策略

source/net/yacy/server/http/RobotsTxtConfig.java 控制了 YaCy 自有网页服务(如 wiki、blog、fileshare、network)对外的爬取可见性。默认情况下 profile、locked、dirs 等敏感路径被设置为 Disallow，运营者应根据需要通过 RobotsTxtConfig(active[]) 构造器传入允许列表。

网络与端口映射

YaCy 在 NAT 后的部署主要依赖 source/net/yacy/utils/upnp/UPnP.java 中的 UPnP 实现。它通过 GatewayDiscover 探测路由器，建立从公网 IP 到内网监听端口的映射关系。映射种类由 UPnPMappingType.java 枚举，目前支持 HTTP 与 HTTPS 两种协议。

UPnPMapping.java 是一个简单的值对象，将配置键(CONFIG_PORT_KEY、CONFIG_ENABLED_KEY)与具体端口号封装在一起，从而把"配置 -> 端口 -> 映射条目"这一流程解耦。

flowchart LR
    A[Switchboard 启动] --> B{upnp.enabled?}
    B -- true --> C[GatewayDiscover 扫描]
    C --> D[读取 UPnPMapping 配置]
    D --> E[向路由器请求 AddPortMapping]
    E --> F[PortMappingEntry 写入]
    F --> G[P2P 节点宣告公网地址]
    B -- false --> H[使用 staticIP 配置]
    H --> G

社区 issue #315 与 #791 都反映了一个长期未解决的需求：当 YaCy 部署在 Traefik、nginx 等反代之后时，对外的"公网端口"与本地的"监听端口"通常不同。目前 YaCy 仅支持二者一致，这使得 Kubernetes 等容器编排场景下 P2P 入站连接难以打通。临时方案是让容器直接暴露同一端口，或使用 host 网络模式。

运维与可观测性

YaCy 通过 source/net/yacy/htroot/api/status_p.java 暴露进程级别的运行状态，包括内存使用、爬虫队列、当前在线 peer 数等。该 servlet 与 yacy.conf 中的运行期计数器共同构成健康检查接口，可以被容器编排器定期探测。

文件共享与上传入口由 source/net/yacy/htroot/api/share.java 提供，支持任意二进制上传并附加到指定 URL，常被外部 CMS 用作索引推送通道。配合 htroot/api/push_p.html 的 HTML 表单，运营人员可以手动触发索引注入。

国际化的翻译文件生成器 source/net/yacy/utils/translation/GenerateMasterXliff.java 在多语言部署中起到关键作用：它读取 locales/*.lng 并合并为一份 XLIFF 主文件，便于通过外部翻译平台分发。

常见问题与故障排查

下表汇总社区高频问题及应对建议：

See Also

• P2P Peer-to-Peer Protocol
• Search Index Subsystem
• Crawler and Scheduler
• HTTP Server and Servlets

1. 概述与定位

YaCy 是一个完整的搜索引擎应用程序，由三大核心子系统组成：搜索（Search）、索引（Indexing）和抓取（Crawling）。README.md 中明确指出："YaCy is a full search engine application containing a server hosting a search index, a web application to provide a nice user front-end for searches and index creation and a production-ready web crawler with a scheduler to keep a search index fresh"（README.md:31-36）。这三大子系统共同支撑起 YaCy 既能作为个人/内网搜索工具、又能加入全球 P2P 搜索网络的能力。

按照 README 所述，每个 YaCy 对等节点（peer）都可以加入一个大型搜索网络，通过内置的 P2P 协议与其他 YaCy 实例交换搜索索引（README.md:46-48）。同时，用户也可以通过 Web 界面选择不同的运行模式（cluster / solo / intranet），从而完全退出网络共享，本地单独使用。

2. 子系统组成

2.1 抓取子系统（Crawling）

抓取子系统负责按调度从互联网或内网 HTTP/FTP/SMB 服务器下载文档。charts/README.md 中特别说明："YaCy is a free, distributed search engine that can operate in two primary modes: P2P Network Mode ... Standalone/Intranet Mode"（charts/README.md:11-13），抓取行为正是这两种模式的核心差异点之一。

抓取过程涉及的辅助组件包括：

• RobotsTxtConfig：用于控制 robots.txt 中不同端点（wiki、blog、bookmarks、homepage、fileshare、surftips、news、status、network、profile 等）是否对爬虫屏蔽（source/net/yacy/server/http/RobotsTxtConfig.java:13-31）。
• UPnP 工具集：包括 UPnP.java、UPnPMappingType.java（仅区分 HTTP 与 HTTPS）、UPnPMapping.java（包私有的值对象，用于存放端口映射所需的协议、描述、配置键等），共同实现在 NAT 后自动开放抓取/服务所需的端口（source/net/yacy/utils/upnp/UPnP.java:1-50、source/net/yacy/utils/upnp/UPnPMappingType.java:22-26、source/net/yacy/utils/upnp/UPnPMapping.java:22-32）。
• status_p API：暴露抓取队列、爬虫 profile 与系统资源占用等运行状态，便于管理员观察抓取子系统负载（source/net/yacy/htroot/api/status_p.java:1-40）。

社区反馈表明，节点监听端口与对外公布的 P2P 端口无法分离是长期存在的痛点（参见 Issue #315 "Separate peer data exchange port and web interface port"），且在反向代理（如 Traefik）后部署时需要暴露公网端口（Issue #791），UPnP 模块正是为了解决 NAT 后可达性而设计。

2.2 索引子系统（Indexing）

索引子系统接收抓取到的文档并构建可查询的倒排索引。YaCy 通过 Solr 集成（基于 EmbeddedSolrConnector）维护主索引和 Webgraph 索引（见仓库 defaults/solr/ 与 defaults/solr.collection.schema、defaults/solr.webgraph.schema），文档以 YaCy 文档格式（yacydoc）持久化。

与索引紧密相关的 API 端点：

注意：getpageinfo 已被 @Deprecated 标注，新代码应使用 getpageinfo_p（source/net/yacy/htroot/api/getpageinfo.java:30-32）。

2.3 搜索子系统（Search）

搜索子系统通过 Web 前端（搜索结果页）与 HTTP/XML、HTTP/JSON API（README 中提到的"orange API icon"）对外提供查询能力。README.md 强调："YaCy has many built-in interfaces, and they are all based on HTTP/XML and HTTP/JSON"（README.md:7-9），这使得外部脚本（位于 bin/ 目录）也能便捷地调用搜索能力。

渲染层由 TemplateEngine（source/net/yacy/server/http/TemplateEngine.java:35-50）和 serverObjects（提供 putWiki、参数解析等模板变量构造能力，source/net/yacy/server/serverObjects.java:1-40）共同完成模板替换。

3. 数据流程

下图概括了从 URL 发现到查询返回的整体数据流：

flowchart LR
    A[URL 调度器<br/>CrawlSwitchboard] --> B[抓取器<br/>Crawler]
    B --> C[文档解析<br/>getpageinfo_p / yacydoc]
    C --> D[Solr 索引<br/>EmbeddedSolrConnector]
    D --> E[P2P 索引交换<br/>Switchboard]
    E --> F[本地倒排索引]
    F --> G[查询服务<br/>Search API]
    G --> H[TemplateEngine 渲染]
    H --> I[Web UI / XML / JSON]
    B -.需要端口开放.-> J[UPnP 端口映射]
    K[robots.txt 配置<br/>RobotsTxtConfig] -.控制.-> B

抓取得到的页面进入索引后，可经由 P2P 协议在节点之间交换，从而形成全局搜索网络（README.md:46-50）；用户也可以选择仅查询本地索引以保护隐私。

4. 部署与配置

Kubernetes 部署场景下，可以通过 Helm chart 调整爬虫/搜索相关参数，例如设置管理密码、持久化大小以及 Service 类型（charts/README.md:33-39）。需要注意的是：

• 容器化部署若缺少 .git 目录，会导致版本字符串异常显示为 yacy_v1.941_fatal: not a git repository...（参见 Issue #796），构建时应确保正确打包版本元数据。
• 通过 YACY_ 环境变量注入配置时，仅部分键生效；驼峰命名的设置（如 staticIP、browserPopUpTrigger）目前无法通过环境变量映射（参见 Issue #794），需要直接修改 yacy.conf。
• 当抓取和 Web 监听复用同一端口时（Issue #315、Issue #791），反向代理或 UPnP 场景下需要谨慎规划端口策略。

5. 常见失败模式

• 资源闲置：社区报告 CPU 负载仅 5–60%、iowait 极低，但爬虫未被充分调度（Issue #799），可通过 status_p API 检查 CrawlSwitchboard 的队列深度。
• RSS/认证失效：Tor 等环境下会出现短暂的授权丢失并伴随 "failed RSS" 弹窗（Issue #798），通常与会话 Cookie 与 P2P 通告机制相关。
• 构建失败：Ant 构建过程中如 Ivy 拉取依赖失败，会导致 build.xml 早期中断（Issue #788）。

See Also

• README.md — 项目概览
• charts/README.md — Kubernetes 部署说明
• Issue #315、#791 — 端口分离与反向代理相关讨论
• Issue #794 — YACY_ 环境变量配置键映射问题
• Issue #796 — 容器化版本字符串异常
• Issue #798 — RSS 与认证失效

概述

YaCy 是一个基于对等网络（P2P）的去中心化搜索引擎，其对外能力主要由 HTTP/XML 与 HTTP/JSON 接口驱动，开发者通过 Web 界面与 bin/ 下的 Shell 脚本即可调用核心搜索、索引与抓取功能。项目的扩展性体现在三个层面：模板驱动的服务端页面渲染、基于 Servlet 的 API 端点、以及通过环境变量与配置文件暴露的运行时配置钩子。本页基于仓库检索到的源码片段总结其 API 体系与扩展点，并指出当前上下文对 AI/LLM 集成模块的覆盖缺口。

API 端点体系

YaCy 的 API 通过 source/net/yacy/htroot/api/ 下的 Servlet 实现，每个端点均暴露一个静态的 respond(RequestHeader, serverObjects, serverSwitch) 方法，由 Switchboard 统一调度。

每个端点都遵循 serverObjects 键值容器模式：POST/GET 参数解析、模板占位符替换、序列化输出。

资料来源：source/net/yacy/htroot/api/share.java:35-50、source/net/yacy/htroot/api/bookmarks/get_bookmarks.java:1-30。

模板与渲染扩展

TemplateEngine (TemplateEngine.java) 是服务端 HTML 模板的核心，负责解析 htroot/ 下的占位符（如 #[clientname]#、#{links}...#{/links}#）以及条件块（#(similar)#...#(/similar)#）。模板中还可引用子模板，例如：

#%env/templates/metas.template%#
#%env/templates/embeddedheader.template%#

serverObjects.putWiki() (serverObjects.java) 提供了在响应中嵌入 Wiki 代码的能力，调用 Switchboard.wikiParser.transform() 进行解析。这意味着开发者既可以新建 .html 模板，也可以复用 Wiki 语法嵌入富文本。

自动化与配置扩展

• UPnP 端口映射：UPnP.java 配合 UPnPMappingType.java（HTTP / HTTPS）自动在路由器上开放服务端口；社区反馈（issue #315、issue #791）多次呼吁分离 P2P 端口与 Web 端口，目前仍需通过反向代理（如 Traefik）或 UPnP 实现。
• Robots.txt 配置：RobotsTxtConfig.java 提供基于端点的抓取许可开关（WIKI、BLOG、NEWS、STATUS 等），默认 LOCKED、DIRS、PROFILE 禁止爬取。
• 环境变量覆盖：YACY_ 前缀的环境变量可在启动时注入配置；社区报告（issue #794）指出 camelCase 键（如 staticIP、browserPopUpTrigger）目前无法通过该机制正确生效，运维需直接编辑 yacy.conf。
• 本地化扩展：GenerateMasterXliff.java 将 locales/*.lng 文件聚合并生成 XLIFF 主翻译文件，便于第三方贡献新语种。

部署与可观测性扩展

charts/README.md 提供了 Helm Chart 配置示例，支持从 Docker Hub 拉取官方镜像（yacy/yacy_search_server）或本地构建镜像。Chart 中 values.yaml 可注入 resources、nodeSelector、tolerations、affinity 等 K8s 调度参数，便于在集群中水平扩展 YaCy 对等节点。该扩展机制与 README.md 所述的 "peer-to-peer network protocol" 形成互补：既可通过 P2P 协议互连，也可借由容器编排快速复制实例。

graph LR
  Client[客户端] -->|HTTP/JSON| Servlet[API Servlet]
  Servlet --> SO[serverObjects]
  SO --> TE[TemplateEngine]
  TE --> HTML[htroot/*.html]
  Servlet --> SB[Switchboard]
  SB --> Index[索引 / 抓取 / P2P]
  SB -.UPnP.-> Router[路由器]
  Helm[Helm Chart] --> Docker[容器化实例]
  Docker --> SB

关于 AI/LLM 集成的当前覆盖

检索到的仓库片段未包含 source/net/yacy/ai/ 下的类（例如 LLM、LLMSwarm、RAGAugmentor、ToolCallProtocol、ToolProvider、ToolHandler）。这意味着本仓库当前提交中：

• 尚无对外暴露的 LLM 推理客户端封装；
• 尚无基于检索增强生成（RAG）的查询改写或答案合成路径；
• 尚无模型上下文协议（MCP）/工具调用层注册点。

若后续版本引入上述模块，预期会沿用现有扩展模式：通过 Servlet 注册新端点、在 serverObjects 中注入模型输出，并由 TemplateEngine 渲染最终 UI。这与 getpageinfo 已迁移至 getpageinfo_p（getpageinfo.java 中标注 @Deprecated）所体现的"新接口替代旧接口"的演进路径一致。

常见问题与故障模式

• 环境变量命名不生效：参见 issue #794，camelCase 键需直接写入 DATA/yacy.conf。
• 容器内版本号异常：参见 issue #796，需在构建上下文中注入 .git 元数据以避免出现 fatal: not a git repository 字样。
• 公网端口与监听端口不一致：参见 issue #791，当前需借助反向代理或 UPnP 解决。
• 构建失败：参见 issue #788，通常与 build.xml 中 Ivy 依赖下载失败相关。

参见

• README.md — 项目总览与 P2P 网络说明
• charts/README.md — Helm Chart 部署指南
• htroot/api/ — Web 接口模板目录
• source/net/yacy/htroot/api/ — API Servlet 源码目录

Pitfall Log / 踩坑日志

项目：yacy/yacy_search_server

摘要：发现 15 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：Can't build YaCy。

1. 安装坑 · 来源证据：Can't build YaCy

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Can't build YaCy
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/yacy/yacy_search_server/issues/788 | 来源类型 github_issue 暴露的待验证使用条件。

2. 安装坑 · 来源证据：No way to set public port differing from listening port

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：No way to set public port differing from listening port
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/yacy/yacy_search_server/issues/791 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

3. 配置坑 · 来源证据：Issues with using YACY_ environment variables for camelCase settings

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Issues with using YACY_ environment variables for camelCase settings
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/yacy/yacy_search_server/issues/794 | 来源类型 github_issue 暴露的待验证使用条件。

4. 安全/权限坑 · 来源证据：Security issue disclosure

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security issue disclosure
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/yacy/yacy_search_server/issues/735 | 来源类型 github_issue 暴露的待验证使用条件。

5. 安全/权限坑 · 来源证据：Separate peer data exchange port and web interface port

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Separate peer data exchange port and web interface port
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/yacy/yacy_search_server/issues/315 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

6. 安装坑 · 依赖 Docker 环境

• 严重度：medium
• 证据强度：runtime_trace
• 发现：安装/运行入口包含 Docker 命令：docker run -d --name yacy_search_server -p 8090:8090 -p 8443:8443 -v yacy_search_server_data:/opt/yacy_search_server/DATA --restart unless-stopped --log-opt max-size=200m --log-opt max-file=2 yacy/yacy_search_server:latest
• 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
• 复现命令：docker run -d --name yacy_search_server -p 8090:8090 -p 8443:8443 -v yacy_search_server_data:/opt/yacy_search_server/DATA --restart unless-stopped --log-opt max-size=200m --log-opt max-file=2 yacy/yacy_search_server:latest
• 证据：identity.distribution | https://github.com/yacy/yacy_search_server | docker run -d --name yacy_search_server -p 8090:8090 -p 8443:8443 -v yacy_search_server_data:/opt/yacy_search_server/DATA --restart unless-stopped --log-opt max-size=200m --log-opt max-file=2 yacy/yacy_search_server:latest

7. 安装坑 · 来源证据：Containerized YaCy peers show broken version string

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Containerized YaCy peers show broken version string
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/yacy/yacy_search_server/issues/796 | 来源类型 github_issue 暴露的待验证使用条件。

8. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/yacy/yacy_search_server | README/documentation is current enough for a first validation pass.

9. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/yacy/yacy_search_server | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/yacy/yacy_search_server | no_demo; severity=medium

11. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/yacy/yacy_search_server | no_demo; severity=medium

12. 安全/权限坑 · 来源证据：Disappointed user says goodbye.

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Disappointed user says goodbye.
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/yacy/yacy_search_server/issues/790 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

13. 安全/权限坑 · 来源证据：disappearing authorization and failed RSS

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：disappearing authorization and failed RSS
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/yacy/yacy_search_server/issues/798 | 来源类型 github_issue 暴露的待验证使用条件。

14. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/yacy/yacy_search_server | issue_or_pr_quality=unknown

15. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/yacy/yacy_search_server | release_recency=unknown