# mongo-connector

**Repository Path**: Talbot3/mongo-connector

## Basic Information

- **Project Name**: mongo-connector
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-28
- **Last Updated**: 2026-01-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Mongo Connector

<div align="center">

**从 MongoDB 集群到目标系统的实时数据复制管道**

[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
[![MongoDB Version](https://img.shields.io/badge/mongodb-3.6%2B-green.svg)](https://www.mongodb.com/)
[![License](https://img.shields.io/badge/license-Apache%202.0-orange.svg)](LICENSE)

[完整文档](docs/README.md) | [在线 Wiki](https://github.com/yougov/mongo-connector/wiki) | [Gitee 镜像](https://gitee.com/Talbot3/mongo-connector)

</div>

---

## 简介

Mongo Connector 最初是 MongoDB 的一个实验室项目，现在由 YouGov, Plc. 和 Talbot3 共同维护并向社区开源。

**最新版本 (v3.2.0)**: 移除了 mongo-orchestration 依赖，采用现代化 uv + hatchling 构建系统。详见 [CHANGELOG.md](CHANGELOG.md)。

### 系统概述

`mongo-connector` 创建了一个从 MongoDB 集群到一个或多个目标系统的数据管道，例如：

- 🔍 **Solr** - 开源搜索平台
- 🔎 **Elasticsearch** - 分布式搜索和分析引擎
- 🍃 **MongoDB** - 另一个 MongoDB 实例

它首先将 MongoDB 中的数据同步到目标系统，然后通过跟踪 MongoDB oplog 实时保持同步。

---

## 快速开始

### 环境要求

- Python 3.9+
- MongoDB 3.6 到 7.0+
- PyMongo 4.0+

### 安装

```bash
# 基础安装（复制到 MongoDB）
pip install mongo-connector

# 安装带 Solr 支持
pip install 'mongo-connector[solr]'

# 安装带 Elasticsearch 支持
pip install 'mongo-connector[elastic2]'

# 使用 uv（推荐，更快）
uv pip install mongo-connector
```

### 基本使用

1. **启动 MongoDB 副本集**

```bash
mongod --replSet myDevReplSet

# 在 mongo shell 中
rs.initiate()
```

2. **启动 Mongo Connector**

```bash
# 复制到 MongoDB
mongo-connector -m localhost:27017 \
                -t localhost:37017 \
                -d mongo_doc_manager

# 复制到 Solr
mongo-connector -m localhost:27017 \
                -t http://localhost:8983/solr \
                -d solr_doc_manager
```

详细说明请查看 [快速开始指南](docs/getting-started.md)。

---

## 📚 完整文档

我们提供完整的中文文档，方便中国用户使用：

### 快速入门
- 📖 [安装指南](docs/installation.md) - 如何安装 Mongo Connector 及其依赖
- 🚀 [快速开始](docs/getting-started.md) - 快速上手指南，包含简单示例

### 基础概念
- 🏗️ [系统概览](docs/system-overview.md) - Mongo Connector 的内部架构和工作原理
- 📝 [Oplog 进度文件](docs/oplog-progress-file.md) - 了解 oplog.timestamp 文件的作用和管理

### 配置和使用
- ⚙️ [配置选项](docs/configuration-options.md) - 完整的配置选项参考
- 🔐 [使用认证](docs/usage-with-authentication.md) - 配置 MongoDB 和目标系统的身份验证

### 目标系统指南
- 🍃 [在 MongoDB 中使用](docs/usage-with-mongodb.md) - 复制到另一个 MongoDB 实例
- 🔍 [在 Solr 中使用](docs/usage-with-solr.md) - 复制到 Apache Solr 搜索引擎

---

## 🎯 主要特性

### ✅ 实时复制
- 通过跟踪 MongoDB oplog 实现毫秒级数据同步
- 支持副本集和分片集群
- 自动处理回滚和故障恢复

### 🔄 多目标支持
- 同时复制到多个目标系统
- 支持不同类型的目标系统组合
- 灵活的命名空间过滤和重命名

### 🛠️ 易于配置
- JSON 格式配置文件
- 丰富的命令行选项
- 支持字段级过滤

### 📦 可扩展架构
- 插件化 DocManager 系统
- 支持自定义目标系统
- 清晰的代码结构

---

## 📦 DocManager 插件

Mongo Connector 支持多种目标系统，通过插件方式安装：

| 目标系统 | 安装命令 | 文档链接 |
|---------|---------|---------|
| MongoDB | `pip install mongo-connector` | [使用指南](docs/usage-with-mongodb.md) |
| Elasticsearch 1.x | `pip install 'mongo-connector[elastic]'` | [elastic-doc-manager](https://github.com/yougov/elastic-doc-manager) |
| Elasticsearch 2.x/5.x | `pip install 'mongo-connector[elastic2]'` | [elastic2-doc-manager](https://github.com/yougov/elastic2-doc-manager) |
| Solr | `pip install 'mongo-connector[solr]'` | [使用指南](docs/usage-with-solr.md) |

---

## 🧪 测试

### 运行单元测试

```bash
# 运行特定测试
pytest tests/test_config.py tests/test_namespace_config.py -v

# 使用测试脚本
./run_tests.sh quick
```

### 运行端到端测试（需要 Docker）

```bash
# 启动 MongoDB
docker-compose -f docker-compose.test.yml up -d

# 初始化副本集
docker exec mongo-test-primary mongosh --eval 'rs.initiate({...})'

# 运行测试
python test_simple_e2e.py

# 清理
docker-compose -f docker-compose.test.yml down
```

---

## 📖 相关资源

### 官方资源
- **GitHub**: https://github.com/yougov/mongo-connector
- **Gitee (维护仓库)**: https://gitee.com/Talbot3/mongo-connector
- **在线 Wiki**: https://github.com/yougov/mongo-connector/wiki

### 开发者文档
- [PyPI 发布指南](PyPI_RELEASE_GUIDE.md) - 如何发布到 PyPI
- [项目架构指南](CLAUDE.md) - 项目结构和设计说明
- [变更日志](CHANGELOG.md) - 版本更新记录

### MongoDB 相关文档
- [MongoDB Manual](https://docs.mongodb.com/manual/)
- [副本集](https://docs.mongodb.com/manual/replication/)
- [分片集群](https://docs.mongodb.com/manual/sharding/)
- [认证](https://docs.mongodb.com/manual/core/authentication/)

---

## 🤝 贡献

欢迎贡献代码、报告问题或提出改进建议！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request

在 [Gitee](https://gitee.com/Talbot3/mongo-connector) 或 [GitHub](https://github.com/yougov/mongo-connector) 提交 Issue 和 Pull Request。

---

## ❓ 故障排除

遇到问题？

1. 查看 [完整文档](docs/README.md)
2. 阅读 [FAQ](https://github.com/yougov/mongo-connector/wiki/FAQ)
3. 在 [Gitee Issues](https://gitee.com/Talbot3/mongo-connector/issues) 搜索或提问

---

## 📄 许可证

Apache License 2.0 - 详见 [LICENSE](LICENSE) 文件

---

## 🎉 致谢

- 原始作者: MongoDB Labs
- 当前维护者: YouGov, Plc. 和 Talbot3
- 感谢所有贡献者的支持！

---

<div align="center">

**⭐ 如果这个项目对您有帮助，请给我们一个 Star！**

Made with ❤️ by the Mongo Connector community

</div>