MongoDB 8.x 架构师完全指南：从单机到高可用，从 CRUD 到 AI 向量搜索

version: '3.8'

services:

  mongodb:

    image: mongo:8.0

    container\_name: mongodb

    restart: unless-stopped

    ports:

      - "27017:27017"

    environment:

      MONGO\_INITDB\_ROOT\_USERNAME: root

      MONGO\_INITDB\_ROOT\_PASSWORD: example123

      MONGO\_INITDB\_DATABASE: demo

    volumes:

      - mongo\_data:/data/db

      - ./init-mongo.js:/docker-entrypoint-initdb.d/init-mongo.js:ro

    networks:

      - mongo-net

  mongo-express:

    image: mongo-express:1.0.2

    container\_name: mongo-express

    restart: unless-stopped

    ports:

      - "8081:8081"

    environment:

      ME\_CONFIG\_MONGODB\_ADMINUSERNAME: root

      ME\_CONFIG\_MONGODB\_ADMINPASSWORD: example123

      ME\_CONFIG\_MONGODB\_URL: mongodb://root:example123@mongodb:27017/

      ME\_CONFIG\_BASICAUTH\_USERNAME: admin

      ME\_CONFIG\_BASICAUTH\_PASSWORD: admin123

    depends\_on:

      - mongodb

    networks:

      - mongo-net

volumes:

  mongo\_data:

networks:

  mongo-net:

    driver: bridge

db = db.getSiblingDB('demo');

db.createUser({

  user: 'demouser',

  pwd: 'demo123',

  roles: [{ role: 'readWrite', db: 'demo' }]

});

db.products.insertMany([

  { name: 'iPhone 16', price: 7999, tags: ['手机', '苹果'], stock: 100 },

  { name: 'MacBook Pro', price: 14999, tags: ['电脑', '苹果'], stock: 50 }

]);

docker-compose up -d

# 验证

docker ps

curl http://localhost:8081  # 打开监控界面，用户名: admin / admin123

mongo-demo/

├── pom.xml

├── src/main/java/com/example/

│   ├── MongoApplication.java

│   ├── model/

│   │   ├── Product.java      # 商品（基础CRUD）

│   │   ├── Order.java        # 订单（事务）

│   │   └── SensorData.java   # 传感器（时序）

│   ├── repository/

│   │   ├── ProductRepository.java

│   │   └── OrderRepository.java

│   ├── service/

│   │   ├── ProductService.java

│   │   └── VectorSearchService.java

│   └── controller/

│       ├── ProductController.java

│       └── OrderController.java

└── src/main/resources/

    └── application.yml

<parent>

    <groupId>org.springframework.boot</groupId>

    <artifactId>spring-boot-starter-parent</artifactId>

    <version>2.7.18</version>

</parent>

<dependencies>

    <dependency>

        <groupId>org.springframework.boot</groupId>

        <artifactId>spring-boot-starter-data-mongodb</artifactId>

    </dependency>

    <dependency>

        <groupId>org.springframework.boot</groupId>

        <artifactId>spring-boot-starter-web</artifactId>

    </dependency>

    <dependency>

        <groupId>org.projectlombok</groupId>

        <artifactId>lombok</artifactId>

        <optional>true</optional>

    </dependency>

 <!-- 用于事务支持 -->

    <dependency>

        <groupId>org.springframework.boot</groupId>

        <artifactId>spring-boot-starter-aop</artifactId>

    </dependency>

</dependencies>

spring:

  data:

    mongodb:

      uri: mongodb://demouser:demo123@localhost:27017/demo

      database: demo

server:

  port: 8080

// Product.java

@Document(collection = "products")

@Data

@Builder

public class Product {

    @Id

 private String id;

 private String name;

 private Double price;

 private List<String> tags;

 private Integer stock;

 // 灵活的扩展属性，不同商品有不同字段

 private Map<String, Object> attributes;

    @CreatedDate

 private Date createdAt;

}

// ProductRepository.java

public interface ProductRepository extends MongoRepository<Product, String> {

    List<Product> findByTagsContaining(String tag);

    List<Product> findByPriceBetween(Double min, Double max);

    @Query("{ 'attributes.color': ?0 }")

    List<Product> findByColor(String color);

}

// ProductController.java

@RestController

@RequestMapping("/api/products")

@RequiredArgsConstructor

public class ProductController {

 private final ProductRepository productRepo;

    @PostMapping

 public Product create(@RequestBody Product p) {

 return productRepo.save(p);

    }

    @GetMapping

 public List<Product> list() {

 return productRepo.findAll();

    }

    @GetMapping("/tag/{tag}")

 public List<Product> byTag(@PathVariable String tag) {

 return productRepo.findByTagsContaining(tag);

    }

    @GetMapping("/price")

 public List<Product> byPrice(@RequestParam double min, @RequestParam double max) {

 return productRepo.findByPriceBetween(min, max);

    }

}

# 创建带灵活属性的商品

curl -X POST http://localhost:8080/api/products \

  -H "Content-Type: application/json" \

  -d '{"name":"华为 Mate 70","price":5999,"tags":["手机","华为"],

       "stock":200,"attributes":{"内存":"16GB","存储":"512GB","颜色":"黑色"}}'

# 按标签查询

curl http://localhost:8080/api/products/tag/手机

# 预期输出：返回所有手机类商品 JSON 数组

// ProductService.java

@Service

@RequiredArgsConstructor

public class ProductService {

 private final MongoTemplate mongoTemplate;

 public List<Document> salesStatsByCategory() {

        Aggregation agg = Aggregation.newAggregation(

            Aggregation.unwind("tags"),

            Aggregation.group("tags")

                .count().as("count")

                .sum("price").as("totalRevenue")

                .avg("price").as("avgPrice"),

            Aggregation.sort(Sort.by(Sort.Direction.DESC, "totalRevenue")),

            Aggregation.limit(10)

        );

        AggregationResults<Document> result =

            mongoTemplate.aggregate(agg, "products", Document.class);

 return result.getMappedResults();

    }

}

// 对应 Controller 端点

@GetMapping("/stats/category")

public List<Document> categoryStats() {

 return productService.salesStatsByCategory();

}

curl http://localhost:8080/api/products/stats/category

# 预期返回：[{"\_id":"手机","count":5,"totalRevenue":35000,"avgPrice":7000}, ...]

// Order.java

@Document(collection = "orders")

@Data

@Builder

public class Order {

    @Id

 private String id;

 private String productId;

 private Integer quantity;

 private Double totalAmount;

 private String status;  // PENDING, CONFIRMED, CANCELLED

    @CreatedDate

 private Date createdAt;

}

// OrderService.java

@Service

@RequiredArgsConstructor

public class OrderService {

 private final MongoTemplate mongoTemplate;

 private final ProductRepository productRepo;

 private final OrderRepository orderRepo;

    @Transactional  // Spring 事务，需配置 MongoTransactionManager

 public Order createOrder(String productId, Integer qty) {

        Product product = productRepo.findById(productId)

            .orElseThrow(() -> new RuntimeException("商品不存在"));

 if (product.getStock() < qty) {

 throw new RuntimeException("库存不足");

        }

 // 扣库存

        product.setStock(product.getStock() - qty);

        productRepo.save(product);

 // 创建订单

        Order order = Order.builder()

            .productId(productId)

            .quantity(qty)

            .totalAmount(product.getPrice() \* qty)

            .status("CONFIRMED")

            .build();

 return orderRepo.save(order);

    }

}

// 配置事务管理器

@Configuration

public class MongoConfig {

    @Bean

    MongoTransactionManager transactionManager(MongoDatabaseFactory dbFactory) {

 return new MongoTransactionManager(dbFactory);

    }

}

# 正常下单

curl -X POST "http://localhost:8080/api/orders?productId=XXX&qty=2"

# 超卖测试（库存不足时事务回滚）

curl -X POST "http://localhost:8080/api/orders?productId=XXX&qty=9999"

# 预期：返回 "库存不足" 错误，数据库中订单和库存均不变

// ChangeStreamListener.java

@Component

@RequiredArgsConstructor

@Slf4j

public class InventoryChangeListener implements ApplicationRunner {

 private final MongoTemplate mongoTemplate;

    @Override

 public void run(ApplicationArguments args) {

 // 异步监听，生产环境用线程池

 new Thread(() -> {

            ChangeStreamOptions options = ChangeStreamOptions.builder()

                .filter(Aggregation.newAggregation(

                    Aggregation.match(

                        Criteria.where("operationType").in("update", "replace")

                    )

                )).build();

            mongoTemplate.changeStream("products",

                options, Document.class)

                .doOnNext(event -> {

                    Document body = event.getBody();

 if (body != null) {

                        Integer stock = body.getInteger("stock");

 if (stock != null && stock < 10) {

                            log.warn("⚠️ 库存预警！商品 {} 库存仅剩 {}",

                                body.getString("name"), stock);

 // 实际生产：推送钉钉/企微告警

                        }

                    }

                })

                .subscribe();

        }).start();

    }

}

// 通过 MongoTemplate 创建时序集合

@Configuration

public class TimeSeriesConfig {

    @Bean

 public CommandLineRunner createTimeSeriesCollection(MongoTemplate mongoTemplate) {

 return args -> {

 if (!mongoTemplate.collectionExists("sensor\_data")) {

                mongoTemplate.createCollection("sensor\_data",

                    CollectionOptions.empty()

                        .timeSeries(

                            TimeSeriesOptions.timeSeries("timestamp")

                                .metaField("sensorId")

                                .granularity(TimeSeriesGranularity.MINUTES)

                        ));

            }

        };

    }

}

// SensorData.java

@Document(collection = "sensor\_data")

@Data

@Builder

public class SensorData {

 private String sensorId;     // metaField

 private Date timestamp;      // timeField

 private Double temperature;

 private Double humidity;

}

// 批量插入传感器数据

@PostMapping("/sensor/batch")

public void insertSensorData() {

    List<SensorData> batch = IntStream.range(0, 100)

        .mapToObj(i -> SensorData.builder()

            .sensorId("sensor-001")

            .timestamp(new Date(System.currentTimeMillis() - i \* 60000L))

            .temperature(20.0 + Math.random() \* 10)

            .humidity(60.0 + Math.random() \* 20)

            .build())

        .collect(Collectors.toList());

    mongoTemplate.insertAll(batch);

}

// Store.java

@Document(collection = "stores")

@Data

public class Store {

    @Id

 private String id;

 private String name;

    @GeoSpatialIndexed(type = GeoSpatialIndexType.GEO\_2DSPHERE)

 private GeoJsonPoint location;  // [longitude, latitude]

}

// 查询 5km 范围内的门店

public List<Store> findNearby(double lng, double lat, double radiusKm) {

    Point point = new Point(lng, lat);

    Distance distance = new Distance(radiusKm, Metrics.KILOMETERS);

 return mongoTemplate.find(

 new Query(Criteria.where("location")

            .nearSphere(point).maxDistance(distance.getNormalizedValue())),

        Store.class

    );

}

version: '3.8'

services:

  mongo1:

    image: mongo:8.0

    container\_name: mongo1

    command: mongod --replSet rs0 --bind\_ip\_all

    ports:

      - "27017:27017"

    volumes:

      - mongo1\_data:/data/db

    networks:

      - rs-net

  mongo2:

    image: mongo:8.0

    container\_name: mongo2

    command: mongod --replSet rs0 --bind\_ip\_all

    ports:

      - "27018:27017"

    volumes:

      - mongo2\_data:/data/db

    networks:

      - rs-net

  mongo3:

    image: mongo:8.0

    container\_name: mongo3

    command: mongod --replSet rs0 --bind\_ip\_all

    ports:

      - "27019:27017"

    volumes:

      - mongo3\_data:/data/db

    networks:

      - rs-net

volumes:

  mongo1\_data:

  mongo2\_data:

  mongo3\_data:

networks:

  rs-net:

    driver: bridge

# 启动容器

docker-compose up -d

# 进入 mongo1 初始化副本集

docker exec -it mongo1 mongosh

# 在 mongosh 中执行

rs.initiate({

  \_id: "rs0",

  members: [

    { \_id: 0, host: "mongo1:27017", priority: 2 },

    { \_id: 1, host: "mongo2:27017", priority: 1 },

    { \_id: 2, host: "mongo3:27017", priority: 1 }

  ]

})

# 验证状态

rs.status()

spring:

  data:

    mongodb:

      uri: mongodb://root:example123@localhost:27017,localhost:27018,localhost:27019/demo?replicaSet=rs0&authSource=admin

# 停掉主节点，观察自动切换

docker stop mongo1

# 等待约 10 秒，进入 mongo2 查看

docker exec -it mongo2 mongosh --eval "rs.status()"

# 预期：mongo2 或 mongo3 变成 PRIMARY

// 存储文档向量（使用本地 embedding 模型或调用 API）

@Document(collection = "knowledge\_base")

@Data

public class KnowledgeDoc {

    @Id

 private String id;

 private String content;          // 原始文本

 private String category;         // 分类标签

 private List<Double> embedding;  // 向量，1536 维（OpenAI text-embedding-3-small）

 private Date createdAt;

}

// VectorSearchService.java

@Service

@RequiredArgsConstructor

public class VectorSearchService {

 private final MongoTemplate mongoTemplate;

 // Atlas 环境下的向量搜索

 public List<KnowledgeDoc> semanticSearch(List<Double> queryVector, int topK) {

 // $vectorSearch 聚合管道（需 Atlas 或开启向量索引）

        String pipeline = String.format(

 "[{ \"$vectorSearch\": { \"index\": \"vector\_index\", " +

 "\"path\": \"embedding\", \"queryVector\": %s, " +

 "\"numCandidates\": %d, \"limit\": %d } }]",

            queryVector.toString(), topK \* 10, topK);

 return mongoTemplate.aggregate(

            Aggregation.newAggregation(

                Aggregation.stage(Document.parse(

 "{ $vectorSearch: { index: 'vector\_index', " +

 "path: 'embedding', queryVector: " + queryVector +

 ", numCandidates: 200, limit: " + topK + " } }"))

            ),

 "knowledge\_base",

            KnowledgeDoc.class

        ).getMappedResults();

    }

}

# 典型 AI Coding 工作流

claude "帮我用 Spring Boot 2 写一个基于 MongoDB 向量搜索的客服问答系统，

        包含知识库录入接口、语义搜索接口，使用 text-embedding-3-small 向量化"

# → Claude Code 直接生成代码文件、pom.xml、application.yml，并运行测试

# 快速体验（一行命令，包含 PostgreSQL + FerretDB + mongosh）

docker run -d --rm --name ferretdb -p 27017:27017 \

  -e POSTGRES\_USER=ferret \

  -e POSTGRES\_PASSWORD=ferret123 \

  ghcr.io/ferretdb/ferretdb-eval:2

# 连接测试（兼容 MongoDB 驱动）

mongosh mongodb://ferret:ferret123@localhost:27017/

# Spring Boot 连接：直接替换 URI 即可，驱动无需修改

spring:

  data:

    mongodb:

      uri: mongodb://ferret:ferret123@localhost:27017/demo

docker run -d --name couchdb \

  -e COUCHDB\_USER=admin \

  -e COUCHDB\_PASSWORD=admin123 \

  -p 5984:5984 \

  couchdb:3.3

# 访问 Fauxton 管理界面

open http://localhost:5984/\_utils