# tangduo **Repository Path**: aberic/tangduo ## Basic Information - **Project Name**: tangduo - **Description**: No description available - **Primary Language**: Java - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-02-13 - **Last Updated**: 2026-07-28 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # TangDuo ## 项目简介 **tangduo（汤朵）** 提供轻量、易用的技术解决方案，适用于中小型项目快速开发与集成。 ## 核心特性 1. **轻量简洁**：代码结构清晰，无冗余依赖，易于理解和二次开发 2. **持续迭代**：基于 `develop` 分支持续更新，不断优化功能与修复问题 3. **开源免费**：遵循开源协议，可自由使用、修改与分发 4. **易用性强**：提供简洁的使用方式，降低开发者接入成本 ## 适用场景 - 中小型项目快速搭建 - 技术学习与源码研究 - 个人开发者工具集成 - 轻量级业务系统开发 ## 核心模块结构 仓库采用多模块拆分的方式组织代码，各模块职责边界清晰，具体模块如下： | 模块名 | 核心定位 | |---------|------------------------------------------------------------------------| | [`sdk4j21/`](/sdk4j21) | 适配 Java 21 版本的 SDK 模块，封装通用的工具类、基础接口或适配 Java 21 新特性的核心能力 | | [`sdk4j8/`](/sdk4j8) | 适配 Java 8 版本的 SDK 模块，保障项目在低版本 Java 环境下的兼容性，提供与 `sdk4j21` 功能对齐的基础能力 | | [`db/`](/db) | 数据库操作核心模块，负责封装数据持久化相关逻辑，是整个项目的数据存储层 | | [`index/`](/index) | 索引相关模块，用于处理数据索引构建、检索优化等能力 | | [`search/`](/search) | 检索功能模块，包含 `http/` 子目录，负责对外提供检索相关的 HTTP 接口，或处理检索请求的网络交互、参数解析等 | | [`common/`](/common) | 通用公共模块，封装全项目复用的工具类、常量定义、异常处理、通用配置等基础能力，为其他模块提供底层支撑 | ## 使用说明 1. 克隆项目到本地 ```bash git clone https://gitee.com/aberic/tangduo.git ``` 2. 切换至对应版本分支，如开发分支 ```bash git checkout develop ``` 3. 按照项目内具体模块说明完成配置与启动 ## 核心能力 ✅ **嵌入式部署**：无外部依赖，直接集成到 Java 项目，开箱即用 ✅ **多类型存储**：支持结构化对象、JSON 文档存储，兼顾灵活与规范 ✅ **高性能检索**：集成分词引擎 + BM25 相关性排序，支持全文检索/条件检索 ✅ **异步写入优化**：基于异步 Channel 模型，批量写入性能优异 ✅ **事务一致性**：支持索引操作原子性，保证数据存储与索引更新一致性 ✅ **轻量化运维**：文件级存储，备份/迁移仅需拷贝目录，无复杂配置 ### 整体架构 TangDuo 采用模块化设计，核心分为三层： ``` ┌─────────────────┐ │ search 模块 │ 对外暴露 RESTful API，封装 DB 能力 └────────┬────────┘ │ ┌────────▼────────┐ │ db 模块 │ 核心业务层，提供对象/文档存储、富查询能力，整合索引能力 └────────┬────────┘ │ ┌────────▼────────┐ │ index 模块 │ 底层索引层，提供索引读写、异步刷盘、事务一致性保障 └─────────────────┘ ``` #### 模块职责 | 模块 | 核心能力 | 对外形态 | |---------|--------------------------------------------------------------------------|-------------------------------| | `index` | 索引读写、异步刷盘、事务封装、文件 IO 优化 | 底层 API（供 db 模块调用） | | `db` | 对象/文档存储、富查询（条件/分词）、批量操作、数据一致性保障 | Java 核心 API（单例入口） | | `search`| 基于 Spring Boot 封装 RESTful API，暴露数据库/索引/数据全量操作能力 | [HTTP 接口（开箱即用）](/search/http) | #### 核心接口调用示例 | 功能 | 请求方式 | 接口路径 | 示例请求体 | |--------------|----------|------------------------|----------------------------------------------------------------------------| | 创建数据库 | PUT | /db/my_test_db | 无（路径参数） | | 创建索引 | PUT | /index | `{"database":"my_test_db","index":"user_index","version":1,"name":"user_index"}` | | 插入数据 | PUT | /data | `{"database":"my_test_db","index":"user_index","seg":true,"value":"{\"name\":\"张三\",\"age\":25}"}` | | 全文检索 | GET | /data/search | `{"database":"my_test_db","index":"user_index","query":"张三","limit":10}` | | 条件检索 | GET | /data/select | `{"database":"my_test_db","index":"user_index","conditions":[{"field":"age","op":">","value":20}]}` | | 删除数据 | DELETE | /data | `{"database":"my_test_db","index":"user_index","key":"user_001"}` | ### 核心特性详解 #### 1. 多类型存储 | 存储类型 | 适用场景 | 核心能力 | |------------|-------------------------|--------------------------------------------------------------------------| | 对象存储 | 结构化 Java 对象 | 自定义序列化、版本管理、批量操作、原子性保障 | | 文档存储 | JSON 非结构化/半结构化 | 自动字段索引、分词检索、大文档分片（规划） | #### 2. 检索能力 | 检索类型 | 特性 | |------------|---------------------------------------------------------| | 全文检索 | HanLP/IK 分词、BM25 相关性排序、支持批量检索 | | 条件检索 | 等值/范围/模糊匹配、多条件 AND/OR/NOT、排序、分页（search-after/from-size） | | 精确查询 | 按主键快速定位，基于文件索引直接读取，性能无损耗 | #### 3. 性能优化 - **异步写入**：Index 模块基于 Channel 异步写线程模型，避免磁盘 IO 阻塞业务线程 - **批量操作**：支持批量插入/删除，减少文件 IO 次数 - **索引优化**：自动路由查询条件到对应索引，避免全量扫描 - **文件分片**：单个数据文件达到阈值自动分片，平衡读写效率 #### 4. 数据安全 - **事务原子性**：保证“数据存储 + 索引更新”原子性，避免数据不一致 - **写前校验**：校验数据合法性（字段类型/长度/约束），杜绝脏数据 - **崩溃恢复**：基于日志实现异常宕机后数据恢复 - **并发安全**：ConcurrentHashMap + ReentrantLock 保证多线程安全 ### 适用场景 - 嵌入式检索服务（无需部署外部中间件） - 轻量级全文检索（日志检索、文档检索、内容检索） - 小体量结构化/非结构化数据存储 + 检索 - 快速搭建本地测试/演示环境的检索能力 - 对部署复杂度敏感、追求轻量化的业务场景 ## 使用 Docker 部署 为简化部署流程、保证环境一致性，TangDuo 提供 Docker 镜像，支持一键部署，无需手动配置依赖、编译打包，适用于生产环境快速落地。 #### 一、核心镜像信息 - 镜像地址：`registry.cn-hangzhou.aliyuncs.com/aberic/tangduosearch:latest` - 基础环境：基于 OpenJDK 21 - 默认端口：19219（业务接口）、19220（健康检查/监控接口） - 数据目录：容器内 `/data` #### 二、一键部署命令 执行以下命令，快速启动 TangDuo 容器（支持开机自启、数据持久化、时区同步）： ```shell docker run --name tangduosearch --restart=always \ -p 19219:19219 \ -p 19220:19220 \ -v /etc/localtime:/etc/localtime \ -v /etc/timezone:/etc/timezone \ -v /data/vol/tangduosearch:/data \ -itd registry.cn-hangzhou.aliyuncs.com/aberic/tangduosearch:latest ``` #### 三、部署命令参数说明 |参数|说明| |---|---| |`-name tangduosearch`|指定容器名称为 tangduosearch，便于后续管理（如停止、重启）| |`-p 19219:19219`|映射业务接口端口（宿主机端口:容器内端口），外部通过宿主机 19219 端口访问业务接口| |`-p 19220:19220`|映射健康检查/监控端口，用于容器健康检测、服务监控| |`-v /data/vol/tangduosearch:/data`|数据持久化：将容器内 /data 目录（数据库数据存储目录）映射到宿主机 /data/vol/tangduosearch 目录，避免容器删除后数据丢失| #### 四、Dockerfile 详情（镜像构建逻辑） 镜像的 [dockerfile](build/tangduosearch/Dockerfile) 内容，清晰呈现镜像构建流程，便于自定义修改或验证。 #### 五、可自定义环境变量 部署时可通过 `\-e` 参数覆盖默认环境变量，适配不同场景需求，支持的环境变量如下（对应 [application.yml](search/src/main/resources/application.yml) 配置）： ## 贡献指南 欢迎提交 Issue 反馈问题，或通过 Pull Request 参与代码贡献，共同完善项目。 ## 许可证 本项目采用开源协议，具体许可信息请参考项目内 LICENSE 文件。