YaCy.Uno 设计方案

基于 Uno Platform (C#/.NET 9) 的去中心化 P2P 搜索引擎 兼容 YaCy 协议，跨平台运行（Windows / macOS / Linux / WebAssembly / iOS / Android）

一、项目概述

1.1 项目定位

YaCy.Uno 是 YaCy 去中心化搜索引擎的 Uno Platform (C#) 实现版本。它将：

• 完全兼容 YaCy P2P 协议（可与 Java/Go 版本节点互通）
• 采用 Uno Platform 5.x + .NET 9 实现真正的跨平台
• 提供 Material Design 3 风格的现代 UI
• 支持 WebAssembly / Desktop / Mobile 多目标平台
• 拥抱 .NET 开源生态，充分利用高性能库

1.2 命名与端口

1.3 与其他版本对比

二、技术架构

2.1 总体架构

┌─────────────────────────────────────────────────────────────┐
│                    YaCy.Uno Application                     │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────────┐  │
│  │  Uno Platform│  │ ASP.NET Core │  │ Spectre.Console   │  │
│  │  XAML UI     │  │ Web API      │  │ TUI               │  │
│  │  (Desktop/   │  │ (REST/SSE/   │  │ (Terminal Client) │  │
│  │   WASM/      │  │  WebSocket)  │  │                   │  │
│  │   Mobile)    │  │              │  │                   │  │
│  └──────┬───────┘  └──────┬───────┘  └───────┬───────────┘  │
│         │                 │                  │              │
│  ┌──────┴─────────────────┴──────────────────┴───────────┐  │
│  │                  Application Services                 │  │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ │  │
│  │  │ Search   │ │ Crawl    │ │ P2P/DHT  │ │ Index     │ │  │
│  │  │ Service  │ │ Service  │ │ Service  │ │ Service   │ │  │
│  │  └────┬─────┘ └────┬─────┘ └────┬─────┘ └─────┬─────┘ │  │
│  └───────┼────────────┼────────────┼─────────────┼───────┘  │
│  ┌───────┴────────────┴────────────┴─────────────┴───────┐  │
│  │                     Core Engine                       │  │
│  │  ┌──────────────┐ ┌───────────┐ ┌──────────────────┐  │  │
│  │  │ SQLite FTS5  │ │ Document  │ │ Protocol         │  │  │
│  │  │ Full-Text    │ │ Parsers   │ │ (YaCy P2P compat)│  │  │
│  │  │ Index        │ │ (30+)     │ │                  │  │  │
│  │  └──────┬───────┘ └───────────┘ └──────────────────┘  │  │
│  │  ┌──────┴────────────────────────────────────────────┐│  │
│  │  │              Storage Layer                        ││  │
│  │  │  SQLite (EF Core + FTS5) - 统一数据与索引存储       ││  │
│  │  └───────────────────────────────────────────────────┘│  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

2.2 技术栈选型

核心框架

网络与通信

文档解析

UI 与体验

测试

三、项目结构

yacy.uno/
├── 设计方案.md                           # 本文档
├── 研发计划.md                           # 开发计划
├── README.md                            # 项目说明
├── LICENSE                              # Apache 2.0 / LGPL
├── Directory.Build.props                # 全局构建属性
├── Directory.Packages.props             # 中央包版本管理
├── yacy.uno.sln                         # 解决方案文件
│
├── src/                                 # 源代码
│   ├── YaCy.Uno.Core/                   # 核心引擎库 (net9.0)
│   │   ├── Models/                      # 数据模型
│   │   │   ├── Document.cs              # 文档模型
│   │   │   ├── Seed.cs                  # P2P 节点种子
│   │   │   ├── WordReference.cs         # 词引用 (RWI)
│   │   │   ├── CrawlProfile.cs          # 爬取配置
│   │   │   ├── SearchResult.cs          # 搜索结果
│   │   │   └── ...
│   │   ├── Search/                      # 搜索引擎
│   │   │   ├── SearchEngine.cs          # 搜索引擎入口
│   │   │   ├── QueryParser.cs           # 查询解析
│   │   │   ├── RankingEngine.cs         # 排名算法
│   │   │   ├── SnippetGenerator.cs      # 摘要生成
│   │   │   └── FederatedSearch.cs       # 联邦搜索
│   │   ├── Index/                       # 索引管理
│   │   │   ├── FtsIndexManager.cs       # FTS5 索引管理器
│   │   │   ├── DocumentIndexer.cs       # 文档索引器
│   │   │   └── RwiStore.cs              # 反向词索引存储 (RWI)
│   │   ├── Crawler/                     # 网页爬虫
│   │   │   ├── CrawlEngine.cs           # 爬虫引擎
│   │   │   ├── CrawlScheduler.cs        # 爬取调度
│   │   │   ├── RobotsParser.cs          # robots.txt 解析
│   │   │   ├── UrlQueue.cs              # URL 队列
│   │   │   ├── HttpLoader.cs            # HTTP 加载器
│   │   │   └── SitemapParser.cs         # Sitemap 解析
│   │   ├── Parser/                      # 文档解析器
│   │   │   ├── IDocumentParser.cs       # 解析器接口
│   │   │   ├── HtmlParser.cs            # HTML 解析
│   │   │   ├── PdfParser.cs             # PDF 解析
│   │   │   ├── OfficeParser.cs          # Office 解析
│   │   │   ├── RssParser.cs             # RSS/Atom 解析
│   │   │   ├── XmlParser.cs             # XML 解析
│   │   │   ├── PlainTextParser.cs       # 纯文本解析
│   │   │   └── ParserFactory.cs         # 解析器工厂
│   │   ├── P2P/                         # P2P 网络
│   │   │   ├── Protocol/                # YaCy 协议实现
│   │   │   │   ├── HelloProtocol.cs     # 握手协议
│   │   │   │   ├── SearchProtocol.cs    # 远程搜索
│   │   │   │   ├── TransferProtocol.cs  # 索引传输
│   │   │   │   └── SeedEncoding.cs      # 种子编解码
│   │   │   ├── DHT/                     # 分布式哈希表
│   │   │   │   ├── DHTManager.cs        # DHT 管理
│   │   │   │   ├── DHTSelection.cs      # DHT 节点选择
│   │   │   │   ├── DHTDispatcher.cs     # DHT 分发
│   │   │   │   └── DHTTransmission.cs   # DHT 传输
│   │   │   ├── Network/                 # 网络管理
│   │   │   │   ├── PeerManager.cs       # 节点管理
│   │   │   │   ├── SeedDB.cs            # 种子数据库
│   │   │   │   ├── ConnectionManager.cs # 连接管理
│   │   │   │   └── Bootstrap.cs         # 引导发现
│   │   │   └── Security/               # 安全
│   │   │       ├── CryptoHelper.cs      # 加密工具
│   │   │       └── AuthManager.cs       # 认证管理
│   │   ├── Storage/                     # 存储层
│   │   │   ├── YaCyDbContext.cs          # EF Core DbContext
│   │   │   ├── IDocumentStore.cs        # 文档存储接口
│   │   │   ├── SqliteDocumentStore.cs   # SQLite 实现
│   │   │   └── Migrations/             # 数据库迁移
│   │   ├── Config/                      # 配置
│   │   │   ├── YaCyConfig.cs            # 配置模型
│   │   │   ├── NetworkConfig.cs         # 网络配置
│   │   │   └── CrawlConfig.cs           # 爬取配置
│   │   └── Utils/                       # 工具类
│   │       ├── UrlUtils.cs              # URL 工具
│   │       ├── HashUtils.cs             # 哈希工具
│   │       ├── TextUtils.cs             # 文本工具
│   │       └── Tokenizer.cs             # 分词器
│   │
│   ├── YaCy.Uno.Server/                 # Web API 服务 (ASP.NET Core)
│   │   ├── Program.cs                   # 入口点
│   │   ├── Controllers/                 # API 控制器
│   │   │   ├── SearchController.cs      # 搜索 API
│   │   │   ├── CrawlController.cs       # 爬取 API
│   │   │   ├── PeersController.cs       # 节点 API
│   │   │   ├── DhtController.cs         # DHT API
│   │   │   ├── StatsController.cs       # 统计 API
│   │   │   ├── ConfigController.cs      # 配置 API
│   │   │   ├── IndexController.cs       # 索引管理 API
│   │   │   └── YaCyProtocolController.cs# YaCy 协议兼容端点
│   │   ├── Hubs/                        # SignalR Hub
│   │   │   ├── SearchHub.cs             # 搜索实时推送
│   │   │   └── CrawlHub.cs             # 爬取状态推送
│   │   ├── Services/                    # 后台服务
│   │   │   ├── CrawlBackgroundService.cs # 后台爬取
│   │   │   ├── P2PBackgroundService.cs  # P2P 网络维护
│   │   │   └── DHTBackgroundService.cs  # DHT 维护
│   │   ├── Middleware/                  # 中间件
│   │   │   ├── AuthMiddleware.cs        # 认证中间件
│   │   │   └── RateLimitMiddleware.cs   # 限流中间件
│   │   └── appsettings.json             # 应用配置
│   │
│   ├── YaCy.Uno.App/                    # Uno Platform 桌面/WASM UI
│   │   ├── App.xaml / App.xaml.cs       # 应用入口
│   │   ├── MainWindow.xaml              # 主窗口
│   │   ├── Views/                       # 页面视图
│   │   │   ├── HeroPage.xaml            # 首页 (搜索入口)
│   │   │   ├── SearchPage.xaml          # 搜索结果
│   │   │   ├── CrawlPage.xaml           # 爬虫管理
│   │   │   ├── PeersPage.xaml           # 节点列表
│   │   │   ├── DhtPage.xaml             # DHT 统计
│   │   │   ├── StatsPage.xaml           # 系统统计
│   │   │   ├── ConfigPage.xaml          # 设置
│   │   │   └── HelpPage.xaml            # 帮助
│   │   ├── ViewModels/                  # MVVM ViewModel
│   │   │   ├── HeroViewModel.cs
│   │   │   ├── SearchViewModel.cs
│   │   │   ├── CrawlViewModel.cs
│   │   │   ├── PeersViewModel.cs
│   │   │   ├── DhtViewModel.cs
│   │   │   ├── StatsViewModel.cs
│   │   │   ├── ConfigViewModel.cs
│   │   │   └── MainViewModel.cs
│   │   ├── Controls/                    # 自定义控件
│   │   │   ├── SearchBar.xaml           # 搜索栏
│   │   │   ├── SearchResultCard.xaml    # 结果卡片
│   │   │   ├── NavigationDrawer.xaml    # 导航抽屉
│   │   │   ├── StatusBar.xaml           # 状态栏
│   │   │   └── NotificationStack.xaml   # 通知栈
│   │   ├── Themes/                      # 主题资源
│   │   │   ├── MaterialTheme.xaml       # Material Design 3
│   │   │   ├── LightTheme.xaml          # 亮色主题
│   │   │   └── DarkTheme.xaml           # 暗色主题
│   │   ├── Services/                    # UI 服务
│   │   │   ├── ApiClient.cs             # REST API 客户端
│   │   │   ├── NavigationService.cs     # 导航服务
│   │   │   └── ThemeService.cs          # 主题切换
│   │   ├── Converters/                  # 值转换器
│   │   ├── Strings/                     # 国际化
│   │   │   ├── en/Resources.resw        # English
│   │   │   └── zh-CN/Resources.resw     # 中文
│   │   └── Platforms/                   # 平台特定代码
│   │       ├── Desktop/                 # 桌面平台
│   │       ├── WebAssembly/             # WASM 平台
│   │       ├── iOS/                     # iOS
│   │       └── Android/                 # Android
│   │
│   └── YaCy.Uno.Cli/                    # TUI 命令行客户端
│       ├── Program.cs                   # CLI 入口
│       ├── Commands/                    # 命令定义
│       │   ├── SearchCommand.cs         # yacy search <query>
│       │   ├── CrawlCommand.cs          # yacy crawl <url>
│       │   ├── StatusCommand.cs         # yacy status
│       │   ├── PeersCommand.cs          # yacy peers
│       │   └── ServeCommand.cs          # yacy serve
│       └── UI/                          # TUI 界面
│           └── DashboardView.cs         # 仪表盘
│
├── tests/                               # 测试项目
│   ├── YaCy.Uno.Core.Tests/             # 核心库测试
│   ├── YaCy.Uno.Server.Tests/           # API 集成测试
│   └── YaCy.Uno.Benchmarks/             # 性能基准
│
├── docs/                                # 文档
│   ├── api.md                           # API 文档
│   ├── p2p-protocol.md                  # P2P 协议说明
│   └── deployment.md                    # 部署指南
│
└── docker/                              # Docker 部署
    ├── Dockerfile                       # Docker 构建
    └── docker-compose.yml               # Docker Compose

四、核心模块设计

4.1 搜索引擎 (Search Engine)

全文索引 — SQLite FTS5

采用 SQLite FTS5 作为全文搜索引擎，与 YaCy-Go 技术栈一致：

-- FTS5 全文索引虚拟表
CREATE VIRTUAL TABLE documents_fts USING fts5(
    url_hash,          -- 文档唯一标识 (UNSAFE not indexed)
    url,               -- 原始 URL
    title,             -- 标题 (高权重)
    description,       -- 描述
    content,           -- 正文 (主搜索字段)
    host,              -- 主域名
    language,          -- 语言
    content_type,      -- MIME 类型
    tokenize = 'unicode61 porter',  -- 多语言 + 词干提取
    content = '',      -- 无内容表关联
    content_rowid = 'rowid'
);

-- 元数据表（与 FTS 配合）
CREATE TABLE documents (
    rowid INTEGER PRIMARY KEY,
    url_hash TEXT UNIQUE NOT NULL,
    url TEXT NOT NULL,
    title TEXT,
    size INTEGER,
    crawl_date TEXT,
    last_modified TEXT,
    inbound_links INTEGER DEFAULT 0,
    outbound_links INTEGER DEFAULT 0,
    keywords TEXT,
    author TEXT
);

// 索引字段常量（对应 FTS5 列）
public static class IndexFields
{
    public const string UrlHash = "url_hash";
    public const string Url = "url";
    public const string Title = "title";
    public const string Description = "description";
    public const string Content = "content";
    public const string Host = "host";
    public const string Language = "language";
    public const string ContentType = "content_type";
}

搜索流程

查询输入 → QueryParser (FTS5 语法解析)
        → SQLite FTS5 全文匹配 (bm25 排序)
        → 本地索引查询
        → 并行: P2P 远程搜索 (DHT 目标节点)
        → 结果合并 (RankingEngine: BM25 + 入链/新鲜度因子)
        → SnippetGenerator (FTS5 highlight 高亮)
        → SSE/SignalR 流式输出

排名因子

4.2 网页爬虫 (Crawler)

// 爬虫引擎架构
CrawlEngine
├── CrawlScheduler          // 调度器（优先级队列 + 域名频率限制）
├── UrlQueue                // URL 队列（SQLite 持久化）
├── HttpLoader              // HTTP 加载器（HttpClient + Polly 重试）
├── RobotsParser             // robots.txt 遵守
├── SitemapParser            // Sitemap 发现
├── ContentExtractor         // 内容提取（AngleSharp）
├── ParserPipeline           // 解析器管道（HTML→PDF→Office→...）
└── IndexSubmitter           // 索引提交（→ FTS5 + DHT 分发）

特性：

• 多工作者并行爬取（Channel<T> + Task 并行模型）
• 域名级别频率限制（Polite crawling）
• robots.txt / meta robots 遵守
• 可配置爬取深度、广度、文件类型过滤
• 增量爬取 / 条件抓取（If-Modified-Since / ETag）
• 爬取状态实时推送（SignalR / SSE）

4.3 P2P 网络 (P2P Network)

协议兼容性

完全实现以下 YaCy 协议端点（兼容 Java YaCy 和 Go YaCy）：

DHT 实现

DHT 设计:
- 分区数: 256 (2^8)
- 冗余因子: 3 (senior 节点)
- 分区算法: 词哈希 → 节点哈希 → 最近节点选择
- 索引分发: 后台定时分发到目标节点

节点类型

4.4 文档解析器 (Document Parsers)

public interface IDocumentParser
{
    string[] SupportedMimeTypes { get; }
    int Priority { get; }
    Task<ParsedDocument> ParseAsync(Stream content, string mimeType, Uri sourceUrl, CancellationToken ct);
}

支持的格式（优先级排序）：

4.5 存储层 (Storage)

双存储架构

存储层:
├── SQLite (EF Core + FTS5)   → 统一数据与索引存储
│   ├── documents             → 文档元数据表
│   ├── documents_fts         → FTS5 全文索引 (虚拟表)
│   ├── rwi_terms             → 反向词索引 (RWI)
│   ├── seeds                 → 节点种子表
│   ├── crawl_queue           → 爬取队列表
│   ├── crawl_profiles        → 爬取配置表
│   ├── bookmarks             → 书签表
│   ├── blacklist             → 黑名单表
│   └── config                → 配置表
└── 文件系统
    ├── data/yacy.db          → SQLite 数据库文件 (含 FTS5 索引)
    ├── data/log/             → 日志文件
    └── data/export/          → 导出文件

五、API 设计

5.1 REST API 端点

完全对标 YaCy-Go 的 API 设计，确保生态兼容：

搜索 API

GET  /api/search?q={query}&offset={0}&limit={10}&lang={all}
GET  /api/search/stream?q={query}                   # SSE 流式
GET  /api/search/async                              # 异步搜索
GET  /api/suggest?q={prefix}                        # 搜索建议

爬取 API

POST /api/crawl                                     # 提交爬取任务
GET  /api/crawl/status                              # 爬取状态
GET  /api/crawl/history                             # 爬取历史
POST /api/crawl/pause                               # 暂停
POST /api/crawl/resume                              # 恢复
POST /api/crawl/abort                               # 中止

节点 API

GET  /api/peers                                     # 节点列表
GET  /api/peers/stats                               # 节点统计
POST /api/peers/connect                             # 连接节点

DHT API

GET  /api/dht/stats                                 # DHT 统计
GET  /api/dht/distribution/stats                    # 分布统计

管理 API

GET  /api/stats                                     # 系统统计
GET  /api/config                                    # 配置读取
PUT  /api/config/:key                               # 配置更新
GET  /api/index/browse                              # 索引浏览
POST /api/index/export                              # 索引导出
POST /api/index/import                              # 索引导入

5.2 实时通信

• Server-Sent Events (SSE): 搜索结果流式推送
• SignalR: 爬取状态/P2P 事件实时推送
• WebSocket: 备选方案（WASM 兼容）

六、UI 设计

6.1 设计语言

参考 YaCy-Go 的 Material Design 3 风格：

• 主色调: #667eea (蓝紫渐变) → #764ba2
• 字体: Segoe UI / Inter / Noto Sans CJK
• 圆角: 12-16px (卡片), 24px (按钮)
• 阴影: Material elevation system
• 动画: 流畅的页面切换和状态转换
• 主题: 明暗主题切换 + 系统跟随

6.2 页面设计

6.3 导航

桌面端:
┌──────┬────────────────────────────────────────┐
│      │ [AppBar: Logo | 搜索框 | 主题切换 | 通知] │
│ 侧边 │──────────────────────────────────────────│
│ 导航 │                                          │
│ 菜单 │           页面内容区域                    │
│      │                                          │
│      │                                          │
└──────┴────────────────────────────────────────┘

移动端:
┌──────────────────────────────────────────────┐
│ [AppBar: ≡ | 标题 | 主题 | 通知]              │
│──────────────────────────────────────────────│
│                                              │
│           页面内容区域                        │
│                                              │
│──────────────────────────────────────────────│
│ [🏠首页] [🔍搜索] [🕷爬取] [👥节点] [⚙设置]  │
└──────────────────────────────────────────────┘

七、部署方案

7.1 运行模式

7.2 Docker 支持

FROM mcr.microsoft.com/dotnet/aspnet:9.0 AS base
FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
# Multi-stage build for minimal image size

7.3 系统要求

八、安全设计

• HTTPS/TLS: 内置 Kestrel TLS 支持
• 认证: 管理界面 HTTP Basic Auth + JWT Token
• RSA 2048: 节点身份密钥对（兼容 YaCy 协议）
• 速率限制: ASP.NET Core Rate Limiting 中间件
• CORS: 可配置跨域策略
• Input Validation: 所有输入参数校验

九、国际化

• 使用 .NET 资源文件 (.resw) 实现 i18n
• 初始支持：English (en), 中文 (zh-CN)
• 可扩展的翻译框架

十、开源协议

• 许可证: Apache License 2.0（与 YaCy-Go 一致）
• 贡献: 遵循 GitHub Flow，PR + Code Review
• CI/CD: GitHub Actions 自动化构建/测试/发布